shadcn-ui

Next.js 向け Shadcn UI

概要

Shadcn UI は、Radix UI と Tailwind CSS を基盤に構築された、再利用可能なコンポーネントのコレクションです。npm パッケージではありません。代わりに、CLI がコンポーネントのソースコードをプロジェクト内の components/ui/ に直接コピーします。これにより、すべてのコンポーネントを完全に所有し、制御できます。すべてのコンポーネントはデフォルトでアクセシブル（Radix による）で、Tailwind CSS でスタイル設定されており、組み合わせて使用できます。

公式ドキュメント： https://ui.shadcn.com

クイックスタート

既存の Next.js プロジェクトで Shadcn UI を初期化します。

npx shadcn@latest init

必要に応じてコンポーネントを追加します。

npx shadcn@latest add button card dialog

インポートして使用します。

import { Button } from "@/components/ui/button"

export default function Page() {
  return <Button variant="outline">Click me</Button>
}

CLI の全リファレンス（すべてのコマンド、フラグ、components.json のスキーマ）については、references/cli-and-configuration.md を参照してください。

基本的なワークフロー

Shadcn UI を使って構築する際は、次の標準的な手順に従ってください。

1. 初期化 — npx shadcn@latest init を実行して components.json を生成し、パスを設定します
2. コンポーネントを追加 — 必要なコンポーネントごとに npx shadcn@latest add [name] を実行します
3. UI を構成 — ページやレイアウトでコンポーネントを組み合わせ、インタラクティブなコンポーネントは "use client" でラップします
4. テーマ — globals.css で CSS 変数を設定し、ライトモード／ダークモードを構成します
5. カスタマイズ — 必要に応じて components/ui/ 内のコンポーネントのソースを直接編集します

コンポーネントのインポート規約

すべての Shadcn コンポーネントは components/ui/ にインストールされ、@/ パスエイリアスを使用します。

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
import { Dialog, DialogTrigger, DialogContent } from "@/components/ui/dialog"

すべての Shadcn コンポーネントは内部的に クライアントコンポーネント（Radix UI のフックを使用）です。Next.js App Router で使用する場合は、次のいずれかを行います。

• ファイルの先頭に "use client" があるファイルにインポートする、または
• クライアントコンポーネントのラッパー内にインポートする

コンポーネントの完全なカタログ（カテゴリ別、インストールコマンド、インポート、バリエーションを含む）については、references/components.md を参照してください。

Next.js App Router との統合

サーバーコンポーネントとクライアントコンポーネント

Shadcn コンポーネントは Radix UI のプリミティブ（フック、ref、イベントハンドラー）を使用するため、クライアントランタイムが必要です。次のルールを適用してください。

シナリオ	方法
Shadcn コンポーネントのみを含むページ	ページファイルに "use client" を追加します
データ取得と UI が混在するページ	ページはサーバーコンポーネントのままにし、インタラクティブな部分をクライアントコンポーネントに切り出します
プロバイダーを含むレイアウト	"use client" のラッパーコンポーネントにプロバイダーを追加します

layout.tsx でのプロバイダーの設定

専用のクライアントコンポーネントにグローバルプロバイダーを配置します。

// app/providers.tsx
"use client"
import { ThemeProvider } from "next-themes"
import { TooltipProvider } from "@/components/ui/tooltip"

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <TooltipProvider>
        {children}
      </TooltipProvider>
    </ThemeProvider>
  )
}

// app/layout.tsx (Server Component)
import { Providers } from "./providers"

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

レイアウトのパターン、レスポンシブデザイン、コンポーネントの構成については、references/composition-patterns.md を参照してください。

フォームの構築

Shadcn のフォームでは、検証に React Hook Form と Zod を、UI に Shadcn Form コンポーネントを使用します。

npx shadcn@latest add form input label
npm install zod

基本的なパターン：

"use client"
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { z } from "zod"
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"

const schema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function MyForm() {
  const form = useForm<z.infer<typeof schema>>({
    resolver: zodResolver(schema),
    defaultValues: { email: "", name: "" },
  })

  function onSubmit(values: z.infer<typeof schema>) {
    // handle submission
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
        <FormField control={form.control} name="email" render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl><Input placeholder="[email protected]" {...field} /></FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  )
}

高度なフォームのパターン（セレクト、チェックボックス、日付ピッカー、動的配列、Server Actions）については、references/forms.md と examples/form-with-validation.tsx を参照してください。

データテーブル

