---
title: "Chakra UIとは？v3の使い方・インストール手順とv2移行の注意点【2026年9月】"
url: "https://www.issoh.co.jp/tech/details/3059/"
published: 2024-07-16
updated: 2026-09-27
categories: ["React"]
publisher: "株式会社一創"
---

# Chakra UIとは？v3の使い方・インストール手順とv2移行の注意点【2026年9月】

**Chakra UI（チャクラUI）**は、React向けのUIコンポーネントライブラリです。ボタン・フォーム・ダイアログなどの部品と、`padding="4"`のようにpropsでスタイルを書く仕組みをまとめて提供します。ライセンスはMITで、商用でも無料で使えます。

2026年9月27日時点の最新版は**v3.37.0**（2026年8月28日公開）です。v3は2024年10月に出た全面改訂版で、インストール手順も書き方もv2と大きく違います。検索で見つかる解説にはv2の手順が多く、そのまま真似ると`framer-motion`を余計に入れたり、効かないpropsを書いたりします。この記事ではv3の導入手順と基本の使い方を、手元で型チェックとレンダリングを通したコードで示し、v2から移行するときに型エラーにならない落とし穴まで扱います。

## まとめ：Chakra UI v3の要点

- 最新版はv3.37.0。インストールは`npm i @chakra-ui/react @emotion/react`の2パッケージで、Node.js 20以上が必要。
- 導入後に`npx @chakra-ui/cli snippet add`でProviderなどの部品をプロジェクトへコピーし、アプリ全体を`<Provider>`で包む。
- 見た目はスタイルプロップ、複雑な部品は`Table.Root`のような「名前.部品名」の組み立て式で書く。
- v2からの移行は公式のcodemodで大半を自動変換できる。ただし`colorScheme`の残りは型チェックを通ってしまうので、変換後に検索で洗い出す。
- v2も2026年6月にパッチ版が出たが、セキュリティ修正の対象は最新メジャー（v3）だけ。新規採用ならv3一択。

## Chakra UIの仕組み：Ark UIとEmotionの上に載ったコンポーネント群

v3のChakra UIは、見た目と振る舞いを別々の部品に任せています。開閉・フォーカス移動・キーボード操作といった振る舞いは、同じ開発チームの**Ark UI**（v3.37.0の依存は@ark-ui/react 5.39.0）が担います。アクセシビリティ対応はこの層に入っているため、自前でaria属性を書き足す場面は多くありません。

スタイルは**Emotion**が実行時にCSSを生成します。公式のインストールページは「Today, Chakra UI uses Emotion at runtime」と明記したうえで、Panda CSSに着想を得たゼロランタイム方式へ段階的に移る方針を示しています。実行時のCSS生成を避けたい案件なら、同じチームが作った[Panda CSS（型付きスタイル生成の設定と採用判断）](/tech/details/16479/)を先に検討する価値があります。

### バージョンごとのサポート状況

| 系列 | 確認時点の最新版 | 公開日        | 扱い                    |
| -- | -------- | ---------- | --------------------- |
| v3 | 3.37.0   | 2026-08-28 | 開発の本線                 |
| v2 | 2.10.10  | 2026-06-04 | パッチ版のみ（セキュリティ修正の約束なし） |
| v1 | 1.8.9    | 2022-09-16 | 以後リリースなし              |

v2は2026年6月にも2.10.10が出ています（トーストの`aria-hidden`付与と、ユーティリティの無限ループ修正）。ただしリポジトリのSECURITY.mdは「We release security updates for the latest major version.」としており、脆弱性の修正が約束されているのはv3だけです。v2のまま運用を続けるなら、依存パッケージの脆弱性通知を自分で追う前提になります。

## Chakra UI v3のインストール手順

Next.jsとViteのどちらでも、最初の3手順は共通です。v2の手順にあった`@emotion/styled`と`framer-motion`は、v3では不要になりました。

### 共通手順：パッケージとスニペットの追加

```
# 1. 本体とEmotionを入れる（Node.js 20以上）
npm i @chakra-ui/react @emotion/react

# 2. Provider などのスニペットを components/ui に書き出す
npx @chakra-ui/cli snippet add
```

