跳到正文
目录与搜索
⌘K

原语 / Animate UI

Avatar Group · Animate UI

相互叠放的圆形头像组:悬停的那一个会向上浮起,提示气泡在头像之间滑行。

安装

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

终端
bun add @animate-ui/react motion

用法

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

avatar-group.tsx
import {
  AvatarGroup,
  AvatarGroupTooltip,
  AvatarGroupTooltipArrow,
} from '@animate-ui/react/primitives/avatar-group';

export function Team({ people }: { people: { name: string; src: string }[] }) {
  return (
    <AvatarGroup className="h-12 -space-x-3" invertOverlap>
      {people.map((person) => (
        <img
          key={person.name}
          src={person.src}
          alt={person.name}
          className="size-12 rounded-full border-3 border-background"
        />
      ))}
    </AvatarGroup>
  );
}
avatar-group.tsx
<div className="size-12 rounded-full border-3 border-background bg-muted">
  SK
  <AvatarGroupTooltip className="rounded-md bg-foreground px-3 py-1.5 text-xs text-background">
    <AvatarGroupTooltipArrow className="size-2.5 fill-foreground" />
    <p>Skyleen</p>
  </AvatarGroupTooltip>
</div>

动效

  • 悬停或按下的头像以 stiffness 300 / damping 17 的弹簧上浮,约 17% 过冲后落定,回落时也会轻微低于原位。
  • 提示气泡使用共享布局动画,从一个头像滑向下一个,不关闭重开;减少动效下直接切换。

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

API

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

属性类型默认值
childrenReact.ReactElement | React.ReactElement[]—
invertOverlapbooleanfalse
translatestring | number'-30%'
transitionTransition{ type: 'spring', stiffness: 300, damping: 17 }
tooltipTransitionTransition{ type: 'spring', stiffness: 400, damping: 29 }
openDelaynumber0
closeDelaynumber0
side"top" | "bottom" | "left" | "right""top"
sideOffsetnumber25
align"start" | "center" | "end""center"
alignOffsetnumber0
…propsReact.ComponentProps<'div'>—

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

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