dalao.ai

shadcn/ui

复制进你自己代码库的组件开源

关于 shadcn/ui

shadcn/ui 不是一个装进来就用的 npm 组件库，而是一套把组件源码直接放进使用者项目的方法，外加分发这些代码的命令行工具和注册表。按钮、对话框、表格的代码从此归项目所有，可以随意修改。它由化名 shadcn 的设计工程师在 2023 年 1 月作为个人项目发布，作者同年 8 月加入 Vercel，项目现在由 Vercel 支持，MIT 开源，完全免费。2026 年，它把重心转向了 AI 智能体的界面。

编辑部更新于 阅读约 8 分钟

shadcn/ui 界面截图

它解决什么问题

传统组件库的用法是：从 npm 装一个包，import 组件，直接用。官方文档说，这套办法一直好用，直到组件要贴合团队自己的设计规范，或者需要一个库里没有的组件。到那时，往往只能给组件再包一层、写样式覆盖，或者混用几家 API 互不兼容的库。

shadcn/ui 的做法是把组件代码交给使用者。一个组件分三层：最底下是负责键盘、焦点、无障碍这些交互细节的无样式组件，可选 Base UI、React Aria 或 Radix；中间用 Tailwind 写样式；最上面那层组件代码直接放在使用者的仓库里。官方把设计原则归纳为五条：代码开放、接口可组合、便于分发、默认样式好看、方便 AI 读写。

它同时是一套代码分发系统。官方定义了一个平铺的文件格式（schema），描述组件、依赖和属性，再用 shadcn 命令行工具把组件装进不同框架的项目。任何人都能按这个格式发布自己的注册表。2026 年 6 月起，任何公开的 GitHub 仓库都能直接变成注册表；8 月又扩展到私有仓库，官方说这是应团队要求，用来分发不便公开的内部设计系统、功能套件和智能体规则，命令和公开仓库完全一样。

更新日志写道，shadcn/ui 在 2023 年 1 月发布，最初建立在 Radix 之上。Vercel 的官方指南称它起初是作者的个人副业项目。2023 年 8 月 9 日，shadcn 在 X 上宣布以设计工程师身份加入 Vercel。他现在的个人主页写着：Vercel AI 团队的设计工程师，创建了 shadcn/ui 和 shadcn/registry，并与 Jared、Shu、Max 共同创建了 v0。Vercel 把它称为“Vercel 支持的开源项目”，官方文档页脚写的是“Built by shadcn at Vercel”。Vercel 的 AI 应用生成工具 v0 生成 React 代码时，也默认采用 shadcn/ui。

底层也在变。2026 年 7 月，官方把新项目的默认底层从 Radix 换成 Base UI，理由之一是在 shadcn/create 上新建的项目里，选 Base UI 的是选 Radix 的两倍；Radix 仍然完全支持。同月，React Aria 成为第三种可选底层。

这不是一个组件库。它是你用来构建自己组件库的方式。

shadcn/ui 官方文档

核心能力

代码归使用者。组件以源码进入项目，改行为就是直接改代码，不用和库的样式覆盖较劲。所有组件共用一套可组合的接口，团队和 AI 不用为每个组件重学一套 API。

三种底层，八种风格。同一个组件可以选 Base UI、React Aria 或 Radix 作为底层实现，2026 年 10 月新发布的组件三种底层、八种风格全部提供。CLI 也带了几条迁移命令：migrate radix 把分散的 @radix-ui/react-* 导入合并为统一的 radix-ui 包，migrate rtl 让组件支持从右到左排版，migrate icons 在图标库之间切换。没有命令能把现有项目从 Radix 自动迁到 Base UI 或 React Aria。

注册表和预设。任何人都能把组件发布成注册表，私有 GitHub 仓库也行。2026 年 3 月发布的 CLI v4 加入了“预设”：把颜色、主题、图标库、字体、圆角压缩成一串短码，可以在 shadcn/create 上预览，再用 init --preset 建新项目；v4 还加入了 --dry-run 预览改动。4 月又单独发布了 shadcn apply，可以把预设套到已有项目上。

