# `PhiaUi.Components.AvatarGroup`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/display/avatar_group.ex#L1)

AvatarGroup — an overlapping stack of avatars with built-in overflow badge.

Accepts named slot items declaratively so callers do not need to manage
the visible/overflow split themselves. The component slices the item list
at `max`, renders each visible avatar with `ring-2 ring-background` for
separation, then appends a "+N" badge when there are hidden items.

## Sizes

| Value       | Dimensions   | Tailwind classes |
|-------------|--------------|-----------------|
| `"sm"`      | 24 × 24 px   | `h-6 w-6`       |
| `"default"` | 40 × 40 px   | `h-10 w-10`     |
| `"lg"`      | 56 × 56 px   | `h-14 w-14`     |
| `"xl"`      | 72 × 72 px   | `h-18 w-18`     |

## Basic usage

    <.avatar_group>
      <:item src="/avatars/alice.jpg" name="Alice Adams" />
      <:item src="/avatars/bob.jpg"   name="Bob Baker" />
      <:item src="/avatars/carol.jpg" name="Carol Chen" />
    </.avatar_group>

## Limit visible count (overflow badge)

    <.avatar_group max={3}>
      <:item src="/a.jpg" name="Alice" />
      <:item src="/b.jpg" name="Bob" />
      <:item src="/c.jpg" name="Carol" />
      <:item src="/d.jpg" name="Dave" />
      <:item src="/e.jpg" name="Eve" />
    </.avatar_group>
    <%!-- Renders 3 avatars + "+2" overflow badge --%>

## Sizes

    <.avatar_group size="sm" max={4}>
      <:item src="/a.jpg" name="Alice" />
      <:item name="Bob" />
    </.avatar_group>

# `avatar_group`

Renders an overlapping group of avatars with an optional overflow count badge.

Items that exceed `max` are hidden; a `+N` badge is appended automatically
when `N > 0`. All avatars receive `ring-2 ring-background` so each circle
is visually separated from its neighbour.

## Example

    <.avatar_group max={3} size="sm">
      <:item src="/a.jpg" name="Alice" />
      <:item src="/b.jpg" name="Bob" />
      <:item src="/c.jpg" name="Carol" />
      <:item src="/d.jpg" name="Dave" />
    </.avatar_group>

## Attributes

* `max` (`:integer`) - Maximum number of avatars to display before showing the overflow '+N' badge. Defaults to `5`.
* `size` (`:string`) - Size applied to every avatar and the overflow badge. One of `"sm"`, `"default"`, `"lg"`, `"xl"`. Defaults to `"default"`. Must be one of `"sm"`, `"default"`, `"lg"`, or `"xl"`.
* `class` (`:string`) - Additional CSS classes merged via `cn/1` and applied to the container div. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the root `<div>` element.
## Slots

* `item` - One avatar item. Supports `src` (image URL) and `name` (full name for initials fallback). Accepts attributes:

  * `src` (`:string`) - Avatar image URL. Omit to show initials-only fallback.
  * `name` (`:string`) - Full name used both for the alt text and the initials fallback.

---

*Consult [api-reference.md](api-reference.md) for complete listing*