shadcn-vue

shadcn-vue

UI、コンポーネント、デザインシステムを構築するためのフレームワークです。CLI を通じて、コンポーネントがソースコードとしてユーザーのプロジェクトに追加されます。

IMPORTANT: すべての CLI コマンドは、プロジェクトの packageManager に応じて、プロジェクトのパッケージランナーを使って実行してください。npx shadcn-vue@latest、pnpm dlx shadcn-vue@latest、または bunx --bun shadcn-vue@latest を使用します。以下の例では npx shadcn-vue@latest を使用していますが、プロジェクトに適したランナーに置き換えてください。

現在のプロジェクトコンテキスト

!`npx shadcn-vue@latest info --json`

上記の JSON には、プロジェクトの設定とインストール済みコンポーネントが含まれています。任意のコンポーネントのドキュメントとサンプル URL を取得するには、npx shadcn-vue@latest docs <component> を使用してください。

原則

1. まず既存のコンポーネントを使用します。 カスタム UI を作成する前に、npx shadcn-vue@latest search を使ってレジストリを確認してください。コミュニティのレジストリも確認してください。
2. 一から作らず、組み合わせて使います。 設定ページ＝Tabs + Card + フォームコントロール。ダッシュボード＝Sidebar + Card + Chart + Table。
3. カスタムスタイルより、組み込みのバリアントを先に使います。 variant="outline"、size="sm" など。
4. セマンティックカラーを使用します。 bg-primary、text-muted-foreground を使い、bg-blue-500 のような生の値は使用しないでください。

重要なルール

これらのルールは常に適用されます。各ルールには、誤ったコードと正しいコードの組み合わせを示すファイルへのリンクがあります。

スタイリングと Tailwind → rules/styling.md

• レイアウトには class を使い、スタイリングには使いません。 コンポーネントの色やタイポグラフィを上書きしないでください。
• space-x-* や space-y-* は使用しません。 gap-* を使った flex を使用してください。縦方向に積み重ねる場合は、flex flex-col gap-* を使用します。
• 幅と高さが等しい場合は size-* を使用します。 w-10 h-10 ではなく size-10 を使います。
• 省略形の truncate を使用します。 overflow-hidden text-ellipsis whitespace-nowrap は使用しないでください。
• 手動で dark: の色を上書きしません。 セマンティックトークン（bg-background、text-muted-foreground）を使用してください。
• 条件付きクラスには cn() を使用します。 手動でテンプレートリテラルの三項演算子を書かないでください。
• オーバーレイコンポーネントに手動で z-index を設定しません。 Dialog、Sheet、Popover などは、それぞれ独自に重なり順を処理します。

フォームと入力 → rules/forms.md

• フォームには FieldGroup + Field を使用します。 フォームのレイアウトに space-y-* や grid gap-* を使った生の div は使用しないでください。
• InputGroup では InputGroupInput／InputGroupTextarea を使用します。 InputGroup 内に生の Input／Textarea を配置しないでください。
• 入力内のボタンには InputGroup + InputGroupAddon を使用します。
• 選択肢（2～7個）には ToggleGroup を使用します。 Button をループしてアクティブ状態を手動で管理しないでください。
• 関連するチェックボックスやラジオボタンのグループには FieldSet + FieldLegend を使用します。 見出しを含む div は使用しないでください。
• フィールドの検証には data-invalid + aria-invalid を使用します。 Field に data-invalid、コントロールに aria-invalid を設定します。無効化する場合は、Field に data-disabled、コントロールに disabled を設定します。

コンポーネントの構造 → rules/composition.md

• アイテムは必ず対応する Group の中に配置します。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• Dialog、Sheet、Drawer には必ず Title が必要です。 アクセシビリティのため、DialogTitle、SheetTitle、DrawerTitle が必要です。視覚的に非表示にする場合は class="sr-only" を使用します。
• Card の構成要素をすべて使用します。 CardHeader／CardTitle／CardDescription／CardContent／CardFooter を使用します。すべてを CardContent に詰め込まないでください。
• Button に isPending／isLoading はありません。 Spinner + data-icon + disabled を組み合わせて使用します。
• TabsTrigger は必ず TabsList の中に配置します。 Tabs の直下にトリガーを描画しないでください。
• Avatar には必ず AvatarFallback が必要です。 画像の読み込みに失敗した場合に表示されます。

