shadcn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui

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@latest
,
pnpm dlx shadcn@latest
, or
bunx --bun shadcn@latest
— based on the project's
packageManager
. Examples below use
npx shadcn@latest
but substitute the correct runner for the project.

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

重要提示： 请根据项目的
packageManager
选择对应包运行器执行所有CLI命令：
npx shadcn@latest
、
pnpm dlx shadcn@latest
或者
bunx --bun shadcn@latest
。下文示例统一使用
npx shadcn@latest
，请根据项目实际情况替换为正确的运行器。

When to Use

适用场景

Use when adding new components from shadcn/ui or community registries.
Use when styling, composing, or debugging existing shadcn/ui components.
Use when initializing a new project or switching design system presets.
Use to retrieve component documentation, examples, and API references.

需要从shadcn/ui或社区注册表添加新组件时
需要对现有shadcn/ui组件进行样式设置、组合或调试时
需要初始化新项目或切换设计系统预设时
需要获取组件文档、示例和API参考时

Current Project Context

当前项目上下文

json

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

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

npx shadcn@latest docs <component>

to get documentation and example URLs for any component.

json

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "未找到shadcn项目，请先运行shadcn init。"}'`

上述JSON包含项目配置和已安装组件信息。你可以使用

npx shadcn@latest docs <component>

命令获取任意组件的文档和示例URL。

Principles

原则

Use existing components first. Use
```
npx shadcn@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@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

className
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.

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:
颜色。使用语义化token（
```
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

Use
asChild
(radix) or
render
(base) for custom triggers. Check
```
base
```
field from
```
npx shadcn@latest info
```
. → base-vs-radix.md
Dialog, Sheet, and Drawer always need a Title.
```
DialogTitle
```
,
```
SheetTitle
```
,
```
DrawerTitle
```
required for accessibility. Use
```
className="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.

项始终放在对应的组内。

SelectItem

→

SelectGroup

；

DropdownMenuItem

→

DropdownMenuGroup

；

CommandItem

→

CommandGroup

。

自定义触发器使用
asChild
（radix）或
render
（base）。可通过
```
npx shadcn@latest info
```
的
```
base
```
字段确认类型 → base-vs-radix.md
Dialog、Sheet、Drawer必须包含标题。 为了无障碍要求，必须添加
```
DialogTitle
```
、
```
SheetTitle
```
、
```
DrawerTitle
```
，如果需要视觉隐藏可以设置
```
className="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
sonner
. Use
```
toast()
```
from
```
sonner
```
.
Use
Separator
instead of
```
<hr>
```
or
```
<div className="border-t">
```
.
Use
Skeleton
for loading placeholders. No custom
```
animate-pulse
```
divs.
Use
Badge
instead of custom styled spans.

自定义标签前优先使用现有组件。 写带样式的
```
div
```
前先检查是否已有对应组件。
提示框使用
Alert
。不要自行构建带样式的自定义div。
空状态使用
Empty
。不要自行构建空状态标签。
提示框用
sonner
实现。使用
```
sonner
```
提供的
```
toast()
```
方法。
使用
Separator
代替
```
<hr>
```
或
```
<div className="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
```
。
图标以对象形式传入，不要用字符串key。 用
```
icon={CheckIcon}
```
，不要用字符串查找。

CLI

Never decode or fetch preset codes manually. Pass them directly to
```
npx shadcn@latest init --preset <code>
```
.

永远不要手动解码或获取预设代码。 直接将代码传入
```
npx shadcn@latest init --preset <code>
```
即可。

Key Patterns

常用模式

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

tsx

// 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

以下是区分正确shadcn/ui代码的最常见模式，边缘情况请参考上文关联的规则文件。

tsx

// 表单布局：FieldGroup + Field，不要用div + Label
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="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 className="flex flex-col gap-4">  // 正确
<div className="space-y-4">           // 错误

// 相等尺寸：用size-*，不要用w-* h-*
<Avatar className="size-10">   // 正确
<Avatar className="w-10 h-10"> // 错误

