原语
原语
Radix UI、Base UI 与 React Aria 原语的带动效版本,API 完全一致;外加一批 Animate UI 自有原语。
共 125 个原语,按库分为四组。每个原语都是对应库的完整功能加上 Motion,API、部件、data 属性与无障碍行为都保持不变;自有原语不属于任何底座,可以直接从 @animate-ui/react/primitives 引入。
你可以先安装,再用 CLI 批量替换;也可以点开某个原语,查看它的安装命令、真实用法、动效参数与 API。
Base UI
28shadcn/ui 的新底座,无样式、可组合,状态与无障碍由 Base UI 负责。
@animate-ui/react/primitives/base-ui
- Accordion一组带标题的可折叠面板。保留 Base UI 的完整 API,展开与收起由 Motion 接管。
- Alert Dialog要求用户必须作出回应的模态对话框,键盘焦点与 ARIA 语义完全沿用 Base UI。
- Checkbox在选中与未选中之间切换的复选框,勾选标记会自己画出来。
- Collapsible由一个按钮控制展开与收起的单个面板。
- Combobox输入框与预定义选项列表的组合,支持过滤与键盘导航。
- Context Menu在指针位置由右键或长按唤出的菜单。
- Dialog覆盖整个页面的弹窗,底层内容进入 inert 状态。也是 shadcn/ui Sheet 的底座。
- Drawer从屏幕边缘滑入、可跟随手指滑走的抽屉。
- Dropdown Menu由按钮触发的下拉操作菜单,内置完整的键盘导航。
- Hover Card悬停链接时出现的预览卡片,为视觉用户提供更多上下文。
- Menubar桌面应用式的常驻菜单栏,提供一组稳定可达的命令。
- Navigation Menu网站导航用的链接与子菜单集合。
- Pagination带页码、上一页与下一页的分页组件;当前页的描边会在页码之间滑动。
- Popover锚定在按钮上的可访问浮层,用来承载富内容。
- Preview Link Card悬停时显示目标页面截图的链接卡片,卡片本身也可以点击进入。
- Progress展示耗时任务完成进度的进度条,支持不确定状态。
- Questionnaire多步问卷,支持单选、多选、自由填写与跳过;每题滑出后下一题滑入,高度随之滑动。
- Radio Group一组单选按钮,同一时间最多只能选中一项。
- Select从下拉列表中选择预定义值的表单组件,支持键盘输入与类型检索。
- Sheet扩展自 Dialog 的侧边面板,用来展示与主内容互补的信息。
- Sidebar可组合、可换肤的侧边栏;菜单按钮共享一块滑动高亮,折叠为图标时所有内容走同一条曲线。
- Slider易于自定义样式的范围输入控件。
- Switch在开启与关闭之间切换的开关控件。
- Tabs在同一页面内切换相关面板的标签页组件。
- Toast生成轻量提示通知的容器,支持堆叠与自动消失。
- Toggle可开可关的两态按钮。
- Toggle Group一组可独立开关的两态按钮,支持单选或多选。
- Tooltip悬停或聚焦时出现的提示气泡,为视觉用户补充说明。
Radix UI
26最成熟的 headless 原语库,shadcn/ui 的默认底座,API 稳定、生态最大。
@animate-ui/react/primitives/radix-ui
- Accordion垂直堆叠的可交互标题与内容区,一次展开一项或多项;保留 Radix UI 的完整 API。
- Alert Dialog打断当前操作、要求用户明确回应的模态对话框。
- Checkbox在选中与未选中之间切换的复选框,勾选标记由描边动画绘制。
- Collapsible由一个按钮展开或收起的单个内容面板。
- Context Menu在指针位置由右键或长按唤出的上下文菜单。
- Dialog覆盖页面的对话框,弹出时底层内容进入 inert。也是 shadcn/ui Sheet 的底座。
- Drawer从屏幕边缘滑入、跟随手指拖拽的抽屉。它是 Vaul 的直接替代品,API 与 Vaul 相同。
- Dropdown Menu由按钮触发的操作或功能菜单,带键盘导航与子菜单。
- Hover Card为视觉用户预览链接背后内容而出现的浮层卡片。
- Menubar桌面应用式的常驻菜单栏,提供一组稳定、快速可达的命令。
- Navigation Menu用于网站导航的链接与子菜单集合,支持视口跟随。
- Pagination带页码、上一页与下一页的分页;当前页描边会在页码之间滑动。
- Popover由按钮触发的富内容浮层,渲染在 Portal 中。
- Preview Link Card悬停时显示目标页面截图的链接卡片,基于 Radix UI 的 Hover Card。
- Progress展示任务完成进度的进度条,支持确定与不确定状态。
- Questionnaire多步问卷,支持单选、多选、自由填写与跳过;题目依次滑动切换。
- Radio Group一组单选按钮,同一时间只能选中一项,方向键可在选项间移动。
- Select从下拉列表中选择预定义值的表单组件。
- Sheet扩展自 Dialog 的侧边面板,用来承载与主内容互补的信息。
- Sidebar可组合、可换肤的侧边栏,菜单按钮共享一块滑动高亮,折叠时内容走同一条曲线。
- Slider在一个区间内选择数值的滑块输入。
- Switch在开启与关闭之间切换的开关。
- Tabs分层组织内容、一次只显示一个面板的标签页。
- Toggle可开可关的两态按钮。
- Toggle Group一组可独立开关的两态按钮,支持单选或多选。
- Tooltip元素获得键盘焦点或鼠标悬停时出现的信息气泡。
React Aria
24Adobe 出品,交互与无障碍覆盖最细,适合复杂表单与国际化场景。
@animate-ui/react/primitives/react-aria
- Accordion基于 React Aria DisclosureGroup 的一组披露面板,每个标题展开对应的内容区。
- Alert Dialog打断当前流程、要求用户明确回应的模态对话框。
- Checkbox在选中与未选中之间切换的复选框。
- Collapsible基于 React Aria Disclosure 的可折叠内容区。
- Combobox文本输入与列表框的组合,可按输入内容过滤选项。
- Context Menu由右键在指针位置唤出的菜单。
- Dialog覆盖在应用内容之上的对话框。也是 shadcn/ui Sheet 的底座。
- Dropdown Menu由按钮触发的操作或选项列表,支持键盘导航。
- Hover Card悬停链接时预览其背后内容的浮层,基于 PreviewTrigger 与 Popover。
- Pagination带页码、上一页与下一页的分页组件。
- Popover相对于触发元素定位的浮层,可用于对话框触发器、预览触发器或日期选择器。
- Preview Link Card悬停时显示目标页面截图的链接卡片,基于 PreviewTrigger 与 Popover。
- Progress展示确定或不确定进度的进度条。
- Questionnaire多步问卷,支持单选、多选、自由填写与跳过。
- Radio Group一组单选按钮,同一时间只能选中一项。
- Select可展开的选项列表,允许用户选择其中一项。
- Sheet扩展自 Dialog 的侧边面板,补充主内容之外的上下文。
- Sidebar可组合、可换肤的侧边栏,菜单按钮共享一块滑动高亮。
- Slider在一个区间内选择一个或多个值的滑块。
- Switch在开启与关闭之间切换的开关。
- Tabs把内容分成多个区段并允许用户在区段之间切换。
- Toggle可开可关的两态按钮。
- Toggle Group一组可独立开关的两态按钮。
- Tooltip悬停或聚焦时显示元素说明的气泡。
Animate UI
47不属于任何底座的自有原语:文字、按钮、光标、背景与效果。
@animate-ui/react/primitives
- Auto Height内容高度变化时,容器高度自动弹到新的内容高度,并在移动中裁剪溢出内容。
- Avatar Group相互叠放的圆形头像组:悬停的那一个会向上浮起,提示气泡在头像之间滑行。
- Blur入场原语:在加载时或滚动进入视口时,把元素从模糊带到清晰。
- Button按下时会向下压的按钮,按压比例与弹簧都可配置。
- Click在指针点击处播放一次视觉反馈:圆环、涟漪、准星、爆裂或粒子。
- Code Block使用 Shiki 高亮的代码块,可以按字符逐字打出代码,并自动跟随最后一行滚动。
- Copy Button复制文本到剪贴板的按钮,图标会在复制成功后换成对勾。
- Counting Number从起始值计数到目标值的数字,直接写入 DOM,不逐帧触发 React 渲染。
- Cursor自定义光标,以及在光标旁跟随的标签;可限定在某个区域,也可覆盖整页。
- Effect组合入场原语:在加载或进入视口时,同时应用淡入、模糊、滑动与缩放。
- Fade入场原语:在加载时或滚动进入视口时让元素淡入。
- Flip Button悬停时翻面的按钮,正面转走、背面转进来,两面都可以放内容。
- GitHub Stars展示仓库 GitHub 星数的组件:数字滚动计数,星星自下而上填满,并撒出粒子。
- GitHub Stars Button把仓库星数放进按钮:数字滚动、星星填充,点击可直达仓库。
- Gradient Text用渐变填充的文字,渐变会缓慢扫过整行;渐变仅作为文字材质,不作为页面背景。
- Highlight在条目之间滑动的背景块,可由点击、悬停或受控值驱动。
- Highlight Text像荧光笔一样从左侧扫入的文字背景。
- Icon Button点击时从按钮顶部边缘爆出粒子的图标按钮。
- Image Zoom在指针位置放大的图片,可悬停触发或点击触发。
- Input OTP可访问的一次性密码输入框:键入的字符弹入,粘贴的整串验证码依次错开落下。API 与 input-otp 完全一致。
- Liquid Button悬停时颜色从底部涨满按钮的液体按钮。
- Magnetic指针靠近时被吸过去的元素,距离越近吸力越强。
- Morphing Text从一段文字变形到下一段:共有的字母滑到新位置,其余字母淡出、模糊并缩放。
- Motion Grid一格一帧播放动画的点阵,用来做加载与状态指示。
- Particles从元素一侧爆出的粒子,用于点赞、收藏与庆祝。
- Pinned List在置顶组与普通组之间滑动的列表,条目换组时其余条目自动让位。
- Ripple Button从点击位置向外扩散涟漪的按钮。
- Rolling Text像翻牌板一样逐字翻转的文字。
- Rotating Text同一个位置上轮流出现的词组,前一个滑出、后一个滑入。
- Scroll Fade滚动容器的边缘渐隐:只有还有内容可滚的那一侧才淡出,并随滚动实时变化。
- Scroll Progress跟随页面或容器滚动位置的进度条。
- Scrolling Number一列数字滚轮旋转到目标值,并在高亮框下停住。
- Shimmering Text有一道光泽扫过字母的文字。
- Shine扫过元素的一道光,可以只播一次、循环、悬停或点击触发。
- Slide入场原语:在加载或进入视口时把元素滑到位置。
- Sliding Number像里程表一样逐位滚到新值的数字。
- Sliding Text文字滑出框外、副本从另一侧滑入,像菜单链接的悬停效果。
- Splitting Text按字符、单词或行拆开,逐片进入的文字。
- Spring被弹簧线圈拴在原位的可拖拽元素,松手后被拉回去。
- Swapping Text逐字替换成新值:变化的字母原位滑出、新字母滑入,未变化的字母不动。
- TabsAnimate UI 自有的标签页:高亮在触发器之间滑动,面板横向滑入,容器高度跟随当前面板。
- Theme Toggler使用 View Transitions API 把新主题以擦除方式铺满页面的主题切换器。
- Theme Toggler Button循环切换主题的按钮,图标会转变成下一个。
- Tilt朝指针方向做 3D 倾斜的卡片。
- TooltipAnimate UI 自有的 Tooltip:同一 Provider 下的提示共享一个气泡,在触发器之间滑行,而不是关闭再打开。
- Typing Text逐字打出的文字,可带闪烁光标;支持多段文本循环。
- Zoom入场原语:在加载或进入视口时把元素从缩小状态放大到位。