shadcn-vue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn-vue

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

IMPORTANT: Run all CLI commands using the project's package runner:
npx shadcn-vue@latest
,
pnpm dlx shadcn-vue@latest
, or
bunx --bun shadcn-vue@latest
— based on the project's
packageManager
. Examples below use
npx shadcn-vue@latest
but substitute the correct runner for the project.

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

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

Current Project Context

当前项目上下文

json

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

The JSON above contains the project config and installed components. Use

npx shadcn-vue@latest docs <component>

to get documentation and example URLs for any component.

json

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

上述JSON包含项目配置和已安装的组件。使用

npx shadcn-vue@latest docs <component>

可获取任意组件的文档及示例URL。

Principles

原则

Use existing components first. Use
```
npx shadcn-vue@latest search
```
to check registries before writing custom UI. Check community registries too.
Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
Use built-in variants before custom styles.
```
variant="outline"
```
,
```
size="sm"
```
, etc.
Use semantic colors.
```
bg-primary
```
,
```
text-muted-foreground
```
— never raw values like
```
bg-blue-500
```
.

优先使用现有组件。在编写自定义UI之前，使用
```
npx shadcn-vue@latest search
```
检查注册表，同时也要查看社区注册表。
组合而非重造。设置页面 = Tabs + Card + 表单控件；仪表盘 = Sidebar + Card + Chart + Table。
优先使用内置变体而非自定义样式。例如
```
variant="outline"
```
、
```
size="sm"
```
等。
使用语义化颜色。如
```
bg-primary
```
、
```
text-muted-foreground
```
—— 绝不要使用
```
bg-blue-500
```
这类原始值。

Critical Rules

核心规则

These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.

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

Styling & Tailwind → styling.md

样式与Tailwind → styling.md

class
for layout, not styling. Never override component colors or typography.

No
space-x-*
or
space-y-*
. Use

flex

with

gap-*

. For vertical stacks,

flex flex-col gap-*

Use
size-*
when width and height are equal.
```
size-10
```
not
```
w-10 h-10
```
.

Use
truncate
shorthand. Not

overflow-hidden text-ellipsis whitespace-nowrap

No manual
dark:
color overrides. Use semantic tokens (
```
bg-background
```
,
```
text-muted-foreground
```
).
Use
cn()
for conditional classes. Don't write manual template literal ternaries.
No manual
z-index
on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.

class
用于布局，而非样式。绝不要覆盖组件的颜色或排版。
禁止使用
space-x-*
或
space-y-*
。使用
```
flex
```
搭配
```
gap-*
```
。垂直堆叠使用
```
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等组件会自行处理层级堆叠。

Forms & Inputs → forms.md

表单与输入 → forms.md

Forms use
FieldGroup
+
Field
. Never use raw
```
div
```
with
```
space-y-*
```
or
```
grid gap-*
```
for form layout.

InputGroup
uses
InputGroupInput
/
InputGroupTextarea
. Never raw

Input

Textarea

inside

InputGroup

Buttons inside inputs use
InputGroup
+
InputGroupAddon
.
Option sets (2–7 choices) use
ToggleGroup
. Don't loop
```
Button
```
with manual active state.
FieldSet
+
FieldLegend
for grouping related checkboxes/radios. Don't use a
```
div
```
with a heading.

Field validation uses
data-invalid
+
aria-invalid
.

data-invalid

Field

aria-invalid

on the control. For disabled:

data-disabled

Field

disabled

on the control.

表单使用
FieldGroup
+
Field
。绝不要使用原始
```
div
```
搭配
```
space-y-*
```
或
```
grid gap-*
```
来布局表单。

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
```
。

Component Structure → composition.md

组件结构 → composition.md

Items always inside their Group.

SelectItem

→

SelectGroup

DropdownMenuItem

→

DropdownMenuGroup

CommandItem

→

CommandGroup

Dialog, Sheet, and Drawer always need a Title.
```
DialogTitle
```
,
```
SheetTitle
```
,
```
DrawerTitle
```
required for accessibility. Use
```
class="sr-only"
```
if visually hidden.

Use full Card composition.

CardHeader

CardTitle

CardDescription

CardContent

CardFooter

. Don't dump everything in

CardContent

