illegalCreed

中文

English

中文

English

Appearance

Chakra UI ​

React 现代风格 UI 库的标杆、style props + 可访问性 (a11y) 业界顶级的简洁优雅组件库——由尼日利亚开发者 Segun Adebayo (segunadebayo) 于 2019 年 在 GitHub 创建并开源，凭借**「写组件就像写 Tailwind」的 style props 设计哲学** + 可访问性 (a11y) 一等公民 + TypeScript-first 类型完备 三大特性，成为 海外 React SaaS / Dashboard / 设计驱动应用 中与 MUI、Mantine 并列的「第二梯队主流选择」。最新稳定版 v3.x（截至 2026 年 5 月已发布 v3.35.0，v3.0 在 2024 年 11 月正式发布——是一次基于 Ark UI（同团队 headless 组件库）+ Panda CSS 设计系统的彻底重写，v2 → v3 是 breaking 重写，接受 v3 已经稳定的事实），完全基于 React 18 / 19 + TypeScript 5+ + Emotion CSS-in-JS + Ark UI headless，核心 @chakra-ui/react 提供 100+ 组件 覆盖 Layout / Typography / Forms / Data Display / Feedback / Disclosure / Overlay / Navigation / Media 九大类别，GitHub 38k+ Star，npm 周下载量 80 万+。核心生态矩阵：@chakra-ui/react（100+ 组件 + 所有 style props + system API） / @emotion/react（CSS-in-JS 底层，必装） / @chakra-ui/cli（CLI 工具，含 snippet 命令安装预制组件如 Provider / Toaster / ColorMode 等） / @ark-ui/react（headless 组件底层，v3 同团队产物） / next-themes（暗色模式集成，v3 推荐方案，替代 v2 的 ColorModeProvider）。核心特性：Style Props 系统业界最完整（200+ style props 直接在组件上写 styling：<Box mt="4" px="6" bg="blue.500" color="white">——比 Mantine 30+ Box props 更激进、比 MUI sx prop 更直观） / 可访问性 (a11y) 一等公民（所有组件遵循 WAI-ARIA、键盘导航 / 焦点管理 / 屏幕阅读器支持完美——号称「a11y by default」） / TypeScript-first（所有组件 / props / theme / recipes 完整 TS 类型，strictTokens 模式 可强制只用设计 token） / ChakraProvider + createSystem + defineConfig（v3 新架构：基于 Panda CSS 的 design system 引擎、tokens / semanticTokens / recipes / slotRecipes 完整定制） / 暗色模式深度集成（v3 改用 next-themes 库 + ColorModeProvider / useColorMode / useColorModeValue / ColorModeButton 完整方案 + _dark / _light 条件 props） / Compound Component 模式（v3 重大变更：Modal → Dialog.Root + Dialog.Trigger + Dialog.Content、FormControl → Field.Root + Field.Label + Field.ErrorText、Avatar → Avatar.Root + Avatar.Image + Avatar.Fallback——所有复合组件都改为点号命名） / asChild prop 组合（Radix UI 风格 slot 模式：<Button asChild><a href="/...">Link</a></Button> —— 一键改变底层渲染元素同时保留所有 Button 样式） / Conditional Style Props（响应式 + 状态 + 主题 三合一对象语法：bg={{ base: "white", _dark: "black", md: "gray.50" }}） / Recipes & Slot Recipes（基于 Panda CSS 的组件变体系统：defineRecipe / defineSlotRecipe / cva / sva —— 类型安全的 base + variants + compoundVariants + defaultVariants） / Color Palette 11 shade（v3 起每色板从 50/100/200/.../900 扩展到 50-950 共 11 个 shade） / Snippet CLI（npx @chakra-ui/cli snippet add 安装预制组件到本地源码——Provider / Toaster / ColorMode / Tooltip 等，类似 shadcn/ui 的「拷贝代码到项目」哲学） / 完整 SSR（Next.js App Router / Pages Router / Remix / Vite SSR / TanStack Router 一键集成） / @chakra-ui/icons 已移除（v3 起官方移除自家图标包，推荐 react-icons / lucide-react）。典型用户群：海外 React SaaS / Dashboard / 设计驱动应用（如 Vercel 早期 / 部分 OSS 项目）、TypeScript-first 团队、追求 style props 写法的开发者、对 a11y 有硬要求的产品（医疗 / 政府 / 教育） —— 如果你的项目追求 Tailwind 风格的 style props + a11y 业界顶级 + TypeScript 极致体验，那 Chakra UI v3 是继 Mantine 之后最值得考虑的选择。截至 2026 年的 v3.x 处于「重写后稳定演进期」，v3.0 (2024.11) + v3.x 持续迭代 —— 是 React 中后台 / SaaS 项目里最有性格、最贯彻 style props 哲学、a11y 体验最好的免费开源组件库。

