<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# AvatarGroup

Avatars stacked with a slight overlap, such as the cooks on a recipe, with a "+N" count after `max`. Its `label` names the group for screen readers, and its `size` applies to every avatar in it.

```tsx
import { AvatarGroup } from "@/components/ouro/avatar/avatar";
```

## Example

```tsx
<AvatarGroup label="Cooks" max={3} size="sm">
  {cooks.map((cook) => <Avatar key={cook.id} name={cook.name} src={cook.photoUrl} />)}
</AvatarGroup>
```

## Use instead when

- Use a list of `Avatar`s with names beside them instead when readers need to see who each person is.

## Props

Type: `AvatarGroupProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The `Avatar`s, in order. |
| `className` | `string` |  | Layout only: margins, grid placement (`mt-4`). Appearance classes warn in development. |
| `label` (required) | `string` |  | What the group is, for screen readers: "Cooks on this recipe". Required, so the group has a name. |
| `max` | `number` | unlimited | Shows at most this many avatars, then a "+N" count for the rest. |
| `moreLabel` | `((count: number) => string)` | (count) => `${count} more` | What screen readers hear for the "+N" count, for other languages. |
| `ref` | `Ref<HTMLDivElement>` |  | Reaches the rendered element. |
| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "xs" \| "3xl"` | `"md"` | The size of every avatar in the group, and of the count. |
| `total` | `number` |  | How many there are in all, when you pass only the first few avatars (a recipe with 120 cooks). The "+N" count is `total` minus the avatars shown. |

## Native attributes

Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: AvatarGroup merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

[^layout-classes]: test:registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > forwards a ref and lets app layout classes win verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > forwards a ref and lets app layout classes win)