Yamada UIとは？@yamada-ui/react v2の導入とテーマ設計・v1移行【2026年8月版】

Yamada UIを調べ始めて最初に詰まるのは、npmで何をインストールするのかという一点です。答えは@yamada-ui/reactの1パッケージで、yamada-uiという名前のパッケージはnpmに存在しません。v1の頃はコンポーネントごとにパッケージが分かれていた名残があり、この点だけで導入につまずきます。

本記事は2026年8月6日時点の最新版である@yamada-ui/react 2.2.6（2026年7月30日公開）を基準に、インストールからUIProviderの配置、セマンティックトークンを使ったカラーモード設計、そしてv1からv2へ移行するときに書き換えが必要になる箇所までを扱います。掲載したコードは、2.2.6・React 19.2.8・TypeScript 5.9.3（strictモード）の組み合わせで型エラーが出ないことを確認したものです。

まとめ

• npmで配布されているパッケージは@yamada-ui/reactの1本のみです。最新は2.2.6で、2026年7月30日公開です（2026年8月6日時点）。
• v2系のpeerDependenciesはReact 19以上です。React 18で止まっているプロジェクトはv2を採用できず、v1系の最終版1.7.8（2025年8月7日公開）が上限になります。
• アプリのルートをUIProviderで包むことが動作条件です。テーマの差し替えはextendThemeで行います。
• カラーモードは1つのセマンティックトークンにライト用とダーク用の2値を持たせる設計で、コンポーネント側に条件分岐を書かずに切り替わります。
• v1からの移行では、コンポーネント単位の分割パッケージを@yamada-ui/reactへ集約し、CardやFieldなど複合コンポーネントの参照をCard.Root形式の名前空間に書き換えます。
• 日本語ドキュメントが公式に用意されている点が、Chakra UIやMUIに対する実務上の差になります。

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

Yamada UIは、Hirotomo Yamada氏が個人で立ち上げたReact向けのコンポーネントライブラリです。GitHubリポジトリyamada-ui/yamada-uiは2022年10月6日作成、ライセンスはMIT、スター数は1,021（2026年8月6日時点）。最初のnpm公開は0.1.0で2023年6月3日でした。公式READMEは、Chakra UI・shadcn/ui・MUI・Mantineから着想を得たと明記しています。

npmで配布されるのは@yamada-ui/react 1本

導入時に一番間違えやすいのがパッケージ名です。npmレジストリにyamada-uiというパッケージは登録されておらず、取得を試みると404が返ります。正しくは@yamada-ui/reactです。

この混乱にはv1時代の事情があります。v1系ではコンポーネントごとにパッケージが切られており、@yamada-ui/button、@yamada-ui/table、@yamada-ui/form-control、@yamada-ui/coreのように分割されていました。なお分割パッケージは本体と別採番で、たとえば@yamada-ui/form-controlの最終版は2.1.15ですが、これはv2世代ではなくv1世代のものです。

v2.0.0（2025年7月15日公開）でこれらが統合されました。分割パッケージ群は2025年8月7日を最後に更新が止まっています。たとえば@yamada-ui/tableの最終版1.3.15がこの日で、v1系本体の最終版1.7.8が公開された日と同じです。現在のモノレポのpackages配下はreact・cli・utils・forge・workspaceの5つですが、forgeとworkspaceは"private": trueの内部用で、npmに公開されているのは@yamada-ui/react・@yamada-ui/cli・@yamada-ui/utilsの3つだけです。分割パッケージを新規に選ぶ理由はもうありません。

2.2.6が抱えるコンポーネント数と依存構成

2.2.6の同梱型定義を数えると、dist/types/components配下は121ディレクトリ、dist/types/hooks配下は34ディレクトリです。npmが返すtarballのメタ情報では展開後サイズが約20.7MB、ファイル数は12,059。単一パッケージに寄せた分、インストール直後の重量はそれなりにあります。

依存関係を見ると、このライブラリが何を外部に任せているかが分かります。スタイリングはEmotion、アニメーションはmotion、通知はsonner（^2.0.7）、グラフはrecharts（^3.9.2）、テーブルは@tanstack/react-table（^8.21.3）、カルーセルはembla-carousel、アイコンはlucide-reactです。つまりチャートやテーブルは自前実装ではなく、実績のあるライブラリを包んだうえで統一されたテーマ体系に乗せる方針を取っています。これらはpeerDependenciesではなく通常のdependenciesなので、既にrechartsや@tanstack/react-tableを直接使っているプロジェクトでは、メジャーバージョンがずれると別コピーが入ってバンドルが二重になります。導入前に自分側のレンジと突き合わせておくのが安全です。

