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（型付きスタイル生成の設定と採用判断）を先に検討する価値があります。
バージョンごとのサポート状況
| 系列 | 確認時点の最新版 | 公開日 | 扱い |
|---|---|---|---|
| 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 add2つ目のコマンドは、ライブラリの部品を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で最小アプリを動かす手順で確認できます。
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="[email protected]" />
<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からの移行）にまとめています。
テーマのカスタマイズ：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=" srcJavaScriptのプロジェクトでは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系の導入とテーマ設定）のほうが手戻りが少ない。
- チームがTailwind CSSで統一している：Chakraのスタイルプロップとユーティリティクラスが混在すると、同じ余白を2通りで書くことになる。部品のソースを手元に置くshadcn/uiが合う。
- 実行時のCSS生成を避けたい：Emotionはブラウザ上でスタイルを計算してstyleタグを挿入する。ゼロランタイムへの移行はまだ方針の段階なので、現時点でビルド時生成が必須ならPanda CSSか、振る舞いだけを提供するRadix UI Primitivesにスタイルを自前で当てる構成を選ぶ。
よくある質問
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に変えれば使えます。
