🎨

MUIを使う際に知っておきたいポイントまとめ

Toshihisa Tomatsu

2025/09/08に公開

React

mui

tech

 はじめに最近、MUIを使う機会があり、初見だとライブラリの基本的な概念や方針、スタイリングやカスタマイズはどのように行うのか、どの機能を使うのかといった点を把握するのに時間がかかりました。
https://mui.com/
この記事では、React向けUIライブラリのMUIを実際のプロジェクトで使う際、事前に知っておくとキャッチアップがスムーズにいきそうな点を紹介します。
!この記事はMUI v7の情報を元に書いています

 MUIのライブラリ構成や基本情報まず、MUIに関連するライブラリについて整理します。

 主要なライブラリMaterial UI
MUIの中核となるReact UIコンポーネントライブラリ
ボタン、テキストフィールド、ダイアログなど、Material Designに基づいたコンポーネントを提供
MUI System
MUIに組み込まれているスタイリング系の機能を提供するライブラリ
MUIでスタイリングを行う際に利用するsx propsやstyled関数などの機能はこちらで実装
スタイリングやレイアウト系の詳細な仕様についてはMUI Systemのドキュメントを参照する
Joy UI
Material UIとは異なるデザインシステムのUIコンポーネントライブラリ
現在は開発停止のため、新規プロジェクトでは非推奨

 FigmaのDesign KitsMUIのFigma UI Kitが販売されています。Figmaを使ったデザインフローを採用する場合は必要になることが多いです。

 MUI XMUIだけでは提供されていない機能については、MUI Xで補完できます。DateTimePickerやグラフなどの高度なコンポーネントが提供されており、基本機能は無料、日付範囲選択などの一部機能はPro Plan（有料）で利用可能です

 MUIのドキュメントMUIのドキュメントで基本的な使い方やコンポーネント、カスタマイズ方法などを知ることができます。

ComponentsとAPIでページが分かれています

Componentsページ: 各コンポーネントの使用例を確認。APIセクションにAPIドキュメントへの導線がある

APIページ: 渡せるpropsやCSS classesの詳細情報を確認。

 スタイリングとカスタマイズMUIはsx propsというスタイリングの仕組みを提供しているため、CSS ModulesやTailwindのようなCSSライブラリを使う必要はなく、MUIだけで完結します。Themeとの連携を考えるとMUIのsx propsに寄せた方が良いです。

また、コンポーネントをカスタマイズする方法はいくつかありますが、用途に応じて使い分けることが重要です。

 基本的なスタイリング方針MUIのコンポーネントにsx propsを渡してスタイリングしたり、BoxやStackのようなレイアウト系のコンポーネントを組み合わせることで大部分のスタイリングは対応できます。
従来のバージョンではコンポーネントのpropsでmr={2}のような形でmargin-rightを指定できるSystem Propsという仕組みがありました。しかし、これは非推奨になっているため、すべてsx propsに統一することを推奨します。

 1箇所だけスタイルを変更する場合sx propsを渡す
最も基本的な方法です。ただし、sxはrootの要素にのみ適用されるため、コンポーネント内部の特定の要素をカスタマイズしたい場合は、CSS classを指定してカスタマイズする必要があります。各コンポーネントごとのAPIドキュメントに利用できるCSS classesが記載されています。
<Button
  sx={{
    backgroundColor: 'primary.main',
    color: 'white',
    '&:hover': {
      backgroundColor: 'primary.dark',
    },
    '& .Mui-disabled': {
      backgroundColor: 'primary.dark'
    }
  }}
>
  カスタムボタン
</Button>

 カスタマイズされたコンポーネントを再定義する場合styled関数
複数箇所で同じカスタマイズを適用したい場合は、styled関数を使って新しいコンポーネントを作成します。
import { styled } from '@mui/material/styles';
import { Button } from '@mui/material';

const CustomButton = styled(Button)(({ theme }) => ({
  backgroundColor: theme.palette.primary.main,
  color: theme.palette.primary.contrastText,
  '&:hover': {
    backgroundColor: theme.palette.primary.dark,
  },
}));
!styled関数を使う際は、@mui/systemではなく@mui/material/stylesからimportしてください。@mui/systemを使うとThemeの型定義の変更が反映されません。

 コンポーネントのベースとなるスタイルを変更する場合アプリ全体で共通のカスタマイズを適用したい場合は、後述する方法でthemeを設定します。

 themeの拡張とカスタマイズデフォルトのテーマがありますが、そのまま使うことは少ないため、基本的にはカスタマイズすることになります。
デフォルトテーマを見ると初期で設定されている値が分かります。

 createThemeを使ったカスタマイズcreateThemeにカスタマイズする内容を入れることで、デフォルト値を上書きできます。
import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
    secondary: {
      main: '#dc004e',
    },
  },
  typography: {
    h1: {
      fontSize: '2.5rem',
      fontWeight: 600,
    },
    body3: {
      fontSize: '0.75rem',
      lineHeight: 1.2,
    },
  },
});
デフォルトにはないtypographyのvariantを追加できます。上記の例ではbody3を追加していますが、これを使うためには後述する方法で型定義の拡張も必要です。

 コンポーネントのデフォルトスタイルやpropsの変更特定のコンポーネントに対して、デフォルトのスタイルやpropsを設定できます。
