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 date picker

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker label="Basic date picker" />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker label="Basic date picker" />
</LocalizationProvider>

Press Enter to start editing

Uncontrolled vs. Controlled

The component can be uncontrolled or controlled

Uncontrolled picker

Controlled picker

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Stack spacing={2} direction="row">
    <NextDatePicker
      label="Uncontrolled picker"
      defaultValue={dayjs('2022-04-07')}
    />
    <NextDatePicker
      label="Controlled picker"
      value={value}
      onChange={(newValue) => setValue(newValue)}
    />
  </Stack>
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Stack spacing={2} direction="row">
    <NextDatePicker
      label="Uncontrolled picker"
      defaultValue={dayjs('2022-04-07')}
    />
    <NextDatePicker
      label="Controlled picker"
      value={value}
      onChange={(newValue) => setValue(newValue)}
    />
  </Stack>
</LocalizationProvider>

Press Enter to start editing

Responsiveness

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

The MobileNextDatePicker component works best for touch devices and small screens.
The DesktopNextDatePicker component works best for mouse devices and large screens.

By default, the NextDatePicker 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

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Stack spacing={3}>
    <MobileNextDatePicker
      label="For mobile"
      defaultValue={dayjs('2022-04-07')}
    />
    <DesktopNextDatePicker
      label="For desktop"
      defaultValue={dayjs('2022-04-07')}
    />
    <NextDatePicker label="Responsive" defaultValue={dayjs('2022-04-07')} />
  </Stack>
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Stack spacing={3}>
    <MobileNextDatePicker
      label="For mobile"
      defaultValue={dayjs('2022-04-07')}
    />
    <DesktopNextDatePicker
      label="For desktop"
      defaultValue={dayjs('2022-04-07')}
    />
    <NextDatePicker label="Responsive" defaultValue={dayjs('2022-04-07')} />
  </Stack>
</LocalizationProvider>

Press Enter to start editing

Static mode

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

November 2022

SMTWTFS

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticNextDatePicker displayStaticWrapperAs="desktop" />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticNextDatePicker displayStaticWrapperAs="desktop" />
</LocalizationProvider>

Press Enter to start editing

Form props

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

disabled

readOnly

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Stack spacing={3}>
    <NextDatePicker label="disabled" disabled />
    <NextDatePicker label="readOnly" readOnly />
  </Stack>
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Stack spacing={3}>
    <NextDatePicker label="disabled" disabled />
    <NextDatePicker label="readOnly" readOnly />
  </Stack>
</LocalizationProvider>

Press Enter to start editing

Validation

You can find the documentation in the Validation page

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 @mui/x-date-pickers/AdapterDateFnsJalali adapter to support Jalali calendar.

<LocalizationProvider dateAdapter={AdapterDateFnsJalali}>
  <NextDatePicker defaultValue={new Date(2022, 3, 7)} />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDateFnsJalali}>
  <NextDatePicker defaultValue={new Date(2022, 3, 7)} />
</LocalizationProvider>

Press Enter to start editing

Views playground

It's possible to combine year, month, and date selection views. The 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}>
  <StaticNextDatePicker
    orientation="landscape"
    defaultValue={dayjs('2022-04-07')}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticNextDatePicker
    orientation="landscape"
    defaultValue={dayjs('2022-04-07')}
  />
</LocalizationProvider>

Press Enter to start editing

Sub-components

Some lower-level sub-components (DateCalendar, MonthCalendar, and YearCalendar) are also exported.

April 2022

SMTWTFS

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Grid container spacing={3}>
    <Grid item xs={12} md={6}>
      <DateCalendar defaultValue={dayjs('2022-04-07')} />
    </Grid>
    <Grid item xs={12} md={6}>
      <MonthCalendar defaultValue={dayjs('2022-04-07')} />
    </Grid>
    <Grid item xs={12} md={6}>
      <YearCalendar defaultValue={dayjs('2022-04-07')} />
    </Grid>
  </Grid>
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <Grid container spacing={3}>
    <Grid item xs={12} md={6}>
      <DateCalendar defaultValue={dayjs('2022-04-07')} />
    </Grid>
    <Grid item xs={12} md={6}>
      <MonthCalendar defaultValue={dayjs('2022-04-07')} />
    </Grid>
    <Grid item xs={12} md={6}>
      <YearCalendar defaultValue={dayjs('2022-04-07')} />
    </Grid>
  </Grid>
