Yamada UIとは？@yamada-ui/react 2.3の導入手順・CLI・テーマ設計とv1移行

Yamada UIを入れようとして最初に迷うのは、npmで何をインストールするかです。正解は@yamada-ui/reactの1パッケージです。もう1つの落とし穴は、日本語の解説記事の多くが2025年7月のv2.0.0より前に書かれていることです。v1の書き方のままではReact 19必須化やパッケージ統合に引っかかります。

本記事は2026年11月1日時点の最新版@yamada-ui/react 2.3.0（2026年10月28日公開）を基準に、npmとCLIの2通りの導入、Next.js App Routerでの設定、カラーモードとテーマの設計、v1からの移行で書き換える箇所を扱います。掲載したTypeScriptのコードは、2.3.0・React 19.3.1・TypeScript 5.9.3（strictモード）で型検査を通したものです。Next.jsのコードはNext.js 16.4.3の型定義を入れた状態で検査しており、next buildでの実行までは確かめていません。CLIの挙動は@yamada-ui/cli 2.1.16を実際に実行した結果です。CLIは実行時にYamada UIのレジストリから部品を取得するため、条件をそろえて試すならnpx @yamada-ui/[email protected]と版を指定してください。それでも取得する部品の中身はレジストリ側の更新で変わることがあります。

まとめ

• npmのパッケージは@yamada-ui/reactの1本です。最新は2.3.0（2026年10月28日公開）で、npm install yamada-uiは404で失敗します。
• v2系はReact 19以上が必須です。React 18のプロジェクトはv1系の最終版1.7.8（2025年8月7日公開）が上限になります。v1からの移行では、importの統合に加えてisOpenからopenのようなboolean propsの改名と、削除コンポーネントの置き換えが要ります。
• アプリのルートをUIProviderで包めば動きます。YamadaUIProviderという名前のコンポーネントは存在しません。
• v2からはCLIで部品のソースを手元にコピーして書き換える方式も選べます。ただしadd buttonの1回でButtonを使う部品まで連鎖し、44部品が生成されました。
• レスポンシブ指定は既定でmax-widthのメディアクエリになります。Chakra UIやMUIのモバイル起点の感覚で書くと、効く画面幅が逆になります。
• 日本語で公式ドキュメントを読みたいチームには、Chakra UI・MUI・Mantineにない利点があります。一方、npmの月間ダウンロード数はChakra UIの約95分の1で、利用規模は小さいライブラリです。

Yamada UIの実体｜配布パッケージと提供規模

Yamada UIは、Hirotomo Yamada氏が立ち上げたReact向けのコンポーネントライブラリです。GitHubリポジトリは2022年10月6日作成、ライセンスはMITで、スター数は1,033（2026年11月1日時点のGitHub APIのstargazers_count）です。READMEは、Chakra UI・shadcn/ui・MUI・Mantine UIから着想を得たと明記しています。スタイリングはEmotionの上に組まれ、propsでCSSを当てる書き方はChakra UIとほぼ同じ感覚です。

npmのパッケージ名は@yamada-ui/react

npmレジストリでyamada-uiを引くと404が返ります。正しいパッケージは@yamada-ui/reactで、2026年9月30日〜10月29日のダウンロード数は67,078でした（npm Downloads API）。v1時代の@yamada-ui/buttonや@yamada-ui/providersなどの分割パッケージは今もnpmに残っていますが、いずれも「This package is deprecated. Please use @yamada-ui/react instead.」と非推奨の表示が付いています。

2.3.0の型定義には、コンポーネントのディレクトリが124個あります。2.3.0ではProse・Bubble・Marqueeの3部品が追加され、React Server Componentsで遅延読み込みされた子要素がButtonやAccordionのアイコン位置で描画されない不具合が修正されました（CHANGELOG）。

React 19必須とmotion・Emotionの依存

2.3.0のpeerDependenciesは、reactとreact-domが>=19、motionが>=12、@emotion/reactと@emotion/styledが>=11です。npm 7以降はpeerDependenciesを自動で入れるため、次の1行で揃います。

npm install @yamada-ui/react

アニメーションの依存は、0.1.2〜1.7.0がframer-motion、1.7.1（2024年12月11日）からは後継のmotionに切り替わっています。framer-motionを入れる手順を見かけたら、その記事が対象にしている版を確かめてください。現行の2.3.0で必要なのはmotionです。