const theme = createTheme({
  components: {
    MuiButtonBase: {
      defaultProps: {
        disableRipple: true,
      },
      styleOverrides: {
        root: {
          borderRadius: 8,
        },
      },
    },
  },
});

 型定義の拡張MUIをTypeScriptで使う場合、Themeでカスタマイズした内容を型定義に反映する必要があります。

 カスタムvariantの型定義Typographyでデフォルトには存在しないvariantを追加する場合、以下のように型定義を拡張します。
declare module "@mui/material/styles" {
  interface TypographyVariants {
    body3: React.CSSProperties;
  }
  interface TypographyVariantsOptions {
    body3: React.CSSProperties;
  }
}
declare module "@mui/material/Typography" {
  interface TypographyPropsVariantOverrides {
    body3: true;
  }
}
他にも同様の方法でpaletteの名前空間やvariantを増やすこともできます。

 sx propsからThemeへのアクセスsx propsで色などのTheme情報を指定する際、文字列で指定すると型チェックが効きません。
<TableCell
  sx={{
    color: "text.secondary",
    backgroundColor: "blueGrey.50",
  }}
>
  {children}
</TableCell>
間違った値を指定してしまう可能性があるため、theme objectを使ったり、文字列ではなく関数形式でtheme objectにアクセスする方法も検討すると良いでしょう。

 アップデートとメンテナンス
 マイグレーションガイドの活用MUIのバージョンアップを行う際は、必ずマイグレーションガイドを確認しましょう。APIの破壊的変更については、多くの場合codemodが用意されています。

 codemodの活用codemodは、APIの変更を自動的に適用してくれるツールです。CSS Classesが変更されたりした場合も、codemodで移行できます。
npx @mui/codemod@latest <codemod-name> <path>

 その他の補足情報
 独自アイコンの定義MUIのアイコンセットにない独自のアイコンを使いたい場合は、SvgIconコンポーネントを使って定義できます。
import SvgIcon, { type SvgIconProps } from "@mui/material/SvgIcon";

type IconProps = SvgIconProps;

export const MyIcon = (props: IconProps) => (
  <SvgIcon {...props}>
    <svg
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
      fill="none"
    >
      <path
        d="..."
      />
    </svg>
  </SvgIcon>
);

 レイアウトコンポーネントの使い分けレイアウトは主にBoxやStackコンポーネントで行います。Stackを使うとデフォルトでflexレイアウトになっているため、要素を並べる際に便利です。
<Stack direction="row" spacing={2}>
  <Button>ボタン1</Button>
  <Button>ボタン2</Button>
</Stack>

 PaperコンポーネントPaperコンポーネントは、アプリ側で直接使うことはほぼありません。しかし、MUIの多くのコンポーネントが内部的にPaperを使用しているため、Paperのベーススタイルをカスタマイズするとあらゆるコンポーネントにその影響が波及します。変更する際は注意が必要です。

 MUIのimport開発体験のパフォーマンス観点からbarrel importsは避けた方が良いと考えています。
また、ラッパーファイル経由でのimportは避けて直接importするようにすると、mui codemodへの対応が可能になります。muiのcodemodは直接muiパッケージからimportされているファイルのみ対応しているため、直接importしておくことでAPIの移行が容易になります。
// 推奨
// sample.tsx
import Button from '@mui/material/Button';
import TextField from '@mui/material/TextField';

// 非推奨
// mui-wrapper.ts
import Button from '@mui/material/Button';
import TextField from '@mui/material/TextField';
export { Button, TextField }
// sample.tsx
import { Button, TextField } from './mui.ts';

 Slots Propsの活用古いバージョンではXXPropsという形でコンポーネントの特定パーツの差し替えやpropsの指定ができましたが、現在はslotsとslotPropsに統一されています。
<TextField
  slots={{
    input: CustomInput,
  }}
  slotProps={{
    input: {
      sx: {},
    },
  }}
/>

 足りない機能の補完MUIには含まれていない機能も多くあります。例えば、ファイルのDrop系のコンポーネントは組み込みだとないため、react-dropzoneなどのライブラリと組み合わせて自作する必要があります。

 RSC対応RSC（React Server Components）サポートのため、ゼロランタイムCSSのPigment CSSという仕組みが開発されています。ただし、まだ実用段階ではないようです。詳細はマイグレーションガイドを参照してください。

 まとめMUIを実際のプロジェクトで使う際、個人的に事前に知っておけると嬉しかった情報を紹介しました。

この記事が、初めてMUIを使う際の参考になれば幸いです。

Linc'well, inc.Publication

医療スタートアップ Linc'well のエンジニアの記事を集めています。

はじめに

MUIのライブラリ構成や基本情報

主要なライブラリ

FigmaのDesign Kits

MUI X

MUIのドキュメント

スタイリングとカスタマイズ

基本的なスタイリング方針

1箇所だけスタイルを変更する場合

カスタマイズされたコンポーネントを再定義する場合

コンポーネントのベースとなるスタイルを変更する場合

themeの拡張とカスタマイズ

createThemeを使ったカスタマイズ

コンポーネントのデフォルトスタイルやpropsの変更

型定義の拡張

カスタムvariantの型定義

sx propsからThemeへのアクセス

アップデートとメンテナンス

マイグレーションガイドの活用

codemodの活用

その他の補足情報

独自アイコンの定義

レイアウトコンポーネントの使い分け

Paperコンポーネント

MUIのimport

Slots Propsの活用

足りない機能の補完

RSC対応

まとめ

Discussion