migration

What this skill does

# MUI Version Migration

## v4 → v5 Migration

### Package Renames

```bash
# Uninstall v4 packages
npm uninstall @material-ui/core @material-ui/icons @material-ui/lab @material-ui/system

# Install v5 packages
npm install @mui/material @mui/icons-material @mui/lab @mui/system
npm install @emotion/react @emotion/styled   # new required peer deps

# If using styled-components instead of emotion (less common):
npm install @mui/material @mui/styled-engine-sc styled-components
```

### Run the v5 Codemod

The codemod handles ~80% of the mechanical changes automatically.

```bash
# Run the v5 preset-safe codemod (safe subset — no breaking changes)
npx @mui/codemod v5.0.0/preset-safe src/

# Run on a single file
npx @mui/codemod v5.0.0/preset-safe src/components/MyComponent.tsx

# Run individual transforms
npx @mui/codemod v5.0.0/component-rename-prop src/
npx @mui/codemod v5.0.0/moved-lab-modules src/
npx @mui/codemod v5.0.0/optimal-imports src/
```

After running the codemod, review the diff carefully — some transformations may need manual adjustment.

### Import Path Changes

```tsx
// v4
import { makeStyles } from '@material-ui/core/styles';
import { createMuiTheme } from '@material-ui/core/styles';
import Button from '@material-ui/core/Button';
import TextField from '@material-ui/core/TextField';

// v5
import { styled } from '@mui/material/styles';     // replaces makeStyles
import { createTheme } from '@mui/material/styles'; // createMuiTheme → createTheme
import Button from '@mui/material/Button';
import TextField from '@mui/material/TextField';
```

### createTheme Changes

```tsx
// v4
import { createMuiTheme } from '@material-ui/core/styles';

const theme = createMuiTheme({
  palette: {
    primary: { main: '#1976d2' },
  },
  overrides: {                       // v4: overrides
    MuiButton: {
      root: { textTransform: 'none' },
    },
  },
  props: {                           // v4: props
    MuiButton: { disableRipple: true },
  },
});

// v5
import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
  },
  components: {                      // v5: components (combines overrides + props)
    MuiButton: {
      defaultProps: {                // was: props
        disableRipple: true,
      },
      styleOverrides: {              // was: overrides
        root: {
          textTransform: 'none',
        },
      },
    },
  },
});
```

### makeStyles → styled / sx

This is the most impactful change. JSS (`makeStyles`, `withStyles`) is replaced by Emotion.

#### Pattern 1: sx prop (simple, inline styles)

```tsx
// v4 with makeStyles
const useStyles = makeStyles((theme) => ({
  root: {
    padding: theme.spacing(2),
    backgroundColor: theme.palette.background.paper,
    borderRadius: theme.shape.borderRadius,
  },
}));

function MyComponent() {
  const classes = useStyles();
  return <div className={classes.root}>Content</div>;
}

// v5 with sx prop
function MyComponent() {
  return (
    <Box
      sx={{
        p: 2,
        bgcolor: 'background.paper',
        borderRadius: 1,
      }}
    >
      Content
    </Box>
  );
}
```

#### Pattern 2: styled() (reusable styled components)

```tsx
// v4 with makeStyles + clsx
const useStyles = makeStyles((theme) => ({
  card: {
    padding: theme.spacing(3),
    border: `1px solid ${theme.palette.divider}`,
    borderRadius: theme.shape.borderRadius * 2,
  },
  cardHighlighted: {
    borderColor: theme.palette.primary.main,
    backgroundColor: theme.palette.primary.light,
  },
}));

function MyCard({ highlighted }: { highlighted: boolean }) {
  const classes = useStyles();
  return (
    <div className={clsx(classes.card, { [classes.cardHighlighted]: highlighted })}>
      Content
    </div>
  );
}

// v5 with styled()
import { styled } from '@mui/material/styles';

const StyledCard = styled('div', {
  shouldForwardProp: (prop) => prop !== 'highlighted',
})<{ highlighted?: boolean }>(({ theme, highlighted }) => ({
  padding: theme.spacing(3),
  border: `1px solid ${theme.palette.divider}`,
  borderRadius: theme.shape.borderRadius * 2,
  ...(highlighted && {
    borderColor: theme.palette.primary.main,
    backgroundColor: theme.palette.primary.light,
  }),
}));

function MyCard({ highlighted }: { highlighted: boolean }) {
  return <StyledCard highlighted={highlighted}>Content</StyledCard>;
}
```

