Custom field

The Date and Time Pickers let you customize the field by passing props or custom components.

Customize the default field

Customize the TextField

You can use the textField slot to pass custom props to the TextField:

Customize the separator of multi input range fields

You can use the fieldSeparator slot to pass custom props to the Typography rendered between the two TextField:

Customize the start and end fields differently

You can pass conditional props to the textField slot to customize the input styling based on the position.

Use single input fields on range pickers

You can pass the single input fields to the range picker to use it for keyboard editing:

If you want to create a wrapper around the field, make sure to set the fieldType static property to 'single-input'. Otherwise, the picker won't know your field is a single input one and use the multi input event listeners:

You can manually add an endAdornment if you want your range picker to look exactly like on a simple picker:

Change the separator of range fields

You can use the dateSeparator prop to change the separator rendered between the start and end dates:

Change the format density

You can control the field format spacing using the formatDensity prop. Setting formatDensity to "spacious" will add a space before and after each /, - and . character.

Usage with Material UI

Using Material TextField

You can import the TextField component to create custom wrappers:

Using Material PickersTextField

Pass the enableAccessibleFieldDOMStructure to any Field or Picker component to enable the accessible DOM structure:

You can import the PickersTextField component to create custom wrappers:

Usage with Joy UI

Using Joy Input

You can use the Joy UI components instead of the Material UI ones:

Using Joy PickersTextField

Usage with an unstyled input

Using the browser input

Using custom PickersTextField

Usage with another UI

Using an Autocomplete

If your user can only select a value in a small list of available dates, you can replace the field with an Autocomplete listing those dates:

Using a read-only TextField

If you want users to select a value exclusively through the views but you still want the UI to look like a TextField, you can replace the field with a read-only TextField:

Using a Button

If you want users to select a value exclusively through the views and you don't want the UI to look like a TextField, you can replace the field with a Button:

The same can be applied to the DateRangePicker:

How to build a custom field

The main challenge when building a custom field, is to make sure that all the relevant props passed by the pickers are correctly handled.

On the examples below, you can see that the typing of the props received by a custom field always have the same shape:

interface JoyDateFieldProps
  extends UseDateFieldProps<Dayjs, false>, // The headless field props
    BaseSingleInputFieldProps<
      Dayjs | null,
      Dayjs,
      FieldSection,
      false, // `true` for `enableAccessibleFieldDOMStructure`
      DateValidationError
    > {} // The DOM field props

interface JoyDateTimeFieldProps
  extends UseDateTimeFieldProps<Dayjs, false>, // The headless field props
    BaseSingleInputFieldProps<
      Dayjs | null,
      Dayjs,
      FieldSection,
      false, // `true` for `enableAccessibleFieldDOMStructure`
      DateTimeValidationError
    > {} // The DOM field props

The headless field props

This interface depends on which type of field you are building (UseDateField for date field, UseTimeField for a time field, UseDateRangeFieldProps for a date range field, etc.).

It contains:

• the basic props common to all the fields (value, onChange, format, readOnly, etc.)
• the validation props for this type of field (minDate, maxDate, shouldDisableDate, etc.)

The DOM field props

This interface contains the props the pickers pass to its field in order to customize the rendering.

These props are shaped to be received by the built-in fields which are using the TextField from @mui/material. When used with another type of input (or no input at all), you will have to manually pass them to the relevant component.

You can have a look at the BaseSingleInputFieldProps and BaseMultiInputFieldProps interfaces to know exactly what those interfaces contain.

API

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

• <PickersSectionList />
• <PickersTextField />