---

## AvatarGroup
Stacks avatars into an overlapping row with an optional "+N" overflow chip —
the canonical way to show a set of collaborators, assignees or participants compactly.
Data-driven: pass an `items` array of Avatar props; the group propagates a shared `size`
and a cut-out ring so the stack reads cleanly on any surface.

**Import:** `import { AvatarGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<AvatarGroup items={[{ name: 'Ada Lovelace' }, { name: 'Alan Turing' }]} />
```

```svelte
<AvatarGroup items={team} max={4} size="lg" />
```

### Variants
- spacing: loose, normal, tight (default: normal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `AvatarProps[]` | yes |  | The avatars to stack. Each entry is a full set of Avatar props (src, name, status, …). |
| ...AvatarGroupVariants | `VariantProps` | no |  | Styling variants from AvatarGroupVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| borderColor | `string` | no | 'var(--color-surface-base)' | Ring colour drawn around each avatar so the overlap reads as a cut-out. Any CSS colour; defaults to the base surface so the stack looks punched out of the page. |
| class | `string` | no |  | Additional CSS class merged onto the root row. |
| max | `number` | no |  | Maximum avatars to render. When `items` exceeds it, `max - 1` avatars are shown plus a single "+N" overflow chip — where N is the count of hidden avatars — so the total rendered count is exactly `max`. Unset (or `0`/negative) shows every avatar with no chip; use `≥ 2` so the chip sits alongside at least one visible face. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ AvatarGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic palette. |
| size | `AvatarProps['size']` | no |  | Shared size applied to every avatar and the overflow chip — xs, sm, md (default), lg, xl, 2xl. |
| slotClasses | `Partial<Record<AvatarGroupSlots, string>>` | no |  | Per-slot class overrides. Slots: base | overflow |
| spacing | `'tight' | 'normal' | 'loose'` | no |  | Overlap amount between avatars — tight, normal (default), loose. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with slotClasses to rebuild from scratch. |

Inherited from:
- AvatarGroupVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
type MintProp = | string
  | { name: string; config?: MintConfig & Record<string, unknown> }
  | Array<string>
  | Array<string | { name: string; config?: MintConfig & Record<string, unknown> }>
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface MintConfig {
trigger?: 'hover' | 'click' | 'focus' | 'load';
  duration?: number;
  delay?: number;
  easing?: string;
  disabled?: boolean;
}
```

### Slots (slotClasses keys)
`base`, `overflow`