#### Pattern 3: tss-react (drop-in makeStyles replacement)

For large codebases where a full migration is impractical, `tss-react` provides a near-identical API:

```bash
npm install tss-react @emotion/react
```

```tsx
// Minimal diff from v4 makeStyles
import { makeStyles } from 'tss-react/mui';

const useStyles = makeStyles()((theme) => ({
  root: {
    padding: theme.spacing(2),
    backgroundColor: theme.palette.background.paper,
  },
}));

function MyComponent() {
  const { classes } = useStyles();
  return <div className={classes.root}>Content</div>;
}
```

### withStyles → styled

```tsx
// v4
const StyledButton = withStyles((theme) => ({
  root: {
    margin: theme.spacing(1),
  },
  label: {
    color: theme.palette.primary.main,
  },
}))(Button);

// v5
const StyledButton = styled(Button)(({ theme }) => ({
  margin: theme.spacing(1),
  '& .MuiButton-label': {          // target internal class
    color: theme.palette.primary.main,
  },
}));
// Or better — use sx prop on Button directly
```

### color Prop Changes

```tsx
// v4 — color accepted any string
<Button color="default">Default</Button>

// v5 — 'default' removed; use 'inherit' or omit color
<Button>Default</Button>
<Button color="inherit">Inherit parent color</Button>
```

### System Props Removed from Most Components

In v5, system props (like `mt`, `p`, `bgcolor`) work on `Box` and `Stack` but not on
all components. Use the `sx` prop instead.

```tsx
// v4 — system props on Typography
<Typography mt={2} color="primary.main">Text</Typography>

// v5 — use sx prop
<Typography sx={{ mt: 2, color: 'primary.main' }}>Text</Typography>
```

### Lab Component Moves

Several components graduated from `@mui/lab` to `@mui/material`:

| v4 lab | v5 core |
|--------|---------|
| `@material-ui/lab/Alert` | `@mui/material/Alert` |
| `@material-ui/lab/Autocomplete` | `@mui/material/Autocomplete` |
| `@material-ui/lab/Pagination` | `@mui/material/Pagination` |
| `@material-ui/lab/Rating` | `@mui/material/Rating` |
| `@material-ui/lab/Skeleton` | `@mui/material/Skeleton` |
| `@material-ui/lab/SpeedDial` | `@mui/material/SpeedDial` |
| `@material-ui/lab/ToggleButton` | `@mui/material/ToggleButton` |

### v4 → v5 Breaking Changes Checklist

- [ ] Replace `@material-ui/*` with `@mui/*`
- [ ] Add `@emotion/react` and `@emotion/styled` peer deps
- [ ] Replace `createMuiTheme` with `createTheme`
- [ ] Replace `theme.overrides` + `theme.props` with `theme.components`
- [ ] Replace all `makeStyles`/`withStyles` (JSS) with `styled`/`sx`/tss-react
- [ ] Remove `color="default"` — use `color="inherit"` or omit
- [ ] Update Lab imports to core for graduated components
- [ ] Replace `<Hidden>` with `sx={{ display: { xs: 'none', sm: 'block' } }}`
- [ ] Update `Box` system shorthand keys (some changed)
- [ ] Check all `className` overrides — internal class names changed in v5

---

## v5 → v6 Migration

### Run the v6 Codemod

```bash
# Run preset-safe (recommended first step)
npx @mui/codemod v6.0.0/preset-safe src/

# Run on specific directories
npx @mui/codemod v6.0.0/preset-safe src/components/ src/pages/

# Individual transforms (if preset-safe missed something)
npx @mui/codemod v6.0.0/grid-v2-props src/
npx @mui/codemod v6.0.0/sx-prop src/
```

### Grid v2 (Major Breaking Change)

Grid v2 is the default `Grid` in v6. The `item` prop is removed; use `size` instead.
The `xs`, `sm`, `md`, `lg`, `xl` props are replaced by a single `size` prop with an object.

```tsx
// v5 Grid
import Grid from '@mui/material/Grid';

<Grid container spacing={2}>
  <Grid item xs={12} sm={6} md={4}>
    <Card /