Button has no
isPending
/
isLoading
. Compose with

Spinner

data-icon

disabled

TabsTrigger
must be inside
TabsList
. Never render triggers directly in
```
Tabs
```
.
Avatar
always needs
AvatarFallback
. For when the image fails to load.

子项必须包含在对应的Group中。

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
。用于图片加载失败时的回显。

Use Components, Not Custom Markup → composition.md

使用组件而非自定义标记 → composition.md

Use existing components before custom markup. Check if a component exists before writing a styled
```
div
```
.
Callouts use
Alert
. Don't build custom styled divs.
Empty states use
Empty
. Don't build custom empty state markup.
Toast via
vue-sonner
. Use
```
toast()
```
from
```
vue-sonner
```
.
Use
Separator
instead of
```
<hr>
```
or
```
<div class="border-t">
```
.
Use
Skeleton
for loading placeholders. No custom
```
animate-pulse
```
divs.
Use
Badge
instead of custom styled spans.

优先使用现有组件而非自定义标记。在编写带样式的
```
div
```
之前，先确认是否已有对应组件。
提示框使用
Alert
。不要构建自定义样式的div。
空状态使用
Empty
。不要构建自定义空状态标记。
提示消息使用
vue-sonner
。调用
```
vue-sonner
```
中的
```
toast()
```
方法。
**使用
```
Separator
```
**代替
```
<hr>
```
或
```
<div class="border-t">
```
。
**使用
```
Skeleton
```
**作为加载占位符。不要自定义
```
animate-pulse
```
的div。
**使用
```
Badge
```
**代替自定义样式的span。

Icons → icons.md

图标 → icons.md

Icons in
Button
use
data-icon
.

data-icon="inline-start"

data-icon="inline-end"

on the icon.

No sizing classes on icons inside components. Components handle icon sizing via CSS. No
```
size-4
```
or
```
w-4 h-4
```
.
Pass icons as objects, not string keys.
```
:icon="CheckIcon"
```
, not a string lookup.

Button中的图标使用
data-icon
。在图标上添加

data-icon="inline-start"

或

data-icon="inline-end"

。

组件内的图标不要添加尺寸类。组件会通过CSS处理图标尺寸，不要使用
```
size-4
```
或
```
w-4 h-4
```
。
以对象形式传递图标，而非字符串键。使用
```
:icon="CheckIcon"
```
，不要使用字符串查找。

CLI

Apply preset codes directly with the CLI. Use
```
npx shadcn-vue@latest apply <code>
```
for existing projects, or
```
npx shadcn-vue@latest init --preset <code>
```
when initializing.

通过CLI直接应用预设代码。现有项目使用
```
npx shadcn-vue@latest apply <code>
```
，初始化时使用
```
npx shadcn-vue@latest init --preset <code>
```
。

Key Patterns

核心模式

These are the most common patterns that differentiate correct shadcn-vue code. For edge cases, see the linked rule files above.

html

<!-- Form layout: FieldGroup + Field, not div + Label. -->
<FieldGroup>
  <Field>
    <FieldLabel for="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 class="flex flex-col gap-4">  <!-- correct -->
<div class="space-y-4">           <!-- wrong -->

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

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

这些是区分shadcn-vue代码是否规范的最常见模式。如需了解边缘情况，请查看上述链接的规则文件。

html

<!-- 表单布局：使用FieldGroup + Field，而非div + Label。 -->
<FieldGroup>
  <Field>
    <FieldLabel for="email">邮箱</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

<!-- 验证：在Field上添加data-invalid，在控件上添加aria-invalid。 -->
<Field data-invalid>
  <FieldLabel>邮箱</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>邮箱格式无效。</FieldDescription>
</Field>

<!-- 按钮中的图标：使用data-icon，不要添加尺寸类。 -->
<Button>
  <SearchIcon data-icon="inline-start" />
  搜索
</Button>

<!-- 间距：使用gap-*，而非space-y-*。 -->
<div class="flex flex-col gap-4">  <!-- 正确 -->
<div class="space-y-4">           <!-- 错误 -->

<!-- 等尺寸：使用size-*，而非w-* h-*。 -->
<Avatar class="size-10">   <!-- 正确 -->
<Avatar class="w-10 h-10"> <!-- 错误 -->

