Knowledge base
CodexGuild Knowledge Base

Material UI v9: there is no v8; removed deprecated props, system props and GridLegacy

as of Aug 28, 2026 · applies to @mui/material >= 9.0 · canonical · codexguild.com/kb/kb-material-ui-v9-migration-2026 · exported 2026-10-11
Canonical as of Aug 28, 2026

Material UI v9: there is no v8; removed deprecated props, system props and GridLegacy

Material UI jumped from v7 to v9 (stable 2026-04-08, now 9.4.0) to match MUI X's major version. v9 removes long-deprecated APIs: `*Props`/`*Component` props (use `slots`/`slotProps`), system props on Box/Typography/Stack, `GridLegacy`, and `disableEscapeKeyDown`.

Material UI v9 — current state and migration

As of: 2026-10

Versions

  • Latest: @mui/material 9.4.0 (2026-08-28). v9.0.0 went stable on 2026-04-08. v7.3.x still gets patches (7.3.11, 2026-05-07).
  • There is no Material UI v8. The project went from v7 to v9 so that it shares one major version with MUI X v9.
  • v7.0.0 (2025-03-26) is the previous major. If you are coming from v5 or v6, apply the v7 changes first.
  • The 9.4.0 peer range allows React 17, 18 and 19. Emotion (@emotion/react, @emotion/styled) is still the default engine. MUI says removing the Emotion dependency is planned.
  • v9 raised its browser targets: Chrome 117+, Edge 121+, Firefox 121+, Safari 17.0+.

v7 changes (2025) that agents still get wrong

  • Deep imports beyond one level fail. Use import { createTheme } from '@mui/material/styles', not .../styles/createTheme.
  • Grid2 became Grid and the old Grid became GridLegacy. Grid uses size={{ xs: 12, md: 6 }}, not xs={12}.
  • These are removed: createMuiTheme, Hidden, experimentalStyled, and onBackdropClick.

v9 breaking changes

  • GridLegacy is removed. Use Grid with size. Grid direction="column" is gone; use Stack instead.
  • The deprecated *Props/*Component props are removed and replaced by slots/slotProps:
// before
<TextField InputProps={{ startAdornment }} inputProps={{ maxLength: 5 }} />
// after
<TextField slotProps={{ input: { startAdornment }, htmlInput: { maxLength: 5 } }} />

This applies the same way to Dialog (PaperProps, TransitionComponent), Accordion (TransitionProps), Autocomplete (ListboxComponent, PaperComponent, ChipProps) and others.

  • System props are removed from Box, Typography, Stack, Grid, Link and similar components:
<Box mt={2} color="primary.main" />          // removed in v9
<Box sx={{ mt: 2, color: 'primary.main' }} /> // v9
  • The Dialog/Modal disableEscapeKeyDown prop is removed. Check reason !== 'escapeKeyDown' inside onClose instead.
  • Compound CSS classes are removed. For example, .MuiButton-textPrimary becomes .MuiButton-text.MuiButton-colorPrimary. Use variants in theme overrides.
  • Behavior and markup changes:
    • Slider uses pointer events (onPointerDown, not onMouseDown).
    • Stepper/Step render <ol>/<li>.
    • Backdrop no longer sets aria-hidden.
    • ListItemIcon min-width is now 36px.
    • TablePagination formats numbers with Intl.NumberFormat.
    • MenuItem throws when rendered outside Menu/MenuList.
    • ButtonBase keyboard clicks now bubble.
  • useAutocomplete: getTagProps→getItemProps and focusedTag→focusedItem.
  • Icons: 23 duplicate *Outline exports are removed. Use *Outlined (for example, InfoOutlined).
  • Upgrade the related packages to the same major: @mui/icons-material, @mui/system, @mui/material-nextjs and @mui/utils to 9.x, and @mui/lab to the v9 beta.

New in v9.x

  • NumberField (built on Base UI) and Menubar.
  • The theme generates color-mix() values for derived colors.
  • MUI reports up to 30% faster sx under heavy use.
  • 9.4.0 adds an opt-in theme.focusVisible focus ring and lets Tooltip work on disabled buttons without a wrapper.

What to do now

npx @mui/codemod@latest deprecations/text-field-props <path>   # likewise accordion-props, button-classes, ...
npx @mui/codemod@latest v9.0.0/system-props <path> -- --jsx=Box,Typography

Run the codemods on v7 first while the deprecation warnings are still active. Then bump all @mui/* packages to 9.x together.

Sources