⤴️
MUI v6からv7へのアップデート、マイグレート方法

2025/05/25に公開
 MUI v7リリースv6からのマイグレート
https://mui.com/material-ui/migration/upgrade-to-v7/
以下は、公式ドキュメント「Upgrade to v7」の内容を日本語に翻訳したものです。なお、このガイドは、Material UI v6 から v7 へのアップグレード方法および変更点（破壊的変更）について説明しています。

 v7 へのアップグレードこのガイドでは、Material UI v6 から v7 へのアップグレード方法について説明します。

 なぜ Material UI v7 にアップグレードするのか
 1. 改善された ESM サポート
パッケージレイアウトの更新

パッケージレイアウトが更新され、package.json の exports フィールドにより、有効な ESM（ECMAScript Modules）と CommonJS の両方が明確にサポートされるようになりました。

これにより、Vite や webpack などの人気バンドラーで発生していた問題が解決され、Node.js 環境下でも ES モジュールから MUI パッケージを正しく読み込むことが可能になります。

詳細は Node.js のドキュメント https://nodejs.org/api/packages.html をご参照ください。

 2. 品質向上の改善Material UI v7 では、以下のような品質向上の変更が行われています：
スロットパターンの標準化

すべてのコンポーネントで、スロット（slots）パターンが統一され、UI のカスタマイズがよりシンプルになりました。
CSS レイヤーサポート

クライアントサイドアプリでは StyledEngineProvider の enableCssLayer プロパティを、Next.js App Router を利用する場合は AppRouterCacheProvider を介して、CSS レイヤーのサポートが追加されました。
非推奨 API の削減

長年の互換性を保つために残されていた非推奨（deprecated）の API を削除し、API の表面積を縮小、ドキュメントもより見やすくなっています。
また、以下のパッケージを使用している場合は、バージョンも "7.0.0" に更新してください：
@mui/icons-material
@mui/system
@mui/lab
@mui/material-nextjs
@mui/styled-engine
@mui/styled-engine-sc
@mui/utils
※なお、MUI X パッケージ（Data Grid、Date Pickers など）は、Material UI とは異なるバージョン管理戦略が採用されており、以下のパッケージはアップグレード時に変更する必要はありません：
@mui/x-data-grid
@mui/x-data-grid-pro
@mui/x-data-grid-premium
@mui/x-date-pickers
@mui/x-date-pickers-pro
@mui/x-charts
@mui/x-tree-view
@mui/x-tree-view-pro

 最低サポート TypeScript バージョンTypeScript の最低サポートバージョンが v4.7 から v4.9 に引き上げられました。
また、@types/react* パッケージは、利用している react のメジャーバージョンと同一である必要があります。

必要に応じ、以下のコマンドで更新してください：
npm install @types/react@<version> @types/react-dom@<version>

 破壊的変更（Breaking changes）v7 はメジャーリリースのため、パブリック API に影響する変更がいくつかあります。ここでは主要な変更点と、その対応方法について説明します。

 1. パッケージレイアウトの更新ディープインポートの禁止

以前は内部実装へ2階層以上のディープインポートも可能でしたが、これはプライベート API とみなされるため、v7 では使用できなくなりました。
例:
- import createTheme from '@mui/material/styles/createTheme';
+ import { createTheme } from '@mui/material/styles';
モダンバンドルの削除

以前、特定のバンドル（例：modern エイリアスなど）を使用していた場合、これらのエイリアスは削除してください。
例（webpack で設定していた場合）:
     resolve: {
       alias: {
-      '@mui/material': '@mui/material/modern',
-      '@mui/styled-engine': '@mui/styled-engine/modern',
-      '@mui/system': '@mui/system/modern',
-      '@mui/base': '@mui/base/modern',
-      '@mui/utils': '@mui/utils/modern',
-      '@mui/lab': '@mui/lab/modern',
       }
     }

 2. Grid および Grid2 コンポーネントの名称変更Grid のリネーム

非推奨の Grid コンポーネントは GridLegacy に名前が変更され、Grid2 は Grid 名前空間に移動しました。プロジェクトに合わせ、以下のいずれかの対応を行ってください。
アップグレードする場合

以下の codemod を実行してください:
npx @mui/codemod v7.0.0/grid-props <path/to/folder>
旧 Grid を継続使用する場合

インポートを以下のように変更します:
- import Grid, { gridClasses, GridProps } from '@mui/material/Grid';
+ import Grid, { gridLegacyClasses, GridLegacyProps } from '@mui/material/GridLegacy';
テーマの設定や CSS クラスの参照も合わせて更新してください。
Grid2 を使用している場合

