shadcn-ui

shadcn/ui

概要

shadcn/ui は、Radix UI と Tailwind CSS を基盤に構築された、アクセシビリティに配慮したカスタマイズ可能な React コンポーネントのコレクションです。コンポーネントはプロジェクトにコピーされるため（npm パッケージはありません）、コードは自分で所有し、編集できます。Next.js（App Router）、Vite、その他の React フレームワークで動作します。

原則：オープンコード（AI 対応）、コンポーザブルな API、美しいデフォルト設定、CLI とスキーマによる配布。Tailwind v4 とパスエイリアス @/* が必要です。tailwind.config.js は使用せず、テーマとセットアップは CSS のみで行います（@import "tailwindcss" + @theme）。

---

前提条件

• Tailwind v4：メインの CSS に @import "tailwindcss" を記述し、@tailwindcss/vite または @tailwindcss/postcss を使用します。tailwind.config.js は不要です。tailwind-css スキルを参照してください。
• パスエイリアス @/* → ./src/*（またはソースルート）を tsconfig とバンドラー（例：Vite の resolve.alias）に設定します。
• React（Next.js App Router、Vite など）。

---

インストール

参考：公式インストールガイド

新規プロジェクト（推奨）

Tailwind と shadcn を使用してプロジェクトを生成します。公式ドキュメントより：

操作	CLI コマンド
新規プロジェクト	shadcn create
既存プロジェクトを初期化	shadcn init
コンポーネントを追加	shadcn add <name>

パッケージマネージャーから実行します（ドキュメントを参照）。フレームワーク（Next.js、Vite など）、スタイル（new-york を推奨）、ベースカラー、CSS 変数を選択します。

既存プロジェクト（Next.js App Router）

1. 初期化 — components.json、任意の cn ヘルパー、基本スタイルを作成します。実行：shadcn init（パッケージマネージャーから実行します。上記のドキュメントを参照）。

2. パスと Tailwind

   • tsconfig："baseUrl": "."、"paths": { "@/*": ["./src/*"] }（分割している場合は、ルートと app の両方の tsconfig に設定）。
   • Tailwind v4：メインの CSS（例：app/globals.css）に @import "tailwindcss" を記述し、postcss.config.mjs で @tailwindcss/postcss を使用する必要があります。tailwind.config.js は追加しないでください。

3. コンポーネントを追加 — 例：shadcn add button、shadcn add card dialog（下記のコンポーネント一覧を参照）。

コンポーネントは src/components/ui/（または components.json で指定したパス）にインストールされます。

既存プロジェクト（Vite）

• vite.config.ts で resolve.alias: { "@": path.resolve(__dirname, "./src") } を使用します。path を使用する場合は @types/node を追加します。
• Tailwind：Vite の設定に @tailwindcss/vite を追加し、メインの CSS に @import "tailwindcss" を記述します。

---

components.json

スタイル、パス、Tailwind との連携を制御します。主なフィールド：

フィールド	用途
style	"new-york"（新規プロジェクトのデフォルト）または "default"
tailwind.config	Tailwind v4 では "" のままにします。JS 設定ファイルは使用しません
tailwind.css	グローバル CSS（例：src/styles/globals.css または app/globals.css）のパス。ファイルには @import "tailwindcss" を記述します
tailwind.baseColor	テーマのベースカラー：neutral、slate、gray、zinc、stone
tailwind.cssVariables	CSS 変数によるテーマ設定を使用する場合は true（推奨）
aliases.components	例：@/components
aliases.utils	例：@/lib/utils
aliases.ui	例：@/components/ui
rsc	Server Components を使用する Next.js App Router では true、クライアント専用では false

Tailwind v4 では、テーマは設定ファイルではなく、@theme と CSS 変数を使って CSS に記述します。

---

公式コンポーネント（現在の一覧）

shadcn add <name> で追加します（複数の場合：shadcn add button card dialog）。パッケージマネージャーから実行します。Installation のドキュメントを参照してください。

レイアウトと構造

コンポーネント	CLI 名	簡単な説明
Accordion	accordion	折りたたみ可能なセクション（単一または複数を開いた状態にできます）
Aspect Ratio	aspect-ratio	固定比率（例：16/9）のコンテナー
Card	card	CardHeader、CardTitle、CardDescription、CardContent、CardFooter を含むコンテナー
Collapsible	collapsible	展開・折りたたみ可能なコンテンツ
Resizable	resizable	サイズ変更可能なパネル
Separator	separator	水平または垂直の区切り線
Scroll Area	scroll-area	スタイル設定されたスクロール領域
Sidebar	sidebar	組み合わせ可能で、テーマやカスタマイズに対応したサイドバー

フォームと入力

コンポーネント	CLI 名	簡単な説明
Button	button	バリエーション（default、destructive、outline、secondary、ghost、link）を備えたボタン
Checkbox	checkbox	チェックボックス
Form	form	react-hook-form と zod を使用したフォーム（Field、FieldError など）
Input	input	テキスト入力
Input OTP	input-otp	OTP コード入力
Label	label	コントロール用のアクセシブルなラベル
Radio Group	radio-group	ラジオボタンの選択肢グループ
Select	select	Trigger、Content、Item を備えた選択メニュー
Slider	slider	スライダーコントロール
Switch	switch	オン／オフ切り替えスイッチ
Textarea	textarea	複数行のテキスト領域

ナビゲーションとメニュー

コンポーネント	CLI 名	簡単な説明
Breadcrumb	breadcrumb	パンくずナビゲーション
Command	command	コマンドパレット（cmdk）
Context Menu	context-menu	コンテキストメニュー（右クリック）
Dropdown Menu	dropdown-menu	ドロップダウンメニュー
Menubar	menubar	常時表示されるメニューバー
Navigation Menu	navigation-menu	サブメニュー付きのナビゲーション
Pagination	pagination	ページネーション（Previous、Next、Page）
Tabs	tabs	タブ（TabsList、TabsTrigger、TabsContent）

オーバーレイとフィードバック

コンポーネント	CLI 名	簡単な説明
Alert	alert	目立つメッセージ（default、destructive）
Alert Dialog	alert-dialog	確認ダイアログ（例：削除）
Dialog	dialog	モーダル
Drawer	drawer	サイドパネル（Vaul）
Hover Card	hover-card	ホバー時に表示されるカード
Popover	popover	アンカーに固定されたフローティングコンテナー
Sheet	sheet	スライド式のサイドパネル
Tooltip	tooltip	ホバー時またはフォーカス時に表示されるツールチップ

データと状態

コンポーネント	CLI 名	簡単な説明
Avatar	avatar	画像または代替表示となるイニシャル
Badge	badge	バッジ（default、secondary、destructive、outline）
Calendar	calendar	カレンダー（react-day-picker）
Carousel	carousel	カルーセル（embla）
Chart	chart	チャート（recharts）
Progress	progress	プログレスバー
Skeleton	skeleton	読み込み中のプレースホルダー
Sonner	sonner	トースト（推奨。toast の代替）
Table	table	Table、TableHeader、TableBody、TableRow、TableCell など
Toast	toast	トースト（非推奨。Sonner の使用を推奨）

トグルとトグルグループ

コンポーネント	CLI 名	簡単な説明
Toggle	toggle	トグルボタン（オン／オフ）
Toggle Group	toggle-group	トグルグループ（単一または複数）

---

コンポーネントの使用

エイリアス付きのパスからインポートします（shadcn/ui からはインポートしません）。

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

export default function Page() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center gap-4">
      <Button>Click me</Button>
      <Card className="w-[350px]">
        <CardHeader>
          <CardTitle>Card title</CardTitle>
        </CardHeader>
        <CardContent>Content here.</CardContent>
      </Card>
    </div>
  )
}

• カスタマイズ：コンポーネントは className を受け取り、props を展開します。Tailwind クラスと cn() ヘルパー（@/lib/utils から）を使ってクラスを結合してください。
• コンポジション：レイアウトには props よりも、コンポジション（例：CardHeader と CardContent）を優先してください。

---

テーマ設定（Tailwind v4、設定ファイルなし）

Tailwind v4 のみを使用し、tailwind.config.js は使用しません。テーマ設定は CSS のみで行います。

• CSS 変数：tailwind.cssVariables: true の場合、テーマはグローバル CSS の変数（例：--background、--foreground、--primary、--primary-foreground、--muted、--muted-foreground、--accent、--destructive など）によって制御されます。そのファイル内で上書きしてください。
• @theme：shadcn の変数に合わせたデザイントークンを追加または上書きするには、@import "tailwindcss" と同じ CSS ファイル内で @theme { ... } を使用します。
• ベースカラー：components.json（tailwind.baseColor）で設定するか、グローバル CSS の CSS 変数を編集して設定します。

---

よく使われるパターン

• フォーム：form を追加し、react-hook-form と zod を組み合わせます。Input、Label、Button、Select、Checkbox などを使用します。
• レイアウト：セクションには Card、ブロック間には Separator を使用します。レイアウトには Tailwind（flex、grid、container）を使用します。
• モーダルとパネル：モーダルには Dialog、サイドパネルには Sheet または Drawer を使用します。
• メニュー：DropdownMenu、Context Menu、Navigation Menu、Command（パレット）を使用します。
• フィードバック：メッセージには Alert、トーストには Sonner、読み込み中の表示には Skeleton を使用します。
• アイコン：多くの例では lucide-react を使用しています。プロジェクトでアイコンを使用する場合は追加してください。

---

よくある間違い

• エイリアス：TypeScript とバンドラーの両方で、@/ が ./src/（またはソースルート）を参照することを確認してください。
• CSS が読み込まれない：components.json（tailwind.css）で指定したファイルをアプリのエントリーポイント（例：app/layout.tsx）でインポートし、@import "tailwindcss" を含める必要があります。
• Tailwind の設定：tailwind.config.js を作成したり、作成を提案したりしないでください。テーマ設定は CSS（@theme と変数）のみで行います。
• インポート：shadcn/ui ではなく、@/components/ui/<component>（components.json の設定による）からインポートしてください。
• RSC：Next.js App Router で、該当する場合にコンポーネントを Server Components で使用するなら、components.json で rsc: true を設定してください。

---

追加リソース

• reference.md — 公式ドキュメントへのリンク、Tailwind v4 と shadcn、コンポーネントディレクトリ。
• 公式ドキュメント：https://ui.shadcn.com/docs
• コンポーネント：https://ui.shadcn.com/docs/components
• ディレクトリ（コミュニティ）：https://ui.shadcn.com/docs/directory