shadcn-vue

shadcn-vue

用于构建 UI、组件和设计系统的框架。通过 CLI 将组件作为源代码添加到用户的项目中。

IMPORTANT： 所有 CLI 命令都要使用项目的包运行器执行：npx shadcn-vue@latest、pnpm dlx shadcn-vue@latest 或 bunx --bun shadcn-vue@latest，具体取决于项目的 packageManager。以下示例使用 npx shadcn-vue@latest，请替换为项目所用的正确运行器。

当前项目上下文

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

以上 JSON 包含项目配置和已安装的组件。使用 npx shadcn-vue@latest docs <component> 获取任何组件的文档和示例 URL。

原则

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-*。 用 size-10，不要用 w-10 h-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

• 子项始终放在对应的组中。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• Dialog、Sheet 和 Drawer 始终需要标题。 为满足无障碍要求，必须提供 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 显示 Toast。 使用 vue-sonner 中的 toast()。
• 使用 Separator，而非 <hr> 或 <div class="border-t">。
• 使用 Skeleton 作为加载占位符。不要使用自定义的 animate-pulse div。
• 使用 Badge，而非自定义样式的 span。

图标 → 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（Toast）、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. 检查新增组件 — 从任何注册表添加组件或区块后，务必阅读新增文件并确认其正确无误。检查是否缺少子组件（例如，有 SelectItem 却没有 SelectGroup）、缺少导入、组合方式错误，或违反了关键规则。还要将所有图标导入替换为项目上下文中的 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 获取原始文件——始终使用 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 - 语义化颜色、变体、类、间距、尺寸、文本截断、深色模式、cn()、z-index
• forms.md - FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、验证状态
• composition.md - Group、叠加层、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 文档：https://shadcn-vue.com
• Reka UI 文档：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：

   • 用户询问“如何实现 [component]？”
   • 需要特定组件的复制粘贴示例
   • 构建表单、表格、导航或数据展示
   • 触发词：“示例”、“如何使用”、“实现”、“代码示例”

8. 在以下情况下加载 references/cli.md：

   • 用户询问如何运行 CLI（init、add、update、search、view、docs、info、apply），或询问提示内容的含义
   • 需要安装一个或多个组件的确切命令/标志
   • 使用预设、模板或切换预设
   • 排查与 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。
• 使用 CSS 变量类，却未设置 tailwind.cssVariables: true。
• 将 @/ 导入路径硬编码，而不是从项目上下文中读取 aliases。
• 不使用 CLI，而是手动从 GitHub 获取组件文件。
• 未经用户确认就使用 --overwrite。
• 不询问用户，而是猜测注册表名称。

---

配置

shadcn-vue 使用 components.json 配置：

• 组件路径（@/components/ui）
• 工具函数位置（@/lib/utils）
• Tailwind 配置路径
• TypeScript 路径
• 图标库
• 自定义注册表

完整示例： 请参阅 templates/components.json，或通过 npx shadcn-vue@latest init 生成

---

工具函数库

@/lib/utils.ts 文件提供了用于合并 Tailwind 类的 cn() 助手函数：

• 合并多个 className 字符串
• 使用 clsx + tailwind-merge 解决冲突

由 shadcn-vue init 自动生成，无需手动设置。