今天，我们很高兴宣布期待已久的 Chakra UI v3 发布。Chakra v3 收到的反馈令人难以置信，我们感谢那些花时间测试和发现 bug 的人。
Chakra v3 是 Chakra 的完整重写，旨在提升其性能、速度以及组件之间的一致性。我们还新增了 25 个以上组件，这仅仅是个开始。
鸣谢
在为您快速概述之前，我想首先感谢那些为 Chakra v3 的重新设计贡献了想法和努力的人。
-
Park UI：Christian 和 Phil 的基础工作为 Chakra v3 的设计理念奠定了基础。一致的尺寸、颜色、阴影和命名约定是设计系统的核心。
-
Panda：Panda CSS 中创建的主题和样式 API 为 Chakra v3 的样式引擎铺平了道路。最终目标是让在 Park UI 和 Chakra UI 之间切换变得几乎不费力。
-
Radix Themes：为演练场、可组合动画和强调色系统提供了灵感。
-
Shadcn：为 CLI 提供了灵感，并推动了 Chakra 现在所采纳的复制粘贴代码片段理念。
我们还要感谢这些持续贡献并帮助塑造 v3 的个人。
Christian Schröter, Esther Adebayo, Eelco, Alex Stahmer, Tolulope Oyewumi, Abraham Anuoluwapo, Ivica Batinić
设计架构
在 Chakra v3 中，我们通过将无头库 Ark UI 与 Panda CSS 中的样式 API 结合，然后使用 Park UI 作为设计系统，来统一我们的工具生态系统。
我们从头开始重新设计了大部分组件，以确保它们都保持一致，并且在大多数情况下使用设计代币（design tokens）。
语义代币
语义代币让您无需手动重新设置每个组件的样式，即可轻松个性化您的代币。Chakra v3 为每个调色板提供了 7 种语义代币，让您拥有极致的灵活性，无需考虑深色模式。
-
solid（实色）: 调色板的实色
-
muted（柔和）: 调色板的柔和版本
-
subtle（微妙）: 调色板的微妙版本，比柔和版本更浅。
-
emphasized（强调）: 调色板的更突出版本
-
contrast（对比）: 适用于实色背景的颜色（也称为“on-solid”）
-
fg（前景色）: 调色板的前景色
-
focusRing（焦点环）: 调色板的焦点环颜色
以下是一个以语义方式使用红色，并自动适应深色模式的示例。
// A subtle version of red
<Box bg="red.subtle" color="red.fg">
Welcome
</Box>
// A solid version of red
<Box bg="red.solid" color="red.contrast">
Welcome
</Box>为了更进一步，您可以利用新的 colorPalette 功能。它允许您创建一个颜色占位符，该占位符可以使用 CSS 变量在 DOM 树的任何深度上替换为任何颜色。
<Box colorPalette="red">
<Box bg="colorPalette.subtle" color="colorPalette.fg">
Welcome
</Box>
<Box bg="colorPalette.solid" color="colorPalette.contrast">
Welcome
</Box>
</Box>默认开放
我们已从默认封闭组件转向默认开放的复合组件。这使您更容易组合自己的组件，并减少我们的维护工作。
为了说明这种差异，以下是您在 v2 中创建复选框的方式。
<Checkbox>Click me</Checkbox>这是 Chakra v2 中复选框组件的一个虚构示例。
export const Checkbox = forwardRef(function Checkbox(props, ref) {
const { children, iconColor, iconSize, icon, inputProps, ...checkboxProps } =
props
const checkbox = useCheckbox(checkboxProps)
return (
<chakra.label {...checkbox.getRootProps()}>
<input {...checkbox.getInputProps(inputProps, ref)} />
<chakra.span {...getCheckboxProps()}>
<CheckIcon as={icon} color={iconColor} size={iconSize} />
</chakra.span>
{children && (
<chakra.span {...checkbox.getLabelProps()}>{children}</chakra.span>
)}
</chakra.label>
)
})虽然上面的代码片段看起来易于使用，但当您需要自定义时就会遇到挑战。经常会出现以下问题：
- 如何将 props 传递给底层图标？
- 如何将 props 传递给渲染子元素的标签？
- 如何更改复选框的底层动画？
这通常会导致一个组件有许多 props，学习起来可能令人困惑。
我们现在已将 Chakra UI 默认设为可组合的，这意味着您不再默认获得封闭组件。
以下是使用新方法创建复选框的方式。
<Checkbox.Root>
<Checkbox.HiddenInput />
<Checkbox.Control>
<Checkbox.Indicator />
</Checkbox.Control>
<Checkbox.Label>Click me</Checkbox.Label>
</Checkbox.Root>代码量增加了不少，编写起来可能让人不知所措。为了弥补开发体验上的这一小调整，我们创建了“代码片段”（snippets）的概念，它可以帮助您封装可组合的复选框，让您回到最初的 v2 风格。
让我解释一下它的工作原理
代码片段
通过运行代码片段 CLI 命令，Chakra 会组合 Chakra 中的组件并将其放入您的项目中。这让您能够最大程度地控制每个方面。
npx @chakra-ui/cli@init snippets add运行此命令后，您应该会看到原始组件被添加到项目中的 components/ui/* 目录。
// components/ui/checkbox.tsx
export const Checkbox = forwardRef(function Checkbox(props, ref) {
const { children, icon, inputProps, ...restProps } = props
return (
<Checkbox.Root {...restProps}>
<Checkbox.HiddenInput {...inputProps} ref={ref} />
<Checkbox.Control>
<Checkbox.Indicator>{icon}</Checkbox.Indicator>
</Checkbox.Control>
{children && <Checkbox.Label>{children}</Checkbox.Label>}
</Checkbox.Root>
)
})这使得在 v3 中实现与 v2 相同的开发体验（DX）变得容易。
import { Checkbox } from "@/components/ui/checkbox"
const Demo = () => <Checkbox>Click me</Checkbox>提升运行时性能
-
移除主题中的运行时函数： 以前我们允许在主题系统中使用可能对运行时性能产生负面影响的函数。我们现在已切换到一种基于变体的系统，称为“recipes”，这在很大程度上受到了 Panda CSS 的启发。
-
外部化样式引擎： 样式引擎在 React 树之外初始化并被组件使用，从而为每个组件提供更快的样式解析和渲染时间。
-
迁移到 CSS 动画： 我们移除了
framer-motion依赖项，转而使用平台的动画功能。这为我们带来了性能提升，并减小了应用程序的包大小。
新组件
我们新增了来自 Ark UI 的组件。这些无头组件由状态图（statecharts）驱动，并在主要框架中保持一致工作。我们坚信 UI 库的未来是与框架无关的。
我们还新增了展示性组件，以节省您构建 UI 的时间。
拥抱生态系统
我们不想为常见需求重复造轮子。本着这种精神，我们从 Chakra 中移除了大量模块，以使我们专注于提供一流的组件。
- 移除了我们的图标，转而支持更强大的图标库，如
lucide-react或react-icons - 移除了我们内部的颜色模式管理，转而支持
next-themes或remix-themes - 移除了大部分 hooks，转而支持强大的 hooks 库，如
react-use或use-hooks-ts
下一步
- 来自 Ark 的选择器组件：ColorPicker（颜色选择器）、DatePicker（日期选择器）
- 重新设计的 Chakra UI Pro
- 重新设计的 Figma UI Kit
- 重新设计的 FigPilot：我们的 Figma 代码生成工具，可将任何设计转换为与 Chakra 兼容的代码。
- 探索 React 19 style 标签
常见问题
Chakra v3 内部使用 Panda 吗？
不。为了减少破坏性变更，我们决定保留 Emotion（以及运行时 css-in-js），以保留动态样式的好处。v3 中已经有很多变化，所以我们将逐步处理这个问题。
我们甚至可能根本不需要使用 Panda。React 19 中 style 标签的进展非常喜人，它将为 Chakra 带来更大的性能提升，而无需任何迁移成本。
我们会包含所有 Ark UI 的组件吗？
是的，Ark UI 提供了许多有用的组件。我们已经将其中一些包含在 Chakra 中，但随着时间的推移，我们将引入更多有趣的组件，如 ColorPicker（颜色选择器）、DatePicker（日期选择器）。
我们真的需要使用代码片段吗？
不，如果您不喜欢，不必使用代码片段。不过我们建议这样做，它有助于简化您的开发体验，因为您无论如何都得在您这边做同样的工作。
如果您觉得代码片段太多，可以移除您不需要的。
为什么要用新 logo？
v3 的发布标志着 Chakra UI 的新纪元。新纪元以一种非常独特的方式同步了 Zag.js、Ark UI 和 Panda CSS。仅此一点就值得一个新故事和新品牌。
为什么 v3 发布花了这么长时间？
我自己也问过同样的问题。以一种与框架无关且完全基于状态图（statecharts）的方式设计 Chakra UI 的基础是一项艰巨的任务。这以前从未做过，并且花费了大量时间才使其稳定。最终，所有努力都是值得的，我们感谢您的耐心。
开始使用
我们邀请您今天就尝试 Chakra v3，体验快速构建用户界面的乐趣。立即开始使用 Chakra UI v3
npm i @chakra-ui/react @emotion/react探索迁移指南，将您的项目升级到 Chakra UI v3。