开始使用

安装

从图标库页面逐个添加（Lucide 或Hugeicons），这里以 Lucide 的 Bell 为例。每个图标都是项目里的一个文件；驱动它们的核心来自@animate-ui/react/icons，第一次添加图标时由 CLI 一并安装。

bunx shadcn@latest add @animate-ui/icons-lucide-bell

用法

图标可以自己触发：

import { Bell } from '@/components/animate-ui/icons/bell';

<Bell animateOnHover />;

也可以让父级决定，这样悬停整个按钮时图标才动：

import { AnimateIcon } from '@animate-ui/react/icons';

<AnimateIcon animateOnHover asChild>
  <button>
    <Bell /> Notifications
  </button>
</AnimateIcon>;

AnimateIcon 内部的图标继承它的属性，也可以逐个覆盖。

触发器

• animate：为 true 时持续播放，或播放指定的动画名。
• animateOnHover：指针悬停时播放，离开后回到静止。触摸不会触发（手指无法“离开”），需要触摸时加上 animateOnTap。
• animateOnTap：按住时播放，松开或指针离开后回到静止；加 completeOnStop 则总是播完。
• animateOnView：滚动进入视口时播放（animateOnViewMargin、animateOnViewOnce）。

动画

每个图标都有一个 default 动画，通常还有几个具名动画，外加 path（描边自绘）与path-loop。用 animation 选择，各图标库页面会列出每个图标可用的动画。自绘描边的图标会自己往页面里加一条很小的 CSS 规则，让路径静止时是实心的，不需要 Tailwind 配置。

<ArrowRight animateOnHover animation="pointing" />

计时

• speed：播放速率，2 是两倍速。默认 1 时按作者设定的节奏播放，并跟随 AnimateUIProvider 的 tempo。
• delay：动画开始前的毫秒数。
• loop、loopDelay：循环播放，以及每次之间的停顿。离开屏幕时，循环会在当前一轮结束后等待图标回到视口。

持久化

• persistOnAnimateEnd：结束后停留在动画最终状态。
• initialOnAnimateEnd：结束后无过渡地跳回初始状态。
• completeOnStop：停止前先播完当前动画。

减少动效开启时，图标不播放动画。

API

AnimateIcon 接受同样的属性（size 除外），另有 asChild，让动画作用在子元素上。

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