illegalCreed

中文

English

中文

English

Appearance

shadcn/ui 参考 ​

本文为 shadcn@4.7.x（2026 年 5 月稳定版） 的 API 速查文档——70+ 组件清单、CLI 完整命令表、components.json 字段、CSS 变量 token、cva API、TypeScript 类型、Blocks 列表、Themes 列表、Registry schema、MCP 配置一站式查询。

完整概念与示例见 入门 与 指南。

1. 70+ 组件完整清单 ​

1.1 Forms（11 + 个） ​

组件CLI add底层依赖一句话
Buttonbutton@radix-ui/react-slot + cva6 variant + 4 size 按钮
Checkboxcheckbox@radix-ui/react-checkbox复选框
Inputinput-文本输入框
Input Groupinput-group-输入框组（前后缀）
Input OTPinput-otpinput-otpOTP 验证码
Labellabel@radix-ui/react-label表单标签
Native Selectnative-select-原生 select
Radio Groupradio-group@radix-ui/react-radio-group单选组
Selectselect@radix-ui/react-select美化下拉
Switchswitch@radix-ui/react-switch开关
Textareatextarea-多行输入
Toggletoggle@radix-ui/react-toggle单按钮开关
Toggle Grouptoggle-group@radix-ui/react-toggle-group按钮组开关

1.2 Overlay（8 个） ​

组件CLI add底层依赖一句话
Alert Dialogalert-dialog@radix-ui/react-alert-dialog强制确认对话框
Context Menucontext-menu@radix-ui/react-context-menu右键菜单
Dialogdialog@radix-ui/react-dialog模态对话框
Drawerdrawervaul移动 / 桌面通用抽屉
Hover Cardhover-card@radix-ui/react-hover-card悬停卡片
Popoverpopover@radix-ui/react-popover弹出气泡
Sheetsheet@radix-ui/react-dialog4 方向侧边面板
Tooltiptooltip@radix-ui/react-tooltip提示气泡

1.3 Navigation（6 个） ​

组件CLI add底层依赖一句话
Breadcrumbbreadcrumb-面包屑
Dropdown Menudropdown-menu@radix-ui/react-dropdown-menu下拉菜单
Menubarmenubar@radix-ui/react-menubarmacOS 风格菜单栏
Navigation Menunavigation-menu@radix-ui/react-navigation-menu大型导航菜单
Paginationpagination-分页
Sidebarsidebar复合完整侧边栏方案

1.4 Display（12 个） ​

组件CLI add底层依赖一句话
Accordionaccordion@radix-ui/react-accordion手风琴
Alertalert-警告提示
Avataravatar@radix-ui/react-avatar头像（带 Fallback）
Badgebadgecva徽章
Cardcard-卡片容器
Emptyempty-空状态
Kbdkbd-键盘按键
Separatorseparator@radix-ui/react-separator分隔线
Skeletonskeleton-骨架屏
Spinnerspinner-加载旋转
Tabletable-基础表格
Typography--标题段落语义类

1.5 Selection / Interaction（6 个） ​

组件CLI add底层依赖一句话
Button Groupbutton-group-按钮组
Collapsiblecollapsible@radix-ui/react-collapsible单项折叠
ComboboxcomboboxBase UI 或 Command+Popover自动补全下拉
Commandcommandcmdk命令面板（cmd+k）
Itemitem-列表项
Tabstabs@radix-ui/react-tabs标签页

1.6 Layout（5 个） ​

组件CLI add底层依赖一句话
Aspect Ratioaspect-ratio@radix-ui/react-aspect-ratio宽高比容器
Directiondirection@radix-ui/react-directionRTL 方向
Fieldfield@radix-ui/react-slot表单字段封装
Resizableresizablereact-resizable-panels可拖拽分屏
Scroll Areascroll-area@radix-ui/react-scroll-area自定义滚动条

1.7 Specialized（12+ 个） ​