</LocalizationProvider>

Press Enter to start editing

Custom input component

You can customize the rendering of the input with the Input component slot. Make sure to spread inputProps correctly to the custom input component.

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker
    label="Custom input"
    defaultValue={dayjs('2022-04-07')}
    components={{
      Input: BrowserInput,
    }}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker
    label="Custom input"
    defaultValue={dayjs('2022-04-07')}
    components={{
      Input: BrowserInput,
    }}
  />
</LocalizationProvider>

Press Enter to start editing

Customized day rendering

The displayed days are customizable with the Day component slot. You can take advantage of the PickersDay component.

April 2022

SMTWTFS

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticNextDatePicker
    displayStaticWrapperAs="desktop"
    defaultValue={dayjs('2022-04-07')}
    components={{ Day }}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticNextDatePicker
    displayStaticWrapperAs="desktop"
    defaultValue={dayjs('2022-04-07')}
    components={{ Day }}
  />
</LocalizationProvider>

Press Enter to start editing

Customize month layout

You can customize the month layout with some props.

Show additional days

To shows all days of displayed weeks, included those outside of the current month, use showDaysOutsideCurrentMonth.

By default, only weeks of the current month are displayed, but you can provide a total number of week to display with fixedWeekNumber prop. This value is usually set to 6 for Gregorian calendars, because months display can vary between 4 and 6 weeks.

April 2022

SMTWTFS

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticNextDatePicker
    displayStaticWrapperAs="desktop"
    openTo="day"
    defaultValue={dayjs('2022-04-07')}
    showDaysOutsideCurrentMonth
    fixedWeekNumber={6}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticNextDatePicker
    displayStaticWrapperAs="desktop"
    openTo="day"
    defaultValue={dayjs('2022-04-07')}
    showDaysOutsideCurrentMonth
    fixedWeekNumber={6}
  />
</LocalizationProvider>

Press Enter to start editing

Display week number

To display week number, use the displayWeekNumber. You can customize the calendar week header by using the localization key localeText.calendarWeekNumberHeaderText. You can also customize what's rendered as a calendar week number, using a callback for the localization key localeText.calendarWeekNumberText.

Select date

––

November 2022

#SMTWTFS

45.

46.

47.

48.

49.

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    displayWeekNumber
    label="Basic example"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
    localeText={{
      calendarWeekNumberHeaderText: '#',
      calendarWeekNumberText: (weekNumber) => `${weekNumber}.`,
    }}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <StaticDatePicker
    displayWeekNumber
    label="Basic example"
    value={value}
    onChange={(newValue) => {
      setValue(newValue);
    }}
    renderInput={(params) => <TextField {...params} />}
    localeText={{
      calendarWeekNumberHeaderText: '#',
      calendarWeekNumberText: (weekNumber) => `${weekNumber}.`,
    }}
  />
</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 components.Day props.

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker
    defaultValue={initialValue}
    loading={isLoading}
    onMonthChange={handleMonthChange}
    renderLoading={() => <DayCalendarSkeleton />}
    components={{
      Day: ServerDay,
    }}
    componentsProps={{
      day: {
        highlightedDays,
      } as any,
    }}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker
    defaultValue={initialValue}
    loading={isLoading}
    onMonthChange={handleMonthChange}
    renderLoading={() => <DayCalendarSkeleton />}
    components={{
      Day: ServerDay,
    }}
    componentsProps={{
      day: {
        highlightedDays,
      } as any,
    }}
  />
</LocalizationProvider>

Press Enter to start editing

Helper text

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

Helper text example

MM / DD / YYYY

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker
    label="Helper text example"
    componentsProps={{
      input: {
        helperText: 'MM / DD / YYYY',
      },
    }}
  />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <NextDatePicker
    label="Helper text example"
    componentsProps={{
      input: {
        helperText: 'MM / DD / YYYY',
      },
    }}
  />
</LocalizationProvider>

Press Enter to start editing

Date Picker

Basic usage

Uncontrolled vs. Controlled

Responsiveness

Static mode

Form props

Validation

Localization

Jalali calendar system

Views playground

Landscape orientation

Thu, Apr 7

Sub-components

Custom input component

Customized day rendering

Customize month layout

Show additional days

Display week number

––

Dynamic data

Helper text

API