` heading element.
This change may affect customizations relying on the previous DOM structure and CSS specificity.
Additionally, the default heading element might conflict with existing heading structures on your page.
If your styles or DOM manipulations depend on the old structure, you will need to update them to accommodate the new heading element.
If the default heading element conflicts with your existing structure, you can change the heading element using the `slotProps.heading.component` prop.
```jsx
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse malesuada
lacus ex, sit amet blandit leo lobortis eget.
```
#### Summary as a button (from v6.3.0)
- The Accordion Summary HTML structure has been updated to fix invalid HTML introduced by wrapping it with a heading shown above:
- The root element is now a `button`.
- Summary content and the icon wrapper are rendered as `span`.
- Developers using the previous `div` element for styling in the `AccordionSummary` should update their styling. Additionally, those using `Typography` for text, which defaults to rendering a `p` tag, should replace it with a `span`. You can use the `component` prop to replace the HTML tag (`
` to adhere to [the WAI-ARIA spec](https://www.w3.org/TR/wai-aria-1.2/#separator). You might need to adjust your styles accordingly if you are targeting `hr` tags in your CSS.
```diff
-import Divider from '@mui/material/Divider';
+import Divider, { dividerClasses } from '@mui/material/Divider';
const Main = styled.main({
- '& hr': {
+ [`& .${dividerClasses.root}`]: {
marginTop: '16px',
},
});
```
### Grid2
The `Grid2` (previously `Unstable_Grid2`) was updated and stabilized:
- The previous size (`xs`, `sm`, `md`, ...) and offset (`xsOffset`, `smOffset`, `mdOffset`, ...) props, which were named after the theme's breakpoints, were replaced with the `size` and `offset` props.
- The spacing mechanism was reworked to use the `gap` CSS property.
This brings some breaking changes described in the following sections.
#### Unstable prefix removed
The `Grid2` component API was stabilized, so its import no longer contains the `Unstable_` prefix:
```diff
-import { Unstable_Grid2 as Grid2 } from '@mui/material';
+import { Grid2 } from '@mui/material';
```
```diff
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
```
#### Size and offset props renamed
In v5, the size and offset props were named to correspond with the theme's breakpoints.
For the default theme, these were:
- Size: `xs`, `sm`, `md`, `lg`, `xl`
- Offset: `xsOffset`, `smOffset`, `mdOffset`, `lgOffset`, `xlOffset`
In v6, these props are renamed to `size` and `offset`:
```diff
```
If the size or offset is the same for all breakpoints, then you can use a single value:
```diff
-
+
```
Additionally, the `true` value for the `size` prop was renamed to `"grow"`:
```diff
-
+
```
Use this codemod to migrate your project to the new `size` and `offset` props:
```bash
npx @mui/codemod@latest v6.0.0/grid-v2-props
```
:::warning
You need to modify the import from `@mui/material/Unstable_Grid2` to `@mui/material/Grid2` before running the codemod.
:::
##### Using custom breakpoints
The usage described above also applies to custom breakpoints:
```diff
-
+
```
You can use the same codemod for custom breakpoints by providing the breakpoints as an argument:
```bash
npx @mui/codemod@latest v6.0.0/grid-v2-props --jscodeshift='--muiBreakpoints=mobile,desktop'
```
#### disableEqualOverflow prop removed
In v5, the Grid overflowed its parent.
In v6, the Grid is correctly contained within its parent's padding:
This eliminates the need for the `disableEqualOverflow` prop:
```diff
-
+
```
#### Grid item spacing change
In v5, Grid items included spacing in their boxes.
In v6, Grid items no longer include spacing in their boxes by using the [CSS gap property](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/gap).
Note that the item position doesn't change.
:::warning
These updates may lead to unexpected changes to your app's layout.
Still, we strongly recommend adopting this new behavior rather than trying to replicate the old pattern, as the new version is more predictable and modern.
:::
#### Container width
The updated Grid component doesn't grow to the full width of the container by default.
If you need the grid to grow to the full width, you can use the `sx` prop:
```diff
-
+
// alternatively, if the Grid's parent is a flex container:
-
+
```
### ListItem
`ListItem`'s props `autoFocus`, `button`, `disabled`, and `selected`, deprecated in v5, have been removed. To replace the `button` prop, use `ListItemButton` instead. The other removed props are available in the `ListItemButton` component as well.
```diff
-
```
As the `ListItem` no longer supports these props, the class names related to these props were removed. You should use the `listItemButtonClasses` object instead.
```diff
-import { listItemClasses } from '@mui/material/ListItem';
+import { listItemButtonClasses } from '@mui/material/ListItemButton';
-listItemClasses.button
+listItemButtonClasses.root
-listItemClasses.focusVisible
+listItemButtonClasses.focusVisible
-listItemClasses.disabled
+listItemButtonClasses.disabled
-listItemClasses.selected
+listItemButtonClasses.selected
```
### Button with Loading State
As of `@mui/material` **v6.4.0**, the `LoadingButton` from Lab has been removed. Loading functionality is now part of the standard `Button` component. Update your import as follows:
```diff
-import { LoadingButton } from '@mui/lab';
+import { Button } from '@mui/material';
```
```diff
-import LoadingButton from '@mui/lab/LoadingButton';
+import Button from '@mui/material/Button';
```
For more details, see the [Loading section](/material-ui/react-button/#loading-2) in the [Material UI `Button` documentation](/material-ui/react-button/).
### Typography
The `color` prop in the `Typography` component is not a [system prop](https://mui.com/system/properties/) anymore. You can use the `sx` prop instead:
```diff
- theme.palette.primary.main}>
+ theme.palette.primary.main }}>
```
:::info
System props have been deprecated in favor of the `sx` prop. Check the [migration guide](/material-ui/migration/migrating-from-deprecated-apis/#system-props) for more information.
:::
You still can access some theme colors directly using the `color` prop. Check the [Typography component API page](/material-ui/api/typography/#typography-prop-color) for the whole list of colors.
```jsx
Secondary text
```
### useMediaQuery types
The following deprecated types are removed in v6:
- `MuiMediaQueryList`: use `MediaQueryList` (from lib.dom.d.ts) instead.
- `MuiMediaQueryListEvent`: use `MediaQueryListEvent` (from lib.dom.d.ts) instead.
- `MuiMediaQueryListListener`: use `(event: MediaQueryListEvent) => void` instead.
## Breaking changes affecting testing
### Ripple effect
The ripple effect's performance has been improved in v6.
Because of this, you might need to update tests involving components with the ripple effect.
If you are using `fireEvent` from `@testing-library/react` to simulate user interactions, you will need to wrap these inside `act` and `await` to avoid React warnings:
```diff
- fireEvent.click(button);
+ await act(async () => fireEvent.mouseDown(button));
```
The components affected by this change are:
- All buttons
- Checkbox
- Chip
- Radio Group
- Switch
- Tabs
## Breaking changes affecting types
### Box
The `component` prop has been removed from the `BoxOwnProps` as it is already included in the `Box` type.
This might affect your code if you are using the `styled` function with the `Box` component.
If this is the case, use a `div` element instead of `Box`:
```diff
-const StyledBox = styled(Box)`
+const StyledDiv = styled('div')`
color: white;
`;
```
This yields the same end result.
If this doesn't work for you, you can also cast the `styled` returned value to `typeof Box`:
```diff
const StyledBox = styled(Box)`
color: white;
-`;
+` as typeof Box;
```
## Stabilized APIs
### CssVarsProvider and extendTheme
The `CssVarsProvider` and `extendTheme` APIs are now stable.
If you're already using them in v5 you can now drop the experimental prefix:
```diff
-import { experimental_extendTheme as extendTheme, Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
+import { extendTheme, CssVarsProvider } from '@mui/material/styles';
```
See [CSS theme variables](/material-ui/customization/css-theme-variables/overview/) for more details about working with these APIs.
### Color mode theme utility
Material UI v6 introduces a new utility for adding styles to specific color modes called `theme.applyStyles()`, designed to replace `theme.palette.mode` when applying light or dark styles:
```diff
const MyComponent = styled('button')(({ theme }) => ({
padding: '0.5rem 1rem',
border: '1px solid,
- borderColor: theme.palette.mode === 'dark' ? '#fff' : '#000',
+ borderColor: '#000',
+ ...theme.applyStyles('dark', {
+ borderColor: '#fff',
+ })
}))
```
Use these codemods to migrate your project to `theme.applyStyles()`:
```bash
npx @mui/codemod@latest v6.0.0/styled
npx @mui/codemod@latest v6.0.0/sx-prop
npx @mui/codemod@latest v6.0.0/theme-v6
```
:::info
If you have a custom theme, run `v6.0.0/theme-v6` against the file that contains your custom `styleOverrides`.
Otherwise you can ignore this codemod.
:::
## Deprecations
It is not required to immediately go through the deprecations in order to use Material UI v6.
You can do it at your own pace by checking out the [deprecations page](/material-ui/migration/migrating-from-deprecated-apis/).
Those deprecations will be removed in the next major version.
## Pigment CSS integration (optional)
Once you've finished upgrading your app to v6, you'll be ready to start [migrating to Pigment CSS](/material-ui/migration/migrating-to-pigment-css/) for RSC support and a smaller bundle size.
` to adhere to [the WAI-ARIA spec](https://www.w3.org/TR/wai-aria-1.2/#separator). You might need to adjust your styles accordingly if you are targeting `hr` tags in your CSS. ```diff -import Divider from '@mui/material/Divider'; +import Divider, { dividerClasses } from '@mui/material/Divider'; const Main = styled.main({ - '& hr': { + [`& .${dividerClasses.root}`]: { marginTop: '16px', }, }); ``` ### Grid2 The `Grid2` (previously `Unstable_Grid2`) was updated and stabilized: - The previous size (`xs`, `sm`, `md`, ...) and offset (`xsOffset`, `smOffset`, `mdOffset`, ...) props, which were named after the theme's breakpoints, were replaced with the `size` and `offset` props. - The spacing mechanism was reworked to use the `gap` CSS property. This brings some breaking changes described in the following sections. #### Unstable prefix removed The `Grid2` component API was stabilized, so its import no longer contains the `Unstable_` prefix: ```diff -import { Unstable_Grid2 as Grid2 } from '@mui/material'; +import { Grid2 } from '@mui/material'; ``` ```diff -import Grid from '@mui/material/Unstable_Grid2'; +import Grid from '@mui/material/Grid2'; ``` #### Size and offset props renamed In v5, the size and offset props were named to correspond with the theme's breakpoints. For the default theme, these were: - Size: `xs`, `sm`, `md`, `lg`, `xl` - Offset: `xsOffset`, `smOffset`, `mdOffset`, `lgOffset`, `xlOffset` In v6, these props are renamed to `size` and `offset`: ```diff
This eliminates the need for the `disableEqualOverflow` prop:
```diff
-
:::warning
These updates may lead to unexpected changes to your app's layout.
Still, we strongly recommend adopting this new behavior rather than trying to replicate the old pattern, as the new version is more predictable and modern.
:::
#### Container width
The updated Grid component doesn't grow to the full width of the container by default.
If you need the grid to grow to the full width, you can use the `sx` prop:
```diff
-