评价 ​

优点

  • Style Props 系统业界最完整：200+ style props 直接写在组件上——m / mt / mb / mx / my / p / px / py / w / h / minW / maxW / bg / color / fontSize / fontWeight / borderRadius / boxShadow / display / position / flex / grid / gap / colorPalette 等几乎覆盖所有 CSS 属性。比 Mantine 30+ Box props 更激进、比 MUI sx prop 更直观——<Box mt="4" px="6" bg="blue.500"> 就是「上外边距 4 / 左右内边距 6 / 蓝色背景」
  • 可访问性 (a11y) 业界顶级：Chakra 团队对 a11y 的执着业界第一——所有交互组件遵循 WAI-ARIA 1.2 规范、键盘导航完美（Tab / Shift+Tab / Enter / Space / Esc / Arrow 全支持）、焦点管理精细（Dialog 打开自动陷阱焦点 / 关闭返回触发器）、屏幕阅读器友好（aria-label / aria-describedby / aria-expanded 全自动）——「a11y by default」不是口号
  • TypeScript-first + strictTokens 模式：所有组件、props、theme、recipes 完整 TS 类型——strictTokens: true 模式下只能用设计 token，编译期阻止「魔法数字」（如 mt="17px" 会 TS 报错、必须用 mt="4" 引用 theme.spacing[4]）。vs Tailwind 的运行时 PurgeCSS、Chakra 是编译时类型检查
  • ChakraProvider + createSystem 新架构：v3 基于 Panda CSS 设计系统引擎重构 —— createSystem(defaultConfig, defineConfig({ theme: { tokens, semanticTokens, recipes, slotRecipes, conditions } })) 类型联动完美。比 v2 的 extendTheme 类型更强、API 更清晰
  • Compound Component 模式 + Ark UI 底层：v3 把所有复合组件改为点号命名（Dialog.Root / Dialog.Trigger / Dialog.Content / Dialog.CloseTrigger）——结构清晰、可拆分、headless-friendly。底层依赖 Ark UI（同团队 headless 组件库）—— Chakra = Ark UI + Style Props + Theme
  • asChild prop Radix UI 风格组合：<Button asChild><a href="/...">链接</a></Button> —— 一行改变底层渲染元素、保留 Button 所有样式 + Behavior + Accessibility。比 Mantine component prop 在 a11y 上更彻底
  • Conditional Style Props：响应式 + 状态 + 主题 三合一对象语法 —— bg={{ base: "white", _dark: "black", md: "gray.50", _hover: "gray.100" }}。30+ 状态条件（_hover / _focus / _active / _disabled / _checked / _selected / _dark / _light / _groupHover / _peerFocus）+ 6 个断点（base/sm/md/lg/xl/2xl）任意组合
  • Recipes & Slot Recipes 类型安全：基于 Panda CSS 的组件变体系统 —— defineRecipe({ base, variants, compoundVariants, defaultVariants })、defineSlotRecipe({ slots, base, variants }) —— 完整 TypeScript 类型推导、IDE 智能提示完美。比 CVA / class-variance-authority 集成度更高
  • Color Palette 11 shade (50-950)：v3 起每色板从 50/100/200/.../900 扩展到 50-950 共 11 个 shade（新增 950）—— 暗色模式下能用 950 作为更深的背景色、更细腻的层次
  • Snippet CLI - shadcn 风格 + 包安装混合：npx @chakra-ui/cli snippet add 命令安装预制组件到本地源码（Provider / Toaster / ColorMode / Tooltip 等）—— 拷贝代码可改、可看实现。类似 shadcn/ui 的设计自由度，但底层还是 npm 包形式
  • 暗色模式深度集成 + next-themes：v3 改用 next-themes（业界事实标准）—— ColorModeProvider + useColorMode() + useColorModeValue(light, dark) + ColorModeButton 完整方案。SSR 一致性比 v2 的自家方案更好、与 Next.js App Router 集成完美
  • useBreakpointValue + 响应式 Hook：除了 props 语法、JS 中也能响应式 —— useBreakpointValue({ base: 'mobile', md: 'desktop' }) 返回当前断点对应值。比 Mantine useMediaQuery 更内聚
  • @emotion/react CSS-in-JS 底层：v3 仍然基于 Emotion —— 运行时 CSS 注入、与 React 18 SSR streaming 兼容。vs Mantine v7+ 的 Zero Runtime CSS Modules——Chakra 牺牲一点性能换更动态的 style props
  • 海外文档英文质量极高：chakra-ui.com —— 每个组件都有「Usage」「Props」「Anatomy」「Examples」「Theming」结构清晰、Sandpack 在线编辑、Migration v2 → v3 详尽
  • react-icons + lucide-react 推荐：v3 移除 @chakra-ui/icons、官方推荐 react-icons（含 Lucide / Font Awesome / Material Icons 等 30+ 图标库）或 lucide-react——比维护自家小图标包更明智
  • Vercel 系生态友好：与 Next.js / TanStack Router / Vite 集成方案齐全 —— 文档第一档框架支持
  • 持续高质量迭代 + 公司化支持：背后有 Chakra Systems（专门商业化公司）、有付费 Chakra UI Pro（200+ 业务级组件、$149+）支撑团队工资 —— bus factor 比 Mantine 单人维护更稳定

