Migration from v8 to v9

This guide describes the changes needed to migrate the Date and Time Pickers from v8 to v9.

Introduction

This is a reference guide for upgrading @mui/x-date-pickers from v8 to v9.

Start using the new release

In package.json, change the version of the date pickers package to next.

-"@mui/x-date-pickers": "8.x.x",
+"@mui/x-date-pickers": "next",

-"@mui/x-date-pickers-pro": "8.x.x",
+"@mui/x-date-pickers-pro": "next",

Since v9 is a major release, it contains changes that affect the public API. These changes were done for consistency, improved stability and to make room for new features. Described below are the steps needed to migrate from v8 to v9.

Slots breaking changes

Dialog slot

The dialog slot no longer receives the deprecated TransitionComponent, TransitionProps, and PaperProps props. If you were passing a custom dialog slot, you need to update it to use slots and slotProps instead:

 function CustomDialog({
-  TransitionComponent,
-  TransitionProps,
-  PaperProps,
+  slots,
+  slotProps,
   ...props
 }) {
   // …your custom dialog implementation
 }

 <MobileDatePicker slots={{ dialog: CustomDialog }} />

Fields breaking changes

Renamed fieldRef props

The unstableFieldRef, unstableStartFieldRef, and unstableEndFieldRef props have been renamed to fieldRef, startFieldRef, and endFieldRef respectively. For Picker components, fieldRef should now be passed through the slotProps.field.fieldRef prop.

// Before
<DateField unstableFieldRef={fieldRef} />
<DatePicker slotProps={{ field: { unstableFieldRef: fieldRef } }} />

// After
<DateField fieldRef={fieldRef} />
<DatePicker slotProps={{ field: { fieldRef: fieldRef } }} />

const CustomField = (props: MultiInputDateRangeFieldProps<true>) => (
  <MultiInputDateRangeField
    {...props}
    startFieldRef={startFieldRef}
    endFieldRef={endFieldRef}
  />
);

<DateRangePicker slots={{ field: CustomField }} />;

New clearValue() method on FieldRef

The FieldRef object now includes a clearValue() method to programmatically clear the field's value.

const fieldRef = React.useRef<FieldRef<PickerValue>>(null);

// ...

<DateField fieldRef={fieldRef} />;

// ...

fieldRef.current?.clearValue();

Codemod

The rename-field-ref codemod can be used to automatically apply these changes to your codebase.

npx @mui/x-codemod@next v9.0.0/pickers/rename-field-ref <path>