Data Display

Avatar Group

Overlapping avatar stack with a "+N" overflow chip.

Import

tsx

import { AvatarGroup } from "@cooud-ui/ui";

bash

npx cooud-ui add avatar-group

Examples

With overflow

Show the first few members, then a "+N" chip for the rest. Pass `avatars` for the data-driven shorthand and `max` to cap how many render.

CNALJLMK+2

tsx

<AvatarGroup
  max={4}
  aria-label="Project collaborators"
  avatars={[
    { src: "https://github.com/shadcn.png", alt: "@shadcn", fallback: "CN" },
    { fallback: "AL" },
    { fallback: "JL" },
    { fallback: "MK" },
    { fallback: "RW" },
    { fallback: "TP" },
  ]}
/>

Sizes

The `size` prop drives both the avatars and the overflow chip, so every row stays uniform regardless of the avatars' own sizes.

CNALJL+2

tsx

<div className="flex flex-col gap-4">
  <AvatarGroup size="sm" max={3} aria-label="Reviewers" avatars={reviewers} />
  <AvatarGroup size="md" max={3} aria-label="Reviewers" avatars={reviewers} />
  <AvatarGroup size="lg" max={3} aria-label="Reviewers" avatars={reviewers} />
</div>

API Reference

Generated from the component's exported types.

AvatarGroupProps

Extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof avatarGroupItemVariants>

Prop	Type	Default	Description
`avatars`	`AvatarGroupAvatar[]`	—	Avatars to stack. Compose `<Avatar>` children, or pass `avatars` for the data-driven shorthand. `avatars` takes precedence when both are provided.
`max`	`number`	—	Show the first `max` avatars, then a "+N" overflow chip for the rest.
`spacing`	`string`	`"-space-x-2"`	Horizontal overlap between avatars as a Tailwind negative-margin class (e.g. `-space-x-2`). Defaults to a tasteful offset.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	—