`, the spacing are instead defined inside the `root` slot of the Month Calendar. ### ⏩ Year Calendar To simplify the theme and class structure, the `` component has been moved inside the Year Calendar component. This change causes a few breaking changes: - The classes from `pickersYearClasses` have been moved inside `yearCalendarClasses`: ```diff -import { pickersYearClasses } from '@mui/x-date-pickers/YearCalendar'; +import { yearCalendarClasses } from '@mui/x-date-pickers/YearCalendar'; -const buttonClassName = pickersYearClasses.monthButton; +const buttonClassName = yearCalendarClasses.button; -const selectedButtonClassName = pickersYearClasses.selected; +const selectedButtonClassName = yearCalendarClasses.selected; -const disabledButtonClassName = pickersYearClasses.disabled; +const disabledButtonClassName = yearCalendarClasses.disabled; ``` - The `yearButton` slot of the `PickersYear` style overrides has been replaced by the `button` slot of the `YearCalendar` theme entry: ```diff const theme = createTheme({ components: { - MuiPickersYear: { + MuiYearCalendar: { styleOverrides: { - yearButton: { + button: { color: 'red', }, }, }, }, }); ``` - The button to render a single year is no longer wrapped in a `

`, the spacing are instead defined inside the `root` slot of the Year Calendar. ### ⏩ Treat partially filled date as `null` in `onChange` Before version `v8.x`, entering a partially filled date in the field would fire `onChange` with an invalid date. The date now remains `null` until fully filled. Here are two concrete examples: #### A user fills a Date Field that has no default value 1. The user enters the month, the rendered value is `01/DD/YYYY`, `onChange` is not fired. 2. The user enters the day, the rendered value is `01/01/YYYY`, `onChange` is not fired. 3. The user enters the year, the rendered value is `01/01/2025`, `onChange` is fired with the new date. #### A user cleans the year of a Date Field and enters a new year 1. The user cleans the year, the rendered value is `01/01/YYYY`, `onChange` is fired with `null`. 2. The user enters a new year, the rendered value is `01/01/2026`, `onChange` is fired with the new date. ### ⏩ Deprecate the `disableOpenPicker` prop The `disableOpenPicker` prop has been deprecated on all Picker components and will be removed in the next major release (v9.0.0). If you only want to allow editing through the field, you can use the [field component](/x/react-date-pickers/fields/) directly: ```diff - + - + - + ``` ```diff - + // If you want a single input for both dates. + // If you want one input for each date. - + // If you want a single input for both dates. + // If you want one input for each date. - + // If you want a single input for both dates. + // If you want one input for each date. ``` :::success Using the field instead of the picker significantly decreases your bundle size since all the view components won't be bundled anymore. ::: ### ⏩ Update default `closeOnSelect` and Action Bar `actions` values The default value of the `closeOnSelect` prop has been updated to `false` for all Picker components, except `` and ``, which still have `closeOnSelect` set to `true`. This change goes hand in hand with the new default `actions` prop value for the `` component. The default value of the `actions` prop has been updated to `['cancel', 'accept']` for all Picker components, except `` and ``. If the updated values do not fit your use case, you can [override them](/x/react-date-pickers/custom-components/#component-props). ## Slots breaking changes ### Slot: `field` - The component passed to the `field` slot no longer receives `InputProps` and `inputProps` props. You now need to manually add the UI to open the picker using the `usePickerContext` hook: ```diff import { unstable_useDateField } from '@mui/x-date-pickers/DateField'; +import { usePickerContext } from '@mui/x-date-pickers/hooks'; function CustomField(props) { + const pickerContext = usePickerContext(); return ( + pickerContext.setOpen((prev) => !prev)} + edge="end" + aria-label={fieldResponse.openPickerAriaLabel} + > + + + + ), + }} /> ); } ``` If you are extracting the `ref` from `InputProps` to pass it to another trigger component, you can replace it with `pickerContext.triggerRef`: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; function CustomField(props) { + const pickerContext = usePickerContext(); return ( ); } ``` If you are using a custom editing behavior, instead of using the `openPickerAriaLabel` property returned by the `useXXXField` hooks, you can generate it manually: ```diff +import { usePickerTranslations } from '@mui/x-date-pickers/hooks'; function CustomField(props) { + const translations = usePickerTranslations(); + const formattedValue = props.value?.isValid() ? value.format('ll') : null; + const ariaLabel = translations.openDatePickerDialogue(formattedValue); return ( ); } ``` - The component passed to the `field` slot no longer receives the `value`, `onChange`, `timezone`, `format`, `disabled`, `className`, `sx`, `label`, `name`, `autoFocus`, `focused` and `readOnly` props. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { value } = props; -const { value } = props; +const { value } = usePickerContext(); -const { onChange } = props; -onChange(dayjs(), { validationError: null }); +const { setValue } = usePickerContext(); -setValue(dayjs(), { validationError: null }); -const { timezone } = props; +const { timezone } = usePickerContext(); -const { format } = props; +const { fieldFormat } = usePickerContext(); -const { disabled } = props; +const { disabled } = usePickerContext(); -const { className } = props; +const { rootClassName } = usePickerContext(); -const { sx } = props; +const { rootSx } = usePickerContext(); -const { label } = props; +const { label } = usePickerContext(); -const { name } = props; +const { name } = usePickerContext(); -const { autoFocus } = props; +const { autoFocus: pickerAutoFocus, open } = usePickerContext(); +const autoFocus = pickerAutoFocus && !open, -const { focused } = props; +const { open } = usePickerContext(); +const focused = open ? true : undefined; -const { readOnly } = props; +const { readOnly } = usePickerContext(); ``` :::success If you are using a hook like `useDateField`, you don't have to do anything, the values from the context are automatically applied. ::: - The component passed to the `field` slot no longer receives a `ref`. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const CustomField = React.forwardRef(function CustomField(props, ref) { - return ; -}); +function CustomField(props) { + const { rootRef } = usePickerContext(); + return ; +} ``` - The component passed to the `field` slot no longer receives the `formatDensity`, `enableAccessibleFieldDOMStructure`, `selectedSections`, `onSelectedSectionsChange` and `inputRef` props. These props, formerly mirroring the picker's props, are no longer exposed. You can manually pass them using `slotProps.field` to keep the same behavior: ```diff ``` If you were not passing those props to the picker, then you can use their default values: - `formatDensity`: `"dense"` - `enableAccessibleFieldDOMStructure`: `true` - `selectedSections`: `undefined` - `onSelectedSectionsChange`: `undefined` - `inputRef`: `undefined` :::success If you are using a hook like `useDateField`, you don't have to do anything, the value from the context are automatically applied. ::: ### Slot: `inputAdornment` - The `position` props passed to the `inputAdornment` slot props no longer sets the position of the opening button. This allows defining the position of the opening and clear buttons independently. You can use the `openPickerButtonPosition` prop instead: ```diff ``` ### ⏩ Slot: `layout` - The `` and `` components must now receive the `ownerState` returned by `usePickerLayout` instead of their props: ```diff -const { toolbar, tabs, content, actionBar } = usePickerLayout(props); +const { toolbar, tabs, content, actionBar, ownerState } = usePickerLayout(props); return ( - - + + ); ``` - The component passed to the `layout` slot no longer receives the `value` prop. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; // This contains a small behavior change. // If the picker receives an invalid date, // the old value equals `null`. // the new value equals the invalid date received. -const { value } = props; +const { value } = usePickerContext(); ``` - The component passed to the `layout` slot no longer receives the `disabled` and `readOnly` props. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { disabled } = props; +const { disabled } = usePickerContext(); -const { readOnly } = props; +const { readOnly } = usePickerContext(); ``` - The component passed to the `layout` slot no longer receives the `isRtl` prop. You can use the `useRtl` hook from `@mui/system` instead: ```diff +import { useRtl } from '@mui/system/RtlProvider'; - const { isRtl } = props; + const isRtl = useRtl(); ``` - The component passed to the `layout` slot no longer receives the `orientation` and `isLandscape` props. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { orientation } = props; +const { orientation } = usePickerContext(); -const { isLandscape } = props; +const { orientation } = usePickerContext(); +const isLandscape = orientation === 'landscape'; ``` - The component passed to the `layout` slot no longer receives the `wrapperVariant` prop. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { wrapperVariant } = props; +const { variant } = usePickerContext(); ``` - The component passed to the `layout` slot no longer receives the `view`, `views` and `onViewChange` props. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { view } = props; +const { view } = usePickerContext(); -const { views } = props; +const { views } = usePickerContext(); -const { onViewChange } = props; -onViewChange('month'); +const { setView } = usePickerContext(); +setView('month'); ``` - The component passed to the `layout` slot no longer receives the `onClear`, `onSetToday`, `onAccept`, `onCancel`, `onOpen`, `onClose` `onDismiss`, `onChange` and `onSelectShortcut` props. You can use the `usePickerActionsContext` or the `usePickerContext` hooks instead: ```diff +import { usePickerActionsContext } from '@mui/x-date-pickers/hooks'; -const { onClear } = props; +const { clearValue } = usePickerActionsContext(); -const { onSetToday } = props; +const { setValueToToday } = usePickerActionsContext(); -const { onAccept } = props; +const { acceptValueChanges } = usePickerActionsContext(); -const { onCancel } = props; +const { cancelValueChanges } = usePickerActionsContext(); -const { onOpen } = props; +const { setOpen } = usePickerActionsContext(); +const onOpen = event => { + event.preventDefault(); + setOpen(true); +} -const { onClose } = props; +const { setOpen } = usePickerActionsContext(); +const onClose = event => { + event.preventDefault(); + setOpen(false); +} // This contains a small behavior change. // If the picker is not controlled and has a default value, // opening it and calling `acceptValueChanges` without any change calls `onAccept` // with the default value. // Whereas before, opening it and calling `onDimiss` without any change // did not call `onAccept`. -const { onDismiss } = props; +const { acceptValueChanges } = usePickerActionsContext(); +const onDismiss = acceptValueChanges -const { onChange } = props; -onChange(dayjs(), 'partial'); -onChange(dayjs(), 'finish'); +const { setValue } = usePickerActionsContext(); +setValue(dayjs(), { changeImportance: 'set' }); +setValue(dayjs(), { changeImportance: 'accept' }); -const { onSelectShortcut } = props; -onSelectShortcut(dayjs(), 'accept', myShortcut); +const { setValue } = usePickerActionsContext(); +setValue(dayjs(), { changeImportance: 'accept', shortcut: myShortcut }); ``` :::success The `usePickerContext` also contain all the actions returned by `usePickerActionsContext`. The only difference is that `usePickerActionsContext` only contains variables with stable references that won't cause a re-render of your component. ::: - The component passed to the `layout` slot no longer receives the `rangePosition` and `onRangePositionChange` on range pickers. You can use the `usePickerRangePositionContext` hook instead: ```diff +import { usePickerRangePositionContext } from '@mui/x-date-pickers-pro/hooks'; -const { rangePosition } = props; +const { rangePosition } = usePickerRangePositionContext(); -const { onRangePositionChange } = props; -onRangePositionChange('start'); +const { setRangePosition } = usePickerRangePositionContext(); +setRangePosition('start'); ``` ### ⏩ Slot: `toolbar` - The component passed to the `toolbar` slot no longer receives the `value` prop. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; // This contains a small behavior change. // If the picker receives an invalid date, // the old value would equal `null`. // the new value would equal the invalid date received. -const { value } = props; +const { value } = usePickerContext(); ``` - The component passed to the `toolbar` slot no longer receives the `disabled` and `readOnly` props. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { disabled } = props; +const { disabled } = usePickerContext(); -const { readOnly } = props; +const { readOnly } = usePickerContext(); ``` - The component passed to the `toolbar` slot no longer receives the `isLandscape` prop. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { isLandscape } = props; +const { orientation } = usePickerContext(); +const isLandscape = orientation === 'landscape'; ``` - The component passed to the `toolbar` slot no longer receives the `view`, `views` and `onViewChange` props. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { view } = props; +const { view } = usePickerContext(); -const { views } = props; +const { views } = usePickerContext(); -const { onViewChange } = props; +const { onViewChange } = usePickerContext(); ``` - The component passed to the `toolbar` slot no longer receives the `onChange` prop. You can use the `usePickerActionsContext` or the `usePickerContext` hooks instead: ```diff +import { usePickerActionsContext } from '@mui/x-date-pickers/hooks'; -const { onChange } = props; -onChange(dayjs(), 'partial'); -onChange(dayjs(), 'finish'); +const { setValue } = usePickerActionsContext(); +setValue(dayjs(), { changeImportance: 'set' }); +setValue(dayjs(), { changeImportance: 'accept' }); ``` :::success The `usePickerContext` also contain all the actions returned by `usePickerActionsContext`. The only difference is that `usePickerActionsContext` only contains variables with stable references that won't cause a re-render of your component. ::: - The component passed to the `toolbar` slot no longer receives the `rangePosition` and `onRangePositionChange` on range pickers, instead you can use the `usePickerRangePositionContext` hook: ```diff +import { usePickerRangePositionContext } from '@mui/x-date-pickers-pro/hooks'; -const { rangePosition } = props; +const { rangePosition } = usePickerRangePositionContext(); -const { onRangePositionChange } = props; -onRangePositionChange('start'); +const { setRangePosition } = usePickerRangePositionContext(); +setRangePosition('start'); ``` ### ⏩ Slot: `tabs` - The component passed to the `tabs` slot no longer receives the `view`, `views` and `onViewChange` props. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { view } = props; +const { view } = usePickerContext(); -const { views } = props; +const { views } = usePickerContext(); -const { onViewChange } = props; +const { onViewChange } = usePickerContext(); ``` - The component passed to the `tabs` slot no longer receives the `rangePosition` and `onRangePositionChange` on range pickers, instead you can use the `usePickerRangePositionContext` hook: ```diff +import { usePickerRangePositionContext } from '@mui/x-date-pickers-pro/hooks'; -const { rangePosition } = props; +const { rangePosition } = usePickerRangePositionContext(); -const { onRangePositionChange } = props; -onRangePositionChange('start'); +const { setRangePosition } = usePickerRangePositionContext(); +setRangePosition('start'); ``` ### ⏩ Slot: `actionBar` - The component passed to the `actionBar` slot no longer receives the `onClear`, `onSetToday`, `onAccept` and `onCancel` props. You can use the `usePickerActionsContext` or the `usePickerContext` hooks instead: ```diff +import { usePickerActionsContext } from '@mui/x-date-pickers/hooks'; -const { onClear } = props; +const { clearValue } = usePickerActionsContext(); -const { onSetToday } = props; +const { setValueToToday } = usePickerActionsContext(); -const { onAccept } = props; +const { acceptValueChanges } = usePickerActionsContext(); -const { onCancel } = props; +const { cancelValueChanges } = usePickerActionsContext(); ``` :::success The `usePickerContext` also contain all the actions returned by `usePickerActionsContext`. The only difference is that `usePickerActionsContext` only contains variables with stable references that won't cause a re-render of your component. ::: ### ⏩ Slot: `shortcuts` - The component passed to the `shortcuts` slot no longer receives the `isLandscape` prop. You can use the `usePickerContext` hook instead: ```diff +import { usePickerContext } from '@mui/x-date-pickers/hooks'; -const { isLandscape } = props; +const { orientation } = usePickerContext(); +const isLandscape = orientation === 'landscape'; ``` - The component passed to the `shortcuts` slot no longer receives the `onChange` prop. You can use the `usePickerActionsContext` or the `usePickerContext` hooks instead: ```diff -const { onChange } = props; -onChange(dayjs(), 'accept', myShortcut); +const { setValue } = usePickerActionsContext(); +setValue(dayjs(), { changeImportance: 'accept', shortcut: myShortcut }); ``` :::success The `usePickerContext` also contain all the actions returned by `usePickerActionsContext`. The only difference is that `usePickerActionsContext` only contains variables with stable references that won't cause a re-render of your component. ::: - The component passed to the `shortcuts` slot no longer receives the `isValid` prop. You can use the `useIsValidValue` hook instead: ```diff +import { useIsValidValue } from '@mui/x-date-pickers/hooks'; -const { isValid } = props; -const isTodayValid = isValid(dayjs()); +const isValidValue = useIsValidValue(); +const isTodayValid = isValidValue(dayjs()); ``` ## ✅ Renamed variables and types The following variables and types have been renamed to have a coherent `Picker` / `Pickers` prefix: - ✅ `usePickersTranslations` ```diff -import { usePickersTranslations } from '@mui/x-date-pickers/hooks'; -import { usePickersTranslations } from '@mui/x-date-pickers'; -import { usePickersTranslations } from '@mui/x-date-pickers-pro'; +import { usePickerTranslations } from '@mui/x-date-pickers/hooks'; +import { usePickerTranslations } from '@mui/x-date-pickers'; +import { usePickerTranslations } from '@mui/x-date-pickers-pro'; -const translations = usePickersTranslations(); +const translations = usePickerTranslations(); ``` - ✅ `usePickersContext` ```diff -import { usePickersContext } from '@mui/x-date-pickers/hooks'; -import { usePickersContext } from '@mui/x-date-pickers'; -import { usePickersContext } from '@mui/x-date-pickers-pro'; +import { usePickerContext } from '@mui/x-date-pickers/hooks'; +import { usePickerContext } from '@mui/x-date-pickers'; +import { usePickerContext } from '@mui/x-date-pickers-pro'; -const pickersContext = usePickersContext(); +const pickerContext = usePickerContext(); ``` - ✅ `FieldValueType` ```diff -import { FieldValueType } from '@mui/x-date-pickers/models'; -import { FieldValueType } from '@mui/x-date-pickers'; -import { FieldValueType } from '@mui/x-date-pickers-pro'; +import { PickerValueType } from '@mui/x-date-pickers/models'; +import { PickerValueType } from '@mui/x-date-pickers'; +import { PickerValueType } from '@mui/x-date-pickers-pro'; ``` - ✅ `RangeFieldSection` ```diff -import { RangeFieldSection } from '@mui/x-date-pickers-pro/models'; -import { RangeFieldSection } from '@mui/x-date-pickers-pro'; +import { FieldRangeSection } from '@mui/x-date-pickers-pro/models'; +import { FieldRangeSection } from '@mui/x-date-pickers-pro'; ``` - ✅ `PickerShortcutChangeImportance` ```diff -import { PickerShortcutChangeImportance } from '@mui/x-date-pickers/PickersShortcuts'; -import { PickerShortcutChangeImportance } from '@mui/x-date-pickers'; -import { PickerShortcutChangeImportance } from '@mui/x-date-pickers-pro'; +import { PickerChangeImportance } from '@mui/x-date-pickers/models'; +import { PickerChangeImportance } from '@mui/x-date-pickers'; +import { PickerChangeImportance } from '@mui/x-date-pickers-pro'; ``` ## ⏩ Hooks breaking changes ### ⏩ `useMultiInputDateRangeField` This hook has been removed in favor of the new `useMultiInputRangeField` hook with an improved DX: ```diff import useSlotProps from '@mui/utils/useSlotProps'; -import { unstable_useMultiInputDateRangeField as useMultiInputDateRangeField } from '@mui/x-date-pickers-pro/MultiInputDateRangeField'; +import { useDateRangeManager } from '@mui/x-date-pickers-pro/managers'; +import { unstable_useMultiInputRangeField as useMultiInputRangeField } from '@mui/x-date-pickers-pro/hooks'; import { useSplitFieldProps } from '@mui/x-date-pickers/hooks'; const DateRangeField(props) { const { internalProps, forwardedProps } = useSplitFieldProps(props, 'date'); const { slotProps, slots } = forwardedProps; const startTextFieldProps = useSlotProps({ elementType: 'input', externalSlotProps: slotProps?.textField, ownerState: { ...props, position: 'start' }, }); const endTextFieldProps = useSlotProps({ elementType: 'input', externalSlotProps: slotProps?.textField, ownerState: { ...props, position: 'end' }, }); - const fieldResponse = useMultiInputDateRangeField({ - sharedProps: internalProps, - startTextFieldProps, - endTextFieldProps, - unstableStartFieldRef: internalProps.unstableStartFieldRef, - unstableEndFieldRef: internalProps.unstableEndFieldRef, - }); + const manager = useDateRangeManager(props); + const fieldResponse = useMultiInputRangeField({ + manager, + internalProps, + startForwardedProps: startTextFieldProps, + endForwardedProps: endTextFieldProps, + }); return (/** Your UI */); } ``` :::success The associated types have also been removed. [Learn how to migrate them](/x/migration/migration-pickers-v7/#removed-types). ::: ### ⏩ `useMultiInputTimeRangeField` This hook has been removed in favor of the new `useMultiInputRangeField` hook with an improved DX: ```diff import useSlotProps from '@mui/utils/useSlotProps'; -import { unstable_useMultiInputTimeRangeField as useMultiInputTimeRangeField } from '@mui/x-date-pickers-pro/MultiInputTimeRangeField'; +import { useTimeRangeManager } from '@mui/x-date-pickers-pro/managers'; +import { unstable_useMultiInputRangeField as useMultiInputRangeField } from '@mui/x-date-pickers-pro/hooks'; import { useSplitFieldProps } from '@mui/x-date-pickers/hooks'; const DateRangeField(props) { const { internalProps, forwardedProps } = useSplitFieldProps(props, 'time'); const { slotProps, slots } = forwardedProps; const startTextFieldProps = useSlotProps({ elementType: 'input', externalSlotProps: slotProps?.textField, ownerState: { ...props, position: 'start' }, }); const endTextFieldProps = useSlotProps({ elementType: 'input', externalSlotProps: slotProps?.textField, ownerState: { ...props, position: 'end' }, }); - const fieldResponse = useMultiInputTimeRangeField({ - sharedProps: internalProps, - startTextFieldProps, - endTextFieldProps, - unstableStartFieldRef: internalProps.unstableStartFieldRef, - unstableEndFieldRef: internalProps.unstableEndFieldRef, - }); + const manager = useTimeRangeManager(props); + const fieldResponse = useMultiInputRangeField({ + manager, + internalProps, + startForwardedProps: startTextFieldProps, + endForwardedProps: endTextFieldProps, + }); return (/** Your UI */); } ``` :::success The associated types have also been removed. [Learn how to migrate them](/x/migration/migration-pickers-v7/#removed-types). ::: ### ⏩ `useMultiInputDateTimeRangeField` This hook has been removed in favor of the new `useMultiInputRangeField` hook with an improved DX: ```diff import useSlotProps from '@mui/utils/useSlotProps'; -import { unstable_useMultiInputDateTimeRangeField as useMultiInputDateTimeRangeField } from '@mui/x-date-pickers-pro/MultiInputDateTimeRangeField'; +import { useDateTimeRangeManager } from '@mui/x-date-pickers-pro/managers'; +import { unstable_useMultiInputRangeField as useMultiInputRangeField } from '@mui/x-date-pickers-pro/hooks'; import { useSplitFieldProps } from '@mui/x-date-pickers/hooks'; const DateRangeField(props) { const { internalProps, forwardedProps } = useSplitFieldProps(props, 'date-time'); const { slotProps, slots } = forwardedProps; const startTextFieldProps = useSlotProps({ elementType: 'input', externalSlotProps: slotProps?.textField, ownerState: { ...props, position: 'start' }, }); const endTextFieldProps = useSlotProps({ elementType: 'input', externalSlotProps: slotProps?.textField, ownerState: { ...props, position: 'end' }, }); - const fieldResponse = useMultiInputDateTimeRangeField({ - sharedProps: internalProps, - startTextFieldProps, - endTextFieldProps, - unstableStartFieldRef: internalProps.unstableStartFieldRef, - unstableEndFieldRef: internalProps.unstableEndFieldRef, - }); + const manager = useDateTimeRangeManager(props); + const fieldResponse = useMultiInputRangeField({ + manager, + internalProps, + startForwardedProps: startTextFieldProps, + endForwardedProps: endTextFieldProps, + }); return (/** Your UI */); } ``` :::success The associated types have also been removed. [Learn how to migrate them](/x/migration/migration-pickers-v7/#removed-types). ::: ### ⏩ `usePickerContext` - The `onOpen` and `onClose` methods have been replaced with a single `setOpen` method. This method no longer takes an event, which was used to prevent the browser default behavior: ```diff const pickerContext = usePickerContext(); - + - + - + ``` If you want to prevent the default behavior, you now have to do it manually: ```diff

{ if (event.key === 'Escape') { - pickerContext.onClose(); + event.preventDefault(); + pickerContext.setOpen(false); } }} /> ``` ### ⏩ `useClearableField` This hook has been removed. The custom field component now receives the `clearable` and `onClear` props. You can remove the `useClearableField` hook from your component and use the new props to conditionally render the clear button: ```diff -import { useClearableField } from '@mui/x-date-pickers-pro/hooks'; function CustomField(props) { const { id, label value, + clearable, + onClear, } = props; - const processedFieldProps = useClearableField({ - ...fieldResponse, - slots, - slotProps, - }); + {clearable && value && ( + + + + )} } ``` ## Typing breaking changes ### Do not pass the date object as a generic The `TDate` generic has been removed from all the types, interfaces, and variables of the `@mui/x-date-pickers` and `@mui/x-date-pickers-pro` packages. If you were passing your date object type as a generic to any element of one of those packages, you can remove it: ```diff - value={value} onChange={onChange} /> + -type FieldComponent = DatePickerSlots['field']; +type FieldComponent = DatePickerSlots['field']; -function CustomDatePicker(props: DatePickerProps) {} +function CustomDatePicker(props: DatePickerProps) {} ``` ### Do not pass the section type as a generic The `TSection` generic of the `FieldRef` type has been replaced with the `TValue` generic: ```diff -const fieldRef = React.useRef>(null); +const fieldRef = React.useRef(null); -const fieldRef = React.useRef>(null); +const fieldRef = React.useRef>(null); ``` ### ⏩ Removed types The following types are no longer exported by `@mui/x-date-pickers` and/or `@mui/x-date-pickers-pro`. :::success If you were using them, you can replace them with the examples below. However, consider looking into your usage to see if you really need those types. ::: - `NonEmptyDateRange` ```ts // When using AdapterDayjs import { Dayjs } from 'dayjs'; type NonEmptyDateRange = [Dayjs, Dayjs]; // When using AdapterLuxon import { DateTime } from 'luxon'; type NonEmptyDateRange = [DateTime, DateTime]; // When using AdapterMoment, AdapterMomentJalaali or AdapterMomentHijri import { Moment } from 'moment'; type NonEmptyDateRange = [Moment, Moment]; // When using AdapterDateFns, AdapterDateFnsV3, AdapterDateFnsJalali or AdapterDateFnsJalaliV3 type NonEmptyDateRange = [Date, Date]; ``` - `UseDateFieldComponentProps` ```ts import { UseDateFieldProps } from '@mui/x-date-pickers/DateField'; import { PickerValidDate } from '@mui/x-date-pickers/models'; type UseDateFieldComponentProps< TDate extends PickerValidDate, TEnableAccessibleFieldDOMStructure extends boolean, TChildProps extends {}, > = Omit< TChildProps, keyof UseDateFieldProps > & UseDateFieldProps; ``` - `UseTimeFieldComponentProps` ```ts import { UseTimeFieldProps } from '@mui/x-date-pickers/TimeField'; import { PickerValidDate } from '@mui/x-date-pickers/models'; type UseTimeFieldComponentProps< TDate extends PickerValidDate, TEnableAccessibleFieldDOMStructure extends boolean, TChildProps extends {}, > = Omit< TChildProps, keyof UseTimeFieldProps > & UseTimeFieldProps; ``` - `UseDateTimeFieldComponentProps` ```ts import { UseDateTimeFieldProps } from '@mui/x-date-pickers/DateTimeField'; import { PickerValidDate } from '@mui/x-date-pickers/models'; type UseDateTimeFieldComponentProps< TDate extends PickerValidDate, TEnableAccessibleFieldDOMStructure extends boolean, TChildProps extends {}, > = Omit< TChildProps, keyof UseDateTimeFieldProps > & UseDateTimeFieldProps; ``` - `UseDateRangeFieldProps` ```ts import { DateRangeManagerFieldInternalProps } from '@mui/x-date-pickers-pro/managers'; interface UseDateRangeFieldProps< TEnableAccessibleFieldDOMStructure extends boolean, > extends Omit< DateRangeManagerFieldInternalProps, 'unstableFieldRef' > {} ``` - `UseMultiInputDateRangeFieldProps` ```ts import { DateRangeManagerFieldInternalProps } from '@mui/x-date-pickers-pro/managers'; import { MultiInputFieldRefs } from '@mui/x-date-pickers-pro/models'; interface UseMultiInputDateRangeFieldProps< TEnableAccessibleFieldDOMStructure extends boolean, > extends DateRangeManagerFieldInternalProps, MultiInputFieldRefs {} ``` - `UseMultiInputDateRangeFieldComponentProps` ```ts import { DateRangeManagerFieldInternalProps } from '@mui/x-date-pickers-pro/managers'; import { MultiInputFieldRefs } from '@mui/x-date-pickers-pro/models'; type UseMultiInputDateRangeFieldComponentProps< TEnableAccessibleFieldDOMStructure extends boolean, TChildProps extends {}, > = Omit< TChildProps, | keyof DateRangeManagerFieldInternalProps | keyof MultiInputFieldRefs > & DateRangeManagerFieldInternalProps & MultiInputFieldRefs; ``` - `UseMultiInputTimeRangeFieldProps` ```ts import { TimeRangeManagerFieldInternalProps } from '@mui/x-date-pickers-pro/managers'; import { MultiInputFieldRefs } from '@mui/x-date-pickers-pro/models'; interface UseMultiInputTimeRangeFieldProps< TEnableAccessibleFieldDOMStructure extends boolean, > extends TimeRangeManagerFieldInternalProps, MultiInputFieldRefs {} ``` - `UseMultiInputTimeRangeFieldComponentProps` ```ts import { TimeRangeManagerFieldInternalProps } from '@mui/x-date-pickers-pro/managers'; import { MultiInputFieldRefs } from '@mui/x-date-pickers-pro/models'; type UseMultiInputTimeRangeFieldComponentProps< TEnableAccessibleFieldDOMStructure extends boolean, TChildProps extends {}, > = Omit< TChildProps, | keyof TimeRangeManagerFieldInternalProps | keyof MultiInputFieldRefs > & TimeRangeManagerFieldInternalProps & MultiInputFieldRefs; ``` - `UseMultiInputDateTimeRangeFieldProps` ```ts import { DateTimeRangeManagerFieldInternalProps } from '@mui/x-date-pickers-pro/managers'; import { MultiInputFieldRefs } from '@mui/x-date-pickers-pro/models'; interface UseMultiInputDateTimeRangeFieldProps< TEnableAccessibleFieldDOMStructure extends boolean, > extends DateTimeRangeManagerFieldInternalProps, MultiInputFieldRefs {} ``` - `UseMultiInputDateTimeRangeFieldComponentProps` ```ts import { DateTimeRangeManagerFieldInternalProps } from '@mui/x-date-pickers-pro/managers'; import { MultiInputFieldRefs } from '@mui/x-date-pickers-pro/models'; type UseMultiInputDateTimeRangeFieldComponentProps< TEnableAccessibleFieldDOMStructure extends boolean, TChildProps extends {}, > = Omit< TChildProps, | keyof DateTimeRangeManagerFieldInternalProps | keyof MultiInputFieldRefs > & DateTimeRangeManagerFieldInternalProps & MultiInputFieldRefs; ``` - `MultiInputRangeFieldClasses` ```ts // If you were using MultiInputRangeFieldClasses for a date range field. import { MultiInputDateRangeFieldClasses } from '@mui/x-date-pickers-pro/MultiInputDateRangeField'; // If you were using MultiInputRangeFieldClasses for a time range field. import { MultiInputTimeRangeFieldClasses } from '@mui/x-date-pickers-pro/MultiInputTimeRangeField'; // If you were using MultiInputRangeFieldClasses for a date time range field. import { MultiInputDateTimeRangeFieldClasses } from '@mui/x-date-pickers-pro/MultiInputDateTimeRangeField'; ``` - `MultiInputRangeFieldClassKey` ```ts // If you were using MultiInputRangeFieldClassKey for a date range field. import { MultiInputRangeFieldClassKey } from '@mui/x-date-pickers-pro/MultiInputDateRangeField'; // If you were using MultiInputRangeFieldClassKey for a time range field. import { MultiInputRangeFieldClassKey } from '@mui/x-date-pickers-pro/MultiInputTimeRangeField'; // If you were using MultiInputRangeFieldClassKey for a date time range field. import { MultiInputRangeFieldClassKey } from '@mui/x-date-pickers-pro/MultiInputDateTimeRangeField'; ``` - `BaseSingleInputFieldProps` - If you are building a custom field for a Date Picker: ```diff -import { - BaseSingleInputFieldProps, - DateValidationError, - FieldSection, -} from '@mui/x-date-pickers/models'; -import { UseDateFieldProps } from '@mui/x-date-pickers/DateField'; +import { DatePickerFieldProps } from '@mui/x-date-pickers/DatePicker'; -interface CustomDateFieldProps - extends UseDateFieldProps, - BaseSingleInputFieldProps< - Dayjs | null, - Dayjs, - FieldSection, - true, - DateValidationError - > {} +interface CustomDateFieldProps extends DatePickerFieldProps {} ``` - If you are building a custom field for a Time Picker: ```diff -import { - BaseSingleInputFieldProps, - TimeValidationError, - FieldSection, -} from '@mui/x-date-pickers/models'; -import { UseTimeFieldProps } from '@mui/x-date-pickers/TimeField'; +import { TimePickerFieldProps } from '@mui/x-date-pickers/TimePicker'; -interface CustomTimeFieldProps - extends UseTimeFieldProps, - BaseSingleInputFieldProps< - Dayjs | null, - Dayjs, - FieldSection, - true, - TimeValidationError - > {} +interface CustomTimeFieldProps extends TimePickerFieldProps {} ``` - If you are building a custom field for a Date Time Picker: ```diff -import { - BaseSingleInputFieldProps, - DateTimeValidationError, - FieldSection, -} from '@mui/x-date-pickers/models'; -import { UseDateTimeFieldProps } from '@mui/x-date-pickers/DateTimeField'; +import { DateTimePickerFieldProps } from '@mui/x-date-pickers/DateTimePicker'; -interface CustomDateTimeFieldProps - extends UseDateTimeFieldProps, - BaseSingleInputFieldProps< - Dayjs | null, - Dayjs, - FieldSection, - true, - DateTimeValidationError - > {} +interface CustomDateTimeFieldProps extends DateTimePickerFieldProps {} ``` - If you are building a custom single input field for a Date Range Picker: ```diff -import { - DateRangeValidationError, - RangeFieldSection, - DateRange, -} from '@mui/x-date-pickers-pro/models'; -import { - UseSingleInputDateRangeFieldProps -} from '@mui/x-date-pickers-pro/SingleInputDateRangeField'; +import { DateRangePickerFieldProps } from '@mui/x-date-pickers-pro/DateRangePicker'; -interface CustomDateRangeFieldProps - extends UseSingleInputDateRangeFieldProps, - BaseSingleInputFieldProps< - DateRange, - Dayjs, - RangeFieldSection, - true, - DateRangeValidationError - > +interface CustomDateRangeFieldProps extends DateRangePickerFieldProps {} ``` - If you are building a custom single input field for a Date Time Range Picker: ```diff -import { - DateTimeRangeValidationError, - RangeFieldSection, - DateRange, -} from '@mui/x-date-pickers-pro/models'; -import { - UseSingleInputDateTimeRangeFieldProps -} from '@mui/x-date-pickers-pro/SingleInputDateTimeRangeField'; +import { + DateTimeRangePickerFieldProps +} from '@mui/x-date-pickers-pro/DateTimeRangePicker'; -interface CustomDateTimeRangeFieldProps - extends UseSingleInputDateTimeRangeFieldProps, - BaseSingleInputFieldProps< - DateRange, - Dayjs, - RangeFieldSection, - true, - DateTimeRangeValidationError - > +interface CustomDateTimeRangeFieldProps extends DateTimeRangePickerFieldProps {} ``` - `BaseMultiInputFieldProps` - If you are building a custom multi input field for a Date Range Picker: ```diff -import { - DateRangeValidationError, - RangeFieldSection, - DateRange, -} from '@mui/x-date-pickers-pro/models'; -import { - UseMultiInputDateRangeFieldProps -} from '@mui/x-date-pickers-pro/MultiInputDateRangeField'; +import { DateRangePickerFieldProps } from '@mui/x-date-pickers-pro/DateRangePicker'; -interface CustomDateRangeFieldProps - extends UseMultiInputDateRangeFieldProps, - BaseMultiInputFieldProps< - DateRange, - Dayjs, - RangeFieldSection, - true, - DateRangeValidationError - > {} +interface CustomDateRangeFieldProps + extends Omit< + DateRangePickerFieldProps, + 'unstableFieldRef' | 'clearable' | 'onClear' + >, + MultiInputFieldRefs {} ``` - If you are building a custom multi input field for a Date Time Range Picker: ```diff -import { - DateTimeRangeValidationError, - RangeFieldSection, - DateRange, -} from '@mui/x-date-pickers-pro/models'; -import { - UseMultiInputDateTimeRangeFieldProps -} from '@mui/x-date-pickers-pro/MultiInputDateTimeRangeField'; +import { + DateTimeRangePickerFieldProps +} from '@mui/x-date-pickers-pro/DateTimeRangePicker'; -interface CustomDateTimeRangeFieldProps - extends UseMultiInputDateTimeRangeFieldProps, - BaseMultiInputFieldProps< - DateRange, - Dayjs, - RangeFieldSection, - false, - DateTimeRangeValidationError - > {} +interface JoyMultiInputDateRangeFieldProps + extends Omit< + DateTimeRangePickerFieldProps, + 'unstableFieldRef' | 'clearable' | 'onClear' + >, + MultiInputFieldRefs {} ``` - `BasePickersTextFieldProps` - If your Text Field is used inside a non-range picker or in a range-picker with a single input field: ```diff -import { BasePickersTextFieldProps } from '@mui/x-date-pickers-pro/models'; +import { BaseSingleInputPickersTextFieldProps } from '@mui/x-date-pickers/models'; interface CustomTextFieldProps - extends BasePickersTextFieldProps {} + extends BaseSingleInputPickersTextFieldProps {} ``` - If your Text Field is used inside a range-picker with a multi input field: ```diff -import { BasePickersTextFieldProps } from '@mui/x-date-pickers-pro/models'; +import { BaseMultiInputPickersTextFieldProps } from '@mui/x-date-pickers-pro/models'; interface CustomTextFieldProps - extends BasePickersTextFieldProps {} + extends BaseMultiInputPickersTextFieldProps {} ``` - `ExportedUseClearableFieldProps` ```ts interface ExportedUseClearableFieldProps { clearable?: boolean; onClear?: React.MouseEventHandler; } ``` - `UseClearableFieldSlots` ```ts interface UseClearableFieldSlots { clearIcon?: React.ElementType; clearButton?: React.ElementType; } ``` - `UseClearableFieldSlotProps` ```ts import { SlotComponentProps } from '@mui/utils/types'; import { FieldOwnerState } from '@mui/x-date-pickers/models'; import { ClearIcon } from '@mui/x-date-pickers/icons'; import IconButton from '@mui/material/IconButton'; interface UseClearableFieldSlotProps { clearIcon?: SlotComponentProps; clearButton?: SlotComponentProps; } ``` - `UseClearableFieldResponse` ```ts type UseClearableFieldResponse = Omit< TFieldProps, 'clearable' | 'onClear' | 'slots' | 'slotProps' >; ``` ## Theme breaking change ### ⏩ `MuiPickersPopper` The theme entry have been renamed to have a coherent `Picker` / `Pickers` prefix: ```diff const theme = createTheme({ components: { - MuiPickersPopper: { + MuiPickerPopper: { styleOverrides: {}, }, }, }); ``` The props that can be overridden have also been limited to the one that did not cause any bugs: ```tsx const theme = createTheme({ components: { MuiPickerPopper: { defaultProps: { // Those are now the props with support for theme default props position: "bottom" classes: { root: "custom-root-class} }, }, }, }); ``` ## ⏩ Stop using `LicenseInfo` from `@mui/x-date-pickers-pro` The `LicenseInfo` object is no longer exported from the `@mui/x-date-pickers-pro` package. You can import it from `@mui/x-license` instead: ```diff -import { LicenseInfo } from '@mui/x-date-pickers-pro'; +import { LicenseInfo } from '@mui/x-license'; LicenseInfo.setLicenseKey('YOUR_LICENSE_KEY'); ``` ## ⏩ Stop passing `utils` and the date object to some translation keys Some translation keys no longer require `utils` and the date object as parameters, but only the formatted value as a string. The keys affected by this changes are: `clockLabelText`, `openDatePickerDialogue` and `openTimePickerDialogue`. If you have customized those translation keys, you have to update them following the examples below: - If you are setting a custom value in a picker component: ```diff -clockLabelText: (view, time, utils) => - `Select ${view}. ${ - time === null || !utils.isValid(time) - ? 'No time selected' - : `Selected time is ${utils.format(time, 'fullTime')}` - }` +clockLabelText: (view, formattedTime) => + `Select ${view}. ${ + formattedTime == null ? 'No time selected' : `Selected time is ${formattedTime}` + }` -openDatePickerDialogue: (value, utils) => - value !== null && utils.isValid(value) - ? `Choose date, selected date is ${utils.format(value, 'fullDate')}` - : 'Choose date', +openDatePickerDialogue: (formattedDate) => + formattedDate ? `Choose date, selected date is ${formattedDate}` : 'Choose date' -openTimePickerDialogue: (value, utils) => - value !== null && utils.isValid(value) - ? `Choose time, selected time is ${utils.format(value, 'fullTime')}` - : 'Choose time', +openTimePickerDialogue: (formattedTime) => + formattedTime ? `Choose time, selected time is ${formattedTime}` : 'Choose time' ``` - If you are setting a custom value in the `LocalizationProvider`: ```diff - `Select ${view}. ${ - time === null || !utils.isValid(time) - ? 'No time selected' - : `Selected time is ${utils.format(time, 'fullTime')}` - }` + clockLabelText: (view, formattedTime) => + `Select ${view}. ${ + formattedTime == null ? 'No time selected' : `Selected time is ${formattedTime}` + }` - openDatePickerDialogue: (value, utils) => - value !== null && utils.isValid(value) - ? `Choose date, selected date is ${utils.format(value, 'fullDate')}` - : 'Choose date', + openDatePickerDialogue: (formattedDate) => + formattedDate ? `Choose date, selected date is ${formattedDate}` : 'Choose date' - openTimePickerDialogue: (value, utils) => - value !== null && utils.isValid(value) - ? `Choose time, selected time is ${utils.format(value, 'fullTime')}` - : 'Choose time', + openTimePickerDialogue: (formattedTime) => + formattedTime ? `Choose time, selected time is ${formattedTime}` : 'Choose time' }} > ``` - If you using this translation key in a custom component: ```diff const translations = usePickerTranslations(); -const clockLabelText = translations.clockLabelText( - view, - value, - {} as any, - value == null ? null : value.format('hh:mm:ss') -); +const clockLabelText = translations.clockLabelText( + view, + value == null ? null : value.format('hh:mm:ss') +); -const openDatePickerDialogue = translations.openDatePickerDialogue( - value, - {} as any, - value == null ? null : value.format('MM/DD/YYY') -); +const openDatePickerDialogue = translations.openDatePickerDialogue( + value == null ? null : value.format('MM/DD/YYY') +); -const openTimePickerDialogue = translations.openTimePickerDialogue( - value, - {} as any, - value == null ? null : value.format('hh:mm:ss') -); +const openTimePickerDialogue = translations.openTimePickerDialogue( + value == null ? null : value.format('hh:mm:ss') +); ``` ## ⏩ Remove unused adapter formats The following unused formats have been removed from the adapters and can no longer be overridden via the `dateFormats` prop on the `` component: - `fullTime` - please use `fullTime12h` and `fullTime24h` instead: ```diff ``` - `keyboardDateTime` - please use `keyboardDateTime12h` and `keyboardDateTime24h` instead: ```diff ```