2つ目のコマンドは、ライブラリの部品をnpmの中ではなく自分のリポジトリにソースとして書き出します。既定で生成されるのは`provider.tsx`・`color-mode.tsx`・`toaster.tsx`・`tooltip.tsx`の4ファイルです（CLI 3.37.0で確認）。ダークモードの切り替えは`color-mode.tsx`が`next-themes`を使って実装しているので、中身を読めば挙動を追えます。

TypeScriptの場合は、生成された部品を`@/components/ui/provider`で読み込めるように、既存のTypeScript設定へパス設定を追加します。Viteの標準Reactテンプレートでは`tsconfig.app.json`が対象です。以下は`src`配下にソースを置く構成なので、実際の配置に合わせてパスを調整してください。

```
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "paths": { "@/*": ["./src/*"] }
  }
}
```

### Next.js（App Router）でのProvider設定

公式ドキュメントはNext.js 15と16への対応を明記しています。ルートレイアウトで全体を`Provider`で包み、`<html>`に`suppressHydrationWarning`を付けます。付け忘れると、next-themesがクライアント側でクラスを書き換えるため、ハイドレーションの警告が出ます。

```
// app/layout.tsx
import { Provider } from "@/components/ui/provider"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ja" suppressHydrationWarning>
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  )
}
```

```
// next.config.mjs：使った部品だけを読み込ませる
export default {
  experimental: {
    optimizePackageImports: ["@chakra-ui/react"],
  },
}
```

Chakra UIの部品自体は内部でuseStateなどを使うクライアントコンポーネントですが、Server Componentのページから`'use client'`を書かずにそのまま使えます。`chakra()`ファクトリ、Chakraのフック、render propsを使う自作部品は、`'use client'`付きの別ファイルに分けます。App Routerの基本は[Next.js 16系App Routerで最小アプリを動かす手順](/tech/details/17373/)で確認できます。

### Viteでのパス解決の設定

Viteでは`src/main.tsx`でアプリを`Provider`で包み、tsconfigのパス設定をViteにも伝えます。Vite 8以降は`resolve.tsconfigPaths: true`の1行で済み、Vite 7以下は`vite-tsconfig-paths`プラグインを入れます。この設定が無いと`@/components/ui/provider`の読み込みで失敗します。

```
// vite.config.ts（Vite 8以降）
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react()],
  resolve: { tsconfigPaths: true },
})
```

## 基本の使い方：スタイルプロップと組み立て式コンポーネント

Chakra UIの書き方は2種類だけ覚えれば足ります。単純な要素はpropsでスタイルを指定し、Tableやダイアログのような複合部品は`Table.Root`・`Table.Row`のように部品を組み立てます。

### レスポンシブ指定とuseBreakpointValue

ブレークポイントはモバイルファーストで、`base`（0px）・`sm`（30rem＝約480px）・`md`（48rem＝約768px）・`lg`（62rem＝約992px）・`xl`（80rem）・`2xl`（96rem）の6段階です。propsにオブジェクトを渡すと、その幅以上で値が切り替わります。

```
"use client"

import { Stack, Text, useBreakpointValue } from "@chakra-ui/react"

export function Responsive() {
  // JS側で値を分けたいときだけ使う（見た目の切り替えはpropsで足りる）
  const label = useBreakpointValue({ base: "SP", md: "タブレット", lg: "PC" })
  return (
    <Stack direction={{ base: "column", md: "row" }} gap="4">
      <Text fontSize={{ base: "sm", lg: "md" }}>表示中：{label}</Text>
      <Text hideBelow="md">md未満では非表示</Text>
    </Stack>
  )
}
```

見た目の切り替えは、propsのオブジェクト指定で済ませるのが基本です。`useBreakpointValue`は画面幅が境界をまたぐたびにコンポーネントを再レンダリングさせるので、表示する部品そのものを差し替えたいときに限って使います。v3では`mdToXl`（mdからxlの間だけ）や`lgOnly`のような範囲指定も書けます。

### Tableの書き方（v3の組み立て式）

