Localized dates

Date and Time Pickers support formats from different locales.

Getting started

The default locale of MUI is English (United States). If you want to use other locales—follow the instructions below.

Set a custom locale

With `dayjs`

For dayjs, import the locale and then pass its name to LocalizationProvider:

import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import 'dayjs/locale/de';

<LocalizationProvider dateAdapter={AdapterDayjs} adapterLocale="de">
  {children}
</LocalizationProvider>;

Date

Time

<ToggleButtonGroup
  value={locale}
  exclusive
  fullWidth
  onChange={(event, newLocale) => setLocale(newLocale)}
>
  {locales.map((localeItem) => (
    <ToggleButton key={localeItem} value={localeItem}>
      {localeItem}
    </ToggleButton>
  ))}
</ToggleButtonGroup>
<DateField label="Date" defaultValue={dayjs('2022-04-07')} />
<TimeField label="Time" defaultValue={dayjs('2022-04-07T18:30')} />

<ToggleButtonGroup
  value={locale}
  exclusive
  fullWidth
  onChange={(event, newLocale) => setLocale(newLocale)}
>
  {locales.map((localeItem) => (
    <ToggleButton key={localeItem} value={localeItem}>
      {localeItem}
    </ToggleButton>
  ))}
</ToggleButtonGroup>
<DateField label="Date" defaultValue={dayjs('2022-04-07')} />
<TimeField label="Time" defaultValue={dayjs('2022-04-07T18:30')} />

Press Enter to start editing

With `date-fns`

For date-fns, import the locale and pass it to LocalizationProvider:

import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
import de from 'date-fns/locale/de';

<LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={de}>
  {children}
</LocalizationProvider>;

Date

Time

<ToggleButtonGroup
  value={locale}
  exclusive
  fullWidth
  onChange={(event, newLocale) => setLocale(newLocale)}
>
  {Object.keys(locales).map((localeItem) => (
    <ToggleButton key={localeItem} value={localeItem}>
      {localeItem}
    </ToggleButton>
  ))}
</ToggleButtonGroup>
<DateField label="Date" defaultValue={new Date('2022-04-07')} />
<TimeField label="Time" defaultValue={new Date('2022-04-07T18:30')} />

<ToggleButtonGroup
  value={locale}
  exclusive
  fullWidth
  onChange={(event, newLocale) => setLocale(newLocale)}
>
  {Object.keys(locales).map((localeItem) => (
    <ToggleButton key={localeItem} value={localeItem}>
      {localeItem}
    </ToggleButton>
  ))}
</ToggleButtonGroup>
<DateField label="Date" defaultValue={new Date('2022-04-07')} />
<TimeField label="Time" defaultValue={new Date('2022-04-07T18:30')} />

Press Enter to start editing

With `luxon`

For luxon, pass the locale name to LocalizationProvider:

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

<LocalizationProvider dateAdapter={AdapterLuxon} adapterLocale="de">
  {children}
</LocalizationProvider>;

Date

Time

With `moment`

For moment, import the locale and then pass its name to LocalizationProvider:

import { AdapterMoment } from '@mui/x-date-pickers/AdapterMoment';
import 'moment/locale/de';

<LocalizationProvider dateAdapter={AdapterMoment} adapterLocale="de">
  {children}
</LocalizationProvider>;

Date

Time

<ToggleButtonGroup
  value={locale}
  exclusive
  fullWidth
  onChange={(event, newLocale) => setLocale(newLocale)}
>
  {locales.map((localeItem) => (
    <ToggleButton key={localeItem} value={localeItem}>
      {localeItem}
    </ToggleButton>
  ))}
</ToggleButtonGroup>
<DateField label="Date" defaultValue={moment('2022-04-07')} />
<TimeField label="Time" defaultValue={moment('2022-04-07T18:30')} />

<ToggleButtonGroup
  value={locale}
  exclusive
  fullWidth
  onChange={(event, newLocale) => setLocale(newLocale)}
>
  {locales.map((localeItem) => (
    <ToggleButton key={localeItem} value={localeItem}>
      {localeItem}
    </ToggleButton>
  ))}
</ToggleButtonGroup>
<DateField label="Date" defaultValue={moment('2022-04-07')} />
<TimeField label="Time" defaultValue={moment('2022-04-07T18:30')} />

Press Enter to start editing