组件CLI add底层依赖一句话
Calendarcalendarreact-day-picker日历
Carouselcarouselembla-carousel-react轮播图
Chartchartrecharts数据可视化包装
Data Table- (文档)@tanstack/react-table数据表格模板
Date Picker- (文档)Calendar + Popover日期选择器
Formformreact-hook-form + @hookform/resolvers表单状态管理
Progressprogress@radix-ui/react-progress进度条
Sliderslider@radix-ui/react-slider范围滑块
Sonnersonnersonner现代 Toast
Toasttoast@radix-ui/react-toast旧 Toast

2. CLI 完整命令 ​

2.1 init ​

bash
pnpm dlx shadcn@latest init [options]
Option说明
-t, --template <name>框架模板：next / vite / start / react-router / astro / laravel
-b, --base <type>底层库：radix（默认）/ base
-p, --preset <code>用 Preset 配置
-d, --defaults默认设置
-f, --force强制覆盖
--css-variables / --no-css-variablesCSS 变量开关
--monorepo / --no-monorepoMonorepo 模式
--rtl / --no-rtlRTL 支持
--pointer / --no-pointer按钮 cursor: pointer
--name <name>项目名
--cwd <path>工作目录

2.2 add ​

bash
pnpm dlx shadcn@latest add [components...] [options]
Option说明
-y, --yes跳过确认
-o, --overwrite覆盖现有文件
-a, --all添加全部组件
-p, --path <path>自定义路径
--dry-run预览不写入
--cwd <path>工作目录
bash
# 单组件
pnpm dlx shadcn@latest add button

# 多组件
pnpm dlx shadcn@latest add button dialog dropdown-menu

# Block
pnpm dlx shadcn@latest add login-03 sidebar-07

# 私有 Registry
pnpm dlx shadcn@latest add @acme/my-component

# URL 直接安装
pnpm dlx shadcn@latest add https://acme.com/r/widget.json

# 全部
pnpm dlx shadcn@latest add -a -y

2.3 build ​

bash
pnpm dlx shadcn@latest build <registry.json> [options]
Option说明
-o, --output <dir>输出目录（默认 public/r）
--registry <name>Registry 名称
--cwd <path>工作目录

2.4 apply ​

bash
pnpm dlx shadcn@latest apply <preset-code> [options]
Option说明
--only <part>只应用：theme / font
-y, --yes跳过确认

2.5 view ​

bash
pnpm dlx shadcn@latest view <name> [options]

预览组件源码（不安装）。支持 @namespace/name。

2.6 search / list ​

bash
pnpm dlx shadcn@latest search <query> [options]
pnpm dlx shadcn@latest list [options]
Option说明
-q, --query <text>搜索词
-l, --limit <n>最大结果数
-o, --offset <n>跳过数

2.7 docs ​

bash
pnpm dlx shadcn@latest docs <component>
Option说明
-b, --base <type>radix / base
--jsonJSON 输出

获取组件文档（AI 友好）。

2.8 info ​

bash
pnpm dlx shadcn@latest info [options]
Option说明
--jsonJSON 输出

显示当前项目配置。

2.9 migrate ​

bash
pnpm dlx shadcn@latest migrate <migration>
Migration作用
icons切换图标库（lucide / radix / tabler）
radixRadix 1.x → 2.x
rtl启用 RTL

2.10 preset ​

bash
pnpm dlx shadcn@latest preset decode <code>     # 解码 Preset 内容
pnpm dlx shadcn@latest preset resolve <code>    # 解析最终配置
pnpm dlx shadcn@latest preset url <code>        # 获取 Preset URL
pnpm dlx shadcn@latest preset open <code>       # 浏览器打开

2.11 mcp ​

bash
pnpm dlx shadcn@latest mcp [command]
Subcommand说明
init --client claude配置 Claude Code
init --client cursor配置 Cursor
init --client vscode配置 VS Code

3. components.json 字段速查 ​