カスタムマークアップではなくコンポーネントを使う → rules/composition.md

• カスタムマークアップを書く前に、既存のコンポーネントを使ってください。 スタイル付きの div を書く前に、該当するコンポーネントがあるか確認してください。
• コールアウトには Alert を使ってください。 独自のスタイルを適用した div を作成しないでください。
• 空の状態には Empty を使ってください。 独自の空状態用マークアップを作成しないでください。
• トーストには vue-sonner を使ってください。 vue-sonner の toast() を使ってください。
• <hr> や <div class="border-t"> の代わりに Separator を使ってください。
• 読み込み中のプレースホルダーには Skeleton を使ってください。独自の animate-pulse div は使わないでください。
• 独自のスタイルを適用した span の代わりに Badge を使ってください。

アイコン → rules/icons.md

• Button 内のアイコンには data-icon を使ってください。 アイコンに data-icon="inline-start" または data-icon="inline-end" を指定します。
• コンポーネント内のアイコンにはサイズ指定のクラスを使わないでください。 アイコンのサイズはコンポーネントが CSS で調整します。size-4 や w-4 h-4 は使わないでください。
• アイコンは文字列キーではなく、オブジェクトとして渡してください。 文字列で検索するのではなく、:icon="CheckIcon" と指定します。
• インポートにはプロジェクトの iconLibrary を使ってください。 プロジェクトのコンテキストから iconLibrary を確認してください。@lucide/vue が使えると決めつけないでください。

CLI

• CLI でプリセットコードを直接適用してください。 既存のプロジェクトには npx shadcn-vue@latest apply <code> を使い、初期化時には npx shadcn-vue@latest init --preset <code> を使ってください。

主なパターン

以下は、正しい shadcn-vue コードとそれ以外を区別する、最も一般的なパターンです。例外的なケースについては、上記のリンク先のルールファイルを参照してください。

<FieldGroup>
  <Field>
    <FieldLabel for="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>


<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>


<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>


<div class="flex flex-col gap-4">  
<div class="space-y-4">           


<Avatar class="size-10">   
<Avatar class="w-10 h-10"> 


<Badge variant="secondary">+20.1%</Badge>    
<span class="text-emerald-600">+20.1%</span> 

コンポーネントの選択

用途	使用するもの
ボタン／アクション	適切なバリアントの Button
フォーム入力	Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider
2～7 個の選択肢の切り替え	ToggleGroup + ToggleGroupItem
データ表示	Table、Card、Badge、Avatar
ナビゲーション	Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination
オーバーレイ	Dialog（モーダル）、Sheet（サイドパネル）、Drawer（ボトムシート）、AlertDialog（確認）
フィードバック	vue-sonner（トースト）、Alert、Progress、Skeleton、Spinner
コマンドパレット	Dialog 内の Command
グラフ	Chart（Unovis をラップ）
レイアウト	Card、Separator、Resizable、ScrollArea、Accordion、Collapsible
空の状態	Empty
メニュー	DropdownMenu、ContextMenu、Menubar
ツールチップ／情報	Tooltip、HoverCard、Popover

主要なフィールド

注入されたプロジェクトコンテキストには、次の主要なフィールドが含まれます。

• aliases → インポートには実際のエイリアスプレフィックス（例：@/、~/）を使用し、ハードコードしないでください。
• tailwindVersion → "v4" では @theme inline ブロックを使用し、"v3" では tailwind.config.js を使用します。
• tailwindCssFile → カスタム CSS 変数を定義するグローバル CSS ファイルです。必ずこのファイルを編集し、新しいファイルは作成しないでください。
• style → コンポーネントのビジュアルスタイル（例：nova、vega）です。
• base → プリミティブライブラリ（reka）です。コンポーネント API と利用可能なプロパティに影響します。
• iconLibrary → アイコンのインポート先を決定します。lucide には @lucide/vue、tabler には @tabler/icons-vue などを使用します。@lucide/vue を前提にしないでください。
• resolvedPaths → コンポーネント、ユーティリティ、フックなどの正確なファイルシステム上の配置先です。
• framework → ルーティングとファイルの規則（例：Nuxt と Vite SPA）を決定します。
• packageManager → shadcn-vue 以外の依存関係をインストールする場合は、これを使用します（例：pnpm add date-fns と npm install date-fns）。

