Skip to content
+

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:

Please fill this field

Press Enter to start editing

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:

Press Enter to start editing

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.

Press Enter to start editing

Use single input fields on range pickers

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

Press Enter to start 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:

Press Enter to start editing

Change the separator of range fields

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

to

Press Enter to start editing

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.

Press Enter to start editing

Usage with Material UI

Using Material TextField

You can import the TextField component to create custom wrappers:

Press Enter to start editing

Using Material PickersTextField

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

MM/DD/YYYY
MM/DD/YYYY
Press Enter to start editing

You can import the PickersTextField component to create custom wrappers:

MM/DD/YYYY
MM/DD/YYYY
Press Enter to start editing

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

MM/DD/YYYY
MM/DD/YYYYMM/DD/YYYY
MM/DD/YYYY
MM/DD/YYYY

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 Button

If you only want to allow the user to pick a value through the views, 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>, // The headless field props
    BaseSingleInputFieldProps<
      Dayjs | null,
      Dayjs,
      FieldSection,
      DateValidationError
    > {} // The DOM field props

interface JoyDateTimeFieldProps
  extends UseDateTimeFieldProps<Dayjs>, // The headless field props
    BaseSingleInputFieldProps<
      Dayjs | null,
      Dayjs,
      FieldSection,
      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.