インポートは以下のように更新してください:
- import Grid, { grid2Classes as gridClasses, Grid2Props as GridProps } from '@mui/material/Grid2';
+ import Grid, { gridClasses, GridProps } from '@mui/material/Grid';

 3. InputLabel のサイズプロパティの標準化InputLabel コンポーネントで従来使われていた size="normal" は、"medium" に変更されています。もし size="normal" を使用している場合は、次のように更新してください。
- <InputLabel size="normal">Label</InputLabel>
+ <InputLabel size="medium">Label</InputLabel>

 4. SvgIcon の data-testid 削除プロダクションバンドルでは、@mui/icons-material のアイコンにデフォルトで設定されていた data-testid プロパティが削除されました。これにより、テストで使用していた場合は必要に応じて対処してください。

 5. テーマの動作の変更CSS テーマ変数を利用した場合の挙動

CSS テーマ変数機能が有効な場合、theme.palette.mode はユーザーのカラースキーム（ライト・ダーク）の変更に合わせて動的に変化しなくなりました。

例として、useColorScheme フックでモードを切り替えた場合、モード状態（例えば 'dark'）は変わりますが、theme.palette.mode は初期値のままとなります。

そのため、スタイル内で値を参照する際は、以下のように theme.vars.* を直接利用することが推奨されます。
const Custom = styled('div')(({ theme }) => ({
  color: theme.vars.palette.text.primary,
  background: theme.vars.palette.primary.main,
}));
もし、JavaScript でランタイム計算が必要な場合は、theme.colorSchemes オブジェクトを利用してライトとダークのスタイルを分岐させる方法もあります。
const Custom = styled('div')(({ theme }) => ({
  color: alpha(theme.colorSchemes.light.palette.text.primary, 0.5),
  ...theme.applyStyles('dark', {
    color: alpha(theme.colorSchemes.dark.palette.text.primary, 0.5),
  }),
}));
また、必要に応じて <ThemeProvider forceThemeRerender /> を利用してテーマの再レンダリングを強制することも可能です。

 6. 非推奨 API の削除v5 で非推奨とされていた API は、v7 では完全に削除されています。例えば、従来の createMuiTheme 関数は削除され、代わりに createTheme を利用してください。
- import { createMuiTheme } from '@mui/material/styles';
+ import { createTheme } from '@mui/material/styles';
また、Dialog や Modal コンポーネントの onBackdropClick プロパティは削除され、代わりに onClose コールバックが用意されています。以下は Dialog の例です。
function Example() {
  const [open, setOpen] = React.useState(false);

  const handleClose = (event, reason) => {
    if (reason === 'backdropClick') {
      // バックドロップクリック時の処理
    }
    setOpen(false);
  };

  return (
    <Dialog open={open} onClose={handleClose}>
      {/* ダイアログの内容 */}
    </Dialog>
  );
}
さらに、非推奨だった experimentalStyled も削除され、通常の styled を使用するようにしてください。
- import { experimentalStyled as styled } from '@mui/material/styles';
+ import { styled } from '@mui/material/styles';

 その他のアップグレード時の留意点パッケージのバージョンアップ

上記以外にも、Material UI v7 では内部APIやコンポーネントの細かい名称変更、インポートパスの変更など多数の修正が行われています。たとえば、Grid 系のコンポーネントの名称変更や、テーマ拡張のためのインターフェースの更新など、移行には codemod ツールを利用することで多くの変更を自動化できます。
テストの確認

すべての codemod を実行した後は、アプリケーションのビルドやテストを十分に行い、コンソールエラーが発生していないか確認してください。
ドキュメントの再確認

詳細な移行手順やその他の破壊的変更については、公式ドキュメントを参照してください。

 まとめMaterial UI v7 では、ESM のサポート向上、品質向上、そして不要な非推奨 API の削除など、さまざまな改善が行われています。特にパッケージレイアウトの更新や Grid 系のコンポーネントの名称変更、テーマの動作変更などは、アップグレード時に注意が必要です。公式 codemod ツールを活用し、十分なテストと検証を行った上でアップグレードを進めることをお勧めします。
この翻訳がアップグレードの参考になれば幸いです。公式ドキュメントの詳細な説明も併せてご確認ください。
※この翻訳は、公式ドキュメントの内容を元にしており、最新のアップグレードガイドの内容を反映しています。各コード例はそのままお使いいただけるよう記載していますので、プロジェクトへの適用の際はご自身の環境や依存関係に合わせて適宜修正してください。
MUI v7リリース

v7 へのアップグレード

なぜ Material UI v7 にアップグレードするのか

1. 改善された ESM サポート

2. 品質向上の改善

最低サポート TypeScript バージョン

破壊的変更（Breaking changes）

1. パッケージレイアウトの更新

2. Grid および Grid2 コンポーネントの名称変更

3. InputLabel のサイズプロパティの標準化

4. SvgIcon の data-testid 削除

5. テーマの動作の変更

6. 非推奨 API の削除

その他のアップグレード時の留意点

まとめ

Discussion