// 状态颜色：用Badge变体或语义化token，不要用原始颜色
<Badge variant="secondary">+20.1%</Badge>    // 正确
<span className="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–5 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	`sonner` (toast), `Alert` , `Progress` , `Skeleton` , `Spinner`
Command palette	`Command` inside `Dialog`
Charts	`Chart` (wraps Recharts)
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-5个选项切换	`ToggleGroup` + `ToggleGroupItem`
数据展示	`Table` 、 `Card` 、 `Badge` 、 `Avatar`
导航	`Sidebar` 、 `NavigationMenu` 、 `Breadcrumb` 、 `Tabs` 、 `Pagination`
覆盖层	`Dialog` （模态框）、 `Sheet` （侧边面板）、 `Drawer` （底部弹窗）、 `AlertDialog` （确认弹窗）
反馈	`sonner` （toast）、 `Alert` 、 `Progress` 、 `Skeleton` 、 `Spinner`
命令面板	`Dialog` 内嵌套 `Command`
图表	封装了Recharts的 `Chart`
布局	`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.
isRSC
→ when
```
true
```
, components using
```
useState
```
,
```
useEffect
```
, event handlers, or browser APIs need
```
"use client"
```
at the top of the file. Always reference this field when advising on the directive.

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 (
```
radix
```
or
```
base
```
). Affects component APIs and available props.

iconLibrary
→ determines icon imports. Use

lucide-react

for

lucide

@tabler/icons-react

for

tabler

, etc. Never assume

lucide-react

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

See cli.md —

info

command for the full field reference.

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

aliases
→ 导入时使用实际的别名前缀（比如
```
@/
```
、
```
~/
```
），永远不要硬编码。
isRSC
→ 当值为
```
true
```
时，使用
```
useState
```
、
```
useEffect
```
、事件处理器或浏览器API的组件需要在文件顶部添加
```
"use client"
```
指令，给出相关建议时务必参考该字段。

tailwindVersion
→

"v4"

使用

@theme inline

块；

"v3"

使用

tailwind.config.js

。

tailwindCssFile
→ 定义自定义CSS变量的全局CSS文件，永远编辑该文件，不要新建。
style
→ 组件视觉风格（比如
```
nova
```
、
```
vega
```
）。
base
→ 基础组件库（
```
radix
```
或
```
base
```
），会影响组件API和可用属性。
iconLibrary
→ 决定图标导入方式，
```
lucide
```
对应
```
lucide-react
```
，
```
tabler
```
对应
```
@tabler/icons-react
```
等，永远不要默认使用
```
lucide-react
```
。
resolvedPaths
→ 组件、工具函数、钩子等对应的精确文件系统路径。
framework
→ 路由和文件约定（比如Next.js App Router和Vite SPA的区别）。
packageManager
→ 安装非shadcn依赖时使用该值（比如
```
pnpm add date-fns
```
和
```
npm install date-fns
```
的区别）。

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

info

命令。

Component Docs, Examples, and Usage

组件文档、示例和使用

Run

npx shadcn@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@latest docs button dialog select

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

运行

npx shadcn@latest docs <component>

可以获取组件的文档、示例和API参考URL，访问这些URL可以获取实际内容。

bash

npx shadcn@latest docs button dialog select

在创建、修复、调试或使用组件时，务必先运行
npx shadcn@latest docs
并获取对应URL内容，确保你使用的是正确的API和使用模式，而非猜测。

Workflow

工作流程

Get project context — already injected above. Run
```
npx shadcn@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@latest search
```
.
Get docs and examples — run
```
npx shadcn@latest docs <component>
```
to get URLs, then fetch them. Use
```
npx shadcn@latest view
```
to browse registry items you haven't installed. To preview changes to installed components, use
```
npx shadcn@latest add --diff
```
.
Install or update —
```
npx shadcn@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 (e.g.
```
@bundui
```
,
```
@magicui
```
), 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@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-react
```
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
```
,
```
@tailark
```
, etc.), ask which registry to use. Never default to a registry on behalf of the user.
Switching presets — Ask the user first: reinstall, merge, or skip?
- Reinstall:
```
npx shadcn@latest init --preset <code> --force --reinstall
```
  . Overwrites all components.
- Merge:
```
npx shadcn@latest init --preset <code> --force --no-reinstall
```
  , then run
```
npx shadcn@latest info
```
  to list installed components, then for each installed component use
```
--dry-run
```
  and
```
--diff
```
  to smart merge it individually.
- Skip:
```
npx shadcn@latest init --preset <code> --force --no-reinstall
```
  . Only updates config and CSS, leaves components as-is.

