Spring · Animate UI

被弹簧线圈拴在原位的可拖拽元素，松手后被拉回去。

安装

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

终端

bun add @animate-ui/react motion

用法

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

spring.tsx

import {
  Spring,
  SpringElement,
  SpringProvider,
} from '@animate-ui/react/primitives/spring';

export function Avatar() {
  return (
    <SpringProvider>
      <Spring className="text-muted-foreground" />
      <SpringElement>
        <img src="/avatar.png" alt="Avatar" draggable={false} />
      </SpringElement>
    </SpringProvider>
  );
}

动效

拖动时在原位与元素之间拉伸一根线圈，拉得越远线圈越紧。
松手后按弹簧参数回位，可带过冲；减少动效下直接回位。

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

API

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

属性	类型	默认值
transition	`SpringOptions`	`{ stiffness: 200, damping: 16 }`
pathConfig	`SpringPathConfig`	`{}`
children	`React.ReactNode`	`—`
coilCount	`number`	`8`
amplitudeMin	`number`	`8`
amplitudeMax	`number`	`20`
curveRatioMin	`number`	`0.5`
curveRatioMax	`number`	`1`
bezierOffset	`number`	`8`
…props	`React.SVGProps<SVGSVGElement>`	`—`
asChild	`boolean`	`false`
children	`React.ReactElement`	`—`
…props	`Omit<HTMLMotionProps<'div'>, 'children'>`	`—`

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

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