v2の`Thead`・`Tr`・`Td`は、v3で`Table.Header`・`Table.Row`・`Table.Cell`に変わりました。横スクロールの枠は`TableContainer`から`Table.ScrollArea`へ、数値列の右寄せは`isNumeric`から`textAlign="end"`へ置き換わっています。

```
import { Table } from "@chakra-ui/react"

const users = [
  { id: 1, name: "佐藤", role: "管理者", logins: 128 },
  { id: 2, name: "鈴木", role: "閲覧者", logins: 42 },
]

export function UserTable() {
  return (
    <Table.ScrollArea borderWidth="1px" maxW="full">
      <Table.Root size="sm" striped>
        <Table.Header>
          <Table.Row>
            <Table.ColumnHeader>名前</Table.ColumnHeader>
            <Table.ColumnHeader>権限</Table.ColumnHeader>
            <Table.ColumnHeader textAlign="end">ログイン回数</Table.ColumnHeader>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          {users.map((u) => (
            <Table.Row key={u.id}>
              <Table.Cell>{u.name}</Table.Cell>
              <Table.Cell>{u.role}</Table.Cell>
              <Table.Cell textAlign="end">{u.logins}</Table.Cell>
            </Table.Row>
          ))}
        </Table.Body>
      </Table.Root>
    </Table.ScrollArea>
  )
}
```

### FieldとDialogの基本構成

以下は画面構成の例です。メールアドレスの検証と削除処理は含みません。エラー文を表示するには、検証結果に応じて`Field.Root`へ`invalid`を渡してください。

入力欄のラベル・必須マーク・エラー文は`Field`でまとめます。v2の`isRequired`・`isInvalid`は、v3では`required`・`invalid`です。ダイアログはv2の`Modal`が`Dialog`に改名され、削除確認のような用途は`role="alertdialog"`を付けて作ります。

```
import { Button, CloseButton, Dialog, Field, Input, Portal, Stack } from "@chakra-ui/react"

export function DeleteAccount() {
  return (
    <Stack gap="4">
      <Field.Root required>
        <Field.Label>
          確認用メールアドレス <Field.RequiredIndicator />
        </Field.Label>
        <Input type="email" placeholder="you@example.com" />
        <Field.ErrorText>メールアドレスの形式が正しくありません</Field.ErrorText>
      </Field.Root>

      <Dialog.Root role="alertdialog">
        <Dialog.Trigger asChild>
          <Button colorPalette="red" variant="outline">アカウントを削除</Button>
        </Dialog.Trigger>
        <Portal>
          <Dialog.Backdrop />
          <Dialog.Positioner>
            <Dialog.Content>
              <Dialog.Header>
                <Dialog.Title>本当に削除しますか？</Dialog.Title>
              </Dialog.Header>
              <Dialog.Body>この操作は取り消せません。</Dialog.Body>
              <Dialog.Footer>
                <Dialog.ActionTrigger asChild>
                  <Button variant="outline">キャンセル</Button>
                </Dialog.ActionTrigger>
                <Button colorPalette="red">削除する</Button>
              </Dialog.Footer>
              <Dialog.CloseTrigger asChild>
                <CloseButton size="sm" />
              </Dialog.CloseTrigger>
            </Dialog.Content>
          </Dialog.Positioner>
        </Portal>
      </Dialog.Root>
    </Stack>
  )
}
```

画面の端から出るパネルは`Drawer`で、書き方はDialogとほぼ同じです。placementの指定やv2からの書き換えは[Chakra UI Drawerの使い方（v3の実装とv2からの移行）](/tech/details/4398/)にまとめています。

## テーマのカスタマイズ：createSystemとトークン

v3のテーマは、色やフォントを**トークン**として定義し、`createSystem`で既定の設定に重ねます。v2の`extendTheme`は廃止され、値はすべて`{ value: ... }`の形で書きます。ライトとダークで切り替えたい色は**セマンティックトークン**に置きます。

