Ark UI
基于 Zag.js 状态机的无样式、可访问组件库，支持 React、Vue、Solid 与 Svelte。
项目概述
Ark UI 为多个前端框架提供同一套 Headless Component 思路：组件负责状态、键盘交互、焦点管理和可访问性，视觉样式完全交给产品团队。它适合构建设计系统、跨框架组件平台和交互复杂的业务界面。
Ark UI 是 Chakra Systems 生态中的 Headless Component 库，底层通过 Zag.js 状态机统一描述组件行为，再为 React、Vue、Solid 和 Svelte 提供符合各自习惯的绑定。它不附带固定视觉主题，却提供 Dialog、Select、Combobox、Date Picker、Color Picker、Tree View、File Upload 等 45+ 组件，适合希望完全掌控样式、同时复用成熟交互与无障碍基础的团队。当前四个框架包独立发布，采用 MIT 许可证。
主要特点
Ark UI 将复杂组件行为做成跨框架、无视觉预设的可组合原语。
四框架支持
分别提供 @ark-ui/react、@ark-ui/vue、@ark-ui/solid 与 @ark-ui/svelte，让不同技术栈共享相近的组件模型和行为语义。
状态机驱动
底层复用 Zag.js，将打开、选中、拖拽、键盘导航和焦点切换等交互表达为可预测的状态机。
完全无样式
组件不绑定视觉主题，可使用普通 CSS、Tailwind CSS、Panda CSS、CSS-in-JS 或团队自己的 Token 系统。
可组合部件
Root、Trigger、Content、Item 等部件可自由排列和封装，便于建立符合产品语义的高层组件。
丰富组件目录
除常见弹层和表单控件外，还覆盖 Color Picker、Date Picker、File Upload、Tree View、Tour、Signature Pad 等复杂场景。
可访问交互基础
内置键盘导航、焦点管理和相关 ARIA 语义，降低团队重复实现复杂无障碍行为的成本。
受控与非受控状态
既可快速使用内部状态，也可把值提升到应用层，与表单、URL 状态或业务流程同步。
TypeScript 与按组件导入
提供完整类型和组件子路径导出，便于获得编辑器提示，并让构建工具进行 Tree Shaking。
适用场景
当团队需要自定义视觉语言，又不想从头实现复杂交互时，Ark UI 尤其合适。
跨框架设计系统
组织同时维护 React、Vue、Solid 或 Svelte 产品时，可统一组件行为、命名和设计规范。
品牌化 SaaS 产品
适合需要深度定制主题、动效和交互细节的后台、协作工具与多租户平台。
复杂表单与选择器
Combobox、Select、Date Picker、Color Picker、Tags Input 等可减少边界状态和键盘交互的重复工作。
组件库与低代码平台
将 Ark UI 的行为部件封装为带 Token、变体和业务语义的内部组件，供多个产品复用。
内容与电商界面
Menu、Dialog、Carousel、Pagination、Tree View 等组件可覆盖导航、筛选、商品展示和内容管理。
优点与注意事项
技术选型不仅要看能力，也要理解它带来的团队成本。
主要优点
Ark UI 擅长的地方
- 一套状态机模型覆盖四种主流前端框架
- 不绑定视觉风格，适合品牌化设计系统
- 复杂组件种类丰富，减少从零处理边界交互的成本
- 组件部件粒度细，便于二次封装和扩展
- 具备 TypeScript 类型、可访问语义和键盘交互基础
- MIT 许可证适合个人与商业项目
需要注意
采用前应考虑的问题
Headless 只解决行为和结构；团队仍需设计 Token、状态样式、动效、响应式布局与高对比度方案。
React、Vue、Solid 当前为 5.38.2，Svelte 为 5.23.1。查阅文档和迁移记录时应确认所用框架及具体版本。
核心概念相近，但事件、插槽、响应式状态和模板写法遵循各框架习惯，不能直接复制另一框架的示例。
Zag.js 会按组件引入相关状态机包；应使用子路径导入并通过真实构建产物检查 Tree Shaking 和包体积。
使用 asChild 或封装触发器时，需要确保 DOM 属性、事件和 Ref 被传递，否则可能破坏焦点与键盘行为。
基础行为不等于最终页面自动合规；标签、错误提示、颜色对比、内容顺序和屏幕阅读器体验仍需测试。
依赖 Portal、浏览器尺寸或本地状态的交互组件，应在 Next.js、Nuxt、SvelteKit 等环境中验证 Hydration。
组件目录和组合 API 仍在演进，大版本可能调整部件命名或渲染方式，设计系统应固定版本并分批升级。
快速开始
下面以 React 为主完成安装、受控 Slider 与自定义样式，并给出其他框架的安装方式。
bashnpm install @ark-ui/reacttsximport { Slider } from "@ark-ui/react/slider";
import { useState } from "react";
export function VolumeSlider() {
const [value, setValue] = useState([40]);
return (
<Slider.Root
min={0}
max={100}
value={value}
onValueChange={(details) => setValue(details.value)}
>
<Slider.Label>音量：{value[0]}%</Slider.Label>
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
);
}css.slider [data-part="track"] {
height: 0.5rem;
border-radius: 9999px;
background: #e4e4e7;
}
.slider [data-part="range"] {
height: 100%;
border-radius: inherit;
background: #f4b740;
}
.slider [data-part="thumb"] {
width: 1.25rem;
height: 1.25rem;
border: 2px solid #18181b;
border-radius: 9999px;
background: white;
}
.slider [data-part="thumb"]:focus-visible {
outline: 3px solid color-mix(in srgb, #f4b740 45%, transparent);
outline-offset: 3px;
}bash# Vue
npm install @ark-ui/vue
# Solid
npm install @ark-ui/solid
# Svelte
npm install @ark-ui/sveltebashnpm run lint
npm run typecheck
npm test
npm run build
# 用键盘走完全部流程，并测试 VoiceOver、NVDA 或其他屏幕阅读器
# 验证 Portal 层级、移动端触摸、页面缩放和 Reduced Motion下一步：先选择一个复杂度适中的组件做验证，重点检查键盘操作、焦点恢复、Portal 层级、服务端渲染和最终包体积，再决定是否作为设计系统底层。
类似项目
这些项目同样提供无样式组件、设计系统基础或与 Ark UI 紧密相关的前端能力。
Headless UI
Tailwind Labs 提供的无样式、可访问 UI 组件库，为 React 与 Vue 处理键盘、焦点和复杂交互行为。
查看项目Base UI
无样式、可访问的 React 组件库，以细粒度 Parts、状态属性和灵活组合能力构建设计系统。
查看项目Radix UI
无样式、可访问且高度可组合的 React UI 原语，为设计系统处理焦点、键盘和复杂交互。
查看项目shadcn/ui
把可访问、可组合的组件源码直接加入项目，由团队完整拥有和定制的 UI 分发平台。
查看项目Panda CSS
面向设计系统、在构建时提取样式的类型安全 CSS-in-JS 框架。
查看项目React
用于构建 Web 和原生用户界面的组件化 JavaScript 库。
查看项目Vue.js
渐进式 JavaScript 框架，易学易用且拥有优秀的性能表现。
查看项目SolidJS
采用细粒度响应式和 JSX 构建高性能 Web 用户界面的 JavaScript 库。
查看项目Svelte
将组件编译为精简 JavaScript 的现代 Web UI 框架。
查看项目React Aria
Adobe 提供的可访问 React Hooks 与组件体系，强调国际化和多输入方式。
访问官网Zag.js
Ark UI 使用的框架无关状态机工具集，可直接用于构建自定义 Headless Component。
访问官网Ariakit
面向 React 的低层可访问组件工具包，强调 WAI-ARIA 模式与灵活组合。
访问官网Ark UI vs Headless UI
Ark UI 与 Headless UI 都把视觉样式留给开发者，并内置常见可访问交互。Ark UI 以 Zag.js 状态机为共享行为层，覆盖四个框架且组件目录更广；Headless UI 由 Tailwind Labs 维护，聚焦 React 与 Vue，并与 Tailwind CSS 工作流结合紧密。
| 比较维度 | Ark UI | Headless UI |
|---|---|---|
| 核心定位 | 跨框架 Headless Component | React / Vue 无样式组件 |
| 框架支持 | React、Vue、Solid、Svelte | React、Vue |
| 行为架构 | 共享 Zag.js 状态机 | 针对 React / Vue 实现组件行为 |
| 组件范围 | 45+，包含日期、颜色、文件和树等复杂控件 | 聚焦常用应用界面组件 |
| 样式方案 | 不限定，可配任意 CSS 方案 | 不限定，与 Tailwind CSS 配合自然 |
| 组合模型 | Root / Trigger / Content 等细粒度 Parts | 高层组件 + 子组件组合 |
| 跨框架一致性 | 共享概念和状态机语义 | React 与 Vue API 各自维护 |
| 设计系统 | 适合多框架和复杂组件平台 | 适合 React / Vue 产品快速自定义 |
| 许可证 | MIT | MIT |
如果需要 Solid、Svelte、跨框架设计系统，或 Date Picker、Color Picker、Tree View 等复杂控件，优先评估 Ark UI；如果团队只使用 React/Vue、依赖 Tailwind CSS，并偏好更集中直接的组件目录，Headless UI 往往更简单。最终应以目标组件清单、键盘与屏幕阅读器测试、包体积和升级成本为准。
资料核验
版本、维护信息与本页采用的官方资料来源。
npm 官方元数据核验显示 @ark-ui/react、@ark-ui/vue 与 @ark-ui/solid 的稳定版均为 5.38.2，@ark-ui/svelte 为 5.23.1，四者均采用 MIT 许可证并依赖 Zag.js 组件状态机。官方仓库未归档，核验当天仍有公开维护活动。
官方仓库未归档，核验时最近可见的代码活动日期为 2026 年 8 月 20 日。该状态表示项目近期仍有公开维护活动，不代表固定发布频率或长期支持承诺。