<!-- 状态颜色：使用Badge变体或语义化令牌，而非原始颜色。 -->
<Badge variant="secondary">+20.1%</Badge>    <!-- 正确 -->
<span class="text-emerald-600">+20.1%</span> <!-- 错误 -->

Component Selection

组件选择

Need	Use
Button/action	`Button` with appropriate variant
Form inputs	`Input` , `Select` , `Combobox` , `Switch` , `Checkbox` , `RadioGroup` , `Textarea` , `InputOTP` , `Slider`
Toggle between 2–7 options	`ToggleGroup` + `ToggleGroupItem`
Data display	`Table` , `Card` , `Badge` , `Avatar`
Navigation	`Sidebar` , `NavigationMenu` , `Breadcrumb` , `Tabs` , `Pagination`
Overlays	`Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)
Feedback	`vue-sonner` (toast), `Alert` , `Progress` , `Skeleton` , `Spinner`
Command palette	`Command` inside `Dialog`
Charts	`Chart` (wraps Unovis)
Layout	`Card` , `Separator` , `Resizable` , `ScrollArea` , `Accordion` , `Collapsible`
Empty states	`Empty`
Menus	`DropdownMenu` , `ContextMenu` , `Menubar`
Tooltips/info	`Tooltip` , `HoverCard` , `Popover`

需求	使用组件
按钮/操作	带合适变体的 `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`

Key Fields

核心字段

The injected project context contains these key fields:

aliases
→ use the actual alias prefix for imports (e.g.
```
@/
```
,
```
~/
```
), never hardcode.

tailwindVersion
→

"v4"

uses

@theme inline

blocks;

"v3"

uses

tailwind.config.js

tailwindCssFile
→ the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
style
→ component visual treatment (e.g.
```
nova
```
,
```
vega
```
).
base
→ primitive library (
```
reka
```
). Affects component APIs and available props.

iconLibrary
→ determines icon imports. Use

lucide-vue-next

for

lucide

@tabler/icons-vue

for

tabler

, etc. Never assume

lucide-vue-next

resolvedPaths
→ exact file-system destinations for components, utils, hooks, etc.
framework
→ routing and file conventions (e.g. Nuxt vs Vite SPA).
packageManager
→ use this for any non-shadcn-vue dependency installs (e.g.
```
pnpm add date-fns
```
vs
```
npm install date-fns
```
).

See cli.md —

info

command for the full field reference.

注入的项目上下文包含以下核心字段：

aliases
→ 使用实际的别名前缀进行导入（如
```
@/
```
、
```
~/
```
），绝不要硬编码。

tailwindVersion
→

"v4"

使用

@theme inline

块；

"v3"

使用

tailwind.config.js

。

tailwindCssFile
→ 定义自定义CSS变量的全局CSS文件。始终编辑此文件，不要创建新文件。
style
→ 组件视觉风格（如
```
nova
```
、
```
vega
```
）。
base
→ 基础库（
```
reka
```
）。影响组件API和可用属性。
iconLibrary
→ 决定图标导入方式。
```
lucide
```
使用
```
lucide-vue-next
```
，
```
tabler
```
使用
```
@tabler/icons-vue
```
等。不要默认使用
```
lucide-vue-next
```
。
resolvedPaths
→ 组件、工具、钩子等的准确文件系统路径。
framework
→ 路由和文件约定（如Nuxt vs Vite SPA）。
packageManager
→ 安装非shadcn-vue依赖时使用（如
```
pnpm add date-fns
```
vs
```
npm install date-fns
```
）。

完整字段参考请查看cli.md —

info

命令。

Component Docs, Examples, and Usage

组件文档、示例与用法

Run

npx shadcn-vue@latest docs <component>

to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.

bash

npx shadcn-vue@latest docs button dialog select

When creating, fixing, debugging, or using a component, always run
npx shadcn-vue@latest docs
and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.

运行

npx shadcn-vue@latest docs <component>

可获取组件的文档、示例及API参考URL。获取这些URL以查看实际内容。

bash

npx shadcn-vue@latest docs button dialog select

在创建、修复、调试或使用组件时，请始终先运行
npx shadcn-vue@latest docs
并获取URL。这能确保你使用正确的API和用法模式，而非凭猜测操作。

Workflow

工作流程

Get project context — already injected above. Run
```
npx shadcn-vue@latest info
```
again if you need to refresh.
Check installed components first — before running
```
add
```
, always check the
```
components
```
list from project context or list the
```
resolvedPaths.ui
```
directory. Don't import components that haven't been added, and don't re-add ones already installed.
Find components —
```
npx shadcn-vue@latest search
```
.
Get docs and examples — run
```
npx shadcn-vue@latest docs <component>
```
to get URLs, then fetch them. Use
```
npx shadcn-vue@latest view
```
to browse registry items you haven't installed. To preview changes to installed components, use
```
npx shadcn-vue@latest add --diff
```
.
Install or update —
```
npx shadcn-vue@latest add
```
. When updating existing components, use
```
--dry-run
```
and
```
--diff
```
to preview changes first (see Updating Components below).
Fix imports in third-party components — After adding components from community registries, check the added non-UI files for hardcoded import paths like
```
@/components/ui/...
```
. These won't match the project's actual aliases. Use
```
npx shadcn-vue@latest info
```
to get the correct
```
ui
```
alias (e.g.
```
@workspace/ui/components
```
) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
Review added components — After adding a component or block from any registry, always read the added files and verify they are correct. Check for missing sub-components (e.g.
```
SelectItem
```
without
```
SelectGroup
```
), missing imports, incorrect composition, or violations of the Critical Rules. Also replace any icon imports with the project's
```
iconLibrary
```
from the project context (e.g. if the registry item uses
```
lucide-vue-next
```
but the project uses
```
hugeicons
```
, swap the imports and icon names accordingly). Fix all issues before moving on.
Registry must be explicit — When the user asks to add a block or component, do not guess the registry. If no registry is specified (e.g. user says "add a login block" without specifying
```
@shadcn
```
, etc.), ask which registry to use. Never default to a registry on behalf of the user.
Switching presets — Ask the user first: overwrite, merge, or skip?
- Overwrite:
```
npx shadcn-vue@latest apply <code>
```
  . Overwrites detected components, fonts, and CSS variables.
- Merge:
```
npx shadcn-vue@latest init --preset <code> --force --no-reinstall
```
  , then run
```
npx shadcn-vue@latest info
```
  to list installed components, then for each installed component use
```
--dry-run
```
  and
```
--diff
```
  to smart merge it individually.
- Skip:
```
npx shadcn-vue@latest init --preset <code> --force --no-reinstall
```
  . Only updates config and CSS, leaves components as-is.
- Important: Always run preset commands inside the user's project directory.
```
apply
```
  only works in an existing project with a
```
components.json
```
  file. The CLI automatically preserves the current base (
```
reka
```
  ) from
```
components.json
```
  . If you must use a scratch/temp directory (e.g. for
```
--dry-run
```
  comparisons), pass
```
--base <current-base>
```
  explicitly — preset codes do not encode the base.

获取项目上下文 —— 已在上方注入。如需刷新，可再次运行
```
npx shadcn-vue@latest info
```
。
先检查已安装组件 —— 在运行
```
add
```
之前，务必查看项目上下文中的
```
components
```
列表，或列出
```
resolvedPaths.ui
```
目录。不要导入未添加的组件，也不要重复添加已安装的组件。
查找组件 —— 使用
```
npx shadcn-vue@latest search
```
。
获取文档和示例 —— 运行
```
npx shadcn-vue@latest docs <component>
```
获取URL，然后获取内容。使用
```
npx shadcn-vue@latest view
```
浏览尚未安装的注册表项。如需预览已安装组件的变更，使用
```
npx shadcn-vue@latest add --diff
```
。
安装或更新 —— 使用
```
npx shadcn-vue@latest add
```
。更新现有组件时，先使用
```
--dry-run
```
和
```
--diff
```
预览变更（见下方更新组件）。
修复第三方组件的导入 —— 从社区注册表添加组件后，检查添加的非UI文件中是否有硬编码的导入路径，如
```
@/components/ui/...
```
。这些路径可能与项目实际别名不匹配。使用
```
npx shadcn-vue@latest info
```
获取正确的
```
ui
```
别名（如
```
@workspace/ui/components
```
），并相应重写导入。CLI会自动重写自身UI文件的导入，但第三方注册表组件可能使用默认路径，与项目不匹配。
审核添加的组件 —— 从任何注册表添加组件或模块后，务必阅读添加的文件并验证其正确性。检查是否缺少子组件（如
```
SelectItem
```
未包含在
```
SelectGroup
```
中）、缺少导入、组合错误或违反核心规则。同时，将图标导入替换为项目上下文的
```
iconLibrary
```
（如注册表项使用
```
lucide-vue-next
```
但项目使用
```
hugeicons
```
，则相应替换导入和图标名称）。在继续操作前修复所有问题。
注册表必须明确指定 —— 当用户要求添加模块或组件时，不要猜测注册表。如果未指定注册表（如用户说"添加登录模块"但未指定
```
@shadcn
```
等），请询问使用哪个注册表。绝不要替用户默认选择注册表。
切换预设 —— 先询问用户：覆盖、合并还是跳过？
- 覆盖：
```
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>
```
  —— 预设代码不包含基础库信息。

Updating Components

更新组件

When the user asks to update a component from upstream while keeping their local changes, use

--dry-run

and

--diff

to intelligently merge. NEVER fetch raw files from GitHub manually — always use the CLI.

Run

npx shadcn-vue@latest add <component> --dry-run

to see all files that would be affected.

For each file, run
```
npx shadcn-vue@latest add <component> --diff <file>
```
to see what changed upstream vs local.
Decide per file based on the diff:
- No local changes → safe to overwrite.
- Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
- User says "just update everything" → use
```
--overwrite
```
  , but confirm first.
Never use
--overwrite
without the user's explicit approval.

当用户要求更新上游组件同时保留本地变更时，使用

--dry-run

和

--diff

进行智能合并。绝不要手动从GitHub获取原始文件——务必使用CLI。

运行

npx shadcn-vue@latest add <component> --dry-run

查看所有受影响的文件。

对每个文件，运行
```
npx shadcn-vue@latest add <component> --diff <file>
```
查看上游变更与本地版本的差异。
根据差异逐个文件决定：
- 无本地变更 → 可安全覆盖。
- 有本地变更 → 读取本地文件，分析差异，应用上游更新同时保留本地修改。
- 用户要求"全部更新" → 使用
```
--overwrite
```
  ，但需先确认。
未经用户明确批准，绝不要使用
--overwrite
。

Quick Reference

快速参考

bash

undefined

bash

undefined

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)

npx shadcn-vue@latest init --preset nova npx shadcn-vue@latest init --defaults # 快捷方式：--template=nuxt --preset=nova（基础风格默认）

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.

获取组件文档和示例URL。

npx shadcn-vue@latest docs button dialog select

View registry item details (for items not yet installed).

查看注册表项详情（针对尚未安装的项）。

npx shadcn-vue@latest view @shadcn/button


**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`
**Templates:** `nuxt`, `vite`, `astro` and `laravel`
**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw`), from [shadcn-vue.com](https://shadcn-vue.com).

npx shadcn-vue@latest view @shadcn/button


**命名预设：** `nova`、`vega`、`maia`、`lyra`、`mira`、`luma`
**模板：** `nuxt`、`vite`、`astro` 和 `laravel`
**预设代码：** 带版本前缀的base62字符串（如`a2r6bw`），来自[shadcn-vue.com](https://shadcn-vue.com)。

Detailed References

详细参考

rules/forms.md — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
rules/composition.md — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
rules/icons.md — data-icon, icon sizing, passing icons as objects
rules/styling.md — Semantic colors, variants, class, spacing, size, truncate, dark mode, cn(), z-index
cli.md — Commands, flags, presets, templates
customization.md — Theming, CSS variables, extending components

rules/forms.md — FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、验证状态
rules/composition.md — 分组、覆盖层、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button加载状态
rules/icons.md — data-icon、图标尺寸、以对象形式传递图标
rules/styling.md — 语义化颜色、变体、class、间距、size、truncate、深色模式、cn()、z-index
cli.md — 命令、标志、预设、模板
customization.md — 主题定制、CSS变量、组件扩展