Cursor · Animate UI

自定义光标，以及在光标旁跟随的标签；可限定在某个区域，也可覆盖整页。

安装

自有原语直接来自 @animate-ui/react，不依赖 Radix UI、Base UI 或 React Aria；装上包即可使用。

终端

bun add @animate-ui/react motion

用法

直接从 @animate-ui/react 的对应子路径引入，下面就是完整示例；样式由你的类名决定。

cursor.tsx

import {
  Cursor,
  CursorContainer,
  CursorFollow,
  CursorProvider,
} from '@animate-ui/react/primitives/cursor';

export function Canvas() {
  return (
    <div className="relative h-72">
      <CursorProvider>
        <CursorContainer>
          <Cursor>
            <ArrowIcon />
          </Cursor>
          <CursorFollow side="bottom" align="end">
            <span>Designer</span>
          </CursorFollow>
        </CursorContainer>
      </CursorProvider>
    </div>
  );
}

动效

进入区域时隐藏原生指针，光标与跟随标签从 0 缩放弹入，弹簧 stiffness 550 / damping 30，同时 300ms 淡入。
离开时无过冲地缩回 0 并淡出；触屏设备不启用，减少动效下不播放缩放。

所有时长都会乘以 AnimateUIProvider 的 tempo，并遵守系统的减少动效设置。

API

动效相关的 transition 与 exitTransition 是 Animate UI 唯一新增的属性；其余 props 见上表。

属性	类型	默认值
global	`boolean`	`false`
children	`React.ReactNode`	`—`
asChild	`boolean`	`false`
…props	`HTMLMotionProps<'div'>`	`—`
asChild	`boolean`	`false`
children	`React.ReactNode`	`—`
…props	`HTMLMotionProps<'div'>`	`—`
asChild	`boolean`	`false`
side	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`
sideOffset	`number`	`0`
align	`'start' \| 'center' \| 'end'`	`'end'`
alignOffset	`number`	`0`
transition	`SpringOptions`	`{ stiffness: 500, damping: 50, bounce: 0 }`
children	`React.ReactNode`	`—`
…props	`Omit<HTMLMotionProps<'div'>, 'transition'>`	`—`

未列出的属性与上游 API 完全一致，可在官方文档查阅。

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