shadcn-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui Components

shadcn/ui 组件

Add shadcn/ui components to a themed React project. This skill runs AFTER

tailwind-theme-builder

has set up CSS variables, ThemeProvider, and dark mode. It handles component installation, customisation, and combining components into working patterns.

Prerequisite: Theme infrastructure must exist (CSS variables, components.json, cn() utility). Use

tailwind-theme-builder

first if not set up.

为已配置主题的React项目添加shadcn/ui组件。该技能需在

tailwind-theme-builder

完成CSS变量、ThemeProvider和深色模式配置后使用，负责组件安装、自定义以及将组件组合为可用的交互模式。

前置要求：必须已搭建主题基础设施（CSS变量、components.json、cn()工具函数）。若未配置，请先使用

tailwind-theme-builder

。

Installation Order

安装顺序

Install components in dependency order. Foundation components first, then feature components:

按照依赖顺序安装组件。先安装基础组件，再安装功能组件：

Foundation (install first)

基础组件（优先安装）

bash

pnpm dlx shadcn@latest add button
pnpm dlx shadcn@latest add input label
pnpm dlx shadcn@latest add card

bash

pnpm dlx shadcn@latest add button
pnpm dlx shadcn@latest add input label
pnpm dlx shadcn@latest add card

Feature Components (install as needed)

功能组件（按需安装）

bash

undefined

bash

undefined

Forms

表单

pnpm dlx shadcn@latest add form # needs: react-hook-form, zod, @hookform/resolvers pnpm dlx shadcn@latest add textarea select checkbox switch

pnpm dlx shadcn@latest add form # 依赖：react-hook-form, zod, @hookform/resolvers pnpm dlx shadcn@latest add textarea select checkbox switch

Feedback

反馈组件

pnpm dlx shadcn@latest add toast # needs: sonner pnpm dlx shadcn@latest add alert badge

pnpm dlx shadcn@latest add toast # 依赖：sonner pnpm dlx shadcn@latest add alert badge

Overlay

覆盖层组件

pnpm dlx shadcn@latest add dialog sheet popover dropdown-menu

Data Display

数据展示

pnpm dlx shadcn@latest add table # for data tables, also: @tanstack/react-table pnpm dlx shadcn@latest add tabs separator avatar

pnpm dlx shadcn@latest add table # 用于数据表格，额外依赖：@tanstack/react-table pnpm dlx shadcn@latest add tabs separator avatar

Navigation

导航组件

pnpm dlx shadcn@latest add navigation-menu command

undefined

pnpm dlx shadcn@latest add navigation-menu command

undefined

External Dependencies

外部依赖

Component	Requires
Form	`react-hook-form` , `zod` , `@hookform/resolvers`
Toast	`sonner`
Data Table	`@tanstack/react-table`
Command	`cmdk`
Date Picker	`date-fns` (optional)

Install external deps separately:

pnpm add react-hook-form zod @hookform/resolvers

组件	依赖项
Form	`react-hook-form` , `zod` , `@hookform/resolvers`
Toast	`sonner`
数据表格	`@tanstack/react-table`
Command	`cmdk`
日期选择器	`date-fns` （可选）

单独安装外部依赖：

pnpm add react-hook-form zod @hookform/resolvers

Known Gotchas

常见问题与解决方案

These are documented corrections that prevent common bugs:

以下是经过验证的修正方案，可避免常见bug：

Radix Select — No Empty Strings

Radix Select — 避免空字符串

tsx

// Don't use empty string values
<SelectItem value="">All</SelectItem>           // BREAKS

// Use sentinel value
<SelectItem value="__any__">All</SelectItem>    // WORKS
const actual = value === "__any__" ? "" : value

tsx

// 不要使用空字符串作为值
<SelectItem value="">全部</SelectItem>           // 会出错

// 使用标记值
<SelectItem value="__any__">全部</SelectItem>    // 正常工作
const actual = value === "__any__" ? "" : value

React Hook Form — Null Values

React Hook Form — 空值处理

tsx

// Don't spread {...field} — it passes null which Input rejects
<Input
  value={field.value ?? ''}
  onChange={field.onChange}
  onBlur={field.onBlur}
  name={field.name}
  ref={field.ref}
/>

tsx

// 不要展开{...field} — 它会传递null，而Input组件不接受该值
<Input
  value={field.value ?? ''}
  onChange={field.onChange}
  onBlur={field.onBlur}
  name={field.name}
  ref={field.ref}
/>

Lucide Icons — Tree-Shaking

Lucide Icons — 摇树优化问题

tsx

// Don't use dynamic import — icons get tree-shaken in production
import * as LucideIcons from 'lucide-react'
const Icon = LucideIcons[iconName]  // BREAKS in prod

// Use explicit map
import { Home, Users, Settings, type LucideIcon } from 'lucide-react'
const ICON_MAP: Record<string, LucideIcon> = { Home, Users, Settings }
const Icon = ICON_MAP[iconName]

