shadcn/ui

一个用于构建用户界面、组件和设计系统的框架。通过 CLI 将组件以源代码形式添加到用户的项目中。

重要： 必须根据项目的 packageManager，使用项目的软件包运行器 npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest 运行所有 CLI 命令。以下示例使用 npx shadcn@latest，但请替换为适用于项目的正确运行器。

当前项目上下文

!`npx shadcn@latest info --json`

上面的 JSON 包含项目配置和已安装的组件。使用 npx shadcn@latest docs <component> 可获取任意组件的文档和示例网址。

原则

1. 优先使用现有组件。 编写自定义 UI 前，先使用 npx shadcn@latest search 检查注册表。也要检查社区注册表。
2. 组合现有组件，不要重复造轮子。 设置页面 = 标签页 + 卡片 + 表单控件。仪表板 = 侧边栏 + 卡片 + 图表 + 表格。
3. 优先使用内置变体，而不是自定义样式。 例如 variant="outline"、size="sm" 等。
4. 使用语义化颜色。 使用 bg-primary、text-muted-foreground，禁止使用 bg-blue-500 这样的原始值。

关键规则

这些规则始终强制执行。每条规则均链接到一个包含错误/正确代码对的文件。

样式与 Tailwind → [styling.md](./rules/styling.md)

• className 只用于布局，不用于设置样式。 禁止覆盖组件的颜色或排版。
• **不得使用 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。 对话框、侧边面板、弹出框等组件会自行处理堆叠顺序。