すべてのフィールドのリファレンスについては、cli.md — info コマンドを参照してください。

コンポーネントのドキュメント、例、使用方法

npx shadcn-vue@latest docs <component> を実行すると、コンポーネントのドキュメント、例、API リファレンスの URL を取得できます。実際の内容を確認するには、これらの URL を取得してください。

npx shadcn-vue@latest docs button dialog select

コンポーネントの作成、修正、デバッグ、使用時は、必ず最初に npx shadcn-vue@latest docs を実行して URL を取得してください。 これにより、推測ではなく、正しい API と使用パターンに基づいて作業できます。

コンポーネントごとのドキュメントについては、このスキルの components/<component>.md を参照してください（公式リポジトリから自動生成された 70 個のコンポーネント）。

ワークフロー

1. プロジェクトのコンテキストを取得する — すでに上に挿入されています。更新が必要な場合は、npx shadcn-vue@latest info を再度実行してください。
2. まずインストール済みのコンポーネントを確認する — add を実行する前に、必ずプロジェクトのコンテキストにある components リストを確認するか、resolvedPaths.ui ディレクトリを一覧表示してください。追加されていないコンポーネントをインポートしたり、すでにインストールされているコンポーネントを再追加したりしないでください。
3. コンポーネントを検索する — npx shadcn-vue@latest search を実行します。
4. ドキュメントとサンプルを取得する — npx shadcn-vue@latest docs <component> を実行して URL を取得し、その URL にアクセスします。インストールしていないレジストリアイテムを閲覧するには、npx shadcn-vue@latest view を使用します。インストール済みコンポーネントへの変更をプレビューするには、npx shadcn-vue@latest add --diff を使用します。
5. インストールまたは更新する — npx shadcn-vue@latest add を実行します。既存のコンポーネントを更新する場合は、まず --dry-run と --diff を使って変更をプレビューしてください（下記のコンポーネントの更新を参照）。
6. サードパーティ製コンポーネントのインポートを修正する — コミュニティレジストリからコンポーネントを追加した後、追加された非 UI ファイルに @/components/ui/... のようなハードコードされたインポートパスがないか確認してください。これらはプロジェクトの実際のエイリアスと一致しません。npx shadcn-vue@latest info を使って正しい ui エイリアス（例：@workspace/ui/components）を確認し、それに合わせてインポートを書き換えてください。CLI は自身の UI ファイルのインポートを書き換えますが、サードパーティのレジストリコンポーネントでは、プロジェクトと一致しないデフォルトのパスが使われている場合があります。
7. 追加したコンポーネントを確認する — いずれかのレジストリからコンポーネントやブロックを追加した後は、必ず追加されたファイルを読み、正しいことを確認してください。サブコンポーネントの不足（例：SelectGroup なしの SelectItem）、インポートの不足、構成の誤り、重要なルールへの違反がないか確認します。また、アイコンのインポートはすべて、プロジェクトのコンテキストにある iconLibrary に置き換えてください（例：レジストリアイテムで @lucide/vue が使われていても、プロジェクトで hugeicons を使っている場合は、それに応じてインポートとアイコン名を置き換えます）。次に進む前に、すべての問題を修正してください。
8. レジストリを明示する — ユーザーがブロックやコンポーネントの追加を依頼したときに、レジストリを推測してはいけません。レジストリが指定されていない場合（例：「ログインブロックを追加して」とだけ言われ、@shadcn などが指定されていない場合）は、どのレジストリを使うか確認してください。ユーザーに代わってレジストリを決めてはいけません。
9. プリセットを切り替える — まずユーザーに、上書き、マージ、スキップのどれにするか確認してください。
   • 上書き：npx shadcn-vue@latest apply <code>。検出されたコンポーネント、フォント、CSS 変数を上書きします。
   • マージ：npx shadcn-vue@latest init --preset <code> --force --no-reinstall を実行し、次に npx shadcn-vue@latest info でインストール済みコンポーネントを一覧表示してから、各インストール済みコンポーネントに対して --dry-run と --diff を使用し、個別にスマートマージします。
   • スキップ：npx shadcn-vue@latest init --preset <code> --force --no-reinstall。コンポーネントはそのままにし、設定と CSS のみを更新します。
   • 重要：プリセットのコマンドは、必ずユーザーのプロジェクトディレクトリ内で実行してください。apply は components.json ファイルがある既存のプロジェクトでのみ動作します。CLI は components.json にある現在のベース（reka）を自動的に保持します。--dry-run の比較などでスクラッチ／一時ディレクトリを使う必要がある場合は、--base <current-base> を明示的に指定してください。プリセットコードにはベースが含まれていません。