json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide",
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}
字段类型默认值初始化后可改说明
$schemastring-是JSON Schema
style"new-york" / "default" / "sera""new-york"否视觉风格
rscbooleanfalse是React Server Components 支持
tsxbooleantrue是TypeScript vs JavaScript
tailwind.configstring""是tailwind.config.js 路径（v4 留空）
tailwind.cssstring-是globals.css 路径
tailwind.baseColorstring"neutral"否8 选 1
tailwind.cssVariablesbooleantrue否用 CSS 变量 vs 直接 Tailwind 类
tailwind.prefixstring""是utility 类前缀（如 "tw-"）
aliases.componentsstring"@/components"是组件目录
aliases.utilsstring"@/lib/utils"是utils 路径
aliases.uistring"@/components/ui"是UI 组件路径
aliases.libstring"@/lib"是lib 目录
aliases.hooksstring"@/hooks"是hooks 目录
iconLibrary"lucide" / "radix" / "tabler""lucide"是图标库
registriesobject{}是自定义 Registry 命名空间

3.1 baseColor 8 个选项 ​

Value风格
neutral中性灰（默认）
stone暖灰
zinc冷灰
mauve紫灰
olive橄榄灰
mist雾蓝
taupe灰褐
slate石板蓝灰

4. CSS 变量 token 完整清单 ​

4.1 基础色 token ​

Variable用途
--background默认页面背景
--foreground默认前景文字
--card卡片背景
--card-foreground卡片前景
--popoverPopover / Dialog / Dropdown 背景
--popover-foregroundPopover 前景
--primary主操作色
--primary-foreground主操作前景
--secondary次操作色
--secondary-foreground次操作前景
--muted静音色（次要区域）
--muted-foreground静音前景（次要文字）
--accent强调色（hover / focus）
--accent-foreground强调前景
--destructive危险色（删除 / 错误）
--destructive-foreground危险前景
--border边框
--input输入框边框
--ring焦点环
--radius基础圆角（其他 radius 派生）

4.2 派生 radius ​

css
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);

4.3 Chart 配色 ​

Variable用途
--chart-1图表系列 1
--chart-2图表系列 2
--chart-3图表系列 3
--chart-4图表系列 4
--chart-5图表系列 5

4.4 Sidebar 专用 ​

Variable用途
--sidebarSidebar 背景
--sidebar-foregroundSidebar 前景
--sidebar-primarySidebar 主色
--sidebar-primary-foregroundSidebar 主色前景
--sidebar-accentSidebar 强调
--sidebar-accent-foregroundSidebar 强调前景
--sidebar-borderSidebar 边框
--sidebar-ringSidebar 焦点环

4.5 @theme inline 桥接 ​

css
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ...其余 token 同样桥接 */

  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);

  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  /* ... */
}

之后 Tailwind 即可使用 bg-background / text-foreground / bg-primary / fill-chart-1 / bg-sidebar 等 utility。

5. cn() 函数完整签名 ​

ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]): string;

5.1 ClassValue 类型 ​

ts
type ClassValue =
  | string
  | number
  | boolean
  | null
  | undefined
  | ClassValue[]
  | { [key: string]: any };

5.2 用法示例 ​

ts
cn("px-2", "py-1");                            // "px-2 py-1"
cn("px-2", isActive && "bg-blue-500");         // 条件
cn({ "bg-red-500": isError });                 // 对象语法
cn(["px-2", "py-1"]);                          // 数组语法
cn("px-2", "px-4");                            // → "px-4"（冲突解决）
cn("bg-red-500", "bg-blue-500");               // → "bg-blue-500"
cn("text-sm md:text-base", "md:text-lg");      // 保留 text-sm，md:text-lg 覆盖 md:text-base

6. cva API 完整签名 ​

ts
import { cva, type VariantProps } from "class-variance-authority";

cva(base, config): (props) => string

6.1 Config 结构 ​

ts
type Config = {
  variants?: Record<string, Record<string, string>>;
  defaultVariants?: Record<string, string>;
  compoundVariants?: Array<{
    [variantKey: string]: string | string[];
    className: string;
  }>;
};

6.2 完整示例 ​

ts
const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border border-input bg-background",
      },
      size: {
        sm: "h-8 px-3",
        md: "h-9 px-4",
        lg: "h-10 px-6",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "md",
    },
    compoundVariants: [
      {
        variant: "outline",
        size: "sm",
        className: "border-dashed",
      },
    ],
  },
);

// 自动 TypeScript
type Props = VariantProps<typeof buttonVariants>;
// type Props = {
//   variant?: "default" | "outline" | null | undefined;
//   size?: "sm" | "md" | "lg" | null | undefined;
// }

