# Avatar Group

A stack of overlapping avatars, with an optional overflow count.

- Category: Core Elements
- Page: https://wunderui.com/components/avatar-group
- Tier: Free

## Install

```bash
npx wunderui-cli add avatar-group
```

## Import

```tsx
import { AvatarGroup, AvatarGroupCount, AvatarGroupProps, AvatarStack } from "@/components/ui/avatar"
```

## Minimal usage

Then use it:

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

export function Team() {
  return (
    <AvatarGroup>
      <Avatar color="indigo">
        <AvatarFallback>NL</AvatarFallback>
      </Avatar>
      <Avatar color="purple">
        <AvatarFallback>DO</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  )
}
```

Expected result: You should see two overlapping avatars, NL and DO, and a +3 circle of the same size at the end.

## Usage

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

export function Example() {
  return (
    <AvatarGroup>
      <Avatar color="indigo">
        <AvatarFallback>NL</AvatarFallback>
      </Avatar>
      <Avatar color="purple">
        <AvatarFallback>DO</AvatarFallback>
      </Avatar>
      <Avatar color="pink">
        <AvatarFallback>PR</AvatarFallback>
      </Avatar>
      <Avatar color="green">
        <AvatarFallback>TF</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  )
}
```

## When to use

### Use Avatar Group for

- The people on a project, document or meeting, in a header or a row
- A short list of people where you decide how many faces show
- A row of faces with a button that opens everyone who is not shown
- A list of people passed as data, cut at a limit with a +N count worked out for you (people)

### Use something else

