shadcn-ui

shadcn/ui 组件模式

使用 shadcn/ui、Radix UI 和 Tailwind CSS 构建易于访问且可自定义的 UI 组件。

概览

• 组件会复制到你的项目中——你拥有并可自定义这些代码
• 基于 Radix UI 原语构建，具备完整的无障碍支持
• 使用 Tailwind CSS 和 CSS 变量设置样式并配置主题
• 基于 CLI 安装：npx shadcn@latest add <component>

适用场景

当用户的请求涉及以下内容时启用：

• “设置 shadcn/ui”“初始化 shadcn”“添加 shadcn 组件”
• “安装 button/input/form/dialog/card/select/toast/table/chart”
• “React Hook Form”“Zod 验证”“带验证的表单”
• “无障碍组件”“Radix UI”“Tailwind 主题”
• “shadcn button”“shadcn dialog”“shadcn sheet”“shadcn table”
• “深色模式”“CSS 变量”“自定义主题”
• “使用 Recharts 绘制图表”“柱状图”“折线图”“饼图”

快速参考

可用组件

组件	安装命令	描述
button	npx shadcn@latest add button	变体：default、destructive、outline、secondary、ghost、link
input	npx shadcn@latest add input	文本输入字段
form	npx shadcn@latest add form	集成 React Hook Form 和验证
card	npx shadcn@latest add card	包含页眉、内容和页脚的容器
dialog	npx shadcn@latest add dialog	模态覆盖层
sheet	npx shadcn@latest add sheet	滑出面板（上／右／下／左）
select	npx shadcn@latest add select	下拉选择框
toast	npx shadcn@latest add toast	通知提示
table	npx shadcn@latest add table	数据表格
menubar	npx shadcn@latest add menubar	桌面风格菜单栏
chart	npx shadcn@latest add chart	支持主题配置的 Recharts 封装
textarea	npx shadcn@latest add textarea	多行文本输入框
checkbox	npx shadcn@latest add checkbox	复选框输入项
label	npx shadcn@latest add label	无障碍表单标签

说明

初始化项目

# New Next.js project
npx create-next-app@latest my-app --typescript --tailwind --eslint --app
cd my-app
npx shadcn@latest init

# Existing project
npm install tailwindcss-animate class-variance-authority clsx tailwind-merge lucide-react
npx shadcn@latest init

# Install components
npx shadcn@latest add button input form card dialog select toast

基本组件用法

// Button with variants and sizes
import { Button } from "@/components/ui/button"

<Button variant="default">Default</Button>
<Button variant="destructive" size="sm">Delete</Button>
<Button variant="outline" disabled>Loading...</Button>

使用 Zod 验证的表单

"use client"

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

const formSchema = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(8, "Password must be at least 8 characters"),
})

export function LoginForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: { email: "", password: "" },
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(console.log)} className="space-y-4">
        <FormField name="email" control={form.control} render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl><Input type="email" {...field} /></FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <FormField name="password" control={form.control} render={({ field }) => (
          <FormItem>
            <FormLabel>Password</FormLabel>
            <FormControl><Input type="password" {...field} /></FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit">Login</Button>
      </form>
    </Form>
  )
}

有关高级多字段表单、带 API 提交功能的联系表单以及登录卡片模式，请参阅 references/forms-and-validation.md。

对话框（模态框）

import { Button } from "@/components/ui/button"
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>
    </DialogHeader>
    {/* content */}
  </DialogContent>
</Dialog>

Toast 通知

// 1. Add <Toaster /> to app/layout.tsx
import { Toaster } from "@/components/ui/toaster"

// 2. Use in components
import { useToast } from "@/components/ui/use-toast"

const { toast } = useToast()
toast({ title: "Success", description: "Changes saved." })
toast({ variant: "destructive", title: "Error", description: "Something went wrong." })

柱状图

import { Bar, BarChart, CartesianGrid, XAxis } from "recharts"
import { ChartContainer, ChartTooltipContent } from "@/components/ui/chart"