コンポーネントの更新

ユーザーから、ローカルの変更を維持したまま上流のコンポーネントを更新するよう依頼された場合は、--dry-run と --diff を使用して適切にマージします。GitHub から raw ファイルを手動で取得してはいけません。必ず CLI を使用してください。

1. npx shadcn-vue@latest add <component> --dry-run を実行し、影響を受けるファイルをすべて確認します。
2. 各ファイルについて、npx shadcn-vue@latest add <component> --diff <file> を実行し、上流の変更とローカルの変更を確認します。
3. 差分に基づいて、ファイルごとに判断します。
   • ローカルの変更がない場合 → 安全に上書きできます。
   • ローカルの変更がある場合 → ローカルファイルを読み、差分を分析して、ローカルの変更を維持しながら上流の更新を適用します。
   • ユーザーが「すべてそのまま更新して」と言った場合 → --overwrite を使用しますが、必ず事前に確認してください。
4. ユーザーから明示的な承認を得ずに、--overwrite を使用してはいけません。

クイックリファレンス

# Create a new project.
npx shadcn-vue@latest init --name my-app --preset nova
npx shadcn-vue@latest init --name my-app --preset a2r6bw --template vite

# Initialize existing project.
npx shadcn-vue@latest init --preset nova
npx shadcn-vue@latest init --defaults  # shortcut: --template=nuxt --preset=nova (base style implied)

# Apply a preset to an existing project.
npx shadcn-vue@latest apply a2r6bw

# Add components.
npx shadcn-vue@latest add button card dialog
npx shadcn-vue@latest add --all

# Search registries.
npx shadcn-vue@latest search @shadcn -q "sidebar"

# Get component docs and example URLs.
npx shadcn-vue@latest docs button dialog select

# View registry item details (for items not yet installed).
npx shadcn-vue@latest view @shadcn/button

# Get project info.
npx shadcn-vue@latest info
npx shadcn-vue@latest info --json

名前付きプリセット： nova、vega、maia、lyra、mira、luma テンプレート： nuxt、vite、astro、laravel プリセットコード： バージョン接頭辞付きの base62 文字列（例：a2r6bw）。shadcn-vue.com から取得します。

---

クイックスタート（3 分）

Vue プロジェクト（Vite）の場合

1. shadcn-vue を初期化する

npx shadcn-vue@latest init

初期化中：

• スタイル：New York または Default（後から変更できません！）
• ベースカラー：Slate（推奨）
• CSS 変数：Yes（ダークモードに必須）

2. TypeScript のパスエイリアスを設定する

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. Vite を設定する

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import tailwindcss from "@tailwindcss/vite"; // Tailwind v4
import path from "path";

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

4. 最初のコンポーネントを追加する

npx shadcn-vue@latest add button

---

同梱リソース

テンプレート（templates/）：

• quick-setup.ts - Vue/Nuxt の完全なセットアップガイドと例（190 行）

リファレンス（references/）：

