Fields component

The field components let the user input date and time values with a keyboard and refined keyboard navigation.

Introduction

The fields are React components that let you enter a date or time with the keyboard, without using any popover or modal UI. They provide refined navigation through arrow keys and support advanced behaviors like localization and validation.

Fields to edit a single element

DateField

TimeField

DateTimeField

Fields to edit a range

All fields to edit a range are available in a single input version and in a multi input version.

MultiInputDateRangeField

–

SingleInputDateRangeField

MultiInputTimeRangeField

–

SingleInputTimeRangeField

MultiInputDateTimeRangeField

–

SingleInputDateTimeRangeField

Accessible DOM structure

By default, the fields' DOM structure consists of an <input />, which holds the whole value for the component. Unfortunately it presents accessibility limitations, which are impossible to resolve.

Starting with version v7.x, we have introduced a new DOM structure that allows the field component to set aria attributes on individual sections, providing a far better experience on screen readers. You can opt-in for a new and experimental DOM structure on any field or picker component using the enableAccessibleFieldDOMStructure prop.

Starting with version v8.x, the new DOM structure will be the default for all fields.

<DateField enableAccessibleFieldDOMStructure />
<DatePicker enableAccessibleFieldDOMStructure />
<DateRangePicker enableAccessibleFieldDOMStructure />

This approach is recommended in W3C ARIA example and is also used by native date HTML input element under the hood.

Date Field

MM/DD/YYYY

Usage with `slotProps.field`

When using slotProps.field to pass props to your field component, the field consumes some props (e.g: shouldRespectLeadingZeros) and forwards the rest to the TextField.

For the props consumed by the field, the behavior should remain exactly the same with both DOM structures.

Both components below will respect the leading zeroes on digit sections:

<DatePicker
  slotProps={{ field: { shouldRespectLeadingZeros: true } }}
  enableAccessibleFieldDOMStructure
/>
<DatePicker
  slotProps={{ field: { shouldRespectLeadingZeros: true } }}
/>

For the props forwarded to the TextField, you can have a look at the next section to see how the migration impact them.

Both components below will render a small size UI:
```
<DatePicker
  slotProps={{ field: { size: 'small' } }}
  enableAccessibleFieldDOMStructure
/>
<DatePicker
  slotProps={{ field: { size: 'small' } }}
/>
```

Usage with `slotProps.textField`

If you are passing props to slotProps.textField, these props will now be received by PickersTextField and should keep working the same way as before.

Both components below will render a small size UI:

<DatePicker
  slotProps={{ textField: { size: 'small' } }}
  enableAccessibleFieldDOMStructure
/>
<DatePicker
  slotProps={{ textField: { size: 'small' } }}
/>

Usage with `slots.field`

If you are passing a custom field component to your pickers, you need to create a new one that is using the accessible DOM structure. This new component will need to use the PickersSectionList component instead of an <input /> HTML element.

You can have a look at the custom PickersTextField to have a concrete example.

Usage with `slots.textField`

If you are passing a custom TextField component to your fields and pickers, you need to create a new one that is using the accessible DOM structure.

You can have a look at the second demo of the Material PickersTextField section to have a concrete example.

Usage with theme

If you are using the theme to customize MuiTextField, you need to pass the same config to MuiPickersTextField:

const theme = createTheme({
  components: {
    MuiTextField: {
      defaultProps: {
        variant: 'outlined',
      },
      styleOverrides: {
        root: {
          '& .MuiInputLabel-outlined.Mui-focused': {
            color: 'red',
          },
        },
      },
    },
    MuiPickersTextField: {
      defaultProps: {
        variant: 'outlined',
      },
      styleOverrides: {
        root: {
          '& .MuiInputLabel-outlined.Mui-focused': {
            color: 'red',
          },
        },
      },
    },
  },
});

If you are using the theme to customize MuiInput, MuiOutlinedInput or MuiFilledInput, you need to pass the same config to MuiPickersInput, MuiPickersOutlinedInput or MuiPickersFilledInput:

const theme = createTheme({
  components: {
    // Replace with `MuiOutlinedInput` or `MuiFilledInput` if needed
    MuiInput: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
    // Replace with `MuiPickersOutlinedInput` or `MuiPickersFilledInput` if needed
    MuiPickersInput: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
  },
});

If you are using the theme to customize MuiInputBase, you need to pass the same config to MuiPickersInputBase:

const theme = createTheme({
  components: {
    MuiInputBase: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
    MuiPickersInputBase: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
  },
});

Advanced

What is a section?

In the field components, the date is divided into several sections, each one responsible for the edition of a date token. For example, if the format passed to the field is MM/DD/YYYY, the field will create 3 sections:

A month section for the token MM
A day section for the token DD
A year section for the token YYYY

Those sections are independent, pressing ArrowUp while focusing the day section will add one day to the date, but it will never change the month or the year.

Control the selected sections

Use the selectedSections and onSelectedSectionsChange props to control which sections are currently being selected.

This prop accepts the following formats:

If a number is provided, the section at this index will be selected.
If "all" is provided, all the sections will be selected.
If an object with a startIndex and endIndex fields are provided, the sections between those two indexes will be selected.
If a string of type FieldSectionType is provided, the first section with that name will be selected.
If null is provided, no section will be selected

Usage with multi input range fields

For multi input range fields, you just have to make sure that the right input is focused before updating the selected section(s). Otherwise, the section(s) might be selected on the wrong input.

start

end

–

Usage with single input range fields

For single input range fields, you won't be able to use the section name to select a single section because each section is present both in the start and in the end date. Instead, you can pass the index of the section using the unstableFieldRef prop to access the full list of sections:

start

end

Clearable behavior

You can use the clearable prop to enable the clearing behavior on a field. You can also add an event handler using the onClear callback prop.

DateField

You can also customize the icon you want to be displayed inside the clear IconButton.

Date Field

Date Range Field

<DateField
  label="Date Field"
  clearable
  slots={{ clearIcon: HighlightOffIcon }}
/>
<SingleInputDateRangeField
  label="Date Range Field"
  clearable
  slots={{ clearIcon: BackspaceIcon }}
/>

<DateField
  label="Date Field"
  clearable
  slots={{ clearIcon: HighlightOffIcon }}
/>
<SingleInputDateRangeField
  label="Date Range Field"
  clearable
  slots={{ clearIcon: BackspaceIcon }}
/>

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.