Date picker

The date picker let the user select a date.

Date pickers are displayed with:

Dialogs on mobile
Text field dropdowns on desktop

Basic usage

The date picker is rendered as a modal dialog on mobile, and a textbox with a popup on desktop.

Basic example

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    label="Basic example"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    label="Basic example"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

Press Enter to start editing

Static mode

It's possible to render any date picker without the modal/popover and text field. This can be helpful when building custom popover/modal containers.

April 2022

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    displayStaticWrapperAs="desktop"
    openTo="year"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    displayStaticWrapperAs="desktop"
    openTo="year"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

Press Enter to start editing

Responsiveness

The date picker component is designed and optimized for the device it runs on.

The MobileDatePicker component works best for touch devices and small screens.
The DesktopDatePicker component works best for mouse devices and large screens.

By default, the DatePicker component renders the desktop version if the media query @media (pointer: fine) matches. This can be customized with the desktopModeMediaQuery prop.

There are certain caveats when testing pickers, please refer to this section for more information.

For mobile

For desktop

Responsive

Form props

The date picker component can be disabled or read-only.

disabled

read-only

Localization

Use LocalizationProvider to change the date-library locale that is used to render the date picker. See the documentation page about localization for more details.

Jalali calendar system

Install date-fns-jalali and use @date-io/date-fns-jalali adapter to support Jalali calendar.

<LocalizationProvider dateAdapter={AdapterJalali}>
  <DatePicker
    mask="____/__/__"
    value={value}
    onChange={(newValue) => setValue(newValue)}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterJalali}>
  <DatePicker
    mask="____/__/__"
    value={value}
    onChange={(newValue) => setValue(newValue)}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

Press Enter to start editing

Views playground

It's possible to combine year, month, and date selection views. Views will appear in the order they're included in the views array.

Year only

Year and Month

Year, month and date

Invert the order of views

Just date

Landscape orientation

For ease of use, the date picker will automatically change the layout between portrait and landscape by subscription to the window.orientation change. You can force a specific layout using the orientation prop.

Select date

Thu, Apr 7

April 2022

SMTWTFS

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    orientation="landscape"
    openTo="day"
    value={value}
    shouldDisableDate={isWeekend}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    orientation="landscape"
    openTo="day"
    value={value}
    shouldDisableDate={isWeekend}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

Press Enter to start editing

Sub-components

Some lower-level sub-components (CalendarPicker, MonthPicker, and YearPicker) are also exported. These are rendered without a wrapper or outer logic (masked input, date values parsing and validation, etc.).

April 2022

SMTWTFS

Custom input component

You can customize the rendering of the input with the renderInput prop. Make sure to spread ref and inputProps correctly to the custom input component.

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    label="Custom input"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={({ inputRef, inputProps, InputProps }) => (
      <Box sx={{ display: 'flex', alignItems: 'center' }}>
        <input ref={inputRef} {...inputProps} />
        {InputProps?.endAdornment}
      </Box>
    )}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    label="Custom input"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={({ inputRef, inputProps, InputProps }) => (
      <Box sx={{ display: 'flex', alignItems: 'center' }}>
        <input ref={inputRef} {...inputProps} />
        {InputProps?.endAdornment}
      </Box>
    )}
  />
</LocalizationProvider>

Press Enter to start editing

Customized day rendering

The displayed days are customizable with the renderDay function prop. You can take advantage of the PickersDay component.

April 2022

SMTWTFS

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    displayStaticWrapperAs="desktop"
    label="Week picker"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderDay={renderWeekPickerDay}
    renderInput={(params) => <TextField {...params} />}
    inputFormat="'Week of' MMM d"
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    displayStaticWrapperAs="desktop"
    label="Week picker"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderDay={renderWeekPickerDay}
    renderInput={(params) => <TextField {...params} />}
    inputFormat="'Week of' MMM d"
  />
</LocalizationProvider>

Press Enter to start editing

Dynamic data

Sometimes it may be necessary to display additional info right in the calendar. Here's an example of prefetching and displaying server-side data using the onMonthChange, loading, and renderDay props.

Helper text

You can show a helper text with the date format accepted.

Helper text example

mm/dd/yyyy

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    label="Helper text example"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => (
      <TextField {...params} helperText={params?.inputProps?.placeholder} />
    )}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    label="Helper text example"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => (
      <TextField {...params} helperText={params?.inputProps?.placeholder} />
    )}
  />
</LocalizationProvider>

Press Enter to start editing

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.