Yamada UIのインストール手順｜npmとCLIの2経路

公式の導入ガイドは、npmでパッケージを入れる方法と、CLIでプロジェクトにファイルを生成する方法の2つを示しています。部品の見た目やロジックを書き換える予定がなければ、npmで入れるだけで足ります。

Viteでのnpm導入とUIProviderの配置

インストール後、アプリのルートをUIProviderで包みます。テーマ・カラーモード・通知・ローディングのコンテキストはここから供給されるため、包み忘れるとコンポーネントが期待どおりに動きません。テーマを差し替えないうちはthemeを渡す必要はありません。

import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { UIProvider } from "@yamada-ui/react"
import { App } from "./App"

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <UIProvider>
      <App />
    </UIProvider>
  </StrictMode>,
)

import { Button } from "@yamada-ui/react"

export function App() {
  return <Button colorScheme="primary">はじめてのボタン</Button>
}

colorSchemeはボタンなどの配色を決めるpropsで、primary・secondaryのほかblueやredといった色名を受け取ります。

Next.js App RouterでのColorModeScriptとcookie設定

Next.js（App）のガイドでは、htmlとbodyにsuppressHydrationWarningを付け、bodyの中にColorModeScriptを置きます。カラーモードはlocalStorageかcookieに保存され、このスクリプトが読み込み時に同期を取るためです。サーバー側の描画でも正しい色で出したいときはcookie方式にします。

import { ColorModeScript, UIProvider } from "@yamada-ui/react"
import { cookies } from "next/headers"
import type { ReactNode } from "react"

export default async function RootLayout({ children }: { children: ReactNode }) {
  const cookieStore = await cookies()

  return (
    <html lang="ja" suppressHydrationWarning>
      <body suppressHydrationWarning>
        <ColorModeScript type="cookie" />
        <UIProvider cookie={cookieStore.toString()}>{children}</UIProvider>
      </body>
    </html>
  )
}

公式ガイドのcookie版サンプルは関数にasyncが付いておらず、そのまま貼るとawaitの位置でエラーになります。上のコードはasyncを付けた形です。cookies()を呼ぶとそのルートは動的レンダリングになる点も、公式ガイドが注意として挙げています。

CLIによる部品ソースの生成と更新管理

v2の大きな変更は、shadcn/uiと同じく部品のソースコードをプロジェクトにコピーして使える点です。公式は、variantやsizeのスタイルを変えたいとき、初期値やロジックを変えたいとき、不具合を自分で直したいときにこの方式を勧めています。CLIのドキュメントのコマンドを、空のプロジェクトで@yamada-ui/cli 2.1.16を使って実行しました。

# プロジェクト直下で初期化（ui.json と components/ui/ が作られる）
npx @yamada-ui/cli init

# 部品を手元へコピー（init は CLI 本体を依存に追加しないため、パッケージ名ごと指定する）
npx @yamada-ui/cli add button

# 本家の更新との差分を確認し、取り込む
npx @yamada-ui/cli diff button
npx @yamada-ui/cli update button

# テーマ一式（tokens・semantic-tokens・styles・config.ts）を生成
npx @yamada-ui/cli theme

initが生成するファイルと呼び出し方の注意

init（monorepoを使わない設定）を実行すると、設定ファイルui.jsonとcomponents/ui/index.tsが作られ、@yamada-ui/react 2.3.0とreact 19.3.1が依存に加わりました。index.tsは166行で、@yamada-ui/react/components/accordionのようなコンポーネントのサブパス124件と、フック34件・Provider2件などを再エクスポートしているだけです。この時点では部品のソースはまだコピーされていません。

ドキュメントはyamada-cli add buttonと短い名前で書いていますが、initは@yamada-ui/cli自体をpackage.jsonに追加しません。そのためnpx yamada-cli add buttonはnpmレジストリでyamada-cliを探しに行き、404で失敗しました。上のようにnpx @yamada-ui/cliで呼ぶか、先にnpm install -D @yamada-ui/cliで入れておきます。

add buttonで44部品が生成される理由とdiffの対象