面向智能体界面。2026 年 10 月发布了 Trace 和 Code Block 两个组件，以及 21 个 AI Elements 模式，从对话、输入框到推理过程、工具调用、计划和子智能体都有，每个模式都演示如何渲染 AI SDK 的消息片段。AI Elements 同样没有包可装，是复制进项目的代码。官方说明它将取代 AI SDK Elements，后者会被弃用；已经装进项目的 AI SDK Elements 组件是项目自己的代码，可以继续使用，不必马上迁移。

智能体交互的零件。在 AI Elements 之前，官方已经陆续补齐了对话界面需要的零件：2026 年 6 月发布一组聊天界面组件；8 月发布 Questionnaire，一个多步问答组件，官方举的用途是智能体在继续执行前让用户澄清需求，也可用于新手引导、问卷和配置表单，同样三种底层、八种风格都有，另有无样式版本放在 @shadcn/react 里。同月，@shadcn/helpers 加入了模拟“人在回路”流程的能力：一段脚本化的 AI SDK 对话可以停下来等真实用户输入或审批，再按用户的决定继续。

给 AI 用的入口。官方提供 MCP 服务器，让 AI 助手浏览、搜索、安装注册表里的组件；llms.txt 汇总了所有文档；Skills 给 Claude Code 等编程智能体提供组件和注册表的使用知识。

和同类比

官方拿来对比的是“装 npm 包、import 组件”的传统组件库：后者升级省事，深度定制要绕路；shadcn/ui 定制自由，代码要自己维护。MUI、Chakra UI、Mantine、Radix Themes 和 HeroUI 都是常被拿来比较的 React 组件库，场景描述依据各自官网。

Material UI（MUI）：官方定位是实现 Google Material Design 的开源 React 组件库，组件齐全、开箱即可用于生产，另有设计套件和模板。它面向产品本来就走 Material Design，或者希望后端工程师、非专业设计师也能快速拼出一致界面的团队。

Chakra UI：官方称它是构建网页应用和设计系统的无障碍 React 组件系统，支持 Next.js 服务端组件，用语义化 token 统一颜色、字体等设计决策。它以 npm 包的形式提供一整套带主题系统的组件，组件代码不进使用者的仓库。

Mantine：官网称有 120 多个可定制组件和 70 多个 hooks，同样提供给 AI 用的 llms.txt 和 MCP 服务器。它面向需要大量现成组件和工具 hooks、不用 Tailwind、希望升级时直接拿到修复的团队。

Radix Themes：Radix 团队出的预置样式组件库，官方说它配置极少、装上就能用；想要无样式版本则用 Radix Primitives。它面向想要 Radix 的交互和无障碍质量、接受包里统一提供的样式和升级、不想自己维护组件代码的团队。

HeroUI（前身 NextUI）：官方介绍它面向 React 网页和 React Native，网页版把 React Aria Components 和 Tailwind CSS v4 结合起来。它面向同样用 Tailwind、但希望通过包升级拿到修复，或者需要同时覆盖移动端 React Native 的团队。

谁在用，适合谁

公开数字（均截至 2026-10-25）：GitHub 仓库约 12.6 万星标、1.3 万分叉；命令行工具 shadcn 在 2026-10-16 至 10-22 这一周的 npm 下载量为 8,003,630 次；作者主页显示，官方注册表每月分发约 4500 万次组件，这个数字不含第三方注册表。Vercel 的指南说，很多 React 团队、尤其是用 AI 编程工具的团队，会把它当作第一个引入的东西。

适合谁

用 React 和 Tailwind、想要一套真正属于自己的设计系统的团队：组件代码在自己仓库里，改设计规范就是改代码。也适合要让 AI 编程工具读懂并修改界面的项目，因为组件就是普通源码，官方还提供了 MCP 服务器、给 AI 读的 llms.txt 和 Skills。2026 年 10 月推出的 AI Elements 模式面向做聊天、智能体类产品的团队。

