Skip to main content

muiv7

1. Executive Summary 📝​

The upgrade from MUI v6 to v7 is a significant modernization step. Unlike the massive architectural shift from v4 to v5 (which introduced sx prop), the v6 to v7 migration is more focused on API cleanup, performance, and embracing modern CSS features.

The most impactful changes for developers are:

  1. Removal of Deprecated APIs: Functions and props deprecated in v5 are now completely removed.
  2. Promotion of @mui/lab Components: Many components have graduated from the lab to the core @mui/material library, requiring import path updates.
  3. Modern CSS Integration: MUI v7 introduces opt-in support for native CSS variables and CSS Layers, enabling modern color spaces and improving compatibility with other styling solutions.
  4. Grid Component Overhaul: The default <Grid> is now the more powerful GridV2. The old implementation is still available as <GridLegacy>.

This migration is manageable but requires careful code review, especially regarding imports and theme configuration.

  • From:
    • @mui/icons-material: ^6.1.8
    • @mui/lab: 6.0.1-beta.36
    • @mui/material: ^6.1.8
    • @mui/system: ^6.1.8
  • To:
    • @mui/icons-material: ^7.3.1
    • @mui/lab: 7.0.0-beta.16
    • @mui/material: ^7.3.1
    • @mui/system: ^7.3.1

2. Critical Breaking Changes ⚠️​

These are changes that will likely break your application and require immediate attention.

a. No More Deep Imports​

Directly importing modules from deep paths is no longer supported. This was done to improve ESM support and tree-shaking.

  • Before (❌ Invalid in v7):

    import Button from '@mui/material/Button';
    import { deepmerge } from '@mui/utils';

  • After (✅ Correct in v7):

    import { Button } from '@mui/material';
    import { deepmerge } from '@mui/utils'; // No change for @mui/utils root

    Action Required: Update all component and utility imports to use the top-level package entry point. MUI provides a codemod to help automate this: npx @mui/codemod v7.0.0/top-level-imports <path>.

b. Removal of createMuiTheme​

The createMuiTheme function, which was an alias for createTheme since v5, has been removed.

  • Before (❌ Invalid in v7):

    import { createMuiTheme } from '@mui/material/styles';
    const theme = createMuiTheme({...});

  • After (✅ Correct in v7):

    import { createTheme } from '@mui/material/styles';
    const theme = createTheme({...});

c. Grid is Now GridV2​

The default export for the Grid component is now the improved GridV2, which uses CSS variables and offers more flexibility. The old Grid is available for a smoother transition but is considered legacy.

  • If you import from Grid in GESSO, it’s still using the old Grid. It’s deprecated and will be migrated in a later version.

  • To keep the old Grid behavior temporarily:

    // import from Gesso
    import { Grid, GridItem } from '@acromedia/gesso'
    // import from mui
    import { Unstable_Grid2 as Grid } from '@mui/material'; // In v6
    // In v7, if you still need the old one:
    import GridLegacy from '@mui/material/Grid';
    // classname changes
    '& .MuiGrid-item': { // In v6
      ...
    }
    '& .MuiGridLegacy-item': { // In v7
      ...
    }
    '& .MuiGrid-grid-xs-12': { // In v6
     ...
    }
    '& .MuiGridLegacy-grid-xs-12': { // In v7
      ...
    }

  • To adopt the new Grid:

    import Grid from '@mui/material/Grid'; // This is now GridV2 by default

d. Theme Palette Mode Change​

The theme.palette.mode will now return the actual mode of the theme ('light' or 'dark'), not what was passed to createTheme. This makes it more reliable in themes that derive from other themes. This is a subtle but important change for any logic that depends on the initial theme configuration.

e. TypeScript: Theme Augmentation​

If you are using TypeScript and augmenting the theme, the module path has changed.

  • Before (❌ Invalid in v7):

    declare module '@mui/material/styles/createTheme' {
      interface Theme {...}
    }

  • After (✅ Correct in v7):

    declare module '@mui/material/styles' {
      interface Theme {...}
    }