• cli.md - CLI コマンド、フラグ、プリセット、テンプレート、スマートマージ
• theming.md - テーマ設定と cssVariables
• error-catalog.md - 解決策とともに記載された、ドキュメント化済みの問題 7 件すべて（267 行）
• component-examples.md - 50 件以上のコンポーネント例とコード
• dark-mode-setup.md - ダークモードの完全な実装ガイド
• data-tables.md - TanStack Table を使用したデータテーブル

ルール（references/rules/）：

• styling.md - セマンティックカラー、バリアント、class、間隔、サイズ、省略表示、ダークモード、cn()、z-index
• forms.md - FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、検証状態
• composition.md - グループ、オーバーレイ、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button の読み込み状態
• icons.md - data-icon、アイコンのサイズ設定、オブジェクトとしてのアイコンの受け渡し、iconLibrary

コンポーネントのドキュメント（components/）：

• references/components.md - shadcn-vue の全コンポーネント（70 件）の一覧
• components/<component>.md - インストール、使用方法、例を記載した各コンポーネントのドキュメント

公式ドキュメント：

• shadcn-vue Docs：https://shadcn-vue.com
• Reka UI Docs：https://reka-ui.com
• GitHub：https://github.com/unovue/shadcn-vue

---

参照資料を読み込むタイミング

タスクに応じて、次の参照資料を読み込んでください。

1. 次の場合は references/rules/styling.md を読み込みます。

   • Tailwind クラスを使ったコンポーネントのマークアップを作成またはレビューする場合
   • スタイリングの問題や、見た目の一貫性のなさについてユーザーから相談された場合
   • セマンティックトークン、間隔、サイズの正しい使い方を確認する必要がある場合
   • トリガーフレーズ：「スタイル」「色」「間隔」「ギャップ」「ダークモード」「クラス」

2. 次の場合は references/rules/forms.md を読み込みます。

   • フォームを作成する場合、またはフォームコントロールを扱う場合
   • アクセシブルなフォームフィールドのパターンが必要な場合
   • InputGroup、ToggleGroup、FieldSet、またはバリデーション状態を扱う場合
   • トリガーフレーズ：「フォーム」「入力」「フィールド」「バリデーション」「トグルグループ」

3. 次の場合は references/rules/composition.md を読み込みます。

   • 複数のコンポーネントを組み合わせる場合
   • ダイアログ、カード、メニュー、タブ、またはオーバーレイコンポーネントを作成する場合
   • 特定の UI パターンにどのコンポーネントを使うべきか、ユーザーから尋ねられた場合
   • トリガーフレーズ：「ダイアログ」「カード」「タブ」「メニュー」「オーバーレイ」「空の状態」「アラート」

4. 次の場合は references/rules/icons.md を読み込みます。

   • ボタンやその他のコンポーネントにアイコンを追加する場合
   • アイコンのサイズや配置の問題をトラブルシューティングする場合
   • 正しいアイコンのインポートパッケージを確認する必要がある場合
   • トリガーフレーズ：「アイコン」「lucide」「tabler」「data-icon」

5. 次の場合は references/error-catalog.md を読み込みます。

   • ユーザーから「コンポーネントが見つからない」というエラーやインポートエラーについて相談された場合
   • セットアップコマンドが失敗した場合、または設定の問題が発生した場合
   • Tailwind CSS 変数や TypeScript のパスが機能しない場合
   • トリガーフレーズ：「動作しない」「エラー」「失敗する」「壊れている」

6. 次の場合は references/components.md を読み込みます。

   • どのコンポーネントが利用可能か（名前、カテゴリ、ステータス）をユーザーから尋ねられた場合
   • コンポーネントの追加や使用にあたり、正しいインストール先やインポートパスが必要な場合
   • カスタム実装を勧める前に、そのコンポーネントが存在するか確認する必要がある場合

7. 次の場合は references/component-examples.md を読み込みます。

   • ユーザーから「［コンポーネント］をどう実装すればよいですか？」と尋ねられた場合
   • 特定のコンポーネントのコピーして使える例が必要な場合
   • フォーム、テーブル、ナビゲーション、またはデータ表示を作成する場合
   • トリガーフレーズ：「例」「使い方」「実装」「コードサンプル」