7. react-hook-form + zod 关键 API ​

7.1 useForm ​

ts
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

const form = useForm<FormValues>({
  resolver: zodResolver(schema),
  defaultValues: {...},
  mode: "onSubmit",   // "onChange" / "onBlur" / "onTouched" / "all"
});
Return说明
form.control传给 <FormField control>
form.register(name)注册原生 input
form.handleSubmit(onValid, onInvalid?)包装 submit
form.watch(name?)监听字段值
form.setValue(name, value)设值
form.reset(values?)重置表单
form.getValues()获取所有值
form.formState{ errors, isDirty, isSubmitting, isValid, ... }

7.2 zod 关键 API ​

ts
import { z } from "zod";

// 基础类型
z.string();
z.number();
z.boolean();
z.date();
z.array(z.string());
z.object({ name: z.string() });

// 链式校验
z.string().min(2).max(20).email();
z.number().int().positive().lt(100);
z.string().regex(/^[A-Z]+$/);

// 可选
z.string().optional();
z.string().nullable();

// 默认值
z.string().default("hello");

// 自定义错误
z.string().min(2, "至少 2 个字符");

// 类型推导
type FormValues = z.infer<typeof schema>;

// 跨字段校验
z.object({
  password: z.string(),
  confirm: z.string(),
}).refine((d) => d.password === d.confirm, {
  message: "不一致",
  path: ["confirm"],
});

// transform
z.string().transform((v) => v.trim());

7.3 shadcn Form 组件 ​

tsx
<Form {...form}>            // 包装 RHF FormProvider
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      control={form.control}
      name="email"
      render={({ field, fieldState, formState }) => (
        <FormItem>           // 容器
          <FormLabel>邮箱</FormLabel>  // <label htmlFor>
          <FormControl>      // <Slot id, aria-describedby, aria-invalid>
            <Input {...field} />
          </FormControl>
          <FormDescription>说明文字</FormDescription>  // <p id>
          <FormMessage />    // 错误显示
        </FormItem>
      )}
    />
  </form>
</Form>

7.4 useFormField hook ​

shadcn 内部 hook，可在自定义 FormItem 内使用：

ts
const { id, name, formItemId, formDescriptionId, formMessageId, error } =
  useFormField();

8. @tanstack/react-table 关键 API ​

8.1 useReactTable ​

ts
const table = useReactTable({
  data,                              // 数据数组
  columns,                           // 列定义
  state: {
    sorting,
    columnFilters,
    columnVisibility,
    rowSelection,
    pagination,
  },
  onSortingChange,
  onColumnFiltersChange,
  onColumnVisibilityChange,
  onRowSelectionChange,
  onPaginationChange,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  getFacetedRowModel: getFacetedRowModel(),
  getFacetedUniqueValues: getFacetedUniqueValues(),
});

8.2 列定义 ​

ts
import { type ColumnDef } from "@tanstack/react-table";

const columns: ColumnDef<MyData>[] = [
  {
    accessorKey: "email",
    header: "邮箱",
    cell: ({ row }) => row.getValue("email"),
    enableSorting: true,
    enableHiding: true,
    enableColumnFilter: true,
    filterFn: "includesString",
  },
  {
    id: "actions",
    cell: ({ row }) => <ActionMenu data={row.original} />,
    enableSorting: false,
    enableHiding: false,
  },
];

8.3 table 实例方法 ​

方法说明
table.getHeaderGroups()表头分组
table.getRowModel()渲染行模型
table.getFilteredRowModel()过滤后行
table.getFilteredSelectedRowModel()已选行
table.previousPage() / nextPage()翻页
table.getCanPreviousPage() / getCanNextPage()翻页可用
table.setPageIndex(n)跳页
table.setPageSize(n)每页条数
table.getAllColumns()所有列
table.getColumn(id)按 id 取列

9. Blocks 完整列表（截至 2026.5） ​

9.1 Sidebar Blocks（sidebar-01 ~ sidebar-16） ​

