shadcn-ui

Next.js 的 Shadcn UI

概览

Shadcn UI 是一组基于 Radix UI 和 Tailwind CSS 构建的可复用组件。它不是 npm 包——CLI 会直接将组件源代码复制到项目的 components/ui/ 目录中。这样，你便能完全拥有并控制每个组件。所有组件默认均可访问（由 Radix 提供支持）、使用 Tailwind CSS 设置样式，并且可以组合使用。

官方文档： https://ui.shadcn.com

快速开始

在现有的 Next.js 项目中初始化 Shadcn UI：

npx shadcn@latest init

按需添加组件：

npx shadcn@latest add button card dialog

导入并使用：

import { Button } from "@/components/ui/button"

export default function Page() {
  return <Button variant="outline">Click me</Button>
}

如需查看完整的 CLI 参考（所有命令、标志和 components.json 架构），请参阅 references/cli-and-configuration.md。

核心工作流

使用 Shadcn UI 构建时，请遵循以下标准流程：

1. 初始化 — 运行 npx shadcn@latest init 以生成 components.json 并设置路径
2. 添加组件 — 对需要的每个组件运行 npx shadcn@latest add [name]
3. 组合 UI — 在页面和布局中组合组件，并为交互式组件添加 "use client" 包装
4. 主题 — 在 globals.css 中配置 CSS 变量，以支持浅色／深色模式
5. 自定义 — 如有需要，直接编辑 components/ui/ 中的组件源代码

组件导入约定

所有 Shadcn 组件都会安装到 components/ui/，并使用 @/ 路径别名：

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

每个 Shadcn 组件内部都是客户端组件（使用 Radix UI 钩子）。在 Next.js App Router 中使用时：

• 在顶部包含 "use client" 的文件中导入，或者
• 在客户端组件包装器中导入

如需查看完整的组件目录（按类别划分，包含安装命令、导入方式和变体），请参阅 references/components.md。

Next.js App Router 集成

服务端组件与客户端组件

Shadcn 组件使用 Radix UI 原语（钩子、引用和事件处理程序），因此需要客户端运行时。请遵循以下规则：

场景	处理方式
仅包含 Shadcn 组件的页面	在页面文件中添加 "use client"
混合使用数据获取和 UI 的页面	保持页面为服务端组件；将交互部分提取到客户端组件中
包含提供程序的布局	在 "use client" 包装组件中添加提供程序

在 layout.tsx 中设置提供程序

将全局提供程序放入专用的客户端组件中：

// app/providers.tsx
"use client"
import { ThemeProvider } from "next-themes"
import { TooltipProvider } from "@/components/ui/tooltip"

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <TooltipProvider>
        {children}
      </TooltipProvider>
    </ThemeProvider>
  )
}

// app/layout.tsx (Server Component)
import { Providers } from "./providers"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

如需了解布局模式、响应式设计和组件组合，请参阅 references/composition-patterns.md。

构建表单

Shadcn 表单使用 React Hook Form + Zod 进行验证，并使用 Shadcn Form 组件构建 UI：

npx shadcn@latest add form input label
npm install zod

核心模式：

"use client"
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { z } from "zod"
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"

const schema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function MyForm() {
  const form = useForm<z.infer<typeof schema>>({
    resolver: zodResolver(schema),
    defaultValues: { email: "", name: "" },
  })

  function onSubmit(values: z.infer<typeof schema>) {
    // handle submission
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
        <FormField control={form.control} name="email" render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl><Input placeholder="[email protected]" {...field} /></FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  )
}

如需了解高级表单模式（选择框、复选框、日期选择器、动态数组和 Server Actions），请参阅 references/forms.md 和 examples/form-with-validation.tsx。

数据表格

Shadcn 数据表格使用 TanStack Table，采用 3 个文件的架构：

npx shadcn@latest add table
npm install @tanstack/react-table

文件	用途
columns.tsx	使用访问器、表头和单元格渲染器定义 ColumnDef[]
data-table.tsx	使用 useReactTable 构建可复用的 <DataTable> 组件
page.tsx	获取数据（服务端组件）并传递给 <DataTable>

如需了解列定义、排序、筛选、分页和行选择模式，请参阅 references/data-tables.md 和 examples/data-table-example.tsx。

主题

Shadcn UI 使用 globals.css 中的 CSS 变量定义所有颜色令牌。新版 Shadcn 使用 oklch 颜色格式：

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* ... */
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* ... */
}

使用 next-themes 启用深色模式：

npm install next-themes

如需查看完整的变量列表、深色模式切换组件、TweakCN 编辑器工作流、侧边栏令牌和自定义颜色，请参阅 references/theming-and-dark-mode.md。

图表

Shadcn 图表使用带主题的组件封装 Recharts：

npx shadcn@latest add chart
npm install recharts

核心模式：定义一个 ChartConfig 对象，将数据键映射到标签和颜色，并将 Recharts 组件包裹在 <ChartContainer> 中：

const chartConfig = {
  desktop: { label: "Desktop", color: "var(--chart-1)" },
  mobile: { label: "Mobile", color: "var(--chart-2)" },
} satisfies ChartConfig

有关所有图表类型、工具提示/图例配置和响应式模式，请参阅 references/charts.md 和 examples/chart-config-example.tsx。

区块

区块是预先构建的整页或分区级组合（仪表板、登录页、侧边栏）。将区块源码复制到项目中，并安装所需组件。

有关区块目录、文件结构、依赖项和侧边栏系统，请参阅 references/blocks.md 和 examples/dashboard-layout.tsx。

关键规则

应该做	不应该做
使用 npx shadcn@latest add 安装组件	通过 npm 安装组件
从 @/components/ui/... 导入	从 shadcn 或 @shadcn/ui 导入
使用 CSS 变量设置主题（oklch）	在组件中硬编码颜色值
使用交互式组件时添加 "use client"	不使用客户端包装器，直接在服务端组件中使用 Shadcn 组件
编辑 components/ui/ 中的组件源码进行自定义	为简单的样式变更创建包装组件
为区块安装所有依赖项	复制区块代码时不包含其必需组件

参考文件

详细指南

• references/cli-and-configuration.md — CLI 命令、components.json 架构、别名、包管理器
• references/components.md — 按类型分类的完整组件目录，包含变体和导入方式
• references/composition-patterns.md — 布局模式、服务端/客户端组件、提供程序、响应式设计
• references/forms.md — React Hook Form + Zod + Shadcn Form 组件模式
• references/data-tables.md — TanStack Table 集成、列、排序、筛选、分页
• references/charts.md — Recharts 集成、ChartConfig、所有图表类型、工具提示
• references/blocks.md — 区块目录、侧边栏系统、仪表板模式、依赖项
• references/theming-and-dark-mode.md — CSS 变量、oklch、next-themes、TweakCN、自定义颜色
• references/accessibility.md — 内置 Radix 无障碍支持、开发者责任、ARIA 模式

代码示例

• examples/form-with-validation.tsx — 完整表单，包含 Zod 架构、多种字段类型和提交处理器
• examples/data-table-example.tsx — 包含列、排序和分页的数据表格
• examples/dashboard-layout.tsx — 包含侧边栏、页眉和内容区域的仪表板布局
• examples/chart-config-example.tsx — 包含完整 ChartConfig、工具提示和图例的柱状图