導入手順とUIProviderの配置

インストールは1コマンドで終わります。

npm install @yamada-ui/react

peerDependenciesはreact が >=19、react-dom が >=19、@emotion/reactと@emotion/styledが >=11、motionが >=12 です。公式ドキュメントもReact 18以前は非対応と明記しています。ここは妥協点がなく、React 18に固定されているプロジェクトではv2を入れられません。その場合はv1系の最終版1.7.8を使うか、React 19への更新を先に済ませる必要があります。React 19側の変更点はReact 19.2の新機能総まとめにまとめてあります。

コンポーネントを動かす条件は、アプリのルートをUIProviderで包むことです。テーマ・カラーモード・通知・ローディングの各コンテキストがここで供給されるため、包み忘れると個々のコンポーネントが期待どおりに描画されません。

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

export function App({ children }: PropsWithChildren) {
  return <UIProvider>{children}</UIProvider>
}

セマンティックトークンによるカラーモード設計

Yamada UIのカラーモードで特徴的なのは、コンポーネント側に「ダークならこの色」という分岐をほとんど書かない点です。1つのトークンにライト用とダーク用の2値を持たせ、切り替えはトークン解決の層で完結させます。

extendThemeによる1トークン2値の定義

既定テーマのセマンティックトークンは、多くが値を配列で持ちます。型定義を読むとbg.baseは["white", "black"]、fg.baseは["#171717", "#ededed"]、border.baseは["black.100", "white.200/70"]という具合で、配列の1番目がライトモード、2番目がダークモードに対応します（bg.overlayのようにモードを問わない単一値のトークンもあります）。

独自のブランド色も同じ書き方で足せます。extendThemeは引数を既定テーマへディープマージした結果を返す関数なので、戻り値をそのままUIProviderのthemeに渡します。既定トークンを消してしまう心配はありません。

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

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

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

これでbg="brand"と書くだけで、ライトではblue.600、ダークではblue.300が当たります。色の対応表がテーマ側に1か所だけ存在する形になるため、ダークモード対応漏れがコンポーネント単位で散らばりません。

useColorModeとuseColorModeValueでの切り替え

useColorModeが返すコンテキストのうち、実務で使うのはcolorMode・internalColorMode・changeColorMode・toggleColorModeの4つです（型定義にはこのほかにforcedがあります）。colorModeは解決済みのlightかdark、internalColorModeはユーザー設定としてのsystemを含む値で、「OS設定に従う」を選択肢に出すUIではこの2つを使い分けます。色以外の値をモードで切り替えたいときはuseColorModeValueを使います。

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" size="md" onClick={toggleColorMode}>
        {label}（現在: {colorMode}）
      </Button>
    </Box>
  )
}

選択したモードの保存先は既定でlocalStorageです。サーバーサイドレンダリングを使う構成では、ここが必ず問題になります。サーバー側はlocalStorageを読めないため初回HTMLはライト前提で返り、クライアントで復元した瞬間に色が入れ替わる、いわゆるちらつきが起きます。型定義でもstorageのコメントがサーバーサイドレンダリング時はcookieを使うよう指示しており、型は"cookie" | "localStorage"の2値です。対処はUIProviderにstorage="cookie"を渡すことです。colorModeStorageKeyは保存キーの名前を変えるだけでストレージ自体は切り替わらないため、これだけ指定してもちらつきは消えません。

useLoading・useNoticeによる非同期処理のUI標準化

画面ごとにconst [loading, setLoading] = useState(false)を書き、スピナーの位置とトーストの実装を各画面で決める、という進め方は規模が大きくなるほど破綻します。Yamada UIはこの2つをProvider側の関心事として切り出しています。

useLoadingが返すのはbackground・page・screenの3系統で、それぞれにstart・finish・update・forceが生えています。画面全体を覆うのがscreen、ページ遷移向けがpage、邪魔をしない控えめな表示がbackgroundという住み分けです。通知側のuseNoticeは内部でSonnerを使っており、返る関数にclose・closeAll・updateが付属します。

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

export function SaveButton() {
  const notice = useNotice()
  const { screen } = useLoading()

  const onClick = async () => {
    screen.start({ message: "保存中" })

    try {
      await fetch("/api/save", { method: "POST" })
      notice({ description: "保存しました", status: "success" })
    } catch {
      notice({ description: "保存に失敗しました", status: "error" })
    } finally {
      screen.finish()
    }
  }

  return <Button variant="solid" onClick={onClick}>保存</Button>
}