3. Major New Features & Architectural Shifts ✨​

a. Native Color Support with CSS Variables​

This is the flagship feature of v7. You can now opt into using a CssVarsProvider which leverages native CSS variables for the color palette.

Benefits:

  • Supports modern color spaces (P3, LCH, LAB).

  • Avoids the need to re-declare the entire theme in JavaScript for dark mode.

  • Enables easier integration with other CSS-variable-based libraries.

  • How to implement:

    import { Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
    import theme from './theme';

    function App() {
      return (
        <CssVarsProvider theme={theme}>
          {/* Your app components */}
        </CssVarsProvider>
      );
    }

b. CSS Layers Support​

To prevent style specificity conflicts with other libraries (like Tailwind CSS or vanilla CSS), you can now enable CSS Layers. This wraps MUI's styles in a CSS @layer, giving you more control over the cascade.

  • How to implement: 
    import { createTheme, ThemeProvider } from '@mui/material/styles';

    const theme = createTheme({
      cssLayers: true,
    });

    function App() {
      return (
        <ThemeProvider theme={theme}>
          {/* Your app components */}
        </ThemeProvider>
      );
    }

4. @mui/lab Component Graduation 🎓​

A significant number of components have been stabilized and moved from @mui/lab to @mui/material or other dedicated packages like @mui/x-date-pickers. You must update the import paths for these components.

ComponentOld Path (@mui/lab)New Path (@mui/material)
LoadingButton@mui/lab/LoadingButton@mui/material/LoadingButton
Masonry@mui/lab/Masonry@mui/material/Masonry
Timeline@mui/lab/Timeline@mui/material/Timeline
TimelineConnector@mui/lab/TimelineConnector@mui/material/TimelineConnector
TimelineContent@mui/lab/TimelineContent@mui/material/TimelineContent
TimelineDot@mui/lab/TimelineDot@mui/material/TimelineDot
TimelineItem@mui/lab/TimelineItem@mui/material/TimelineItem
TimelineOppositeContent@mui/lab/TimelineOppositeContent@mui/material/TimelineOppositeContent
TimelineSeparator@mui/lab/TimelineSeparator@mui/material/TimelineSeparator
TrapFocus@mui/lab/TrapFocus@mui/material/Unstable_TrapFocus (note: still unstable)
TreeItem@mui/lab/TreeItem@mui/x-tree-view/TreeItem
TreeView@mui/lab/TreeView@mui/x-tree-view/TreeView

Action Required: Search your codebase for imports from @mui/lab and update them to their new, stable locations. You will likely need to add @mui/x-tree-view as a new dependency if you use TreeView.

5. Recommended Migration Steps 🚀​

  1. Update Dependencies: Update your package.json to the target v7 versions.

    npm install @mui/material@latest @mui/icons-material@latest @mui/lab@latest @emotion/react@latest @emotion/styled@latest

  2. Run Codemods: Use the official MUI codemods to automate as much of the process as possible, especially for updating imports.

    npx @mui/codemod v7.0.0/top-level-imports <your-source-path>

  3. Update Theme Creation: Manually change all instances of createMuiTheme to createTheme.

  4. Update Component Imports: Manually find and update all imports for components that graduated from @mui/lab.

  5. Review Grid Usage: Audit every usage of the <Grid> component. Decide whether to migrate to the new API immediately or use <GridLegacy> as a temporary solution.

  6. Check for Other Removed APIs: Search for other APIs that were deprecated in v5 and are now removed, such as darkScrollbar from @mui/material.

  7. Test Thoroughly: After making these changes, perform a comprehensive test of your application's UI and functionality. Pay close attention to layout, theming, and any custom component styling.

  8. Consider New Features: Once your app is stable on v7, consider adopting the new CssVarsProvider for improved color handling and cssLayers if you have style conflicts.

6. Official Resources​