add buttonを実行すると、Buttonだけでなく44部品とui-providerがcomponents/ui/へ生成されました。Buttonのregistry.jsonを見ると、dependents（Buttonを内部で使う部品）にCalendar・Modal・Drawer・Paginationなど13部品が並んでいます。CLIはそれらもコピーし、さらにその部品の依存先まで連鎖して取り込むため、数が膨らみます。手元のButtonを書き換えたとき、Modalの閉じるボタンなどにも同じ変更が反映されるようにするための動きです。

生成後のindex.tsでは、Buttonの行が./components/buttonの再エクスポートに書き換わります。アプリ側のimportを@yamada-ui/reactからcomponents/ui（生成先）に切り替えないと、手元で編集した部品は使われません。UIProviderも同じ生成先から読み込みます。

コピーした部品はdiffで本家の更新を確認し、updateで取り込みます。手元でbutton.style.tsのfontWeightを書き換えたあとにdiff buttonを実行しても、結果は「No updates found.」でした。diffが比べるのは本家側の更新で、手元の改変は差分として出ません。更新が手元の改変とぶつかった箇所は、Gitのマージと同じ形式の競合として表示されるとドキュメントに書かれています。

CLI方式を選ぶ場面と選ばない場面

デザインシステムを自社で持ち、variantを独自に足していく前提ならCLI方式が向いています。一方、見た目をextendThemeやstyle propsで調整する程度なら、npmで入れるだけにすべきです。updateは部品名を省けば全部品をまとめて更新できますが、1部品のために数十ファイルを抱えると、本家の修正が入るたびに差分と競合を確かめる対象がそれだけ増えます。同じ「コピーして所有する」設計のshadcn/uiとの違いは、shadcn/uiの導入手順とBase UI既定化の変更点で整理しています。

カラーモードとテーマの設計

Yamada UIのカラーモードは、1つのセマンティックトークンにライト用とダーク用の2つの値を持たせる設計です。コンポーネント側はトークン名だけを参照し、モードによる分岐を書きません。

extendThemeとdefineConfigによる既定値の設定

extendThemeは既定テーマに差分をディープマージしたテーマを返します。defineConfigのdefaultColorModeは既定がlightで、darkかsystem（OSの設定に従う）に変えられます。

import { UIProvider, defineConfig, extendTheme } from "@yamada-ui/react"
import type { PropsWithChildren } from "react"

const theme = extendTheme({
  semanticTokens: {
    colors: {
      // [ライトモード, ダークモード] の順に 1 トークンへ 2 値を持たせる
      brand: ["blue.600", "blue.300"],
    },
  },
})

const config = defineConfig({ defaultColorMode: "system" })

export function AppProvider({ children }: PropsWithChildren) {
  return (
    <UIProvider theme={theme} config={config}>
      {children}
    </UIProvider>
  )
}

brandはライトでblue.600、ダークでblue.300に解決されます。ダーク側を明るい色にしておくのは、暗い背景の上で文字や枠のコントラストを保つためです。比率の基準はコントラスト比の4.5対1と3対1の適用範囲で確認できます。トークンや既定の設定をまるごと編集したい場合は、CLIのthemeコマンドでtokens・semantic-tokens・styles・config.tsの一式を生成し、それをUIProviderのthemeとconfigに渡します。

useColorModeによるカラーモードの切り替え

import { Box, Button, useColorMode, useColorModeValue } from "@yamada-ui/react"

export function ThemeToggle() {
  const { colorMode, toggleColorMode } = useColorMode()
  const label = useColorModeValue("ダークモードへ", "ライトモードへ")

  return (
    <Box bg="brand" color="fg.contrast" p="md">
      <Button variant="outline" onClick={toggleColorMode}>
        {label}（現在: {colorMode}）
      </Button>
    </Box>
  )
}

useColorModeValueは、第1引数をライト、第2引数をダークの値として返します。表示文言のようにトークン化しにくい値の切り替えに使います。Next.js App Routerでは、このThemeToggleや後述のSaveButtonのようにフックを使う部品のファイル先頭に"use client"を書き、Client Componentとして読み込みます。非同期のRootLayoutには付けません。

レスポンシブ指定の向き（既定はmax-width）

style propsにブレークポイントをキーにしたオブジェクトを渡すと、画面幅で値が変わります。注意すべきは向きです。公式のレスポンシブデザインの説明のとおり、Yamada UIは既定で@media screen and (max-width: …)を生成します。baseが広い画面の値で、md（48em＝768px）やsm（30em＝480px）はその幅以下で上書きされます。