Block ID风格
sidebar-01简单浮动 sidebar + 折叠图标
sidebar-02多组导航 + 用户菜单
sidebar-03团队切换 + 多级菜单
sidebar-04浮动 + 暗色主题
sidebar-05二级菜单悬浮
sidebar-06嵌套子菜单
sidebar-07经典 Dashboard sidebar
sidebar-08仅图标模式
sidebar-09Inset 风格
sidebar-10简洁右侧 sidebar
sidebar-11带搜索 + 团队
sidebar-12浮动 + 顶部头像
sidebar-13双侧 sidebar
sidebar-14多级菜单
sidebar-15标签页式 sidebar
sidebar-16极简 sidebar

9.2 Login Blocks（login-01 ~ login-05） ​

Block ID风格
login-01简单卡片登录
login-02双栏登录（左表单 / 右插画）
login-03OAuth + 邮箱登录
login-04居中卡片 + 多 OAuth
login-05全屏背景图 + 登录卡

9.3 Signup Blocks（signup-01 ~ signup-03） ​

Block ID风格
signup-01简单注册
signup-02双栏注册
signup-03多步骤注册

9.4 Dashboard Blocks（dashboard-01 ~ dashboard-07） ​

Block ID风格
dashboard-01经典数据 Dashboard
dashboard-02设置页
dashboard-03表单 Dashboard
dashboard-04Charts 多图表
dashboard-05数据表 + 卡片
dashboard-06简洁 Dashboard
dashboard-07多 sidebar 复杂 Dashboard

9.5 Authentication Blocks ​

Block ID内容
authentication-01二因素验证
authentication-02OTP 输入
authentication-03重置密码

9.6 Charts Blocks ​

访问 /charts 查看 50+ 图表样例（柱状 / 折线 / 饼图 / 雷达 / 散点 / 等）。

9.7 Calendar Blocks ​

Block ID用途
calendar-01基础日历
calendar-02范围选择
calendar-03多月显示
calendar-04带 schedule

10. Registry schema ​

10.1 registry.json ​

ts
type Registry = {
  $schema: "https://ui.shadcn.com/schema/registry.json";
  name: string;
  homepage: string;
  items: RegistryItem[];
};

10.2 registry-item ​

ts
type RegistryItem = {
  // 基础
  $schema?: string;
  name: string;
  type: RegistryItemType;
  title?: string;
  description?: string;
  author?: string;

  // 依赖
  registryDependencies?: string[];  // 其他 registry item
  dependencies?: string[];          // npm 包
  devDependencies?: string[];

  // 文件
  files: RegistryFile[];

  // 样式
  tailwind?: {
    config?: object;                // tailwind.config.js extend
  };
  cssVars?: {
    light?: Record<string, string>;
    dark?: Record<string, string>;
    theme?: Record<string, string>;
  };

  // 元数据
  meta?: {
    iframeHeight?: string;
    [key: string]: any;
  };
  docs?: string;
  categories?: string[];
};

type RegistryItemType =
  | "registry:lib"        // 工具函数
  | "registry:block"      // 完整 Block
  | "registry:component"  // 单组件
  | "registry:ui"         // shadcn UI 组件
  | "registry:hook"       // React hook
  | "registry:page"       // 完整页面
  | "registry:file"       // 任意文件
  | "registry:style"      // 主题
  | "registry:theme";     // 完整主题

type RegistryFile = {
  path: string;
  type: RegistryItemType;
  content?: string;
  target?: string;        // 目标路径（不同于 path）
};

10.3 完整示例 ​

json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "fancy-button",
      "type": "registry:component",
      "title": "Fancy Button",
      "description": "一个动画按钮",
      "registryDependencies": ["button"],
      "dependencies": ["motion@10.0.0"],
      "files": [
        {
          "path": "registry/new-york/fancy-button/fancy-button.tsx",
          "type": "registry:component"
        }
      ],
      "tailwind": {
        "config": {
          "theme": {
            "extend": {
              "colors": { "brand": "var(--brand)" }
            }
          }
        }
      },
      "cssVars": {
        "light": { "brand": "oklch(0.5 0.2 240)" },
        "dark": { "brand": "oklch(0.7 0.2 240)" }
      },
      "categories": ["buttons"]
    }
  ]
}

