shadcn-ui

shadcn/ui

概述

shadcn/ui 是一套基于 Radix UI 和 Tailwind CSS 构建的易于访问、可自定义的 React 组件。组件会复制到你的项目中（不通过 npm 包分发）；你拥有并可以编辑这些代码。适用于 Next.js（App Router）、Vite 和其他 React 框架。

原则：开放代码（可供 AI 使用）、可组合的 API、精美的默认样式，以及通过 CLI 和 schema 分发。需要 Tailwind v4 和路径别名 @/*。我们不使用 tailwind.config.js；主题和配置仅通过 CSS 设置（@import "tailwindcss" + @theme）。

---

前置条件

• Tailwind v4：在主 CSS 中添加 @import "tailwindcss"；使用 @tailwindcss/vite 或 @tailwindcss/postcss。不使用 tailwind.config.js。请参阅 tailwind-css skill。
• 路径别名 @/* → ./src/*（或你的源代码根目录），配置在 tsconfig 和打包工具中（例如 Vite 的 resolve.alias）。
• React（Next.js App Router、Vite 等）。

---

安装

参考：官方安装指南

新建项目（推荐）

使用 Tailwind 和 shadcn 创建项目脚手架。摘自官方文档：

操作	CLI 命令
新建项目	shadcn create
初始化现有项目	shadcn init
添加组件	shadcn add <name>

通过你的包管理器调用（参见文档）。选择框架（Next.js、Vite 等）、样式（推荐 new-york）、基础颜色和 CSS 变量。

现有项目（Next.js App Router）

1. 初始化 — 创建 components.json、可选的 cn 辅助函数和基础样式。运行：shadcn init（通过包管理器调用；参见上方文档）。

2. 路径和 Tailwind

   • tsconfig："baseUrl": "."、"paths": { "@/*": ["./src/*"] }（如果拆分配置，根目录和 app 的 tsconfig 都要设置）。
   • Tailwind v4：主 CSS（例如 app/globals.css）必须包含 @import "tailwindcss"，并在 postcss.config.mjs 中使用 @tailwindcss/postcss。不要添加 tailwind.config.js。

3. 添加组件 — 例如 shadcn add button、shadcn add card dialog（参见下方组件列表）。

组件会安装到 src/components/ui/（或 components.json 中指定的路径）。

现有项目（Vite）

• 在 vite.config.ts 中使用 resolve.alias: { "@": path.resolve(__dirname, "./src") }；如果使用 path，请添加 @types/node。
• Tailwind：在 Vite 配置中使用 @tailwindcss/vite，并在主 CSS 中添加 @import "tailwindcss"。

---

components.json

控制样式、路径和 Tailwind 集成。主要字段：

字段	用途
style	"new-york"（新项目的默认值）或 "default"
tailwind.config	使用 Tailwind v4 时留空为 ""；我们不使用 JS 配置文件
tailwind.css	全局 CSS 的路径（例如 src/styles/globals.css 或 app/globals.css），文件中包含 @import "tailwindcss"
tailwind.baseColor	主题基础颜色：neutral、slate、gray、zinc、stone
tailwind.cssVariables	使用 CSS 变量设置主题时为 true（推荐）
aliases.components	例如 @/components
aliases.utils	例如 @/lib/utils
aliases.ui	例如 @/components/ui
rsc	使用 Server Components 的 Next.js App Router 项目设为 true；仅客户端项目设为 false

在 Tailwind v4 中，主题通过 CSS 中的 @theme 和 CSS 变量设置，而不是写在配置文件中。

---

官方组件（当前列表）

通过 shadcn add <name> 添加（多个组件可用：shadcn add button card dialog）。通过包管理器调用：参见安装文档。

布局与结构

组件	CLI 名称	简短描述
Accordion	accordion	可折叠的分区（可展开单个或多个）
Aspect Ratio	aspect-ratio	固定宽高比的容器（例如，16/9）
Card	card	包含 CardHeader、CardTitle、CardDescription、CardContent、CardFooter 的容器
Collapsible	collapsible	可展开/折叠的内容
Resizable	resizable	可调整大小的面板
Separator	separator	水平或垂直分隔线
Scroll Area	scroll-area	带样式的滚动区域
Sidebar	sidebar	可组合、可换主题且可自定义的侧边栏

表单与输入

组件	CLI 名称	简短描述
Button	button	带有不同变体的按钮（default、destructive、outline、secondary、ghost、link）
Checkbox	checkbox	复选框
Form	form	使用 react-hook-form + zod 的表单（Field、FieldError 等）
Input	input	文本输入框
Input OTP	input-otp	OTP 验证码输入框
Label	label	控件的无障碍标签
Radio Group	radio-group	单选选项组
Select	select	包含 Trigger、Content、Item 的选择器
Slider	slider	滑块控件
Switch	switch	开/关切换开关
Textarea	textarea	多行文本区域

导航与菜单

组件	CLI 名称	简短描述
Breadcrumb	breadcrumb	面包屑导航
Command	command	命令面板（cmdk）
Context Menu	context-menu	上下文菜单（右键菜单）
Dropdown Menu	dropdown-menu	下拉菜单
Menubar	menubar	固定显示的菜单栏
Navigation Menu	navigation-menu	带子菜单的导航
Pagination	pagination	分页（上一页、下一页、页码）
Tabs	tabs	标签页（TabsList、TabsTrigger、TabsContent）

覆盖层与反馈

组件	CLI 名称	简短描述
Alert	alert	突出显示的消息（default、destructive）
Alert Dialog	alert-dialog	确认对话框（例如，删除）
Dialog	dialog	模态框
Drawer	drawer	侧边面板（Vaul）
Hover Card	hover-card	悬停时显示的卡片
Popover	popover	锚定的浮动容器
Sheet	sheet	滑出的侧边面板
Tooltip	tooltip	悬停/聚焦时显示的提示信息

数据与状态

组件	CLI 名称	简短描述
Avatar	avatar	图片或姓名首字母回退显示
Badge	badge	徽章（default、secondary、destructive、outline）
Calendar	calendar	日历（react-day-picker）
Carousel	carousel	轮播组件（embla）
Chart	chart	图表（recharts）
Progress	progress	进度条
Skeleton	skeleton	加载占位符
Sonner	sonner	Toast 通知（推荐；替代 toast）
Table	table	表格、TableHeader、TableBody、TableRow、TableCell 等
Toast	toast	Toast 通知（已弃用，推荐使用 Sonner）

切换与切换组

组件	CLI 名称	简短描述
Toggle	toggle	切换按钮（开/关）
Toggle Group	toggle-group	切换组（单选或多选）

---

使用组件

从别名路径导入（而非从 shadcn/ui 导入）：

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export default function Page() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center gap-4">
      <Button>Click me</Button>
      <Card className="w-[350px]">
        <CardHeader>
          <CardTitle>Card title</CardTitle>
        </CardHeader>
        <CardContent>Content here.</CardContent>
      </Card>
    </div>
  )
}

• 自定义：组件接受 className 并展开 props；使用 Tailwind 类和 cn() 助手函数（来自 @/lib/utils）合并类。
• 组合：布局时优先使用组合方式（例如，CardHeader + CardContent），而非 props。

---

主题设置（Tailwind v4，无配置文件）

我们只使用 Tailwind v4；不使用 tailwind.config.js。主题设置仅通过 CSS 完成：

• CSS 变量：启用 tailwind.cssVariables: true 后，主题由全局 CSS 中的变量驱动（例如 --background、--foreground、--primary、--primary-foreground、--muted、--muted-foreground、--accent、--destructive 等）。在该文件中覆盖这些变量。
• @theme：在与 @import "tailwindcss" 相同的 CSS 文件中使用 @theme { ... }，以添加或覆盖与 shadcn 变量相匹配的设计令牌。
• 基础颜色：在 components.json（tailwind.baseColor）中设置，或通过编辑全局 CSS 中的 CSS 变量设置。

---

常见模式

• 表单：添加 form；搭配 react-hook-form 和 zod 使用。使用 Input、Label、Button、Select、Checkbox 等组件。
• 布局：使用 Card 作为分区；在区块之间使用 Separator；使用 Tailwind（flex、grid、container）进行布局。
• 模态框和面板：使用 Dialog 创建模态框；使用 Sheet 或 Drawer 创建侧边面板。
• 菜单：DropdownMenu、Context Menu、Navigation Menu、Command（命令面板）。
• 反馈：使用 Alert 显示消息；使用 Sonner 显示提示消息；使用 Skeleton 显示加载状态。
• 图标：许多示例使用 lucide-react；如果项目使用图标，请添加该依赖。

---

常见错误

• 别名：确保 TypeScript 和打包工具中的 @/ 都指向 ./src/（或你的源代码根目录）。
• CSS 未加载：components.json（tailwind.css）中指定的文件必须在应用入口（例如 app/layout.tsx）中导入，并包含 @import "tailwindcss"。
• Tailwind 配置：不要创建或建议使用 tailwind.config.js。主题只能在 CSS 中设置（通过 @theme 和变量）。
• 导入：根据 components.json 中的配置，从 @/components/ui/<component> 导入，而不是从 shadcn/ui 导入。
• RSC：在 Next.js App Router 中，如果组件用于 Server Components，请在适用时于 components.json 中设置 rsc: true。

---

其他资源

• reference.md — 官方文档链接、Tailwind v4 + shadcn、组件目录。
• 官方文档：https://ui.shadcn.com/docs
• 组件：https://ui.shadcn.com/docs/components
• 目录（社区）：https://ui.shadcn.com/docs/directory