ボタン単位でスピナーを出したいだけなら、Button自体がloadingを受け取ります。loadingIconで見た目を、loadingPlacementでstartかendかを指定でき、押下中の表示のためにコンポーネントを自作する必要はありません。フォームの状態管理まで含めて整理したい場合は、React Hook Formの使い方と組み合わせる構成が定番です。

v1からv2への移行で書き換えが必要な箇所

Yamada UIを扱う日本語記事の多くはv1時代に書かれており、v2.0.0（2025年7月15日公開）以降の変更が反映されていません。既存プロジェクトを上げるときに実際に手が入るのは、次の2か所です。

React 19必須化と周辺依存の入れ替え

v1系はReact 18で動きましたが、v2系はpeerDependenciesでReact 19以上を要求します。加えてアニメーション基盤の指定がmotion >=12 になっており、framer-motionを直接入れている構成では置き換えが必要です。Emotionは@emotion/react・@emotion/styledともに >=11 のままです。

React 19への更新が当面できないなら、v2への移行は見送るべきです。v1系の最終版1.7.8は2025年8月7日公開で以降更新が止まっており、期限付きの選択肢である点は認識しておく必要があります。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種、sizeはxsから2xlまでの6段階です。MUIのcontainedやoutlinedとは語彙が違うため、他ライブラリの記憶で書くと型エラーになります。

Chakra UI・MUIとの選定基準

Yamada UIはChakra UIの設計思想を色濃く受け継いでおり、propsでスタイルを当てる書き味はほぼ地続きです。判断材料になる数値を並べます（いずれも2026年8月6日時点）。

スター数はMUIとおよそ97倍、Chakra UIともおよそ40倍の開きがあります。詰まったときに先行事例へ当たれる量では、この2つが明確に有利です。それでもYamada UIを選ぶ理由になるのは、公式ドキュメントが日本語で整備されている点に尽きます。UIライブラリの学習コストの大半はコンポーネント固有のprops名を引く時間で、これが母語で読めるかどうかは、チームにReact経験の浅いメンバーがいるほど効いてきます。

逆に採用を見送るべき場面もはっきりしています。React 18に固定されたレガシー環境、Material Designの見た目が要件に含まれる案件、そして開発者の入れ替わりが激しく採用実績の多さそのものが要件になるチームでは、無理に選ぶ必要はありません。propsでスタイルを当てる方式そのものを避け、Web標準寄りの設計を採る選択肢もあり、その考え方はRemix 3のコンポーネントライブラリが分かりやすい対比になります。画面設計の粒度からライブラリを決めたい場合は業務システムの画面デザインとライブラリ選定を先に読むと判断が早くなります。

よくある質問

Yamada UIのnpmパッケージ名は何ですか？

@yamada-ui/reactです。npm install @yamada-ui/reactでインストールします。yamada-uiというスコープなしの名前でnpmレジストリを引くと404が返ります。

UIProviderは必ず設置する必要がありますか？

必要です。テーマ・カラーモード・通知・ローディングの各コンテキストがUIProviderから供給されるため、アプリのルートで包まないとコンポーネントが期待どおりに動きません。テーマを差し替えないうちはthemeを渡さず<UIProvider>とだけ書けば既定テーマが適用されます。

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

v2系は使えません。2.2.6のpeerDependenciesはreact・react-domともに >=19 で、公式ドキュメントもReact 18以前は非対応と記載しています。React 18のまま使うならv1系の最終版1.7.8（2025年8月7日公開）が上限で、以降の更新は入っていません。

コンポーネントごとに個別インストールできますか？

v2ではできません。v1では@yamada-ui/buttonのようにコンポーネント単位でパッケージが分かれていましたが、v2.0.0で@yamada-ui/reactへ統合されました。ただしパッケージ内のサブパスは公開されており、import { Button } from "@yamada-ui/react/components/button"のような個別importは通ります。バンドルサイズを抑えたい場合は、個別インストールではなくこの形かバンドラのツリーシェイキングに任せます。

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

公式サイトyamada-ui.comに日本語版（/ja 配下）が用意されており、導入手順から各コンポーネントのprops一覧まで日本語で読めます。リポジトリのREADMEとコントリビューションガイドにも日本語版があります。

関連記事

• React 19.2の新機能総まとめ：<Activity>コンポーネントやuseEffectEvent、cacheSignalなど注目ポイント徹底解説
• 業務システムの画面デザイン｜実装者向けUI設計パターンとライブラリ選定
• React Hook Formとは？使い方・バリデーション・v7の書き方を実例で解説
• Remix 3 の新しいコンポーネントライブラリとは何か：Web標準ベースのUIコンポーネント設計を解説