CSS Modules

グローバルCSSは、app/layout.tsxでimportするだけでサイト全体にスタイルを一括適用できる手軽さがある一方で、あらゆるページ・コンポーネントに影響が及ぶため、簡単にクラス名が衝突するような問題が起こりがちです。たとえば「Buttonコンポーネント用の.buttonクラスを定義したら、別のコンポーネントの.buttonと競合してスタイルが崩れた」といったケースが典型的です。CSS Modulesは、この「クラス名の衝突」を仕組みとして解消するための機能です。

1. ファイル名の規約とスコープ化

CSS Modulesを使うには、CSSファイルの名前を**xxx.module.css**という規約に沿ってつけます。この規約に従うと、Next.jsはビルド時にクラス名をbutton_button__aB12xのような一意な文字列へ自動的に変換します。この変換のおかげで、別のファイルで同じ.buttonというクラス名を書いても、実際に生成されるクラス名は別物になるため衝突しません。

1.1 CSSファイルの作成

Buttonコンポーネント用のCSSファイルを作成します。Visual Studio Codeのエクスプローラーで app フォルダを右クリックし、「新しいフォルダー」から components フォルダを作成します。次に、作成した components フォルダを右クリックして「新しいファイル」から Button.module.css を作成します。

styling-practice/
└── app/
    └── components/  ← このフォルダを作成
        └── Button.module.css  ← このファイルを作成

作成した Button.module.css に以下の内容を書き込みます。

.button {
  padding: 8px 16px;
  border: none;
  border-radius: 6px;
  background-color: #2563eb;
  color: #ffffff;
  font-size: 14px;
  cursor: pointer;
}

.button:hover {
  background-color: #1d4ed8;
}

1.2 tsxファイルへの適用

このCSSをTypeScript側から読み込みます。CSS Modulesを使うTypeScriptファイルでは、CSSファイルをオブジェクトとしてimportします。オブジェクトのプロパティ名が、CSS内で定義したクラス名と対応します。書き方は以下のとおりです。

import styles from './コンポーネント名.module.css';

export function コンポーネント名() {
  return <要素タグ className={styles.クラス名}>...</要素タグ>;
}

以下は、Button.module.css の .button クラスをButtonコンポーネントに適用する例です。Visual Studio Codeのエクスプローラーで components フォルダを右クリックし、「新しいファイル」から Button.tsx を作成します。

styling-practice/
└── app/
    └── components/
        ├── Button.module.css
        └── Button.tsx  ← このファイルを作成

作成した Button.tsx に以下の内容を書き込みます。

'use client';

import styles from './Button.module.css';

type Props = {
  label: string;
  onClick?: () => void;
};

export function Button({ label, onClick }: Props) {
  return (
    <button className={styles.button} onClick={onClick}>
      {label}
    </button>
  );
}

1.3 画面への配置と動作確認

作成したButtonコンポーネントを画面に表示するため、app/page.tsx を以下の内容に置き換えます。

'use client';

import { Button } from './components/Button';

export default function Home() {
  return (
    <main style={{ padding: '32px' }}>
      <Button label="保存" onClick={() => alert('保存しました')} />
    </main>
  );
}

保存すると、ブラウザで開いている http://localhost:3000 の表示が置き換わり、create-next-app の初期ページが消えて、トップページの左上に青い「保存」ボタンが1つだけ表示された状態になります。背景は前節で適用したグローバルCSSの薄いグレー(#f9fafb)が引き続き効いていることも確認します。ボタンをクリックすると 保存しました のアラートが出ることを確認します。さらに、DevTools(F12 キー、または右クリック→「検証」)のElementsタブで <button> の class 属性を確認すると、Button_button__xxxxx のように自動生成されたクラス名が付与されており、コンポーネント単位でクラス名がスコープ化されている様子を確認できます。

コードを解説します。

'use client';

Button.tsx と app/page.tsx の先頭に付けているディレクティブで、そのファイルをClient Componentとして扱うことをNext.jsに伝えます。<button>のonClickのようにブラウザ側で動くイベントハンドラを含むコンポーネントや、そのハンドラを関数propとして渡す側のコンポーネントはClient Componentである必要があります。前章のNext.jsの基本の「Server ComponentとClient Componentの使い分け」で扱った内容です。

import styles from './Button.module.css';

.module.css ファイルをオブジェクトとして import しています。styles オブジェクトのプロパティが、CSSファイルで定義した各クラス名に対応します。

<button className={styles.button} onClick={onClick}>

styles.button を className に渡すことで、ビルド時に自動生成される一意なクラス名(Button_button__xxxxx のような形式)が要素に付与されます。この仕組みにより、他ファイルで .button を定義してもクラス名が衝突しません。

2. クラス名の動的な切り替え