tsx

// 不要使用动态导入 — 生产环境中图标会被摇树优化移除
import * as LucideIcons from 'lucide-react'
const Icon = LucideIcons[iconName]  // 生产环境失效

// 使用显式映射
import { Home, Users, Settings, type LucideIcon } from 'lucide-react'
const ICON_MAP: Record<string, LucideIcon> = { Home, Users, Settings }
const Icon = ICON_MAP[iconName]

Dialog Width Override

Dialog 宽度覆盖

tsx

// Default sm:max-w-lg won't be overridden by max-w-6xl
<DialogContent className="max-w-6xl">       // DOESN'T WORK

// Use same breakpoint prefix
<DialogContent className="sm:max-w-6xl">    // WORKS

tsx

// 默认的sm:max-w-lg不会被max-w-6xl覆盖
<DialogContent className="max-w-6xl">       // 无效

// 使用相同的断点前缀
<DialogContent className="sm:max-w-6xl">    // 有效

Customising Components

组件自定义

shadcn components use semantic CSS tokens from your theme. To customise:

shadcn组件使用主题中的语义化CSS令牌进行样式控制。自定义方式如下：

Variant extension

扩展变体

Add custom variants by editing the component file in

src/components/ui/

tsx

// button.tsx — add a "brand" variant
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      brand: "bg-brand text-brand-foreground hover:bg-brand/90",
      // ... existing variants
    },
  },
})

通过编辑

src/components/ui/

目录下的组件文件添加自定义变体：

tsx

// button.tsx — 添加"brand"变体
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      brand: "bg-brand text-brand-foreground hover:bg-brand/90",
      // ... 现有变体
    },
  },
})

Colour overrides

颜色覆盖

Use semantic tokens from your theme — never raw Tailwind colours:

tsx

// Don't use raw colours
<Button className="bg-blue-500">             // WRONG

// Use semantic tokens
<Button className="bg-primary">              // RIGHT
<Card className="bg-card text-card-foreground">  // RIGHT

使用主题中的语义化令牌——切勿直接使用Tailwind原始颜色：

tsx

// 不要使用原始颜色
<Button className="bg-blue-500">             // 错误

// 使用语义化令牌
<Button className="bg-primary">              // 正确
<Card className="bg-card text-card-foreground">  // 正确

Workflow

工作流程

Step 1: Assess Needs

步骤1：评估需求

Determine what UI patterns the project needs:

Need	Components
Forms with validation	Form, Input, Label, Select, Textarea, Button, Toast
Data display with sorting	Table, Badge, Pagination
Admin CRUD interface	Dialog, Form, Table, Button, Toast
Marketing/landing page	Card, Button, Badge, Separator
Settings/preferences	Tabs, Form, Switch, Select, Toast
Navigation	NavigationMenu (desktop), Sheet (mobile), ModeToggle

确定项目所需的UI交互模式：

需求	对应组件
带验证的表单	Form、Input、Label、Select、Textarea、Button、Toast
带排序的数据展示	Table、Badge、Pagination
后台CRUD界面	Dialog、Form、Table、Button、Toast
营销/落地页	Card、Button、Badge、Separator
设置/偏好页面	Tabs、Form、Switch、Select、Toast
导航	NavigationMenu（桌面端）、Sheet（移动端）、ModeToggle

Step 2: Install Components

步骤2：安装组件

Install foundation first, then feature components for the identified needs. Use the commands above.

先安装基础组件，再根据已确定的需求安装功能组件，使用上述提供的命令。

Step 3: Build Recipes

步骤3：构建交互方案

Combine components into working patterns. See references/recipes.md for complete working examples:

Contact Form — Form + Input + Textarea + Button + Toast
Data Table — Table + Column sorting + Pagination + Search
Modal CRUD — Dialog + Form + Button
Navigation — Sheet + NavigationMenu + ModeToggle
Settings Page — Tabs + Form + Switch + Select + Toast

将组件组合为可用的交互模式。完整的可用示例请查看references/recipes.md：

联系表单 — Form + Input + Textarea + Button + Toast
数据表格 — Table + 列排序 + 分页 + 搜索
模态框CRUD — Dialog + Form + Button
导航系统 — Sheet + NavigationMenu + ModeToggle
设置页面 — Tabs + Form + Switch + Select + Toast

Step 4: Customise

步骤4：自定义

Apply project-specific colours and variants using semantic tokens from the theme.

使用主题中的语义化令牌，应用项目专属的颜色和组件变体。

Reference Files

参考文档

When	Read
Choosing components, install commands, props	references/component-catalogue.md
Building complete UI patterns	references/recipes.md

场景	参考文档
选择组件、安装命令、组件属性	references/component-catalogue.md
构建完整UI交互模式	references/recipes.md