Date and Time Pickers - Base concepts

The Date and Time pickers expose a lot of components to fit your every need.

Controlled value

All the components have a value / onChange API to set and control the values:

Imports

All the components exported by @mui/x-date-pickers are also exported by @mui/x-date-pickers-pro but without the nested imports.

For example, to use the DatePicker component, the following three imports are valid:

import { DatePicker } from '@mui/x-date-pickers/DatePicker';
import { DatePicker } from '@mui/x-date-pickers';
import { DatePicker } from '@mui/x-date-pickers-pro';

Other components

Choose interaction style

Depending on your use case, different interaction styles are preferred.

• For input editing with a popover or modal for mouse interaction, use the Picker components:

• For input-only editing, use the Field components:

• For inline editing, use the Calendar / Clock components:

Date or time editing?

The Date and Time Pickers are divided into six families of components. The demo below shows each one of them using their field component:

Responsiveness

Each Picker is available in a responsive, desktop and mobile variant:

• The responsive component (e.g. DatePicker) which renders the desktop component or the mobile one depending on the device it runs on.

• The desktop component (e.g. DesktopDatePicker) which works best for mouse devices and large screens. It renders the views inside a popover and allows editing values directly inside the field.

• The mobile component (e.g. MobileDatePicker) which works best for touch devices and small screens. It renders the view inside a modal and does not allow editing values directly inside the field.

Find your component

There are many components available, each fitting specific use cases. Use the form below to find the component you need:

Accessibility

Both Desktop and Mobile Date and Time Pickers are using role="dialog" to display their interactive view parts and thus they should follow Modal accessibility guidelines. This behavior is automated as much as possible, ensuring that the Date and Time Pickers are accessible in most cases. A correct aria-labelledby value is assigned to the dialog component based on the following rules:

• Use toolbar id if the toolbar is visible;
• Use the id of the input label if the toolbar is hidden;

TypeScript

In order to benefit from the CSS overrides and default prop customization with the theme, TypeScript users need to import the following types. Internally, it uses module augmentation to extend the default theme structure.

// When using TypeScript 4.x and above
import type {} from '@mui/x-date-pickers/themeAugmentation';
import type {} from '@mui/x-date-pickers-pro/themeAugmentation';
// When using TypeScript 3.x and below
import '@mui/x-date-pickers/themeAugmentation';
import '@mui/x-date-pickers-pro/themeAugmentation';

const theme = createTheme({
  components: {
    MuiDatePicker: {
      styleOverrides: {
        root: {
          backgroundColor: 'red',
        },
      },
    },
  },
});

Testing caveats

Responsive components

Be aware that running tests in headless browsers might not pass the default mediaQuery (pointer: fine). In such case you can force pointer precision via browser flags or preferences.

Field components

To add tests about a field value without having to care about those characters, you can remove the specific character before testing the equality. Here is an example about how to do it.

// Helper removing specific characters
const cleanText = (string) =>
  string.replace(/\u200e|\u2066|\u2067|\u2068|\u2069/g, '');

// Example of a test using the helper
expect(cleanText(input.value)).to.equal('04-17-2022');