CSS Modulesでは、コンポーネントに渡された props の値に応じて、適用するクラス名を動的に切り替えることができます。たとえば同じButtonでも、普段は通常のボタンを表示しておき、削除や取り消しといったユーザに注意を促したい場面では赤系の「危険」を示すクラスに切り替える、といった使い分けが典型例です。

ここでは、Buttonコンポーネントに「通常(primary)」と「危険操作用(danger)」の2種類のバリエーションを持たせ、variant prop の値によって適用するクラスを切り替えられるようにします。

2.1 バリエーション用CSSクラスの追加

まずCSSファイル側にバリエーション用のクラスを追加します。app/components/Button.module.css を以下の内容に置き換えます。

.button {
  padding: 8px 16px;
  border: none;
  border-radius: 6px;
  color: #ffffff;
  font-size: 14px;
  cursor: pointer;
}

.primary {
  background-color: #2563eb;
}

.primary:hover {
  background-color: #1d4ed8;
}

.danger {
  background-color: #dc2626;
}

.danger:hover {
  background-color: #b91c1c;
}

2.2 tsxファイルでの動的なクラス名切り替え

コンポーネント側では、propsで受け取ったバリエーションに応じて、テンプレートリテラルで複数のクラス名を組み合わせます。書き方は以下のとおりです。

className={`${styles.共通クラス} ${styles[propsの変数名]}`}

以下は、variant propの値に応じて .primary または .danger を切り替える例です。app/components/Button.tsx を以下の内容に置き換えます。

'use client';

import styles from './Button.module.css';

type Variant = 'primary' | 'danger';

type Props = {
  label: string;
  variant?: Variant;
  onClick?: () => void;
};

export function Button({ label, variant = 'primary', onClick }: Props) {
  return (
    <button
      className={`${styles.button} ${styles[variant]}`}
      onClick={onClick}
    >
      {label}
    </button>
  );
}

2.3 画面への配置と動作確認

呼び出し側のapp/page.tsxを、チェックボックスで「危険な操作モード」を切り替えると、同じButtonの見た目・ラベル・アラート文言が動的に切り替わる形に置き換えます。

'use client';

import { useState } from 'react';
import { Button } from './components/Button';

export default function Home() {
  const [isDangerMode, setIsDangerMode] = useState(false);
  return (
    <main style={{ padding: '32px', display: 'flex', flexDirection: 'column', gap: '12px', alignItems: 'flex-start' }}>
      <label>
        <input
          type="checkbox"
          checked={isDangerMode}
          onChange={(e) => setIsDangerMode(e.target.checked)}
        />
        {' '}危険な操作モード
      </label>
      <Button
        label={isDangerMode ? '削除' : '保存'}
        variant={isDangerMode ? 'danger' : 'primary'}
        onClick={() => alert(isDangerMode ? '削除しました' : '保存しました')}
      />
    </main>
  );
}

保存すると、ブラウザで開いている http://localhost:3000 のトップページに、危険な操作モード のチェックボックスと、その下に1つのボタンが縦に並んで表示されます。チェックボックスがオフの初期状態では、以下のようにボタンは青い「保存」で、クリックすると 保存しました のアラートが出ます。

チェックボックスをオンにすると、同じ1つのButtonの色が赤に、ラベルが「削除」に切り替わり、クリック時のアラートも 削除しました に変わります。

DevTools(F12 キー、または右クリック→「検証」)のElementsタブで <button> の class 属性を観察すると、チェックボックスの切り替えに応じて Button_button__xxxxx Button_primary__yyyyy と Button_button__xxxxx Button_danger__zzzzz の間でクラス名が動的に入れ替わる様子を確認できます。

コードを解説します。

type Variant = 'primary' | 'danger';

variant prop が取りうる値を文字列リテラル型で定義しています。'primary' と 'danger' 以外の値を渡すと、TypeScriptがコンパイル時にエラーとして検出します。

className={`${styles.button} ${styles[variant]}`}

テンプレートリテラルで2つのクラス名を半角スペース区切りで連結しています。前半の styles.button は常に適用される共通スタイルで、後半の styles[variant] が variant の値に応じて .primary または .danger に切り替わります。styles[variant] のように角括弧でアクセスすると、propsの値によって取り出すクラスを動的に切り替えられます。

const [isDangerMode, setIsDangerMode] = useState(false);
...
variant={isDangerMode ? 'danger' : 'primary'}

useStateで管理している isDangerMode の値に応じて、variant propに渡す文字列を三項演算子で切り替えています。propの値が変わるたびにReactがButtonを再レンダリングし、Button内部の styles[variant] によって適用されるクラス名が .primary と .danger の間で切り替わります。同じButtonコンポーネントのインスタンスに対して、状態に応じて適用するCSSクラスを動的に差し替えられるのがCSS Modulesの利点です。

CSSは通常のCSSとまったく同じ構文で書けるため、これまでのCSS知識をそのまま活かせる点もCSS Modulesの利点です。加えて、クラス名の衝突を気にせずコンポーネント単位でスタイルを閉じ込められます。