11. MCP Server 配置 ​

11.1 .mcp.json（Claude Code） ​

json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

11.2 .cursor/mcp.json（Cursor） ​

json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

11.3 .vscode/mcp.json（VS Code） ​

json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

11.4 MCP 工具能力 ​

工具说明
list-components列出所有可安装组件
search-components搜索组件
add-components安装组件
get-component-docs获取文档
list-blocks列出 Blocks

12. TypeScript 核心类型 ​

12.1 cva 类型 ​

ts
import { type VariantProps } from "class-variance-authority";

const buttonVariants = cva(...);
type ButtonVariants = VariantProps<typeof buttonVariants>;

12.2 ChartConfig ​

ts
import { type ChartConfig } from "@/components/ui/chart";

const config = {
  desktop: {
    label: "桌面",
    color: "var(--chart-1)",
    icon?: React.ComponentType,
    theme?: { light: string; dark: string },
  },
} satisfies ChartConfig;

12.3 Form 类型 ​

ts
type FieldValues = Record<string, any>;

type ControllerRenderProps<TFieldValues, TName> = {
  onChange: (...event: any[]) => void;
  onBlur: () => void;
  value: any;
  name: string;
  ref: React.Ref<any>;
  disabled?: boolean;
};

12.4 Sidebar 类型 ​

ts
type SidebarContextProps = {
  state: "expanded" | "collapsed";
  open: boolean;
  setOpen: (open: boolean) => void;
  openMobile: boolean;
  setOpenMobile: (open: boolean) => void;
  isMobile: boolean;
  toggleSidebar: () => void;
};

const useSidebar: () => SidebarContextProps;

12.5 Theme（next-themes） ​

ts
import { useTheme } from "next-themes";

const {
  theme,        // "light" / "dark" / "system" / undefined
  themes,       // ["light", "dark", "system"]
  setTheme,     // (theme: string) => void
  resolvedTheme,// 实际应用的（system → light/dark）
  systemTheme,  // 系统偏好
  forcedTheme,  // 强制主题
} = useTheme();

13. 关键 Hook 速查 ​

Hook来源用途
useTheme()next-themes主题切换
useSidebar()shadcn/ui sidebarSidebar 状态
useFormField()shadcn/ui formFormItem 内部
useForm()react-hook-form表单状态
useFieldArray()react-hook-form动态字段
useReactTable()@tanstack/react-table表格状态
useToast()shadcn/ui toast（旧）旧 Toast 系统

14. 键盘快捷键速查 ​

14.1 Dialog / Sheet / Drawer ​

键行为
Esc关闭
Tab焦点循环（焦点陷阱内）
Shift+Tab反向焦点循环

14.2 DropdownMenu / Context Menu / Menubar ​

键行为
↑ / ↓上下移动
← / →子菜单展开 / 关闭
Enter / Space选中
Esc关闭
Home / End首项 / 末项
字母键typeahead 搜索

14.3 Combobox / Command ​

键行为
字母搜索过滤
↑ / ↓移动高亮
Enter选中
Esc关闭

14.4 Tabs ​

键行为
← / →切换标签（水平）
↑ / ↓切换标签（垂直）
Home / End首 / 末标签

14.5 Accordion ​

键行为
↑ / ↓切换项
Enter / Space展开 / 收起
Home / End首 / 末项

14.6 Slider ​

键行为
← / → / ↑ / ↓微调
PageUp / PageDown大幅调整
Home / End最小 / 最大值

14.7 Sidebar 全局 ​

键行为
Cmd+B / Ctrl+B切换 Sidebar

15. 常用 Tailwind utility 速查（shadcn 风格） ​

15.1 颜色 ​

text
bg-background / text-foreground            主色
bg-primary / text-primary-foreground       主操作
bg-secondary / text-secondary-foreground   次操作
bg-muted / text-muted-foreground           次要
bg-accent / text-accent-foreground         强调（hover）
bg-destructive                             危险色
border-border                              边框
ring-ring                                  焦点环

15.2 圆角 ​