Shadcn のデータテーブルでは、3 ファイル構成の TanStack Table を使用します。

npx shadcn@latest add table
npm install @tanstack/react-table

ファイル	用途
columns.tsx	アクセサー、ヘッダー、セルのレンダラーを指定した ColumnDef[] を定義します
data-table.tsx	useReactTable を使用する、再利用可能な <DataTable> コンポーネントです
page.tsx	データを取得（サーバーコンポーネント）し、<DataTable> に渡します

列の定義、並べ替え、フィルタリング、ページネーション、行選択のパターンについては、references/data-tables.md と examples/data-table-example.tsx を参照してください。

テーマ設定

Shadcn UI では、すべてのカラー・トークンに globals.css の CSS 変数を使用します。現在の Shadcn では oklch カラーフォーマットを使用します。

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* ... */
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* ... */
}

next-themes でダークモードを有効にします。

npm install next-themes

変数の完全な一覧、ダークモード切り替えコンポーネント、TweakCN エディターのワークフロー、サイドバーのトークン、カスタムカラーについては、references/theming-and-dark-mode.md を参照してください。

チャート

Shadcn Charts は、テーマ対応のコンポーネントで Recharts をラップしています。

npx shadcn@latest add chart
npm install recharts

基本パターン：データキーをラベルと色に対応付ける ChartConfig オブジェクトを定義し、Recharts のコンポーネントを <ChartContainer> でラップします。

const chartConfig = {
  desktop: { label: "Desktop", color: "var(--chart-1)" },
  mobile: { label: "Mobile", color: "var(--chart-2)" },
} satisfies ChartConfig

すべてのチャートタイプ、ツールチップ／凡例の設定、レスポンシブ対応のパターンについては、references/charts.md と examples/chart-config-example.tsx を参照してください。

ブロック

ブロックは、ページ全体またはセクション単位の、あらかじめ構築された構成要素（ダッシュボード、ログインページ、サイドバーなど）です。ブロックのソースをプロジェクトにコピーし、必要なコンポーネントをインストールしてください。

ブロックカタログ、ファイル構成、依存関係、サイドバーシステムについては、references/blocks.md と examples/dashboard-layout.tsx を参照してください。

主なルール

推奨事項	禁止事項
npx shadcn@latest add を使用してコンポーネントをインストールする	npm でコンポーネントをインストールする
@/components/ui/... からインポートする	shadcn または @shadcn/ui からインポートする
テーマ設定には CSS 変数（oklch）を使用する	コンポーネントに色の値をハードコードする
インタラクティブなコンポーネントを使用する場合は "use client" を追加する	クライアント側のラッパーなしで、Server Components 内で Shadcn コンポーネントを使用する
カスタマイズするには components/ui/ のコンポーネントソースを編集する	単純なスタイル変更のためにラッパーコンポーネントを作成する
ブロックに必要な依存関係をすべてインストールする	必要なコンポーネントを追加せずにブロックのコードをコピーする

リファレンスファイル

詳細ガイド

• references/cli-and-configuration.md — CLI コマンド、components.json スキーマ、エイリアス、パッケージマネージャー
• references/components.md — 種類別に分類された全コンポーネントカタログ、バリアント、インポート
• references/composition-patterns.md — レイアウトパターン、Server／Client コンポーネント、プロバイダー、レスポンシブデザイン
• references/forms.md — React Hook Form + Zod + Shadcn Form コンポーネントのパターン
• references/data-tables.md — TanStack Table の統合、列、並べ替え、フィルタリング、ページネーション
• references/charts.md — Recharts の統合、ChartConfig、全チャートタイプ、ツールチップ
• references/blocks.md — ブロックカタログ、サイドバーシステム、ダッシュボードのパターン、依存関係
• references/theming-and-dark-mode.md — CSS 変数、oklch、next-themes、TweakCN、カスタムカラー
• references/accessibility.md — Radix に組み込まれたアクセシビリティ機能、開発者の責任、ARIA パターン

コード例

• examples/form-with-validation.tsx — Zod スキーマ、複数のフィールドタイプ、送信ハンドラーを含む完全なフォーム
• examples/data-table-example.tsx — 列、並べ替え、ページネーションを備えたデータテーブル
• examples/dashboard-layout.tsx — サイドバー、ヘッダー、コンテンツ領域を備えたダッシュボードレイアウト
• examples/chart-config-example.tsx — 完全な ChartConfig、ツールチップ、凡例を備えた棒グラフ