Some of the moment methods do not support scoped locales. For accurate localization, you will have to manually update the global locale before updating it in LocalizationProvider.

function App({ children }) {
  const [locale, setLocale] = React.useState('en-us');

  if (moment.locale() !== locale) {
    moment.locale(locale);
  }

  return (
    <LocalizationProvider dateAdapter={AdapterMoment} adapterLocale={locale}>
      <Stack>
        <Button onClick={() => setLocale('de')}>Switch to German</Button>
        {children}
      </Stack>
    </LocalizationProvider>
  );
}

12h/24h format

All the time and datetime components will automatically adjust to the locale's time setting, i.e. the 12-hour or 24-hour format. You can override the default setting with the ampm prop:

Locale default

AM / PM

24 hours

Custom formats

Custom field format

The fields have a default format that depends on the picker being used, the views enabled, and the 12h/24h format.

If this default format does not suit you, you can customize it using the format prop:

Date Field

Date Picker

<DateField
  label="Date Field"
  format="MM - DD - YYYY"
  defaultValue={dayjs('2022-04-07')}
/>
<NextDatePicker
  label="Date Picker"
  format="YYYY/MM/DD"
  defaultValue={dayjs('2022-04-07')}
/>

<DateField
  label="Date Field"
  format="MM - DD - YYYY"
  defaultValue={dayjs('2022-04-07')}
/>
<NextDatePicker
  label="Date Picker"
  format="YYYY/MM/DD"
  defaultValue={dayjs('2022-04-07')}
/>

Press Enter to start editing

Custom field placeholder

When a section is empty, the fields displays its placeholder instead of an empty value. For example, if you did not fill any value for the year section, the field will render the year placeholder.

These placeholders are based on your current component localization, not on your date localization.

English locale (default)

German locale

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DateField label="English locale (default)" />
</LocalizationProvider>
<LocalizationProvider
  dateAdapter={AdapterDayjs}
  // Define the date locale to have the right format `day.month.year`.
  adapterLocale="de"
  // Define the translations (component localization) to have the right placeholders.
  // (e.g. `JJJJ` for the year)
  localeText={germanLocale}
>
  <DateField label="German locale" />
</LocalizationProvider>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DateField label="English locale (default)" />
</LocalizationProvider>
<LocalizationProvider
  dateAdapter={AdapterDayjs}
  // Define the date locale to have the right format `day.month.year`.
  adapterLocale="de"
  // Define the translations (component localization) to have the right placeholders.
  // (e.g. `JJJJ` for the year)
  localeText={germanLocale}
>
  <DateField label="German locale" />
</LocalizationProvider>

Press Enter to start editing

For more information on how to define your component localization, check out the Translated components page.

To customize the format used in the toolbar, use the toolbarFormat prop of the toolbar slot.

April 2022

SMTWTFS

<StaticNextDatePicker
  displayStaticWrapperAs="desktop"
  defaultValue={dayjs('2022-04-07')}
  componentsProps={{ toolbar: { toolbarFormat: 'ddd DD MMMM' } }}
  showToolbar
/>

<StaticNextDatePicker
  displayStaticWrapperAs="desktop"
  defaultValue={dayjs('2022-04-07')}
  componentsProps={{ toolbar: { toolbarFormat: 'ddd DD MMMM' } }}
  showToolbar
/>

Press Enter to start editing

Custom day of week format

Use dayOfWeekFormatter to customize day names in the calendar header. This prop takes the short name of the day provided by the date library as an input, and returns it's formatted version. The default formatter only keeps the first letter and capitalises it.

The example bellow adds a dot at the end of each day in the calendar header:

April 2022

Su.Mo.Tu.We.Th.Fr.Sa.

<DateCalendar
  value={value}
  onChange={(newValue) => setValue(newValue)}
  dayOfWeekFormatter={(day) => `${day}.`}
/>

<DateCalendar
  value={value}
  onChange={(newValue) => setValue(newValue)}
  dayOfWeekFormatter={(day) => `${day}.`}
/>

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.

<LocalizationProvider />

Localized dates

Getting started

Set a custom locale

With dayjs

With date-fns

With luxon

With moment

12h/24h format

Custom formats

Custom field format

Custom field placeholder

Custom toolbar format

Thu 07 April

Custom day of week format

API

With `dayjs`

With `date-fns`

With `luxon`

With `moment`