获取项目上下文 — 上文已经自动注入，如需刷新可以重新运行
```
npx shadcn@latest info
```
。
优先检查已安装组件 — 运行
```
add
```
命令前，务必先检查项目上下文的
```
components
```
列表或
```
resolvedPaths.ui
```
目录内容，不要导入未添加的组件，也不要重复安装已存在的组件。
查找组件 — 运行
```
npx shadcn@latest search
```
。
获取文档和示例 — 运行
```
npx shadcn@latest docs <component>
```
获取URL，然后访问获取内容。可以用
```
npx shadcn@latest view
```
浏览未安装的注册表项，预览已安装组件的修改可以用
```
npx shadcn@latest add --diff
```
。
安装或更新 — 运行
```
npx shadcn@latest add
```
。更新现有组件时，先使用
```
--dry-run
```
和
```
--diff
```
预览修改（见下文更新组件部分）。
修复第三方组件的导入路径 — 从社区注册表（比如
```
@bundui
```
、
```
@magicui
```
）添加组件后，检查新增的非UI文件是否存在硬编码的导入路径，比如
```
@/components/ui/...
```
，这类路径不一定匹配项目实际别名。使用
```
npx shadcn@latest info
```
获取正确的
```
ui
```
别名（比如
```
@workspace/ui/components
```
）并对应重写导入路径。CLI会自动重写自有UI文件的导入路径，但第三方注册表组件可能使用不匹配项目的默认路径。
审核新增组件 — 从任意注册表添加组件或区块后，务必阅读新增文件并验证正确性。检查是否缺少子组件（比如
```
SelectItem
```
没有对应
```
SelectGroup
```
）、是否缺少导入、组合方式是否正确、是否违反核心规则。同时将所有图标导入替换为项目上下文
```
iconLibrary
```
对应的图标（比如注册表项使用
```
lucide-react
```
但项目使用
```
hugeicons
```
，需要对应替换导入和图标名称），解决所有问题后再继续。
必须明确指定注册表 — 用户要求添加区块或组件时，不要猜测注册表。如果没有指定注册表（比如用户只说“添加登录区块”，没有指定
```
@shadcn
```
、
```
@tailark
```
等），询问用户要使用哪个注册表，永远不要替用户默认选择注册表。
切换预设 — 先询问用户选择：重新安装、合并还是跳过？
- 重新安装：
```
npx shadcn@latest init --preset <code> --force --reinstall
```
  ，会覆盖所有组件。
- 合并：
```
npx shadcn@latest init --preset <code> --force --no-reinstall
```
  ，然后运行
```
npx shadcn@latest info
```
  列出已安装组件，对每个已安装组件单独使用
```
--dry-run
```
  和
```
--diff
```
  进行智能合并。
- 跳过：
```
npx shadcn@latest init --preset <code> --force --no-reinstall
```
  ，仅更新配置和CSS，组件保持不变。

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@latest add <component> --dry-run

to see all files that would be affected.

For each file, run
```
npx shadcn@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@latest add <component> --dry-run

查看所有会被影响的文件。

对每个文件，运行
```
npx shadcn@latest add <component> --diff <file>
```
查看上游和本地的差异。
根据差异按文件决定处理方式：
- 无本地修改 → 可以安全覆盖。
- 有本地修改 → 阅读本地文件，分析差异，应用上游更新的同时保留本地修改。
- 用户要求“直接更新所有内容” → 使用
```
--overwrite
```
  ，但务必先确认。
没有用户明确批准的情况下永远不要使用
--overwrite
。

Quick Reference

快速参考

bash

undefined

bash

undefined

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.

创建 monorepo 项目

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=base-nova

npx shadcn@latest init --preset base-nova npx shadcn@latest init --defaults # 快捷方式：--template=next --preset=base-nova

Add components.

添加组件

npx shadcn@latest add button card dialog npx shadcn@latest add @magicui/shimmer-button 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

Search registries.

搜索注册表

npx shadcn@latest search @shadcn -q "sidebar" npx shadcn@latest search @tailark -q "stats"

Get component docs and example URLs.

获取组件文档和示例URL

npx shadcn@latest docs button dialog select

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

查看注册表项详情（适用于未安装的项）

npx shadcn@latest view @shadcn/button


**Named presets:** `base-nova`, `radix-nova`
**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
**Preset codes:** Base62 strings starting with `a` (e.g. `a2r6bw`), from [ui.shadcn.com](https://ui.shadcn.com).

npx shadcn@latest view @shadcn/button


**命名预设：** `base-nova`、`radix-nova`
**模板：** `next`、`vite`、`start`、`react-router`、`astro`（均支持`--monorepo`）和`laravel`（不支持monorepo）
**预设代码：** 以`a`开头的Base62字符串（比如`a2r6bw`），来自[ui.shadcn.com](https://ui.shadcn.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, className, spacing, size, truncate, dark mode, cn(), z-index
rules/base-vs-radix.md — asChild vs render, Select, ToggleGroup, Slider, Accordion
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 — 语义化颜色、变体、className、间距、size、truncate、暗色模式、cn()、z-index
rules/base-vs-radix.md — asChild和render的区别、Select、ToggleGroup、Slider、Accordion
cli.md — 命令、参数、预设、模板
customization.md — 主题、CSS变量、扩展组件