8. 次の場合は references/cli.md を読み込みます。

   • CLI（init、add、update、search、view、docs、info、apply）の実行方法や、プロンプトの意味をユーザーから尋ねられた場合
   • 1 つ以上のコンポーネントをインストールするための正確なコマンドやフラグが必要な場合
   • プリセットやテンプレートを扱う場合、またはプリセットを切り替える場合
   • CLI 関連の問題（レジストリ、パス、上書き）をトラブルシューティングする場合

9. 次の場合は references/dark-mode-setup.md を読み込みます。

   • ダークモードやテーマの切り替えを実装する場合
   • Vue 3 + Vite、Nuxt、または Astro のセットアップについてユーザーから言及された場合
   • テーマ管理のコンポーザブルパターンが必要な場合
   • トリガーフレーズ：「ダークモード」「テーマ」「ライト／ダーク」「カラースキーム」

10. 次の場合は references/theming.md を読み込みます。

    • ユーザーが CSS 変数（cssVariables、:root、.dark）を使ってテーマトークンをカスタマイズしたい場合
    • Tailwind を CSS 変数ベースの色や角丸に接続する必要がある場合
    • shadcn-vue のデザイントークン（色、角丸、タイポグラフィ）を設定または調整する場合

11. 次の場合は references/data-tables.md を読み込みます。

    • 並べ替え、フィルタリング、ページネーションに対応したテーブルを作成する場合
    • ユーザーから TanStack Table または DataTable について言及された場合
    • トリガーフレーズ：「データテーブル」「テーブル」「tanstack」「並べ替え」「ページネーション」

---

重要なセットアップルール

必ず行うこと

✅ コンポーネントを追加する前に init を実行します

• 必要な設定とユーティリティを作成します
• パスエイリアスを設定します

✅ テーマ設定には CSS 変数を使用します（cssVariables: true）

• ダークモードに対応できます
• テーマを柔軟にカスタマイズできます

✅ TypeScript のパスエイリアスを設定します

• コンポーネントのインポートに必要です
• components.json のエイリアスと一致させる必要があります

✅ components.json をバージョン管理に含めます

• チームメンバー間で同じ設定を使うために必要です
• プロジェクトのセットアップを記録できます

してはいけないこと

❌ 初期化後に style を変更しないでください

• 完全な再インストールが必要です
• 代わりに、新しいディレクトリで再初期化してください

❌ Radix Vue と Reka UI v2 を混在させないでください

• コンポーネントの API に互換性がありません
• どちらか一方を使用してください

❌ TypeScript の設定を省略しないでください

• コンポーネントのインポートに失敗します
• IDE の自動補完が機能しません

❌ Tailwind CSS なしで使用しないでください

• コンポーネントは Tailwind でスタイル設定されています
• 正しくレンダリングされません

---

よくある間違い

• init の前に add を実行し、components.json がない状態になる。
• tailwind.cssVariables: true を設定せずに CSS 変数クラスを使用する。
• プロジェクトのコンテキストから aliases を読み取らず、@/ インポートをハードコードする。
• CLI を使わずに GitHub からコンポーネントファイルを手動で取得する。
• ユーザーの確認なしに --overwrite を使用する。
• ユーザーに確認せず、レジストリ名を推測する。

---

設定

shadcn-vue は components.json を使って、以下を設定します。

• コンポーネントのパス（@/components/ui）
• Utils の場所（@/lib/utils）
• Tailwind の設定ファイルのパス
• TypeScript のパス
• アイコンライブラリ
• カスタムレジストリ

完全な例： templates/components.json を参照するか、npx shadcn-vue@latest init で生成してください。

---

Utils ライブラリ

@/lib/utils.ts ファイルは、Tailwind クラスをマージするための cn() ヘルパーを提供します。

• 複数の className 文字列を結合します
• clsx と tailwind-merge を使って競合を解決します

shadcn-vue init によって自動生成されます。手動で設定する必要はありません。