import { Box, Text } from "@yamada-ui/react"

export function Hero() {
  return (
    <Box p={{ base: "2xl", md: "md" }}>
      <Text fontSize={{ base: "3xl", sm: "xl" }}>新しいダッシュボード</Text>
    </Box>
  )
}

このコードでは、768px以下で余白がmdに、480px以下で文字サイズがxlに縮みます。Chakra UIやMUIはmin-widthのモバイル起点なので、同じ書き方をすると効く範囲が逆になります。モバイル起点にそろえたいときはdefineConfig({ breakpoint: { direction: "up" } })をUIProviderのconfigに渡します。

useAsyncCallback・useNoticeによる非同期処理の表示制御

保存ボタンのような非同期処理の表示は、Yamada UIではフックで用意されています。useLoadingはscreen・page・backgroundの3系統を返し、それぞれにstart・update・finish・forceがあります。useNoticeは内部でSonnerを使う通知です。

公式が勧めるのは、これらをまとめて扱うuseAsyncCallbackです。戻り値のloadingをButtonに渡せば押下中のスピナーが出て、第3引数の{ loading: "page" }でページ単位のローディングも同時に動きます。

import { Button, useAsyncCallback, useNotice } from "@yamada-ui/react"

export function SaveButton() {
  const notice = useNotice()

  const [loading, onClick] = useAsyncCallback(
    async () => {
      try {
        const res = await fetch("/api/save", { method: "POST" })
        if (!res.ok) throw new Error(`HTTP ${res.status}`)

        notice({ description: "保存しました", status: "success" })
      } catch (error) {
        notice({ description: `保存に失敗しました（${String(error)}）`, status: "error" })
      }
    },
    [notice],
    { loading: "page" },
  )

  return (
    <Button loading={loading} onClick={onClick}>
      保存
    </Button>
  )
}

2.3.0の実装を読むと、useAsyncCallbackはtryとfinallyでローディングを止めるだけで、例外を握りつぶしません。fetchのネットワークエラーを中で捕まえないと、ローディングは止まっても未処理の例外が残ります。HTTP 500のような応答はfetchが例外にしないため、res.okの確認も必要です。上のコードはその2点を入れた形です。入力値の検証まで含めてフォームを組むなら、Field.RootとReact Hook Formの使い方の組み合わせが扱いやすい構成です。

v1からv2への移行で書き換える箇所

既存のv1プロジェクトを上げるとき、まず手が入るのはReact本体とimportの2点です。そのうえで、公式の移行ガイドが挙げるpropsの改名・削除コンポーネント・テーマAPIの変更を順に当てていきます。

React 19への更新の先行

v1系のpeerDependenciesはReact 18以上でしたが、v2系はReact 19以上です。React本体の更新が先に必要で、その範囲はReact 19.2の新機能と19.2.8までの修正で確認できます。React 19へ上げられない事情があるなら、v2への移行は見送るべきです。その場合、参照する情報はv1系の最終版1.7.8時点のものに限り、v2向けの記述と混ぜないようにします。

パッケージの統合と複合コンポーネントの名前空間形式

importの書き換えが移行作業の中心です。コンポーネント単位のパッケージ指定をすべて@yamada-ui/reactへ寄せます。

// v1（コンポーネントごとに分割されていた）
import { Button } from "@yamada-ui/button"
import { FormControl } from "@yamada-ui/form-control"

// v2（単一パッケージ + 名前空間形式）
import { Button, Card, Field, Input } from "@yamada-ui/react"

複合コンポーネントは名前空間形式に変わりました。カードはCard.Root・Card.Header・Card.Body・Card.Footer、フォーム項目はField.Rootという並びです。

import { Card, Field, Input, Text } from "@yamada-ui/react"

export function ProfileCard() {
  return (
    <Card.Root variant="outline">
      <Card.Header>
        <Text fontSize="lg" fontWeight="bold">プロフィール</Text>
      </Card.Header>
      <Card.Body>
        <Field.Root label="表示名" helperMessage="全角20文字まで">
          <Input placeholder="山田太郎" />
        </Field.Root>
      </Card.Body>
    </Card.Root>
  )
}