text
rounded-sm    --radius-sm
rounded-md    --radius-md
rounded-lg    --radius-lg
rounded-xl    --radius-xl

15.3 data-state 选择器 ​

text
data-[state=open]:bg-blue-500
data-[state=closed]:opacity-0
data-[state=on]:bg-primary
data-[disabled]:opacity-50
data-[highlighted]:bg-accent

15.4 tw-animate-css 动画 ​

text
animate-in / animate-out
fade-in-0 / fade-out-0
slide-in-from-top / slide-in-from-bottom
zoom-in-95 / zoom-out-95

15.5 size 简写 ​

text
size-4 = w-4 h-4 = 16px × 16px
size-8 = w-8 h-8 = 32px × 32px
size-9 = w-9 h-9 = 36px × 36px

15.6 svg 自动尺寸（Button / Item 内） ​

text
[&_svg]:size-4                       // 内部 svg 16px
[&_svg]:pointer-events-none           // 禁用 svg 鼠标
[&_svg]:shrink-0                      // 不收缩
[&_svg:not([class*='size-'])]:size-4  // 未显式指定时 16px

16. 版本演进时间线 ​

日期版本 / 事件
2023.1shadcn/ui 首次发布
2024.3v1.0 稳定
2024.10React 19 兼容
2025.2Tailwind v4 支持 + OKLCH 色
2025.8MCP Server + Registry 体系
2026.2Radix UI 包统一 + Base UI 双支持
2026.4RTL + Pointer + Sera style
2026.5v4.7.0（当前稳定）

17. 与官方文档对应表 ​

主题官方 URL
首页https://ui.shadcn.com
文档https://ui.shadcn.com/docs
Installationhttps://ui.shadcn.com/docs/installation
Next.jshttps://ui.shadcn.com/docs/installation/next
Vitehttps://ui.shadcn.com/docs/installation/vite
TanStack Starthttps://ui.shadcn.com/docs/installation/tanstack
Astrohttps://ui.shadcn.com/docs/installation/astro
React Routerhttps://ui.shadcn.com/docs/installation/react-router
Laravelhttps://ui.shadcn.com/docs/installation/laravel
Manualhttps://ui.shadcn.com/docs/installation/manual
components.jsonhttps://ui.shadcn.com/docs/components-json
Theminghttps://ui.shadcn.com/docs/theming
Dark Modehttps://ui.shadcn.com/docs/dark-mode
CLIhttps://ui.shadcn.com/docs/cli
Monorepohttps://ui.shadcn.com/docs/monorepo
Registryhttps://ui.shadcn.com/docs/registry
MCPhttps://ui.shadcn.com/docs/mcp
Blockshttps://ui.shadcn.com/blocks
Themes 生成器https://ui.shadcn.com/themes
Chartshttps://ui.shadcn.com/charts
组件总览https://ui.shadcn.com/docs/components
Changeloghttps://ui.shadcn.com/docs/changelog

18. 周边生态速查 ​

项目URL说明
Magic UIhttps://magicui.design动画效果组件
Aceternity UIhttps://ui.aceternity.com复杂动画 + 3D
Origin UIhttps://originui.com业务组件库
Park UIhttps://park-ui.com多框架组件
Tremorhttps://tremor.soDashboard 组件
shadcn-vuehttps://www.shadcn-vue.comVue fork
shadcn-sveltehttps://shadcn-svelte.comSvelte fork
Catalysthttps://catalyst.tailwindui.comTailwind 官方设计系统（参考）
Lucide Iconshttps://lucide.dev默认图标库
Sonnerhttps://sonner.emilkowal.skiToast 库
vaulhttps://vaul.emilkowal.skiDrawer 库
cmdkhttps://cmdk.paco.meCommand 底层
react-day-pickerhttps://daypicker.devCalendar 底层
embla-carouselhttps://www.embla-carousel.comCarousel 底层
react-hook-formhttps://react-hook-form.comForm 底层
zodhttps://zod.devSchema 校验
@tanstack/react-tablehttps://tanstack.com/tableDataTable 底层
rechartshttps://recharts.orgChart 底层

19. 完成参考后 ​

完成参考查阅后，可继续：