表单与输入控件 → [forms.md](./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。

组件结构 → [composition.md](./rules/composition.md)

• 条目必须始终放在相应的组内。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• 自定义触发器使用 asChild（Radix）或 render（Base）。 检查 npx shadcn@latest info 返回的 base 字段。→ [base-vs-radix.md](./rules/base-vs-radix.md)
• 对话框、侧边面板和抽屉式面板始终需要标题。 为满足无障碍要求，必须使用 DialogTitle、SheetTitle、DrawerTitle。如果需要在视觉上隐藏标题，请使用 className="sr-only"。
• 使用完整的卡片组合结构。 CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不得将所有内容都塞进 CardContent。
• 按钮不提供 isPending/isLoading。 使用 Spinner + data-icon + disabled 组合实现。
• TabsTrigger 必须位于 TabsList 内。 禁止直接在 Tabs 中渲染触发器。
• Avatar 始终需要 AvatarFallback。 以便在图片加载失败时显示后备内容。

使用组件，而不是自定义标记 → [composition.md](./rules/composition.md)

• 先使用现有组件，再使用自定义标记。 编写带样式的 div 前，先检查是否已有相应组件。
• 提示信息使用 Alert。 不得构建自定义样式的 div。
• 空状态使用 Empty。 不得构建自定义空状态标记。
• Toast 遵循项目基础库。 从 toast 组件导入 toast，供

Base UI 项目使用。Radix 和 React Aria 项目使用 sonner 提供的 toast()。

• 使用 Separator，而不是 <hr> 或 <div className="border-t">。
• 使用 Skeleton 作为加载占位符。不得使用自定义的 animate-pulse div。
• 使用 Badge，而不是带自定义样式的 span 元素。

图标 → [icons.md](./rules/icons.md)

• Button 中的图标使用 data-icon。 在图标上设置 data-icon="inline-start" 或 data-icon="inline-end"。
• 组件内的图标不得使用尺寸类。 组件通过 CSS 处理图标尺寸。不得使用 size-4 或 w-4 h-4。
• 以对象形式传递图标，而不是使用字符串键。 使用 icon={CheckIcon}，不要通过字符串查找。

聊天与消息 → [chat.md](./rules/chat.md)

• 聊天 UI 组合使用聊天基础组件。 会话使用 MessageScroller，消息行使用 Message，消息呈现区域使用 Bubble。禁止手工编写气泡 div，也不得使用原始滚动容器。
• MessageScroller 负责管理滚动行为。 流式内容跟随、锚定和跳转至最新消息（MessageScrollerButton）均为内置功能。不得编写 useStickToBottom/ResizeObserver 钩子。
• 附件使用 Attachment；系统注释和分隔项使用 Marker。 不得使用 Item 卡片，也不得使用 Separator + 标签。

CLI

• 禁止手动解码预设代码或构建预设 URL。 使用 npx shadcn@latest preset decode <code>、preset url <code> 或 preset open <code>。对于结合项目上下文的预设检测，使用 npx shadcn@latest preset resolve。
• 直接通过 CLI 应用预设代码。 对于现有项目，使用 npx shadcn@latest apply <code>；初始化时使用 npx shadcn@latest init --preset <code>。

关键模式

这些是区分正确 shadcn/ui 代码的最常见模式。有关边缘情况，请参阅上方链接的规则文件。

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>

// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong

// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong

// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

组件选择

| 需求 | 使用 | | -------------------------- | --------------------------------------------------------------------------------------------------- | | 按钮/操作 | 采用适当变体的 Button | | 表单输入 | Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider | | 在 2–5 个选项之间切换 | ToggleGroup + ToggleGroupItem | | 数据展示 | Table, Card, Badge, Avatar | | 导航 | Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination | | 浮层 | Dialog（模态框）、Sheet（侧边面板）、Drawer（底部面板）、AlertDialog（确认） | | 反馈 | toast (Base UI), sonner (Radix/Aria), Alert, Progress, Skeleton, Spinner | | 命令面板 | 在 Dialog 中使用 Command | | 图表 | Chart（封装 Recharts） | | 布局 | Card, Separator, Resizable, ScrollArea, Accordion, Collapsible | | 空状态 | Empty | | 菜单 | DropdownMenu, ContextMenu, Menubar | | Tooltips/info | Tooltip, HoverCard, Popover | | 聊天/对话 UI | MessageScroller, Message, Bubble, Attachment, Marker |

关键字段

已注入的项目上下文包含以下关键字段：

• aliases → 导入时使用实际的别名前缀（例如 @/、~/），禁止硬编码。
• isRSC → 当值为 true 时，使用 useState、useEffect、事件处理程序或浏览器 APIs 的组件需要在文件顶部添加 "use client"。提供有关该指令的建议时，必须始终参考此字段。
• tailwindVersion → "v4" 使用 @theme inline 代码块；"v3" 使用 tailwind.config.js。
• tailwindCssFile → 用于定义自定义 CSS 变量的全局 CSS 文件。必须始终编辑此文件，禁止创建新文件。
• style → 组件的视觉样式（例如 nova、vega）。
• base → 原语库（radix 或 base）。会影响组件 APIs 和可用属性。
• iconLibrary → 决定图标的导入方式。使用 lucide 时采用 lucide-react，使用 tabler 时采用 @tabler/icons-react，依此类推。不得默认使用 lucide-react。
• resolvedPaths → 组件、工具函数、钩子等内容在文件系统中的确切目标位置。
• framework → 路由和文件约定（例如 Next.js 应用路由器与 Vite SPA）。
• packageManager → 安装任何非 shadcn 依赖项时使用此字段（例如 pnpm add date-fns 与 npm install date-fns）。
• preset → 当前项目已解析的预设代码和值。仅需预设信息时，使用 npx shadcn@latest preset resolve --json。

有关完整的字段参考，请参阅 [cli.md — info 命令](./cli.md)。

组件文档、示例和用法

运行 npx shadcn@latest docs <component> 以获取组件文档、示例和 API 参考文档的 URL。访问这些 URL 以获取实际内容。

npx shadcn@latest docs button dialog select

创建、修复、调试或使用组件时，必须始终先运行 npx shadcn@latest docs 并访问这些 URL。 这可确保你依据正确的 API 和用法模式开展工作，而不是靠猜测。

工作流

1. 获取项目上下文 — 已在上方注入。如需刷新，请再次运行 npx shadcn@latest info。
2. 先检查已安装的组件 — 运行 add 前，始终检查项目上下文中的 components 列表，或列出 resolvedPaths.ui 目录。不得导入尚未添加的组件，也不得重新添加已安装的组件。
3. 查找组件 — npx shadcn@latest search。
4. 获取文档和示例 — 运行 npx shadcn@latest docs <component> 获取 URL，然后获取其内容。使用 npx shadcn@latest view 浏览尚未安装的注册表项。要预览已安装组件的更改，请使用 npx shadcn@latest add --diff。
5. 安装或更新 — 运行 npx shadcn@latest add。更新现有组件时，先使用 --dry-run 和 --diff 预览更改（请参阅下文的 [更新组件](#updating-components)）。
6. 修复第三方组件中的导入 — 从社区注册表添加组件（例如 @bundui、@magicui）后，检查已添加的非 UI 文件中是否存在 @/components/ui/... 之类的硬编码导入路径。这些路径不会与项目的实际别名匹配。使用 npx shadcn@latest info 获取正确的 ui 别名（例如 @workspace/ui/components），并相应重写导入。CLI 会重写其自身 UI 文件中的导入，但第三方注册表组件可能使用与项目不匹配的默认路径。
7. 审核已添加的组件 — 从任意注册表添加组件或区块后，必须始终查看已添加的文件并验证其正确性。检查是否存在缺少子组件（例如有 SelectItem 而没有 SelectGroup）、导入缺失、组合方式错误或违反 [关键规则](#critical-rules) 的情况。还要依据项目上下文中的项目 iconLibrary 替换所有图标导入（例如，如果注册表项使用 lucide-react，而项目使用 hugeicons，则相应替换导入和图标名称）。修复所有问题后再继续。
8. 必须明确指定注册表 — 当用户要求添加区块或组件时，不得猜测注册表。如果未指定注册表（例如用户说“添加一个登录区块”，但未指定 @shadcn、@tailark、owner/repo 等），请询问使用哪个注册表。禁止代用户默认选择注册表。
9. 切换预设 — 先询问用户：覆盖、部分应用、合并还是跳过？

• 检查当前预设：npx shadcn@latest preset resolve。需要结构化值时，使用 --json。
• 检查传入的预设：npx shadcn@latest preset decode <code>。使用 preset url <code> 或 preset open <code> 分享或打开预设构建器。
• 覆盖：npx shadcn@latest apply <code>。覆盖检测到的组件、字体和 CSS 变量。
• 部分应用：npx shadcn@latest apply <code> --only theme,font。仅更新选定的预设部分，而不重新安装 UI 组件。支持的值为 theme 和 font；允许使用逗号分隔的组合。特意不支持 icon，因为更改图标可能需要完整地重新安装组件并执行转换。
• 合并：运行 npx shadcn@latest init --preset <code> --force --no-reinstall，然后运行 npx shadcn@latest info 列出已安装的组件，再针对每个已安装组件使用 --dry-run 和 --diff，分别对其进行[智能合并](#updating-components)。
• 跳过：npx shadcn@latest init --preset <code> --force --no-reinstall。仅更新配置和 CSS，组件保持不变。
• 重要提示：必须始终在用户的项目目录中运行预设命令。apply 仅适用于包含 components.json 文件的现有项目。CLI 会自动保留 components.json 中当前使用的基础库（base 或 radix）。如果必须使用临时目录（例如用于进行 --dry-run 比较），请明确传入 --base <current-base>——预设代码中未编码基础库信息。

更新组件

当用户要求从上游更新组件，同时保留本地更改时，使用 --dry-run 和 --diff 进行智能合并。禁止从 GitHub 手动获取原始文件——必须始终使用 CLI。

1. 运行 npx shadcn@latest add <component> --dry-run，查看所有将受影响的文件。
2. 针对每个文件运行 npx shadcn@latest add <component> --diff <file>，查看上游版本与本地版本之间的差异。
3. 根据差异逐个文件决定如何处理：

• 没有本地更改 → 可以安全覆盖。
• 存在本地更改 → 读取本地文件并分析差异，在保留本地修改的同时应用上游更新。
• 用户说“直接全部更新”→ 使用 --overwrite，但必须先确认。

1. 未经用户明确批准，不得使用 --overwrite。

快速参考

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

# Create a monorepo project.
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo

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

# Apply a preset to an existing project.
npx shadcn@latest apply a2r6bw
npx shadcn@latest apply a2r6bw --only theme
npx shadcn@latest apply a2r6bw --only font
npx shadcn@latest apply a2r6bw --only theme,font

# Inspect preset codes and project preset state.
npx shadcn@latest preset decode a2r6bw
npx shadcn@latest preset url a2r6bw
npx shadcn@latest preset open a2r6bw
npx shadcn@latest preset resolve
npx shadcn@latest preset resolve --json

# Add components.
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add owner/repo/item
npx shadcn@latest add --all

# Preview changes before adding/updating.
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx
npx shadcn@latest add owner/repo/item --dry-run

# Search registries.
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"
npx shadcn@latest search owner/repo -q "login"
npx shadcn@latest search                          # all configured registries
npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type

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

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

命名预设： nova、vega、maia、lyra、mira、luma 模板： next、vite、start、react-router、astro（均支持 --monorepo）和 laravel（不支持 monorepo） 预设代码： 带版本前缀的 base62 字符串（例如 a2r6bw 或 b0），来自 ui.shadcn.com。

详细参考

• [rules/forms.md](./rules/forms.md) — FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、验证状态
• [rules/composition.md](./rules/composition.md) — 分组、浮层、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button 加载状态
• [rules/chat.md](./rules/chat.md) — MessageScroller、Message、Bubble、Attachment、Marker；流式传输、锚定、跳转至最新消息
• [rules/icons.md](./rules/icons.md) — data-icon、图标尺寸、以对象形式传递图标
• [rules/styling.md](./rules/styling.md) — 语义化颜色、变体、className、间距、尺寸、文本截断、深色模式、cn()、z-index
• [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild 与 render 的对比、Select、ToggleGroup、Slider、Accordion
• [cli.md](./cli.md) — 命令、标志、预设、模板
• [registry.md](./registry.md) — 源注册表编写、include、条目定义、依赖项、GitHub 注册表规则
• [customization.md](./customization.md) — 主题设置、CSS 变量、扩展组件