AvatarGroup

Stacks avatars into an overlapping row for a set of collaborators, assignees, or participants, with a “+N” chip once the count passes max. Pass an items array of Avatar props; a shared size and the cut-out ring apply to every avatar.

Playground

Max

Spacing

Size

<script lang="ts">
  import { AvatarGroup } from '@urbicon-ui/blocks';

  const items = [
    { name: 'Ada Lovelace', status: 'online' },
    { name: 'Alan Turing', initials: 'AT' },
    { name: 'Grace Hopper', randomColor: true, status: 'busy' },
    { name: 'Katherine Johnson', randomColor: true },
    { name: 'Edsger Dijkstra' },
    { name: 'Barbara Liskov' }
  ];
</script>

<AvatarGroup
  {items}
  max={4}
  size="md"
/>

01 Examples

Basic stack

Pass an items array of Avatar props. Each entry becomes an avatar, overlapped with a cut-out ring so the set reads as one unit.

<AvatarGroup
  items={[
    { name: 'Ada Lovelace' },
    { name: 'Alan Turing' },
    { name: 'Grace Hopper' },
    { name: 'Katherine Johnson' }
  ]}
/>

Overflow — max

When items exceeds max, the group renders max − 1 avatars plus a single “+N” chip, so the total rendered count is exactly max. Here six people cap to four slots.

<AvatarGroup items={team} max={4} />

Sizes

size applies to every avatar and the overflow chip alike. Available: xs, sm, md (default), lg, xl, 2xl.

{#each ['sm', 'md', 'lg', 'xl'] as size}
  <AvatarGroup items={team} max={4} {size} />
{/each}

02 Appearance

Spacing

spacing controls the overlap: tight packs the stack, loose spreads it out, normal is the default.

tight

normal

loose

{#each ['tight', 'normal', 'loose'] as spacing}
  <AvatarGroup items={team} max={4} {spacing} />
{/each}

Identity colours

Set randomColor on an item to derive its background colour from its name; the same name always maps to the same colour, so people without a photo stay distinct. An item with a src shows that photo instead, with the same cut-out ring; the others keep their initials.

<AvatarGroup
  items={[
    { name: 'Ada Lovelace', randomColor: true },
    { name: 'Alan Turing', randomColor: true },
    { name: 'Grace Hopper', randomColor: true },
    { name: 'Barbara Liskov', randomColor: true }
  ]}
/>

03 Accessibility

Group semantics

The stack is a role="group" with a localized aria-label (“User avatars” by default). Override it with your own aria-label to name the specific set: “Project collaborators”, “Assignees”.

Per-avatar naming

Each avatar shows its initials (or photo) from name / src; the group's aria-label gives the whole set its context for assistive tech.

The overflow chip is announced

The +N overflow chip carries its own aria-label (+2, +9), so the hidden count is announced.

The overlap ring is decorative

The overlap ring uses borderColor (default: the background behind it). It is decorative; set it to match the background the group sits on so the cut-out effect holds.

04 API Reference

11 props

11 props 1 required

Prop	Type	Default	Description
`items` required	`AvatarProps[]`	—	The avatars to stack. Each entry is a full set of Avatar props (src, name, status, …).
`borderColor`	`string`	`'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 background so the stack looks punched out of the page.
`class`	`string`	—	Additional CSS class merged onto the root row.
`max`	`number`	—	Maximum avatars to render. When `items` exceeds it, `max - 1` avatars are shown plus a single "+N" overflow chip (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`	—	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']`	—	Shared size applied to every avatar and the overflow chip. One of xs, sm, md (default), lg, xl, 2xl.
`slotClasses`	`Partial<Record<AvatarGroupSlots, string>>`	—	Per-slot class overrides. Slots: base \| overflow
`spacing`	tightnormalloose	—	Overlap amount between avatars: tight, normal (default), loose.
`unstyled`	`boolean`	—	Strip all default styles; combine with slotClasses to rebuild from scratch.
`...AvatarGroupVariants` variant	`VariantProps`	—	Styling variants from AvatarGroupVariants
`...HTMLAttributes<HTMLDivElement>` inherited	`HTMLAttributes`	—	HTML attributes (excluding: 'children' \| 'class')

05 Types

Local type definitions used by this component.

10 types

Only referenced

Name	Kind	Category	Used by	Description
AvatarGroupProps	interface	props	0	—
AvatarProps	interface	props	1	—
AvatarGroupSlots	type	variant	0	Slot names derived from the `tv()` config above — single source of truth for `slotClasses`.
AvatarGroupVariants	type	variant	1	—
MintProp	type	helper	0	—
AvatarSlots	type	variant	0	Slot names derived from the tv() config — single source of truth for slotClasses.
SlotNames	type	helper	0	Extracts the slot-name union from a slotted `tv()` config function — the companion to `VariantProps`. The slot-mode overload returns `(props?) => { [K in keyof S]: SlotFn }`, so `keyof ReturnType<T>` is exactly the set of slot names a component declares in `tv({ slots: … })`. Use it to type a component's `slotClasses` prop from the single source of truth (its `*.variants.ts`) instead of hand-maintaining a parallel union that silently drifts when a slot is added or renamed:
VariantProps	type	helper	1	—
MintName	type	helper	0	A mint name: a built-in (autocompleted), `'none'` to disable, or any consumer-registered name. `(string & {})` keeps the registry open — a custom name still type-checks, it just isn't suggested. A typo therefore also still compiles (it resolves like an unregistered custom name and warns at runtime); the union buys completion and docs, not validation.
MintConfig	interface	helper	0	—

06 Installation

Import

import { AvatarGroup } from '@urbicon-ui/blocks';

llm.txt