缺点

  • 国内市场份额几乎为 0：Chakra UI 在国内 React 中后台市场完全没有存在感 —— 招聘市场、培训、面试、第三方集成都围绕 Ant Design，国内项目选 Chakra UI 的人才储备稀缺
  • v2 → v3 是 breaking 重写、生态有阵痛：2024 年 11 月发布的 v3 是基于 Ark UI + Panda CSS 的彻底重写 —— ChakraProvider API 变 + Modal → Dialog + FormControl → Field + extendTheme → createSystem + colorScheme → colorPalette + isOpen → open 等几十个 breaking —— v2 项目迁移成本巨大、社区 v3 教程仍在补齐
  • 设计语言不强绑定：Chakra 不像 MUI 严格遵循 Material Design、也不像 Ant Design 严格遵循 Ant Design 规范——默认风格中性偏现代，但没有一个完整的设计 token 规范文档（vs Google Material 3 spec / Ant Design 设计价值观）
  • vs MUI：MUI Material Design 严格遵循 + MUI X Data Grid 业界最强表格；Chakra Style Props 更激进 + a11y 更扎实 + TypeScript 类型更精准 —— Material 风格选 MUI、Style Props 哲学选 Chakra、企业 Data Grid 必选 MUI
  • vs Mantine：Mantine 130+ 组件 + 70+ hooks + CSS Modules Zero Runtime + bundle 更小；Chakra a11y 业界第一 + style props 系统更完整 + 11 shade 色板 + Snippet CLI 哲学独特 —— 追求 hooks 套件 + 体积小选 Mantine、追求 a11y + style props 极致选 Chakra
  • vs Ant Design：Ant Design 国内事实标准 + 70+ 企业级组件 + Pro Components 中后台杀器；Chakra a11y + Style Props + 设计自由度 —— 国内中后台选 Ant Design、海外 SaaS 选 Chakra
  • vs shadcn/ui：shadcn 拷贝代码到项目而非安装包 + Tailwind + Radix UI 底层 + 最大设计自由度；Chakra 传统安装包模式 + Snippet CLI 拷贝部分组件 + Style Props 哲学 —— shadcn 给设计师自由度、Chakra 给开箱即用 + 部分自由度
  • DataTable 不如 MUI Data Grid / Ant Design Table：Chakra 的 Table 仅是基础语义化表格组件 —— 没有内置分页 / 排序 / 筛选 / 列固定 / 虚拟滚动，企业级数据表格需要搭配 @tanstack/react-table 或 AG Grid 自行实现
  • bundle 体积偏大：基于 Emotion CSS-in-JS、@chakra-ui/react 完整 import 约 300KB+ gzipped —— 比 Mantine（CSS Modules）略大。Tree Shaking 支持但需要 ESM + 现代打包工具
  • CSS-in-JS 运行时开销：Emotion 运行时注入 style tag —— 比 Mantine v7+ CSS Modules / Tailwind 性能略低。但 v3 已经通过 Panda CSS 编译优化部分降到「近 Zero Runtime」
  • 没有官方 Mobile 版：vs Ant Design antd-mobile —— Chakra 专注 Desktop / Web、没有官方 Mobile 优化，移动端 H5 项目优选 antd-mobile / Vant
  • 国内 CDN / 文档站访问偶有延迟：chakra-ui.com 部署在 Vercel —— 国内偶发慢、但通过 GitHub 镜像 + 本地缓存可缓解
  • 图标方案需要二次决策：v3 移除 @chakra-ui/icons 后、用 react-icons 还是 lucide-react 还是 @iconify/react 需要团队选型 —— 比 MUI 自带 @mui/icons-material / Mantine 推荐 @tabler/icons-react 多一步
  • Ark UI 底层学习曲线：v3 底层是 Ark UI，深度自定义时可能需要直接 import Ark UI 组件——多了一层学习负担。但日常开发用 Chakra 组件即可、无需关心 Ark UI
  • @chakra-ui/pro 商业组件：高级业务组件需要付费（$149+） —— vs Mantine UI 123 个免费、shadcn/ui Blocks 免费
  • Snippet CLI 模式概念分裂：一部分组件（Button / Input / Box）从 @chakra-ui/react import、另一部分（Provider / Toaster / ColorMode）从本地 @/components/ui/... import —— 「装包 + 拷贝」混合模式初学者容易困惑
  • Theme 配置门槛偏高：v3 createSystem(defaultConfig, defineConfig(...)) + tokens { value: "..." } 强制对象包裹 + semanticTokens + recipes + conditions —— 比 Mantine createTheme() 字段更深、入门陡峭

