# Avatar Group

Displays a stacked row of avatars with an overflow indicator when more than three are provided. Useful for showing team members, collaborators, or participants at a glance.

```tsx demo
import { AvatarGroup } from "@tenstorrent/vesper/avatar-group";

const AVATARS = [
  {
    src: "https://api.dicebear.com/10.x/initial-face/svg?seed=bob",
    alt: "Bob",
  },
  {
    src: "https://api.dicebear.com/10.x/initial-face/svg?seed=jim",
    alt: "Jim",
  },
  {
    src: "https://api.dicebear.com/10.x/initial-face/svg?seed=alex",
    alt: "Alex",
  },
  {
    src: "https://api.dicebear.com/10.x/initial-face/svg?seed=marisa",
    alt: "Marisa",
  },
];

export default function AvatarGroupDemo() {
  return <AvatarGroup size="md" avatars={AVATARS} />;
}
```

## Options

| Prop      | Type                                           | Description                                                                                                | Default |
| --------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| `size`    | `"sm" \| "md" \| "lg"`                         | The size applied to all avatars in the group.                                                              | `"md"`  |
| `avatars` | `{ src: string \| undefined; alt?: string }[]` | The list of avatars to display. A maximum of 3 are shown, with an overflow indicator for additional items. | —       |
| `as`      | `ElementType`                                  | The root element type for polymorphic rendering.                                                           | `"div"` |

## Examples

### Basic usage

By default, an `AvatarGroup` will render all avatars at `md` size if the `size` prop is not specified:

```tsx demo
import { AvatarGroup } from "@tenstorrent/vesper/avatar-group";

export default function BasicAvatarGroup() {
  return (
    <AvatarGroup
      avatars={[
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=bob",
          alt: "Bob",
        },
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=jim",
          alt: "Jim",
        },
      ]}
    />
  );
}
```

### Sizes

An `AvatarGroup` can be rendered in one of three sizes: `sm`, `md`, and `lg`:

```tsx demo
import { AvatarGroup } from "@tenstorrent/vesper/avatar-group";

const AVATARS = [
  {
    src: "https://api.dicebear.com/10.x/initial-face/svg?seed=bob",
    alt: "Bob",
  },
  {
    src: "https://api.dicebear.com/10.x/initial-face/svg?seed=jim",
    alt: "Jim",
  },
  {
    src: "https://api.dicebear.com/10.x/initial-face/svg?seed=alex",
    alt: "Alex",
  },
];

export default function AvatarGroupSizes() {
  return (
    <div
      style={{
        display: "flex",
        alignItems: "center",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <AvatarGroup size="sm" avatars={AVATARS} />
      <AvatarGroup size="md" avatars={AVATARS} />
      <AvatarGroup size="lg" avatars={AVATARS} />
    </div>
  );
}
```

### With overflow (>3 avatars)

When more than 3 avatars are present, an `AvatarGroup` will render an overflow indicator:

```tsx demo
import { AvatarGroup } from "@tenstorrent/vesper/avatar-group";

export default function AvatarGroupOverflow() {
  return (
    <AvatarGroup
      avatars={[
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=bob",
          alt: "Bob",
        },
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=jim",
          alt: "Jim",
        },
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=alex",
          alt: "Alex",
        },
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=marisa",
          alt: "Marisa",
        },
      ]}
    />
  );
}
```

### Polymorphic usage

You can use the `as` prop to specify what underlying element to render. In this case, we are passing `as="a"` to render the `AvatarGroup` as an anchor link:

```tsx demo
import { AvatarGroup } from "@tenstorrent/vesper/avatar-group";

export default function AvatarGroupAsLink() {
  return (
    <AvatarGroup
      as="a"
      href="#polymorphic-usage"
      avatars={[
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=bob",
          alt: "Bob",
        },
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=jim",
          alt: "Jim",
        },
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=alex",
          alt: "Alex",
        },
        {
          src: "https://api.dicebear.com/10.x/initial-face/svg?seed=marisa",
          alt: "Marisa",
        },
      ]}
    />
  );
}
```