shadcn by shadcn/ui
npx skills add https://github.com/shadcn/ui --skill shadcn包含 Shell 命令
此技能包含可能执行系统命令的 shell 命令指令(!命令``)。安装前请仔细审查。
一个用于构建用户界面、组件和设计系统的框架。组件通过 CLI 以源代码形式添加到用户的项目中。
重要提示: 使用项目的包运行器运行所有 CLI 命令:
npx shadcn@latest、pnpm dlx shadcn@latest或bunx --bun shadcn@latest—— 具体取决于项目的packageManager。下面的示例使用npx shadcn@latest,但请根据项目替换正确的运行器。
!`npx shadcn@latest info --json`
上面的 JSON 包含项目配置和已安装的组件。使用 npx shadcn@latest docs <组件名> 获取任何组件的文档和示例 URL。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
npx shadcn@latest search 检查注册表。也要检查社区注册表。variant="outline"、size="sm" 等。bg-primary、text-muted-foreground —— 永远不要使用像 bg-blue-500 这样的原始值。这些规则必须始终遵守。每条规则都链接到一个包含错误/正确代码对的文件。
className 用于布局,而非样式。 永远不要覆盖组件的颜色或排版样式。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 等会处理它们自己的堆叠顺序。FieldGroup + Field。 永远不要使用原始的 div 配合 space-y-* 或 grid gap-* 进行表单布局。InputGroup 使用 InputGroupInput/InputGroupTextarea。 永远不要在 InputGroup 内使用原始的 Input/Textarea。InputGroup + InputGroupAddon。ToggleGroup。 不要用 Button 循环并手动管理激活状态。FieldSet + FieldLegend。 不要使用带标题的 div。data-invalid + aria-invalid。 data-invalid 放在 Field 上,aria-invalid 放在控件上。对于禁用状态:data-disabled 放在 Field 上,disabled 放在控件上。SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。asChild (radix) 或 render (base)。 检查 npx shadcn@latest info 中的 base 字段。→ base-vs-radix.mdDialogTitle、SheetTitle、DrawerTitle。如果视觉上隐藏,使用 className="sr-only"。CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不要把所有东西都塞进 CardContent。isPending/isLoading。 使用 Spinner + data-icon + disabled 进行组合。TabsTrigger 必须在 TabsList 内部。 永远不要直接在 Tabs 中渲染触发器。Avatar 始终需要 AvatarFallback。 用于图片加载失败时。div 之前,检查是否存在相应的组件。Alert。 不要构建自定义样式的 div。Empty。 不要构建自定义的空状态标记。sonner。 使用 sonner 中的 toast()。Separator 而不是 <hr> 或 <div className="border-t">。Skeleton 作为加载占位符。不要使用自定义的 animate-pulse div。Badge 而不是自定义样式的 span。Button 中的图标使用 data-icon。 在图标上设置 data-icon="inline-start" 或 data-icon="inline-end"。size-4 或 w-4 h-4。icon={CheckIcon},而不是字符串查找。npx shadcn@latest init --preset <code>。这些是区分正确的 shadcn/ui 代码的最常见模式。对于边缘情况,请参阅上面链接的规则文件。
// 表单布局:FieldGroup + Field,而不是 div + Label。
<FieldGroup>
<Field>
<FieldLabel htmlFor="email">邮箱</FieldLabel>
<Input id="email" />
</Field>
</FieldGroup>
// 验证:data-invalid 在 Field 上,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 变体或语义化标记,而非原始颜色。
<Badge variant="secondary">+20.1%</Badge> // 正确
<span className="text-emerald-600">+20.1%</span> // 错误
| 需求 | 使用 |
|---|---|
| 按钮/操作 | 具有适当变体的 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 |
| 图表 | Chart (包装 Recharts) |
| 布局 | Card、Separator、Resizable、ScrollArea、Accordion、Collapsible |
| 空状态 | Empty |
| 菜单 | DropdownMenu、ContextMenu、Menubar |
| 工具提示/信息 | Tooltip、HoverCard、Popover |
注入的项目上下文包含以下关键字段:
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 命令。
运行 npx shadcn@latest docs <组件名> 获取组件的文档、示例和 API 参考的 URL。获取这些 URL 以获取实际内容。
npx shadcn@latest docs button dialog select
在创建、修复、调试或使用组件时,务必先运行 npx shadcn@latest docs 并获取 URL。 这确保您使用的是正确的 API 和使用模式,而不是猜测。
npx shadcn@latest info。add 之前,始终检查项目上下文中的 components 列表或列出 resolvedPaths.ui 目录。不要导入尚未添加的组件,也不要重新添加已安装的组件。npx shadcn@latest search。npx shadcn@latest docs <组件名> 获取 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,保持组件不变。
* 重要提示:始终在用户的项目目录内运行预设命令。CLI 会自动保留 components.json 中的当前基础库(base 与 )。如果必须使用临时/临时目录(例如用于 比较),请显式传递 —— 预设代码不编码基础库。当用户要求从上游更新组件同时保留其本地更改时,使用 --dry-run 和 --diff 进行智能合并。永远不要手动从 GitHub 获取原始文件 —— 始终使用 CLI。
npx shadcn@latest add <组件名> --dry-run 查看所有将受影响的文件。npx shadcn@latest add <组件名> --diff <文件名> 查看上游与本地之间的差异。--overwrite,但需先确认。--overwrite。# 创建新项目。
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite
# 创建 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
# 初始化现有项目。
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults # 快捷方式:--template=next --preset=base-nova
# 添加组件。
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add --all
# 在添加/更新前预览更改。
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 search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"
# 获取组件文档和示例 URL。
npx shadcn@latest docs button dialog select
# 查看注册表项详情(针对尚未安装的项)。
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。
每周安装量
40.8K
代码库
GitHub 星标数
110.5K
首次出现
2026年3月6日
安全审计
安装于
codex39.4K
cursor39.4K
github-copilot39.3K
opencode39.2K
gemini-cli38.9K
amp38.7K
Contains Shell Commands
This skill contains shell command directives (!command``) that may execute system commands. Review carefully before installing.
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, orbunx --bun shadcn@latest— based on the project'spackageManager. Examples below usenpx shadcn@latestbut substitute the correct runner for the project.
!`npx shadcn@latest info --json`
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.
npx shadcn@latest search to check registries before writing custom UI. Check community registries too.variant="outline", size="sm", etc.bg-primary, text-muted-foreground — never raw values like bg-blue-500.These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.
className for layout, not styling. Never override component colors or typography.space-x-* or space-y-*. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.size-* when width and height are equal. size-10 not w-10 h-10.truncate shorthand. Not .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.SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.asChild (radix) or render (base) for custom triggers. Check base field from npx shadcn@latest info. → base-vs-radix.mddiv.Alert. Don't build custom styled divs.Empty. Don't build custom empty state markup.sonner. Use toast() from sonner.Separator instead of <hr> or <div className="border-t">.Button use data-icon. data-icon="inline-start" or data-icon="inline-end" on the icon.size-4 or w-4 h-4.icon={CheckIcon}, not a string lookup.npx shadcn@latest init --preset <code>.These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.
// 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
| Need | Use |
|---|---|
| Button/action | Button with appropriate variant |
| Form inputs | Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, |
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 blocks; uses .See cli.md — info command for the full field reference.
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.
npx shadcn@latest docs button dialog select
When creating, fixing, debugging, or using a component, always runnpx 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 info again if you need to refresh.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.npx shadcn@latest search.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.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.
npx shadcn@latest add <component> --dry-run to see all files that would be affected.npx shadcn@latest add <component> --diff <file> to see what changed upstream vs local.--overwrite, but confirm first.--overwrite without the user's explicit approval.# 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=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.
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 .
Weekly Installs
40.8K
Repository
GitHub Stars
110.5K
First Seen
Mar 6, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex39.4K
cursor39.4K
github-copilot39.3K
opencode39.2K
gemini-cli38.9K
amp38.7K
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装
radix--dry-run--base <current-base>overflow-hidden text-ellipsis whitespace-nowrapdark: color overrides. Use semantic tokens (bg-background, text-muted-foreground).cn() for conditional classes. Don't write manual template literal ternaries.z-index on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.InputGroup + InputGroupAddon.ToggleGroup. Don't loop Button with manual active state.FieldSet + FieldLegend for grouping related checkboxes/radios. Don't use a div with a heading.data-invalid + aria-invalid. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use className="sr-only" if visually hidden.CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.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.Skeleton for loading placeholders. No custom animate-pulse divs.Badge instead of custom styled spans.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 |
@theme inline"v3"tailwind.config.jstailwindCssFile → 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).npx shadcn@latest add. When updating existing components, use --dry-run and --diff to preview changes first (see Updating Components below).@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.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.@shadcn, @tailark, etc.), ask which registry to use. Never default to a registry on behalf of the user.npx shadcn@latest init --preset <code> --force --reinstall. Overwrites all components.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.npx shadcn@latest init --preset <code> --force --no-reinstall. Only updates config and CSS, leaves components as-is.base vs radix) 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.