Buttonのvariantに指定できるのはsolid・outline・ghost・subtle・surfaceの5種です。MUIのcontainedを渡すと、TypeScriptがTS2322の型エラーで止めます。

boolean propsの改名と削除されたコンポーネント・API

v2ではisOpen・isDisabledのようなis付きのboolean propsが、open・disabledに改名されました。2.3.0のButtonにisDisabledを渡すと、TypeScriptはTS2322で止めます。型エラーを頼りに置き換えていくのが確実です。削除されたものと移行先のうち、使用頻度が高いものを並べます。

テーマ側ではextendComponent・withDefaultPropsなどの部品単位の上書きAPIが削除されました。v1で部品のvariantやsizeをテーマから足していたプロジェクトは、前述のCLIで部品をコピーして書き換える形に移すことになります。Markdownコンポーネントも削除されました。2.3.0で追加されたProseはHTMLの見た目を整える部品でMarkdownの解析はしないため、Markdownを表示するなら別のライブラリでHTMLに変換してからProseで包みます。@yamada-ui/nextも非推奨になったため、Next.jsでは@yamada-ui/reactだけを使います。

Chakra UI・MUI・Mantineとの選定基準

判断材料になる数値を並べます（いずれも2026年11月1日時点。最新版とReact要件はnpmレジストリ、ダウンロード数はnpm Downloads APIの2026年9月30日〜10月29日の値）。

ダウンロード数はChakra UIの約95分の1、MUIの約600分の1です。ダウンロード数は導入事例や解説記事の数そのものではありませんが、利用規模の差は大きく、使いたい部品の実装例が見つかるかは採用前に確かめておくべきです。それでもYamada UIを選ぶ理由になるのは、公式ドキュメントが日本語で整備されている点です。コンポーネントごとのprops一覧を日本語で引けることは、React経験の浅いメンバーがいるチームほど効いてきます。React 19必須はMantineも同じで、Yamada UIだけの制約ではありません。

逆に採用を見送るべき場面もはっきりしています。React 18に固定されたレガシー環境、Material Designの見た目が要件の案件（Material UIが素直）、開発者の入れ替わりが激しく採用実績の多さそのものが要件になるチームです。Chakra UIの書き味が好みで情報量を優先するならChakra UI v3、フォームやフックの充実を重視するならMantineが比較対象になります。ライブラリ選びの前に画面の設計方針から固めたい場合は、UI/UXデザインの支援のように画面設計の段階から相談する進め方もあります。

よくある質問

YamadaUIProviderというコンポーネントはありますか？

ありません。2.3.0が公開しているProvider系はUIProvider・ThemeProvider・ColorModeProvider・LoadingProvider・NoticeProvider・SystemProvider・EnvironmentProvider・I18nProviderなどで、アプリのルートに置くのはUIProviderです。import { UIProvider } from "@yamada-ui/react"で読み込みます。

npm install yamada-uiでインストールできますか？

できません。yamada-uiはnpmに存在せず404になるため、npm install @yamada-ui/reactを使います。CLIもnpx @yamada-ui/cliと書きます。

framer-motionのインストールは必要ですか？

現行版では不要です。1.7.1以降の依存はmotionで、2.3.0はmotion 12以上を求めます。npm 7以降なら@yamada-ui/reactのインストール時に自動で入ります。

React 18のプロジェクトでも使えますか？

v2系は使えません。公式ドキュメントもReact 19への更新を案内しています。React 18のまま使うならv1系の最終版1.7.8（2025年8月7日公開）が上限で、以降の更新はありません。

日本語のドキュメントはありますか？

あります。公式サイトyamada-ui.comの/ja配下に日本語版があり、導入手順からCLI・フック・各コンポーネントのpropsまで日本語で読めます。

関連記事

• Chakra UIとは？v3の使い方・インストール手順とv2移行の注意点【2026年10月】
• Mantineとは？Viteでの導入手順とMantine 9の変更点を実装目線で解説【2026年8月版】
• Material UIとは：v9系の導入からGrid・テーマ設定までコード付きで解説
• shadcn/uiとは？読み方・導入手順とBase UI既定化の変更点をReact開発者向けに解説
• React 19.2の新機能｜Activity・useEffectEvent・cacheSignal・PPRの使い方と19.2.8までの修正