Chakra UI v3 でのテーマカスタマイズ方法（v2との違いも紹介）

はじめに

Chakra UI は使いやすさと洗練されたコンポーネントで人気の UI ライブラリですが、2024年末にリリースされた v3 ではテーマのカスタマイズ方法が大きく変更されました。

v2まで主に使われていた extendTheme は廃止され、新たに defineConfig と createSystem を使うスタイルに移行しています。

本記事では、v2 と v3 のカスタマイズ方法の違いを明確に示しながら、v3での実装方法を丁寧に解説します。

v2 のテーマカスタマイズ例

まずは、v2まででよく使われていたテーマカスタマイズ方法を紹介します。

import { extendTheme } from "@chakra-ui/react";

const colors = {
  primary: "#95CC6A",
  secondary: "#8D4BBE",
};

export const theme = extendTheme({ colors });

これをインポートして以下のようにします。

import { ChakraProvider } from "@chakra-ui/react";
import { ReactNode } from "react";
import { theme } from "@/config/theme";

interface AppProviderProps {
  children: ReactNode;
}

export const AppProvider = ({ children }: AppProviderProps) => {
  return <ChakraProvider theme={theme}>{children}</ChakraProvider>;
};

extendTheme を使って簡単にテーマを拡張・定義できました。

v3 の変更点と背景

v3では、テーマ定義が Design Token ベースに完全移行しました。
これに伴い、extendTheme は削除され、次のような構成に変わります：

defineConfig() でトークンベースのテーマを定義

createSystem() で Chakra UI のテーマシステムを生成

ChakraProvider に渡すプロパティは theme ではなく value

v3 のテーマカスタマイズ方法（実装例）

import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react";

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        primary: {
          600: { value: "#95CC6A" },
        },
        secondary: {
          600: { value: "#8D4BBE" },
        },
      },
    },
  },
});

export const system = createSystem(defaultConfig, config);

import { ChakraProvider } from "@chakra-ui/react";
import { ReactNode } from "react";
import { system } from "@/config/system";

interface AppProviderProps {
  children: ReactNode;
}

export const AppProvider = ({ children }: AppProviderProps) => {
  return <ChakraProvider value={system}>{children}</ChakraProvider>;
};

import { ChakraProvider } from "@chakra-ui/react";
import { ReactNode } from "react";
import { system } from "@/config/system";

interface AppProviderProps {
children: ReactNode;
}

export const AppProvider = ({ children }: AppProviderProps) => {
return {children};
};
ポイント：

色などのカスタマイズは tokens 内に定義

カラーのバリエーション（例えば 600 番）を指定して階層化

createSystem で生成した system を ChakraProvider に渡す

まとめ

Chakra UI v3 では extendTheme が使えなくなった

新しい方法では defineConfig + createSystem によるトークンベースの設計が中心

Theme に関する構造は一見複雑だが、柔軟性と拡張性が向上している

v2までの知識がある人ほど戸惑うかもしれませんが、設計思想を理解すればv3のスタイルは非常にパワフルです。

参考

Chakra UI v3 ドキュメント (公式)

Design Tokensについての基礎

気になる点や修正提案があれば、ぜひコメントで教えてください 🙌