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 CustomToolbar = ({ 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:
Action | Behavior |
---|---|
accept |
Accept the current value and close the picker view |
cancel |
Reset to the last accepted date and close the picker view |
clear |
Reset to the empty value and close the picker view |
today |
Reset to today's date (and time if relevant) and close the picker view |
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 switching 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.
Calendar header
The calendar header is available on any component that renders a calendar to select a date or a range of dates. It allows the user to navigate through months and to switch to the month and year views when available.
Component props
You can pass props to the calendar header as shown below:
Component
You can pass a custom component to replace the header, as shown below:
June 2024
When used with a date range component, you receive three additional props to let you handle scenarios where multiple months are rendered:
calendars
: The number of calendars renderedmonth
: The month used for the header being renderedmonthIndex
: The index of the month used for the header being rendered
The demo below shows how to navigate the months two by two:
June 2024
July 2024
Year button
This button allows users to change the selected year in the year
view.
Component props
You can pass props to the year button as shown below:
Component
You can pass a custom component to replace the year button, as shown below:
Month button
This button allows users to change the selected month in the month
view.
Component props
You can pass props to the month button as shown below:
Component
You can pass a custom component to replace the month button, as shown below:
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, as shown below:
Shortcuts
You can add shortcuts to every Picker component. 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.