Animated Avatar Group

Wraps Nuxt UI's UAvatarGroup and adds two hover behaviours on top of it: the avatars ease apart from under each other, and they scale up in a staggered sequence starting from the right.

The overlap is expressed as a ratio of the avatar's pixel size, not as pixels. overlap: 0.4 on an lg avatar (36px) becomes -14.4px of negative inline-end margin. That keeps the visual density identical across all nine sizes — overlap: 0.3 looks the same at 3xs and at 3xl, which is not true if you pass pixels.

Two states change the hover behaviour, and they are not the same:

• With overflow (more avatars than max), the leading "+N" counter stays put while every avatar behind it scales.
• Without overflow, all avatars scale, counter included.

Everything is CSS custom properties plus data- attributes on the root, so the animation is entirely in the stylesheet rather than in a JS loop. hoverScale and staggerDelay are just the values of --m-avatar-hover-scale and --m-avatar-stagger.

Usage

+1

<template>
  <MAnimatedAvatarGroup
    :avatars="avatars"
    :max="4"
    size="lg"
    :overlap="0.35"
  />
</template>

<script setup lang="ts">
const avatars = [
  { src: 'https://randomuser.me/api/portraits/women/44.jpg', alt: 'Ana Ruiz' },
  { src: 'https://randomuser.me/api/portraits/men/32.jpg', alt: 'Ben Osei' },
  { src: 'https://randomuser.me/api/portraits/women/68.jpg', alt: 'Cleo Park' },
  { src: 'https://randomuser.me/api/portraits/men/75.jpg', alt: 'Dmitri Ilves' },
  { src: 'https://randomuser.me/api/portraits/women/90.jpg', alt: 'Elin Haugen' },
]
</script>

Pick one of two sources for the avatar image: src for a real image, or icon / text for a glyph or initials. alt is what UAvatar uses for its own accessible label, and it is also the component's fallback key, so two avatars with different images must have different alt values or they will share a slot identity and animate as one.

Examples

Avatar group in context

+2

6 people

lgShow 4

<template>
  <div class="flex w-full max-w-md flex-col gap-5">
    <div class="flex items-center justify-between rounded-2xl border border-default bg-default p-5">
      <MAnimatedAvatarGroup
        :avatars="avatars"
        :max="max"
        :size="size"
        :overlap="overlap"
        :hover-scale="1.08"
      />
      <span class="text-xs text-muted">{{ avatars.length }} people</span>
    </div>

    <div class="grid grid-cols-2 gap-3">
      <USelect
        v-model="size"
        :items="['sm', 'md', 'lg', 'xl', '2xl']"
      />
      <USelect
        v-model="max"
        :items="maxItems"
      />
    </div>

    <USlider
      v-model="overlap"
      :min="0"
      :max="0.6"
      :step="0.05"
      label="Overlap"
      class="w-full"
    />
  </div>
</template>

<script setup lang="ts">
const size = ref<'sm' | 'md' | 'lg' | 'xl' | '2xl'>('lg')
const max = ref(4)
const overlap = ref(0.35)

const avatars = [
  { src: 'https://randomuser.me/api/portraits/women/44.jpg', alt: 'Ana Ruiz' },
  { src: 'https://randomuser.me/api/portraits/men/32.jpg', alt: 'Ben Osei' },
  { src: 'https://randomuser.me/api/portraits/women/68.jpg', alt: 'Cleo Park' },
  { src: 'https://randomuser.me/api/portraits/men/75.jpg', alt: 'Dmitri Ilves' },
  { src: 'https://randomuser.me/api/portraits/women/90.jpg', alt: 'Elin Haugen' },
  { src: 'https://randomuser.me/api/portraits/men/11.jpg', alt: 'Farid Nazari' },
]

const maxItems = [
  { label: 'Show 3', value: 3 },
  { label: 'Show 4', value: 4 },
  { label: 'Show all', value: 6 },
]
</script>

Customize

+1

Customize

Reset

Max4

Max visible4

Sizelg

lg

Overlap0.35

Expand on hover

Stagger (s)0.03

Hover scale1.08

Props

Slots

UI

This component's theme exposes the slots below. Override any of them per instance with the ui prop, or app-wide under ui.animatedAvatarGroup in app.config.ts.

Accessibility

The root is a role="group" with aria-label="Avatar group" by default, which is a poor label on its own — pass aria-label="Reviewers" (or any string) and it replaces the default. Avatars are not links here, so the group is a static image list, not an interactive widget; nothing is focusable and there is no keyboard interaction to support.

The visuals are hover-only and the whole effect is gated behind @media (hover: hover) and (pointer: fine), so touch devices never see the fan out — they get the overlapped layout permanently. That is a deliberate choice, not a bug, but it means the two presentations differ enough that you should not rely on the expanded spacing to convey meaning.

prefers-reduced-motion: reduce removes the transition entirely and forces scale: 1, so hover does nothing. The avatars still overlap and the group is still readable — the information is never carried by the animation alone.

The overflow "+N" counter is rendered by UAvatarGroup and inherits its own labelling; since the visible avatars are truncated, aria-label on the group is worth writing explicitly to say how many are in total.

Performance

• There is no JavaScript animation. The component writes four CSS custom properties and flips three data- attributes; the browser handles the rest. Re-rendering is O(1) in the number of avatars.
• The transition list is only margin-inline-end and scale, both compositor-friendly or cheap layout properties, over 250ms with a slightly bouncy cubic-bezier(0.34, 1.56, 0.64, 1).
• Stagger is implemented with ten :nth-last-child() rules plus an :nth-last-child(n + 11) fallback, all capped at ten steps. Past eleven avatars every remaining delay is identical, which is deliberate — a per-item delay for fifty avatars would keep the last one animating for seconds.
• --m-avatar-overflow-delay is computed as visibleCount * staggerDelay so the counter's delay matches the end of the stagger chain. Recomputing it is the only value that depends on the avatar count.
• Animating margin is not free — it relayouts on every frame of the transition. It is scoped to a handful of avatars and never applies above nth-last-child(n + 11), so the cost stays bounded.