Custom slots and subcomponents

Learn how to override the default DOM structure of the Date and Time Pickers.

Overriding slot components

You can override the internal elements of the component (known as "slots") using the slots prop.

Use the slotProps prop if you need to pass additional props to a component slot.

As an example, you could override the ActionBar and pass additional props to the custom component as shown below:

<DatePicker
  {...otherProps}
  slots={{
    // Override default <ActionBar /> with a custom one
    actionBar: CustomActionBar,
  }}
  slotProps={{
    // pass props `actions={['clear']}` to the actionBar slot
    actionBar: { actions: ['clear'] },
  }}
/>

To modify components position, have a look at the custom layout docs page.

Recommended usage

The first two examples below are buggy because the toolbar will remount after each keystroke, leading to a loss of focus.

// ❌ The `toolbar` slot is re-defined each time the parent component renders,
// causing the component to remount.
function MyApp() {
  return (
    <DatePicker
      slots={{
        toolbar: () => (
          <input value={name} onChange={(event) => setName(event.target.value)} />
        ),
      }}
    />
  );
}

// ❌ The `toolbar` slot is re-defined each time `name` is updated,
// causing the component to remount.
function MyApp() {
  const [name, setName] = React.useState('');

  const CustomToolbar = React.useCallback(
    () => <input value={name} onChange={(event) => setName(event.target.value)} />,
    [name],
  );

  return <DatePicker slots={{ toolbar: CustomToolbar }} />;
}

// ✅ The `toolbar` slot is defined only once, it will never remount.
const CustomActionBar = ({ name, setName }) => (
  <input value={name} onChange={(event) => setName(event.target.value)} />
);

function MyApp() {
  const [name, setName] = React.useState('');
  return (
    <DatePicker
      slots={{ toolbar: CustomToolbar }}
      slotProps={{ toolbar: { name, setName } }}
    />
  );
}

Action bar

Component props

The action bar is available on all picker components. By default, it contains no action on desktop, and the actions Cancel and Accept on mobile.

You can override the actions displayed by passing the actions prop to the actionBar within slotProps, as shown here:

<DatePicker
  slotProps={{
    // The actions will be the same between desktop and mobile
    actionBar: {
      actions: ['clear'],
    },
    // The actions will be different between desktop and mobile
    actionBar: ({ wrapperVariant }) => ({
      actions: wrapperVariant === 'desktop' ? [] : ['clear'],
    }),
  }}
/>

In the example below, the action bar contains only one button, which resets the selection to today's date:

Available actions

The built-in ActionBar component supports four different actions:

Component

If you need to customize the date picker beyond the options described above, you can provide a custom component. This can be used in combination with slotProps.

In the example below, the actions are the same as in the section above, but they are rendered inside a menu:

Tabs

The tabs are available on all date time picker components. It allows to switch between date and time interfaces.

Component props

You can override the icons displayed by passing props to the tabs within slotProps, as shown here:

<DateTimePicker
  slotProps={{
    tabs: {
      dateIcon: <LightModeIcon />,
      timeIcon: <AcUnitIcon />,
    },
  }}
/>

By default, the tabs are hidden on desktop, and visible on mobile. This behavior can be overridden by setting the hidden prop:

<DateTimePicker
  slotProps={{
    tabs: {
      hidden: false,
    },
  }}
/>

Component

If you need to customize the date time picker beyond the options described above, you can provide a custom component. This can be used in combination with slotProps.

In the example below, the tabs are using different icons and have an additional component:

Toolbar

The toolbar is available on all date time picker components. It displays the current values and allows to switch between different views.

Component props

You can customize how the toolbar displays the current value with toolbarFormat. By default empty values are replaced by __. This can be modified by using toolbarPlaceholder props.

By default, the toolbar is hidden on desktop, and visible on mobile. This behavior can be overridden by setting the hidden prop:

<DatePicker
  slotProps={{
    toolbar: {
      // Customize value display
      toolbarFormat: 'YYYY',
      // Change what is displayed given an empty value
      toolbarPlaceholder: '??',
      // Show the toolbar
      hidden: false,
    },
  }}
/>

Component

Each component comes with its own toolbar (DatePickerToolbar, TimePickerToolbar, and DateTimePickerToolbar) that you can reuse and customize.

Arrow switcher

The following slots let you customize how to render the buttons and icons for an arrow switcher component—the component to navigate to the "Previous" and "Next" steps of the picker: PreviousIconButton, NextIconButton, LeftArrowIcon, RightArrowIcon.

Component props

You can pass props to the icons and buttons as shown below:

Component

You can pass custom components—to replace the icons, for example—as shown below:

Shortcuts

You can add shortcuts to every pickers. For more information, check the dedicated page.

API

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

• <DatePickerToolbar />
• <DateTimePickerTabs />
• <DateTimePickerToolbar />
• <PickersActionBar />
• <PickersCalendarHeader />
• <PickersShortcuts />
• <TimePickerToolbar />