不适合谁

不用 Tailwind 的项目；只想升级一个依赖版本就拿到全部修复、不愿自己维护组件代码的团队；需要严格遵循 Material Design 等既定设计语言、希望开箱即得完整组件和模板的团队。

上手路径

新项目可以先在 shadcn/create 里可视化挑选底层、风格、颜色和字体，生成一串预设码和对应框架的初始化命令；也可以直接运行 npx shadcn@latest init -t next，模板支持 next、vite、start、react-router、astro 等。以 React Aria 作底层时，初始化加 --base aria。

已有项目运行 npx shadcn@latest init，它会安装依赖、写好 components.json 和全局 CSS。之后按需添加组件，例如 npx shadcn@latest add button；--dry-run 可以先预览会改哪些文件，--diff 可以查看某个文件和注册表版本的差异。

套用别人分享的设计用 npx shadcn@latest apply <预设码>；发布自己的组件用 shadcn build 生成注册表文件。截至 2026-10-25，最新版本是 shadcn@4.22.1，GitHub 发布时间为 2026 年 10 月 19 日 02:11 (UTC+8)。

定价与许可证

完全免费，MIT 许可证，没有付费版。Vercel 的指南说明，个人和商业项目都能用，只需在源码副本中保留版权声明，界面上不需要署名，组件进了仓库后也没有任何用量限制。

风险与局限

复制进来的代码不会自动更新，上游修了什么要自己合并。官方的解释是，底层无样式组件仍通过依赖更新拿到修复，只有最上面那层交给使用者；CLI 的 --diff 可以显示差异，但合并仍是手工活。

项目改动很快。2026 年 5 月加入 shadcn eject，可以把共享的 shadcn/tailwind.css 内联进项目、去掉对 shadcn 包的依赖；7 月新项目默认底层换成 Base UI；9 月把每个项目都要复制的 cn 工具函数改成独立的 cn 包，并提供 migrate cn 命令；10 月宣布弃用 AI SDK Elements。选择也多：三种底层、八种风格。

我们的判断

对用 React 加 Tailwind、想要一套自己能完全掌控、AI 也能直接读改的组件的团队，shadcn/ui 要权衡的是维护成本而不是钱。更看重“升级一个版本号就拿到所有修复”、或者产品要走 Material Design 的团队，用 MUI、Radix Themes 这类套件式组件库维护负担更轻。

亮点

shadcn/ui 改变了前端组件的分发方式。你不是安装一个组件库，而是把无障碍、样式考究的组件复制进自己的代码库，从此归你所有。听起来像是倒退，结果恰恰是大家想要的。

它基于 Tailwind，底层基础组件可在 Radix、Base UI 和 React Aria 之间选择，作者是一位只以 shadcn 为名的设计师兼工程师。它成了大量新 React 应用默认的起点，也成了一整套审美的参照。

它的无障碍组件是复制进你自己的代码库、归你所有的，而不是作为依赖库安装。

资料来源

官方

  1. shadcn/ui 官方文档：Introductionui.shadcn.com · 访问于 2026 年 10 月 25 日
  2. shadcn/ui 安装文档ui.shadcn.com · 访问于 2026 年 10 月 25 日
  3. shadcn CLI 文档ui.shadcn.com · 访问于 2026 年 10 月 25 日
  4. shadcn/ui 更新日志（含 2026-10 Trace、Code Block 与 AI Elements）ui.shadcn.com · 访问于 2026 年 10 月 25 日
  5. 更新日志：Base UI as the Default（2026-07）ui.shadcn.com · 访问于 2026 年 10 月 25 日
  6. 更新日志：React Aria（2026-07）ui.shadcn.com · 访问于 2026 年 10 月 25 日
  7. 更新日志：shadcn/cli v4（2026-03）ui.shadcn.com · 访问于 2026 年 10 月 25 日
  8. 更新日志：cn（2026-09）ui.shadcn.com · 访问于 2026 年 10 月 25 日

动态与深度阅读