安装

安装依赖

bun add @animate-ui/react motion

@animate-ui/react 使用你组件已经依赖的那套原语库：radix-ui、@base-ui/react或 react-aria-components。只需要安装你实际用到的底座。

让组件动起来

在项目根目录运行 CLI。它通过 components.json 找到你安装的 shadcn/ui 组件，把其中的 primitive import 换成 Animate UI 的版本，并删除 Motion 已经接管的 CSS 动画类。

bunx @animate-ui/cli@latest animate all
# 只处理部分组件
bunx @animate-ui/cli@latest animate dialog dropdown-menu tooltip
# 先预览改动，不写入文件
bunx @animate-ui/cli@latest animate accordion --dry-run

命令只修改现有文件，不复制组件。已经处理过的组件会跳过，重复运行不会产生新改动。

调整节奏

所有动画共享一套时长。把应用包进 AnimateUIProvider，就能整体调快或调慢：

import { AnimateUIProvider } from '@animate-ui/react/provider';

export default function Layout({ children }: { children: React.ReactNode }) {
  return <AnimateUIProvider tempo={1.2}>{children}</AnimateUIProvider>;
}

tempo 会乘到每一个时长与弹簧参数上：0.8 更利落，1.2 更从容。不包 Provider 时使用默认值 1。

选择勾选的画法

勾选标记默认“画”出来：选中时描边像笔一样画出，取消时擦除。只有勾选与取消会触发动画；页面加载时已经存在的勾选、或者对话框与菜单打开时出现的勾选，都静止显示。

checkAnimation="pop" 改为弹出：从一半大小、轻微模糊中进入，取消时缩回。单选场景（select、combobox、菜单中的 radio 项）里，勾选会从离开的项滑向被选中的项。

<AnimateUIProvider checkAnimation="pop">{children}</AnimateUIProvider>

它作用于内部所有勾选：复选框，以及菜单、选择器、组合框与列表里的勾选。单个勾选自身的 animation属性优先于它。嵌套 Provider 会保留未设置的项：内层只写 tempo 时，外层checkAnimation 继续生效。

手动安装与样式

Animate UI 不要求 Tailwind。原语只提供行为、无障碍与动效，外观仍由你的类名或样式表决定。CLI 删除的是 tw-animate-css 工具类、shadcn/ui 的关键帧，以及各原语自己的 CSS 过渡（Base UI 的data-starting-style、React Aria 的 data-entering、从 CSS 变量读取的高度等）。

如果你的项目不是 shadcn/ui，也可以直接安装 @animate-ui/react，把 import 换成对应的子路径，不改其他代码。

对应官方文档 2026-10-18 版本。