Avatar Group

Project collaborators

Hover the stack to fan it out

Installation

pnpm dlx shadcn@latest add https://matos-ui.com/r/avatar-group.json

Usage

import { AvatarGroup } from '@/components/matos-ui/avatar-group'

<AvatarGroup
  items={[
    { name: 'Ana Ribeiro', src: '/ana.jpg' },
    { name: 'Bruno Alves' },
    { name: 'Carla Mendes' },
  ]}
  max={5}
/>

Avatars overlap by a negative margin. On hover or keyboard focus the stack "opens": each avatar slides right by one step on a staggered moderate spring so the fan unrolls left-to-right, and the avatar under the cursor lifts with a floating name label. src is optional — a missing or broken image falls back to initials derived from name.

Set spreadOnHover={false} for a static stack, or showLabels={false} to keep the fan without the name tooltips. When prefers-reduced-motion is set the stack never opens — it stays a clean, legible overlap.

Reference

AvatarGroup Props

Prop	Type	Default	Description
`items`	`AvatarGroupItem[]`	-	People to render. `{ src?, name, fallback? }`.
`max`	`number`	-	Cap visible avatars; the remainder collapse into a `+N` chip.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Avatar diameter and label scale.
`spreadOnHover`	`boolean`	`true`	Fan the stack apart on hover / focus.
`showLabels`	`boolean`	`true`	Float each name above its avatar while the stack is open.
`aria-label`	`string`	`"People"`	Accessible name for the group.

AvatarGroupItem

Field	Type	Description
`src`	`string`	Image URL. Falls back to initials when absent/broken.
`name`	`string`	Full name — alt text, title, and hover label.
`fallback`	`string`	Explicit initials. Derived from `name` when omitted.