Skip to content
Edit this page

Date / Time pickers

Date pickers and Time pickers allow selecting a single value from a pre-determined set.

  • On mobile, pickers are best suited for display in a confirmation dialog.
  • For inline display, such as on a form, consider using compact controls such as segmented dropdown buttons.

React components

Setup

Package installation

You need to install 3 different types of package to make the pickers work:

  1. The component (@mui/x-date-pickers or @mui/x-date-pickers-pro) manages the rendering.
  2. The date-library (moment, dayjs, ...) manages the date manipulation.
  3. The adapter (@date-io) exposes your favorite date-library under a unified api used by component.

First you have to install the date-library you want to use to manage dates, and the component package:

// Install component (community version)
yarn add @mui/x-date-pickers
// Install date library (if not already installed)
yarn add moment

We currently support 4 different date-libraries:

  • date-fns adapted by @date-io/date-fns.
  • Day.js adapted by @date-io/dayjs.
  • Luxon adapted by @date-io/luxon.
  • Moment.js adapted by @date-io/moment.

If you need to use js-joda, date-fns-jalali, moment-jalaali, or moment-hijri library, you should be able to find the corresponding date-library from @date-io. In such a case, you will have to install both the date-library and the corresponding @date-io adapter.

// To use moment-jalaali
yarn add moment-jalaali
yarn add @date-io/jalaali

Code setup

After installation completed, you have to set the dateAdapter prop of the LocalizationProvider accordingly. The supported adapters are exported from both the @mui/x-date-pickers and @mui/x-date-pickers-pro.

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

// Day.js
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
// or for date-fns
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
// or for Luxon
import { AdapterLuxon } from '@mui/x-date-pickers/AdapterLuxon';
// or for Moment.js
import { AdapterMoment } from '@mui/x-date-pickers/AdapterMoment';

function App({ children }) {
  return (
    <LocalizationProvider dateAdapter={AdapterDayjs}>
      {children}
    </LocalizationProvider>
  );
}

If you use another library you should import the adapter directly from the @date-io package as follow.

import { LocalizationProvider } from '@mui/x-date-pickers';
import AdapterJalaali from '@date-io/jalaali';

function App({ children }) {
  return (
    <LocalizationProvider dateAdapter={AdapterJalaali}>
      {children}
    </LocalizationProvider>
  );
}

Unsupported libraries

To use a date-library that is not supported yet by @date-io, you will have to write an adapter. Which means writing a file containing the default formats, and the methods. As an example, you can look to the dayjs adapter.

In such a case, don't hesitate to open a PR to get some help.

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

Native pickers

Native date (type="date"), time (type="time") and date&time (type="datetime-local") pickers.

Testing caveats

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

API