```
// src/theme.ts
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: {
          500: { value: "#1a73e8" },
          600: { value: "#1558b0" },
        },
      },
      fonts: {
        body: { value: "'Noto Sans JP', sans-serif" },
      },
    },
    semanticTokens: {
      colors: {
        "brand.solid": {
          value: { _light: "{colors.brand.500}", _dark: "{colors.brand.600}" },
        },
      },
    },
  },
})

export const system = createSystem(defaultConfig, config)
```

作った`system`は、スニペットの`provider.tsx`にある`defaultSystem`と差し替えます。v2で`theme`だったChakraProviderのpropsは、v3では`value`です。

TypeScriptで独自トークンの補完を効かせるには、`npx @chakra-ui/cli typegen src/theme.ts`で型を生成します（CLIはNode.js 20.6.0以上）。公式は`postinstall`か`prepare`のどちらか一方に登録して、CIでも毎回生成する運用を勧めています。生成し忘れると、追加した`brand.solid`が補完に出ません。未定義のトークン名を型エラーにするには、型生成に加えて`strictTokens: true`の設定が必要です。

## v2からv3への移行：主な書き換え対応表

移行はNode.js 22以上の環境で公式のcodemodから始めます。`npx @chakra-ui/codemod upgrade`で、コンポーネント名・props名・importの書き換えをまとめて実行します（`--dry`で事前確認できます）。変換後に手で確かめる項目は次のとおりです。

| v2                             | v3                         |
| ------------------------------ | -------------------------- |
| extendTheme                    | createSystem＋defaultConfig |
| ChakraProvider theme=          | ChakraProvider value=      |
| colorScheme                    | colorPalette               |
| isDisabled・isOpen・isInvalid    | disabled・open・invalid      |
| Stack spacing                  | Stack gap                  |
| Modal                          | Dialog                     |
| AlertDialog                    | Dialog（role=alertdialog）   |
| useColorMode・useColorModeValue | スニペットのcolor-mode.tsx       |
| @chakra-ui/icons               | react-iconsやlucide-react   |
| @chakra-ui/next-js             | Link・BoxのasChild           |
| framer-motion・@emotion/styled  | 不要（アンインストール）               |

カラーモードの関数は本体から消えましたが、スニペットの`color-mode.tsx`が同名の`useColorMode`と`useColorModeValue`を提供します。import元を`@/components/ui/color-mode`に変えれば、呼び出し側のコードはほぼそのまま使えます。

## codemod後のcolorScheme残存と型チェックの限界

v3への移行で最も見落としやすいのが`colorScheme`です。`isDisabled`や`spacing`をv3のコードに残すと、TypeScriptは未対応のpropsとして型エラーを報告します。ところが`colorScheme`は止まりません。CSSにもともと`color-scheme`というプロパティがあり、v3のスタイルプロップとして受け付けられてしまうからです。

検証環境はNode.js 26.5.0、React 19.3.0、TypeScript 5.9.3、@chakra-ui/react 3.37.0です。型チェックとReactDOMServerによるSSRで、次の結果を確認しています。

- `<Button colorScheme="blue">`は`tsc`を通過する。
- サーバー側でレンダリングすると、出力されるCSSは`color-scheme:blue`で、ボタンは既定のグレーのまま。blueパレットへの参照は0件（`colorPalette="blue"`では19件）。
- codemodの変換は、JSXに直接書いた`colorScheme="teal"`は`colorPalette`に直すが、`const primary = { colorScheme: "blue" }`を`<Button {...primary}>`で渡した書き方は変換しない。

つまり、ボタンの色をオブジェクトにまとめて共通化していたプロジェクトほど、変換後もビルドが通ったまま色だけ抜け落ちます。codemodを実行したら、型チェックに頼らず文字列で探してください。

```
# codemod後に残ったv2のpropsを洗い出す
grep -rn -E "colorScheme|isDisabled|isLoading|isOpen|spacing=" src
```

JavaScriptのプロジェクトでは`isDisabled`も通常は型チェックされません。文字列検索に加え、TypeScriptの`checkJs`による検査や、操作テストでも移行漏れを確認できます。

## Chakra UIを選ぶ場面・選ばない場面

ReactのUIライブラリは、部品を丸ごと提供するものと、スタイルの書き方だけを提供するものに分かれます。Chakra UIは前者の中で、Material Designのような特定のデザイン言語に縛られない点が特徴です。