文档地址 ​

Chakra UI 官网 | 入门指南 | Vite 集成 | Next.js App Router 集成 | v2 → v3 Migration | Theming Overview | Styling Overview | Recipes | Slot Recipes | Dark Mode | Conditional Styles | Responsive Design | Components 总览 | Composition | Charts | CLI | Playground | Changelog | Ark UI（headless 底层）

GitHub 地址 ​

chakra-ui/chakra-ui（主仓库，38k+ Star） | chakra-ui/ark（Ark UI headless 组件库） | chakra-ui/panda（Panda CSS 设计系统引擎） | chakra-ui/zag（State machine 状态机底层）

学习路径 ​

  • 入门：pnpm add @chakra-ui/react @emotion/react 安装 / npx @chakra-ui/cli snippet add 安装 Provider / Toaster / ColorMode 等预制组件 / 第一个 <Button> + <Input> / ChakraProvider 包根 / createSystem + defineConfig 创建主题 / Style Props 入门（mt="4" px="6" bg="blue.500"）/ Box + Stack + HStack + VStack 布局 / TypeScript 基础（自动类型推导）/ Vite 集成（推荐 SPA）/ Next.js App Router 集成（推荐 SSR）/ v2 → v3 migration 关键变化（Modal → Dialog、FormControl → Field、extendTheme → createSystem、colorScheme → colorPalette、isOpen → open）/ 暗色模式一行启用（next-themes + ColorModeProvider）/ 第一个表单（Field.Root + Input + Field.Label + Field.ErrorText）/ 第一个 Toast（toaster.create()）
  • 指南：核心：Chakra UI v3 9 大组件分类（Layout / Typography / Forms / Data Display / Feedback / Disclosure / Overlay / Buttons / Media）/ Style Props 完整 API（200+ props + 响应式对象语法 + 主题值引用 + Conditional Style Props 30+ 状态条件）/ createSystem + defineConfig 完整选项（tokens / semanticTokens / recipes / slotRecipes / conditions / breakpoints / globalCss / preflight / strictTokens）/ Recipes & Slot Recipes（defineRecipe / defineSlotRecipe / cva / sva —— base + variants + compoundVariants + defaultVariants）/ Color Mode 完整方案（next-themes 集成 / ColorModeProvider / useColorMode / useColorModeValue / ColorModeButton）/ Compound Component 模式（Dialog.Root + Trigger + Backdrop + Positioner + Content 完整剖解 / Field.Root + Label + HelperText + ErrorText）/ asChild prop（Next.js Link / React Router Link 集成）/ Form 完整方案（Field + react-hook-form + Zod）/ Toast 完整 API（toaster.create / toaster.dismiss / toaster.promise / Toaster 组件 / placement）/ Menu 完整方案（Menu.Root + Trigger + Content + Item + ItemGroup + Separator）/ Ark UI headless 底层（何时直接用 Ark UI）/ Next.js App Router 完整集成 / Vite 集成最佳实践 / 常见踩坑（v2 → v3 不兼容 / Color Mode hydration 闪烁 / SSR style flicker / Snippet CLI 路径冲突 / strictTokens 报错）
  • 参考：API 速查：100+ 组件清单（9 大类）/ Style Props 完整表 / Conditional Style Props 完整表 / createSystem / defineConfig 完整选项树 / Recipes / Slot Recipes API / useColorMode / useColorModeValue / useBreakpoint / useBreakpointValue / Token 体系（colors / spacing / sizes / radii / shadows / fontSizes / fontWeights / lineHeights / letterSpacings / zIndices / borders / animations）/ Semantic Tokens / 默认 Color Palette（50-950，10 色） / Snippet CLI 命令 / TypeScript 核心类型 / Ark UI 底层组件清单