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';

Date library

The Date and Time Pickers are focused on UI/UX and, like most other picker components available, require a third-party library to format, parse, and mutate dates.

MUI's components let you choose which library you prefer for this purpose. This gives you the flexibility to implement any date library you may already be using in your application, without adding an extra one to your bundle.

To achieve this, both @mui/x-date-pickers and @mui/x-date-pickers-pro export a set of adapters that expose the date manipulation libraries under a unified API.

Available libraries

The Date and Time Pickers currently support the following date libraries:

• Day.js
• date-fns
• Luxon
• Moment.js

Recommended library

If you are already using one of the libraries listed above in your application, then you can keep using it with the Date and Time Pickers as well. This will avoid bundling two libraries.

If you don't have your own requirements or don't manipulate dates outside of MUI X components, then the recommendation is to use dayjs because it has the smallest impact on your application's bundle size.

Here is the weight added to your gzipped bundle size by each of these libraries when used inside the Date and Time Pickers:

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 (for example DatePicker) which renders the desktop component or the mobile one depending on the device it runs on.

• The desktop component (for example 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 (for example 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:

Reference date when no value is defined

If value or defaultValue contains a valid date, this date will be used to initialize the rendered component.

In the demo below, you can see that the calendar is set to April 2022 on mount:

When value and defaultValue contains no valid date, the component will try to find a reference date that passes the validation to initialize its rendering:

You can override this date using the referenceDate prop:

This can also be useful to set the part of the value that will not be selectable in the component. For example, in a Time Picker, it allows you to choose the date of your value:

TypeScript

Theme augmentation

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.

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

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

Typing of the date

The Date and Time Pickers components are compatible with several date libraries that use different formats to represent their dates (Date object for date-fns, daysjs.Dayjs object for days-js, etc.). To correctly type all the props that are date-related, the adapters override a global type named PickerValidDate to allow the usage of their own date format. This allows TypeScript to throw an error if you try to pass value={new Date()} to a component using AdapterDayjs for instance.

If you run into TypeScript errors such as DesktopDatePickerProps<Date> error Type 'Date' does not satisfy the constraint 'never', it is probably because you are not importing the adapter in the same TypeScript project as the rest of your codebase. You can fix it by manually importing the adapter in some file of your project as follows:

// Replace `AdapterDayjs` with the adapter you are using.
import type {} from '@mui/x-date-pickers/AdapterDayjs';

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');

Overriding slots and slot props

Date and Time Pickers are complex components built using many subcomponents known as slots. Slots are commonly filled by React components that you can override using the slots prop. You can also pass additional props to the available slots using the slotProps prop. Learn more about the mental model of slots in the Base UI documentation: Overriding component structure.

You can find the list of available slots for each component in its respective API reference doc.

Some parts of the Pickers' UI are built on several nested slots. For instance, the adornment of the TextField on DatePicker contains three slots (inputAdornment, openPickerButton, and openPickerIcon) that you can use depending on what you are trying to customize.