shadcn/ui 组件库：基于 Radix UI 和 Tailwind CSS 的可访问、可定制 React UI 组件

shadcn-ui by giuseppe-trisciuoglio/developer-kit

12,600 周安装量

176 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill 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`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

带 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>
  )
}

查看 references/forms-and-validation.md 以获取高级多字段表单、带 API 提交的联系表单和登录卡片模式。

对话框（模态框）

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>

// 1. 将 <Toaster /> 添加到 app/layout.tsx
import { Toaster } from "@/components/ui/toaster"

// 2. 在组件中使用
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>

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 属性已内置
客户端组件：为交互式组件（钩子、事件）添加 "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() 工具函数、扩展组件

🇺🇸English

shadcn/ui Component Patterns

Build accessible, customizable UI components with shadcn/ui, Radix UI, and Tailwind CSS.

Overview

Components are copied into your project — you own and customize the code
Built on Radix UI primitives for full accessibility
Styled with Tailwind CSS and CSS variables for theming
CLI-based installation: npx shadcn@latest add <component>

When to Use

Activate when user requests involve:

"Set up shadcn/ui", "initialize shadcn", "add shadcn components"
"Install button/input/form/dialog/card/select/toast/table/chart"
"React Hook Form", "Zod validation", "form with validation"
"accessible components", "Radix UI", "Tailwind theme"
"shadcn button", "shadcn dialog", "shadcn sheet", "shadcn table"
"dark mode", "CSS variables", "custom theme"
"charts with Recharts", "bar chart", "line chart", "pie chart"

Quick Reference

Available Components

Component	Install Command	Description
`button`	`npx shadcn@latest add button`	Variants: default, destructive, outline, secondary, ghost, link
`input`	`npx shadcn@latest add input`	Text input field
`form`	`npx shadcn@latest add form`	React Hook Form integration with validation
`card`	`npx shadcn@latest add card`	Container with header, content, footer
`dialog`	`npx shadcn@latest add dialog`	Modal overlay
`sheet`	`npx shadcn@latest add sheet`	Slide-over panel (top/right/bottom/left)
`select`	`npx shadcn@latest add select`	Dropdown select
`toast`	`npx shadcn@latest add toast`	Notification toasts
`table`	`npx shadcn@latest add table`	Data table
`menubar`	`npx shadcn@latest add menubar`	Desktop-style menubar
`chart`	`npx shadcn@latest add chart`	Recharts wrapper with theming
`textarea`	`npx shadcn@latest add textarea`	Multi-line text input
`checkbox`	`npx shadcn@latest add checkbox`	Checkbox input
`label`	`npx shadcn@latest add label`	Accessible form label

Instructions

Initialize Project

# 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

Basic Component Usage

// 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>

Form with Zod Validation

"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>
  )
}

See references/forms-and-validation.md for advanced multi-field forms, contact forms with API submission, and login card patterns.

Dialog (Modal)

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 Notification

// 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." })

Bar Chart

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>

See references/charts-components.md for Line, Area, and Pie chart examples.

Examples

Login Form with Validation

"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>
  )
}

Data Table with Actions

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>
  )},
]

Dialog with Form

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 Notifications

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." })

Best Practices

Accessibility : Use Radix UI primitives — ARIA attributes are built in
Client Components : Add "use client" for interactive components (hooks, events)
Type Safety : Use TypeScript and Zod schemas for form validation
Theming : Configure CSS variables in globals.css for consistent design
Customization : Modify component files directly — you own the code
Path Aliases : Ensure @ alias is configured in tsconfig.json
Registry Security : Only install components from trusted registries; review generated code before production use
Dark Mode : Set up with CSS variables strategy and next-themes
Forms : Always use Form, FormField, , , together

Constraints and Warnings

Not an NPM Package : Components are copied to your project; they are not a versioned dependency
Registry Security : Components from npx shadcn@latest add are fetched remotely; always verify the registry source is trusted before installation
Client Components : Most interactive components require "use client" directive
Radix Dependencies : Ensure all @radix-ui packages are installed
Tailwind Required : Components rely on Tailwind CSS utilities
Path Aliases : Configure @ alias in tsconfig.json for imports

References

Consult these files for detailed patterns and code examples:

references/setup-and-configuration.md — Full installation, tsconfig, tailwind config, CSS variables
references/ui-components.md — Button, Input, Card, Dialog, Sheet, Select, Toast, Table, Menubar
references/forms-and-validation.md — React Hook Form + Zod, advanced forms, login card, contact form
references/charts-components.md — Bar, Line, Area, Pie charts with ChartContainer and theming
references/nextjs-integration.md — App Router, Server/Client Components, dark mode, metadata
references/customization.md — Custom variants, CSS variables, cn() utility, extending components

Weekly Installs

12.1K

Repository

giuseppe-trisci…oper-kit

GitHub Stars

173

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode8.3K

gemini-cli8.0K

codex7.9K

claude-code7.9K

github-copilot7.5K

cursor6.9K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

Toaster : Add <Toaster /> once to root layout