` elements instead of `
`. Update any CSS selectors that target the `hr` tag specifically:
```css
/* v5 - No longer matches */
.MuiDivider-vertical hr { ... }
/* v6 - Use the root class instead */
.MuiDivider-root.MuiDivider-vertical { ... }
```
### Chip Focus Retention Behavior
The `Chip` component now retains focus when the **Esc** key is pressed, whereas v5 blurred the component. If your application logic depends on the previous blur behavior, implement a custom `onKeyUp` handler to manually blur the element.
### Autocomplete onInputChange Reason Values
The `onInputChange` callback in `Autocomplete` now receives additional `reason` values: `"blur"`, `"selectOption"`, and `"removeOption"`. Update your event handlers to account for these new cases:
```tsx
{
if (reason === 'blur' || reason === 'selectOption') {
// Handle new v6 reasons
}
}}
/>
```
## Infrastructure and Type System Changes
Material-UI v6 migration requires updates to your build configuration and type definitions.
### UMD Bundle Removal
The UMD bundle is no longer distributed. Applications using UMD must switch to ESM-based imports or CDN alternatives like [`esm.sh`](https://github.com/mui/material-ui/blob/main/esm.sh). This change affects how you load the library in browser environments without a bundler.
### Typography Color Prop Removal
The `color` prop is no longer a system prop on `Typography`. Custom colors must now be applied via the `sx` prop:
```tsx
import Typography from '@mui/material/Typography';
// v5 - Removed
// v6 - Correct approach
theme.palette.primary.main }}>
```
### Box Component Prop Restriction
The `component` prop has been removed from `BoxOwnProps` type definitions. When extending or styling `Box`, use a native element wrapper or type casting as described in the migration guide.
### useMediaQuery Type Cleanup
Deprecated type aliases (`MuiMediaQueryList`, `MuiMediaQueryListEvent`, `MuiMediaQueryListListener`) have been removed from the `useMediaQuery` hook. Use standard DOM types (`MediaQueryList`, `MediaQueryListEvent`) instead.
### CssVarsProvider Stabilization
The experimental prefixes have been dropped from `CssVarsProvider` and `extendTheme`. Import these utilities directly without the `experimental_` prefix:
```tsx
import { CssVarsProvider, extendTheme } from '@mui/material/styles';
```
## Theming and Testing Adjustments
### Color-Mode Utility Replacement
The `theme.palette.mode` property usage for conditional styling is replaced by the `theme.applyStyles()` method. Update your theme overrides:
```tsx
// v5 - Deprecated pattern
sx={{
color: theme.palette.mode === 'dark' ? '#fff' : '#000',
}}
// v6 - Modern approach
sx={{
...theme.applyStyles('dark', { color: '#fff' }),
...theme.applyStyles('light', { color: '#000' }),
}}
```
The codemod at [`packages/mui-codemod/src/v6.0.0/theme-v6/theme-v6.js`](https://github.com/mui/material-ui/blob/main/packages/mui-codemod/src/v6.0.0/theme-v6/theme-v6.js) handles this conversion automatically:
```bash
npx @mui/codemod v6.0.0/theme-v6
```
### Ripple Effect Testing Requirements
Performance optimizations to the ripple effect require updates to your test suites. Interaction calls that fire events on buttons, checkboxes, chips, and other ripple-enabled components must now be wrapped in `act` and awaited:
```tsx
import { act } from 'react-dom/test-utils';
await act(async () => {
fireEvent.click(button);
});
```
## Automating Migration with Codemods
The `mui/material-ui` repository provides three primary codemods to streamline your Material-UI v6 migration:
1. **`grid-v2-props`** ([`packages/mui-codemod/src/v6.0.0/grid-v2-props/grid-v2-props.js`](https://github.com/mui/material-ui/blob/main/packages/mui-codemod/src/v6.0.0/grid-v2-props/grid-v2-props.js)) - Updates Grid2 imports and converts breakpoint props to the new object syntax.
2. **`list-item-button-prop`** ([`packages/mui-codemod/src/v6.0.0/list-item-button-prop/list-item-button-prop.js`](https://github.com/mui/material-ui/blob/main/packages/mui-codemod/src/v6.0.0/list-item-button-prop/list-item-button-prop.js)) - Transforms `ListItem` button props into `ListItemButton` components.
3. **`theme-v6`** ([`packages/mui-codemod/src/v6.0.0/theme-v6/theme-v6.js`](https://github.com/mui/material-ui/blob/main/packages/mui-codemod/src/v6.0.0/theme-v6/theme-v6.js)) - Converts `theme.palette.mode` checks to `theme.applyStyles()` calls.
Run these codemods before manual adjustments to minimize migration effort.
## Summary
- **Grid2** requires updating imports from `Unstable_Grid2` to `Grid2` and converting responsive props (`xs`, `sm`) to the new `size` and `offset` object syntax.
- **LoadingButton** from `@mui/lab` is removed; use the core `Button` component with the `loading` prop instead.
- **ListItem** no longer accepts `button`, `selected`, `disabled`, or `autoFocus` props; migrate to `ListItemButton` and import `listItemButtonClasses` from the new location.
- **AccordionSummary** now renders within an `` by default; use `slotProps.heading.component` to customize the heading level.
- **Typography** removes the `color` system prop; apply custom colors via the `sx` prop.
- **UMD bundles** are discontinued; switch to ESM imports or modern CDN providers.
- **Testing** requires wrapping ripple interactions in `act` and awaiting them due to performance optimizations.
## Frequently Asked Questions
### How do I migrate Grid2 from Material-UI v5 to v6?
Run the `grid-v2-props` codemod to automatically convert `Unstable_Grid2` imports to `Grid2` and transform flat breakpoint props like `xs={12}` into the object syntax `size={{ xs: 12 }}`. After running the codemod, verify that spacing behaves correctly since Grid2 now uses CSS `gap` and no longer expands to full width by default.
### What happened to LoadingButton in Material-UI v6?
`LoadingButton` was removed from `@mui/lab` in v6.4.0 and its functionality was merged into the core `Button` component. Change your imports from `@mui/lab/LoadingButton` to `@mui/material/Button` and add the `loading` prop to enable the loading state with the circular progress indicator.
### Why did my ListItem buttons stop working after upgrading to v6?
The `button`, `selected`, `disabled`, and `autoFocus` props were removed from `ListItem` to enforce proper component composition. You must replace `` with `` and update any class imports to use `listItemButtonClasses` from `@mui/material/ListItemButton`. The `list-item-button-prop` codemod automates this migration.
### How do I handle dark mode styling without theme.palette.mode in v6?
Material-UI v6 introduces `theme.applyStyles()` as the preferred method for color-mode-specific styling. Replace conditional logic checking `theme.palette.mode` with `theme.applyStyles('dark', { ... })` or `theme.applyStyles('light', { ... })`. The `theme-v6` codemod can automate this conversion across your codebase.