const chartConfig = {
  desktop: { label: "Desktop", color: "var(--chart-1)" },
} satisfies import("@/components/ui/chart").ChartConfig

<ChartContainer config={chartConfig} className="min-h-[200px] w-full">
  <BarChart data={data}>
    <CartesianGrid vertical={false} />
    <XAxis dataKey="month" />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <ChartTooltip content={<ChartTooltipContent />} />
  </BarChart>
</ChartContainer>

有关折线图、面积图和饼图示例，请参阅 references/charts-components.md。

示例

带验证的登录表单

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

const formSchema = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(8, "Min 8 characters"),
})

export function LoginForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: { email: "", password: "" },
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(console.log)} className="space-y-4">
        <FormField name="email" control={form.control} render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl><Input type="email" {...field} /></FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <FormField name="password" control={form.control} render={({ field }) => (
          <FormItem>
            <FormLabel>Password</FormLabel>
            <FormControl><Input type="password" {...field} /></FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit">Login</Button>
      </form>
    </Form>
  )
}

带操作的数据表格

import { ColumnDef } from "@tanstack/react-table"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import { DataTable } from "@/components/ui/data-table"

const columns: ColumnDef<User>[] = [
  { id: "select", header: ({ table }) => (
    <Checkbox checked={table.getIsAllPageRowsSelected()} />
  ), cell: ({ row }) => (
    <Checkbox checked={row.getIsSelected()} />
  )},
  { accessorKey: "name", header: "Name" },
  { accessorKey: "email", header: "Email" },
  { id: "actions", cell: ({ row }) => (
    <Button variant="ghost" size="sm">Edit</Button>
  )},
]

带表单的对话框

import { Button } from "@/components/ui/button"
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Add User</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Add New User</DialogTitle>
    </DialogHeader>
    {/* <LoginForm /> */}
  </DialogContent>
</Dialog>

Toast 通知

import { useToast } from "@/components/ui/use-toast"
import { Button } from "@/components/ui/button"

const { toast } = useToast()

toast({ title: "Saved", description: "Changes saved successfully." })
toast({ variant: "destructive", title: "Error", description: "Failed to save." })

最佳实践

• 无障碍性：使用 Radix UI 原语——内置 ARIA 属性
• 客户端组件：为交互式组件（hooks、事件）添加 "use client"
• 类型安全：使用 TypeScript 和 Zod 模式验证表单
• 主题配置：在 globals.css 中配置 CSS 变量，确保设计一致
• 自定义：直接修改组件文件——你拥有这些代码
• 路径别名：确保在 tsconfig.json 中配置了 @ 别名
• 注册表安全：仅从可信注册表安装组件；在生产环境中使用前检查生成的代码
• 深色模式：使用 CSS 变量策略和 next-themes 进行设置
• 表单：始终将 Form、FormField、FormItem、FormLabel、FormMessage 配合使用
• Toaster：在根布局中添加一次 <Toaster />

限制与警告

• 不是 NPM 包：组件会复制到你的项目中；它们不是带版本号的依赖项
• 注册表安全性：通过 npx shadcn@latest add 添加的组件会从远程获取；安装前请务必确认注册表来源可信
• 客户端组件：大多数交互式组件都需要 "use client" 指令
• Radix 依赖项：确保已安装所有 @radix-ui 包
• 需要 Tailwind：组件依赖 Tailwind CSS 工具类
• 路径别名：在 tsconfig.json 中配置 @ 别名以供导入

参考资料

如需了解详细模式和代码示例，请参阅以下文件：

• references/setup-and-configuration.md — 完整的安装、tsconfig、tailwind 配置和 CSS 变量说明
• references/ui-components.md — Button、Input、Card、Dialog、Sheet、Select、Toast、Table、Menubar
• references/forms-and-validation.md — React Hook Form + Zod、高级表单、登录卡片、联系表单
• references/charts-components.md — 使用 ChartContainer 和主题的 Bar、Line、Area、Pie 图表
• references/nextjs-integration.md — App Router、Server/Client Components、深色模式、元数据
• references/customization.md — 自定义变体、CSS 变量、cn() 工具、扩展组件