Upgrade to v9

This guide explains how to upgrade from Material UI v7 to v9.

Start using the alpha release

In the package.json file, change the package version from latest to next.

-"@mui/material": "latest",
+"@mui/material": "next",

Using next ensures your project always uses the latest v9 pre-releases. Alternatively, you can also target and fix it to a specific version, for example, 9.0.0-alpha.0.

Breaking changes

Since v9 is a new major release, it contains some changes that affect the public API. The steps you need to take to migrate from Material UI v7 to v9 are described below.

Dialog & Modal

The disableEscapeKeyDown prop has been removed. The same behavior could be achieved by checking the value of the reason argument in onClose:

  const [open, setOpen] = React.useState(true);
- const handleClose = () => {
-   setOpen(false);
- };
+ const handleClose = (_event: React.SyntheticEvent<unknown>, reason: string) => {
+   if (reason !== 'escapeKeyDown') {
+     setOpen(false);
+   }
+ };
  return (
-  <Dialog open={open} disableEscapeKeyDown onClose={handleClose}>
+  <Dialog open={open} onClose={handleClose}>
    {/* ... */}
  </Dialog>
  );

The Modal change is the same.

ButtonBase

Click event propagation from Enter and Spacebar

When sending Enter and Spacebar keys on the ButtonBase or components that are composed from ButtonBase, the click event now bubbles to their ancestors.

Also, the event passed to the onClick prop is a MouseEvent instead of the KeyboardEvent captured in the ButtonBase keyboard handlers. This is actually the expected behavior.

Autocomplete

Listbox toggle on right click

The listbox does not toggle anymore when using right click on the input. The left click toggle behavior remains unchanged.

freeSolo type related changes

When the freeSolo prop is passed as true, the getOptionLabel and isOptionEqualToValue props accept string as well for their option and, respectively, value arguments:

- isOptionEqualToValue?: (option: Value, value: Value) => boolean;
+ isOptionEqualToValue?: (
+  option: Value,
+  value: AutocompleteValueOrFreeSoloValueMapping<Value, FreeSolo>,
+ ) => boolean;

- getOptionLabel?: (option: Value | AutocompleteFreeSoloValueMapping<FreeSolo>) => string;
+ getOptionLabel?: (option: AutocompleteValueOrFreeSoloValueMapping<Value, FreeSolo>) => string;

For reference:

type AutocompleteFreeSoloValueMapping<FreeSolo> = FreeSolo extends true
  ? string
  : never;

type AutocompleteValueOrFreeSoloValueMapping<Value, FreeSolo> = FreeSolo extends true
  ? Value | string
  : Value;