m3-baseui

導入

React 18+ プロジェクトに m3-baseui を追加する手順です。スタイリングエンジンは Tailwind CSS v4 か vanilla-extract のどちらか一方を選びます。

1. エンジンを選ぶ

両エンジンは同一 DOM・同一 data-* 属性を出力する drop-in 互換です。 通常はアプリが既に使っている方を選んでください。

詳細は スタイリングエンジン を参照してください。

2. インストール

Tailwind CSS v4

Terminal window
npm i @m3-baseui/react-tailwind @base-ui/react react react-dom
npm i -D tailwindcss@^4 @tailwindcss/vite

vanilla-extract

Terminal window
npm i @m3-baseui/react-vanilla-extract @m3-baseui/tokens @base-ui/react react react-dom
npm i -D @vanilla-extract/css @vanilla-extract/recipes @vanilla-extract/vite-plugin

vanilla-extract 利用時は @m3-baseui/tokens を直接インストールしてください。 アプリの CSS が @m3-baseui/tokens/tokens.css を import するためです。

3. CSS とビルド設定

Tailwind v4（Vite）

vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';


export default defineConfig({
  plugins: [react(), tailwindcss()],
});
app.css
@import '@m3-baseui/react-tailwind/preset.css';


/* 公開コンポーネントの Tailwind クラスを生成するために必須 */
@source "../node_modules/@m3-baseui/react-tailwind/dist";
@source "./";

@source で react-tailwind/dist を指定しないと、 コンポーネントがスタイルなしで描画されることがあります。最も多い導入ミスです。

vanilla-extract

vite.config.ts
import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';


export default defineConfig({
  plugins: [vanillaExtractPlugin(), react()],
});
app.css
@import '@m3-baseui/tokens/tokens.css';

4. テーマを載せる（任意）

コンポーネントは CSS 変数だけを読みます。デフォルト色だけでよければ tokens.css の import で十分です。seed やホスト色・ライト/ダーク切替が必要なら ThemeProvider か syncDocumentTheme を使います（どちらも :root に書きます）。 

import { Button, ThemeProvider, syncDocumentTheme } from '@m3-baseui/react-tailwind';


export default function App() {
  return (
    <ThemeProvider seed="#6750A4" scheme="tonalSpot" mode="system" contrast="standard">
      <Button variant="filled">送信</Button>
    </ThemeProvider>
  );
}


// または命令的に:
// syncDocumentTheme({ mode: 'dark', seed: '#6750A4' });

5. （任意）アイコン

Terminal window
npm i @m3-baseui/icons

Icon は Material Symbols をインライン SVG で描画します。Web フォントの読み込みは不要です。 デフォルト import はよく使うサブセットです。全カタログが必要なときは @m3-baseui/icons/all を使います。どちらか一方だけを import してください。

通常（サブセット）

import { Icon } from '@m3-baseui/icons';


<Icon name="settings" />
<Icon name="favorite" filled size={20} />

全カタログ

import { Icon } from '@m3-baseui/icons/all';


<Icon name="settings" />

よくある問題

  • スタイルが当たらない — Tailwind の @source と CSS import 順序を確認
  • useTheme must be used within ThemeProvider — useTheme を使うときだけ Provider でラップ
  • アイコンが出ない — name を確認するか、全カタログの @m3-baseui/icons/all を import