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

Installation

You need to install two different types of packages 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 (Day.js, date-fns, ...) manages the date manipulation.
// Install component (community version)
yarn add @mui/x-date-pickers

// Install date library (if not already installed)
yarn add dayjs

Why do you need a date library?

Like most picker components available, the MUI Date and Time Pickers 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.

Choosing a date library

Available libraries

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

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 are starting a new project without any date manipulation outside of @mui/x-date-pickers, then we recommend using dayjs because it will have 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:

Library Gzipped size
dayjs@1.11.5 6.77kb
date-fns@2.29.3 19.39kb
luxon@3.0.4 23.26kb
moment@2.29.4 20.78kb

Code setup

After installation, you have to pass your chosen date library's adapter to LocalizationProvider. The supported adapters—as well as LocalizationProvider—are exported from both the @mui/x-date-pickers and @mui/x-date-pickers-pro packages.

All the pickers rendered inside this provider will have access to the adapter through a React context. For this reason, we recommend that you wrap your entire application with a LocalizationProvider so you can use the Date and Time Pickers everywhere.

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

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

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

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('10-11-2021');