Avatar

# Brok UI: Avatar Group (`avatar-group`)

An overlapping stack of avatars with a "+N" overflow chip that gently fans apart on hover. Pure CSS — no JavaScript.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add avatar-group
```

## Usage

```blade
<div class="flex min-h-40 w-full items-center justify-center rounded-lg border border-border bg-card p-8">
    <x-ui.avatar-group :max="4" />
</div>
```

## Props

- `avatars` (array, default `[…]`) — Array of {src, name, initials} entries, or bare name strings, rendered as overlapping faces.
- `max` (int, default `4`) — Faces shown before the rest collapse into a +N avatar.
- `size` (xs|sm|md|lg|xl, default `md`) — Avatar scale forwarded to every member.

## Use when

- Use to visually represent people or entities in collaborative or social contexts.
- Showing several people who share ownership of something, such as collaborators or assignees, as one compact overlapping stack.
- Collapsing a long list of participants into a fixed number of visible faces plus a +N count.

## Avoid when

- Do not rely on avatars alone when names or roles are needed for disambiguation.
- Only one person needs representing; use avatar on its own.

## Anti-patterns

- Relying on an avatar alone for identity

## Rules

- Use the `<brok:avatar-group>` tag (or `<x-ui.avatar-group>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/avatar-group
- Registry JSON (files, props, contract): https://brokui.dev/r/open/avatar-group.json

@props([
    // Each entry: ['src' => url|null, 'name' => 'Full Name', 'initials' => 'FN'].
    // A bare string is treated as a name (initials avatar); `initials` overrides
    // the letters derived from the name.
    'avatars' => [
        ['src' => 'https://picsum.photos/seed/ava/80/80', 'name' => 'Ava Chen'],
        ['src' => 'https://picsum.photos/seed/bram/80/80', 'name' => 'Bram Diaz'],
        ['src' => 'https://picsum.photos/seed/cleo/80/80', 'name' => 'Cleo Park'],
        ['src' => null, 'name' => 'Dev Rao'],
        ['src' => 'https://picsum.photos/seed/esme/80/80', 'name' => 'Esme Liu'],
    ],
    // Maximum faces to show before collapsing the rest into a "+N" chip.
    'max' => 4,
    'size' => 'md',
    // Accessible name of the group; defaults to "People".
    'label' => null,
    // Opt-in: when no label is given, name the group with every person, hidden
    // ones included ("Ava Chen, Bram Diaz and Esme Liu"), and hide the faces
    // and the +N chip from assistive tech so nothing is announced twice.
    'listNames' => false,
    // Opt-in: render each face in avatar's name mode (tinted monogram, and the
    // monogram again when an image fails to load).
    'monogram' => false,
])

@php
    // Normalise: allow a plain string per entry as the name.
    $people = array_map(
        fn ($a) => is_array($a) ? $a : ['src' => null, 'name' => (string) $a],
        array_values($avatars),
    );

    $visible = array_slice($people, 0, (int) $max);
    $overflow = max(0, count($people) - (int) $max);

    $initials = function (string $name): string {
        $parts = preg_split('/\s+/', trim($name)) ?: [];
        return mb_strtoupper(collect($parts)->filter()->take(2)
            ->map(fn ($p) => mb_substr($p, 0, 1))->implode(''));
    };

    $names = collect($people)->pluck('name')->map(fn ($n) => trim((string) $n))->filter()->values();
    $groupLabel = $label ?? __('People');
    if ($listNames && $label === null && $names->isNotEmpty()) {
        $groupLabel = $names->count() === 1
            ? $names->first()
            : __(':names and :last', ['names' => $names->slice(0, -1)->implode(', '), 'last' => $names->last()]);
    }

    // A ring in the surface colour separates overlapping faces; the fan-out is a
    // pure-CSS margin transition driven by `group-hover` (RTL-safe via `ms-*`).
    $faceBase = 'ring-2 ring-background transition-[margin] duration-300 ease-out motion-reduce:transition-none';
    $overlap = '-ms-3 group-hover:ms-0.5';
    // A left-to-right isolate keeps "+3" in that order on an RTL page, where the
    // leading "+" would otherwise move after the number. dir="ltr" on the chip
    // would also flip its -ms-3 overlap.
    $overflowLabel = "\u{2066}+{$overflow}\u{2069}";
@endphp

<div
    data-slot="avatar-group"
    role="group"
    aria-label="{{ $groupLabel }}"
    {{ $attributes->merge(['class' => 'group flex items-center']) }}
>
    @foreach ($visible as $i => $person)
        <x-ui.avatar
            :size="$size"
            :src="$person['src'] ?? null"
            :alt="$person['name'] ?? ''"
            :fallback="$person['initials'] ?? ($monogram ? null : $initials($person['name'] ?? ''))"
            :name="$monogram && filled($person['name'] ?? null) ? $person['name'] : null"
            :kind="$person['kind'] ?? null"
            :decorative="(bool) $listNames"
            class="{{ $i === 0 ? $faceBase : $faceBase.' '.$overlap }}"
        />
    @endforeach

    @if ($overflow > 0)
        <x-ui.avatar
            :size="$size"
            :alt="trans_choice(':count more person|:count more people', $overflow, ['count' => $overflow])"
            :fallback="$overflowLabel"
            :decorative="(bool) $listNames"
            class="{{ $faceBase.' '.$overlap }} font-medium"
        />
    @endif
</div>