- [Avatar](https://wunderui.com/components/avatar) for one person, workspace or team
- [Avatar label](https://wunderui.com/components/avatar) for people listed with a name and a role in a table or a list

## Keyboard

The group is a plain container. Only an interactive count is a control, and it is a native button.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to or away from an interactive count, and to any interactive avatar in the group, in the order they are written. |
| `Enter` or `Space` | Presses the focused count, for example to open the list of the people who are not shown. |

The hover lift follows the mouse only: moving focus with the keyboard does not lift an avatar.

## Behavior

What the group does with state, content, the DOM and motion.

- **Every child is shown:** The group renders every child it gets and does not count, cut or reorder them. Later avatars sit on top of earlier ones.
- **Overlap and rings:** In overlap layout each avatar overlaps the one before by 12 px and gets a 2 px ring in the surface colour. In spaced layout the avatars keep a 6 px gap and get no ring.
- **Count:** A static count is a muted circle with the text you pass, such as +3. As a button it has a border: hover and open use the page tone, a press the subtle tone, disabled dims it to 40 %.
- **Size:** The group has no size setting. The count takes the size of the avatars, 24, 28, 36, 40 or 44 px, so give every avatar the same one.
- **Names for screen readers:** A static count is read as plain +3, so add visually hidden text like more people after it, or use an interactive count with an aria-label. Hide the avatars when names are listed elsewhere.
- **Motion:** Hovering an avatar lifts it by 4 px and scales it to 1.05; neighbours lift less the farther away they are. Only transform animates.
- **Reduced motion:** With reduced motion on, the lift is off: hovering changes nothing.

## Anatomy

- `AvatarGroup`: The row. It overlaps its avatars with a ring in the surface colour, or spaces them with a 6 px gap; hovering one lifts it and nudges its neighbours, except with reduced motion.
- `Avatar`: Each person: an Avatar with initials or an image. Give all avatars in one group the same size.
- `AvatarGroupCount`: The +N circle at the end for everyone not shown, as a static count or a button. It takes the size of the avatars.
- `AvatarStack`
- `Avatar Group`
- `Avatar`
- `Avatar Check`
- `Avatar Fallback`
- `Avatar Image`

## Best practices

### When to use

- Use an Avatar Group to show who is on a project or document, composing each avatar yourself. For people passed as data with a built-in limit, pass people, max and size instead of children (a people list lifts on hover and names each face in a Tooltip too).

### Do

- Cut the list yourself and put the rest in the count as +3. The group renders every child it gets; it does not count or hide anyone.
- Make the count a button when people can open the rest. Give it an aria-label such as Show 3 more people and aria-expanded.
- Place the group on a surface that sets the surface colour, such as a Card. The rings take that colour, so each avatar reads as cut out of the background.
- Pick overlap for a header or a row where room is short, and spaced for a short list where each face should stay whole.
- At sm and xs the faces overlap by 2 px so both initials stay readable; do not tighten them further with your own spacing.

### Don't

- Don't mix avatar sizes in one group. The overlap and the count circle assume one size for every avatar.
- Don't use a group for a single person, or for a list people should read name by name. Use Avatar, or AvatarLabel with a name.

## API reference

### AvatarGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| layout | "overlap" \| "spaced" |  | `overlap` stacks the avatars with a 12 px overlap and a ring in the surface colour. `spaced` puts a 6 px gap between them. |
| max | number | 3 | With `people`: how many faces show before the count. Default 3. |
| people | Person[] |  | A list of people: the group renders their avatars itself, overlapping by 4 px (2 px at `sm` and `xs`, so the second initial is not hidden under the next face), cut at `max` with a "+N" avatar. Hovering a face lifts it and shows the name in… |
| size | "xs" \| "sm" \| "default" \| "lg" \| "xl" | "sm" | With `people`: the avatar size, `sm` 24 px, `xs` 28 px, `default` 36 px, `lg` 40 px, `xl` 44 px. Default `sm`. |

Also accepts React.HTMLAttributes attributes.

### AvatarGroupCount

| Prop | Type | Default | Description |
|---|---|---|---|
| interactive | boolean |  | Renders the count as a button with hover, open, pressed and focus states, for opening the rest of the people. A button takes `aria-label`, `aria-expanded` and `onClick`. Without it the count is a static `div`. |

Also accepts React.ButtonHTMLAttributes attributes.

### AvatarStack

| Prop | Type | Default |
|---|---|---|
| people* | Person[] |  |
| className | string |  |
| max | number | 3 |
| size | "sm" \| "xs" \| "default" | "sm" |

## Examples

### Layout: overlap or spaced

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

export function Example() {
  return (
    <AvatarGroup>
      <Avatar color="indigo">
        <AvatarFallback>NL</AvatarFallback>
      </Avatar>
      <Avatar color="purple">
        <AvatarFallback>DO</AvatarFallback>
      </Avatar>
      <Avatar color="pink">
        <AvatarFallback>PR</AvatarFallback>
      </Avatar>
      <Avatar color="green">
        <AvatarFallback>TF</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  )
}
```

### Overflow: none, count or button

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

export function Example() {
  return (
    <AvatarGroup>
      <Avatar color="indigo">
        <AvatarFallback>NL</AvatarFallback>
      </Avatar>
      <Avatar color="purple">
        <AvatarFallback>DO</AvatarFallback>
      </Avatar>
      <Avatar color="pink">
        <AvatarFallback>PR</AvatarFallback>
      </Avatar>
      <Avatar color="green">
        <AvatarFallback>TF</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  )
}
```

### Sizes: 24, 28, 36, 40 and 44 px

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

export function Example() {
  return (
    <AvatarGroup>
      <Avatar color="indigo">
        <AvatarFallback>NL</AvatarFallback>
      </Avatar>
      <Avatar color="purple">
        <AvatarFallback>DO</AvatarFallback>
      </Avatar>
      <Avatar color="pink">
        <AvatarFallback>PR</AvatarFallback>
      </Avatar>
      <Avatar color="green">
        <AvatarFallback>TF</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  )
}
```

### People list: pass people, set the limit and the size

```tsx
import { AvatarGroup } from "@/components/ui/avatar-group"
import type { AvatarColor } from "@/components/ui/avatar"

const PEOPLE: { name: string; color: AvatarColor }[] = [
  { name: "Nora Lindgren", color: "indigo" },
  { name: "Daniel Okafor", color: "purple" },
  { name: "Priya Raman", color: "pink" },
  { name: "Tomás Ferreira", color: "green" },
  { name: "Maya Kessler", color: "orange" },
  { name: "Amara Diallo", color: "red" },
]

export function Example() {
  return <AvatarGroup people={PEOPLE} />
}
```

## In context

### Project header: who is on the project

The group sits at the end of a card header. Its rings match the card colour, so each face looks cut out of the card.

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

const PEOPLE = [
  { name: "Nora Lindgren", initials: "NL", color: "indigo" },
  { name: "Daniel Okafor", initials: "DO", color: "purple" },
  { name: "Priya Raman", initials: "PR", color: "pink" },
  { name: "Tomás Ferreira", initials: "TF", color: "green" },
] as const

export function Example() {
  return (
    <div className="flex items-center justify-between gap-4 rounded-xl border border-border bg-card p-4 [--surface:var(--card)]">
      <div className="flex min-w-0 flex-col">
        <h3 className="truncate text-base font-semibold">Q4 launch plan</h3>
        <p className="text-xs text-text-secondary">7 people, updated today</p>
      </div>
      <AvatarGroup>
        {PEOPLE.map((person) => (
          <Avatar key={person.name} color={person.color} aria-hidden>
            <AvatarFallback>{person.initials}</AvatarFallback>
          </Avatar>
        ))}
        <AvatarGroupCount>+3</AvatarGroupCount>
      </AvatarGroup>
    </div>
  )
}
```

### Members: the overflow button opens the list

Five people are visible. The +3 button opens the rest and tells screen readers whether the list is open.

```tsx
import { useState } from "react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

const VISIBLE = [
  { name: "Nora Lindgren", initials: "NL", color: "indigo" },
  { name: "Daniel Okafor", initials: "DO", color: "purple" },
  { name: "Priya Raman", initials: "PR", color: "pink" },
  { name: "Tomás Ferreira", initials: "TF", color: "green" },
  { name: "Maya Kessler", initials: "MK", color: "orange" },
] as const

const MORE = [
  { name: "Elias Vogel", role: "Engineering", initials: "EV", color: "blue" },
  { name: "Amara Diallo", role: "Billing", initials: "AD", color: "red" },
  { name: "Felix Moreno", role: "Support", initials: "FM", color: "yellow" },
] as const

export function Example() {
  const [open, setOpen] = useState(true)

  return (
    <div className="flex w-72 flex-col gap-3">
      <AvatarGroup>
        {VISIBLE.map((person) => (
          <Avatar key={person.name} size="lg" color={person.color} aria-hidden>
            <AvatarFallback>{person.initials}</AvatarFallback>
          </Avatar>
        ))}
        <AvatarGroupCount
          interactive
          aria-label="Show 3 more people"
          aria-expanded={open}
          onClick={() => setOpen(!open)}
        >
          +3
        </AvatarGroupCount>
      </AvatarGroup>
      {open && (
        <div className="rounded-lg border border-border bg-popover p-1 [--surface:var(--popover)]">
          <p className="flex h-7 items-center px-2 text-xs text-text-tertiary">3 more people</p>
          {MORE.map((person) => (
            <div key={person.name} className="flex h-12 items-center gap-3 px-2">
              <Avatar size="xs" color={person.color} aria-hidden>
                <AvatarFallback>{person.initials}</AvatarFallback>
              </Avatar>
              <span className="flex flex-col">
                <span className="text-sm font-medium">{person.name}</span>
                <span className="text-xs text-text-secondary">{person.role}</span>
              </span>
            </div>
          ))}
        </div>
      )}
    </div>
  )
}
```

## For AI agents

`get_component("avatar-group")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