| 候補             | スタイルの仕組み           | 部品の持ち方    |
| -------------- | ------------------ | --------- |
| Chakra UI v3   | Emotion（実行時）       | npm＋スニペット |
| Material UI    | Emotion（実行時）       | npm       |
| shadcn/ui      | Tailwind CSS（ビルド時） | ソースをコピー   |
| Tailwind CSS単体 | ビルド時にクラス生成         | 部品なし      |
| Panda CSS      | ビルド時に生成            | 部品なし      |

社内の管理画面や業務システムのように、独自のデザインで画面数が多く、アクセシビリティも確保したい案件ではChakra UIが向きます。トークンとセマンティックトークンでブランド色とダークモードを一か所に集められ、ダイアログやメニューのキーボード操作をArk UIに任せられるからです。

選ばないほうがよいのは次の3つの場面です。

- **Material Designに準拠する必要がある**：最初からMaterial Designの部品を持つ[Material UI（v9系の導入とテーマ設定）](/tech/details/17551/)のほうが手戻りが少ない。
- **チームがTailwind CSSで統一している**：Chakraのスタイルプロップとユーティリティクラスが混在すると、同じ余白を2通りで書くことになる。部品のソースを手元に置く[shadcn/ui](/tech/details/4092/)が合う。
- **実行時のCSS生成を避けたい**：Emotionはブラウザ上でスタイルを計算してstyleタグを挿入する。ゼロランタイムへの移行はまだ方針の段階なので、現時点でビルド時生成が必須ならPanda CSSか、振る舞いだけを提供する[Radix UI Primitives](/tech/details/7856/)にスタイルを自前で当てる構成を選ぶ。

## よくある質問

### Chakra UIは無料？商用利用できる？

本体（@chakra-ui/react）はMITライセンスで、商用でも無料で使えます。有料なのは、CLIの`blocks`コマンドで追加できる「Chakra UI Pro」のブロック集で、公式販売ページ（pro.chakra-ui.com）の表示は、個人向けが買い切り299ドル、チーム向けが899ドルです（2026年9月27日確認・セール価格の可能性があるため購入時に再確認してください）。

### Chakra UIの読み方は？

「チャクラ・ユーアイ」と読み、日本語の記事では「チャクラUI」とも表記されます。英語では綴りを詰めた「chakraui」や、パッケージ名の「@chakra-ui/react」で検索されることもあります。

### これから使うならv2とv3のどちら？

v3です。v2は2026年6月にも2.10.10が公開されましたが、セキュリティ修正の対象は最新メジャーのv3だけとリポジトリに明記されています。v2の解説記事のコードはv3では動かないものが多いため、参照するドキュメントの版も確かめてください。

### Chakra UIはServer Componentsで使える？

使えます。Chakraの部品はクライアントコンポーネントですが、Server Componentのページから`'use client'`を書かずに配置できます。`chakra()`ファクトリ、Chakraのフック、render propsを使う自作部品は、`'use client'`付きの別ファイルに置く必要があります。

### v3でもuseColorModeValueは使える？

本体からは削除されましたが、`npx @chakra-ui/cli snippet add`で生成される`color-mode.tsx`が同名の関数を提供します。import元を`@/components/ui/color-mode`に変えれば使えます。

## 関連記事

- [Chakra UI Drawerの使い方｜v3の実装とv2からの移行・placement設定を解説](/tech/details/4398/)
- [Panda CSSとは？型付きスタイル生成の設定と採用判断を実装目線で解説](/tech/details/16479/)
- [shadcn/uiとは？読み方・導入手順とBase UI既定化の変更点をReact開発者向けに解説](/tech/details/4092/)
- [Material UIとは：v9系の導入からGrid・テーマ設定までコード付きで解説](/tech/details/17551/)
- [Radix UI Primitivesとは？特徴・導入・Themesとの違いを解説](/tech/details/7856/)

---

出典: [Chakra UIとは？v3の使い方・インストール手順とv2移行の注意点【2026年9月】](<https://www.issoh.co.jp/tech/details/3059/>)（株式会社一創）