Avatar Group

Headless avatar stack with a bounded tile count and an accessible overflow tile.


Package	`@vizejs/ui/avatar-group`
Maturity	stable
Own the source	`vize lib pull avatar-group`
Requires	avatar
Aliases	avatar group, avatar stack, facepile, people list
Covers	Chakra UI AvatarGroup, MUI AvatarGroup, Mantine Avatar.Group

Usage

import { AvatarGroup, AvatarGroupOverflow } from "@vizejs/ui/avatar-group";

Or copy the source into your project with vize lib pull avatar-group (see Source Distribution).

API

`AvatarGroup<Item>`

Source: src/families/layout/avatar-group/avatar-group.vue

Props

Prop	Type	Default	Description
`items` (required)	`readonly Item[]`	`required`	People rendered as avatar tiles, in order.
`max`	`number`	`undefined`	Maximum number of tiles, including the overflow tile. `undefined` never collapses.
`total`	`number`	`undefined`	Total number of people when `items` is a page of a larger set; the remainder joins the overflow count.
`spacing`	`number \| string`	`undefined`	Overlap or gap published as `--vize-ui-avatar-group-spacing`. Numbers are pixels.
`messages`	`AvatarGroupMessageOverrides \| undefined`	`undefined`	Localized overflow strings.
`ariaLabel`	`string`	`undefined`	Accessible list name, e.g. "Project members".
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the list.

Slots

Slot	Slot props	Description
`item`	`AvatarGroupItemSlotState<Item>`	Renders one visible person, typically an `Avatar`.
`overflow`	`AvatarGroupOverflowSlotState<Item>`	Replaces the default overflow tile. Receives the hidden items and count.

Exposed

Member	Type	Description
`visibleItems`	`readonly Item[]`	Items rendered as tiles.
`hiddenItems`	`readonly Item[]`	Items collapsed into the overflow tile.
`overflowCount`	`number`	Hidden count including any `total` remainder.
`state`	`AvatarGroupState`	Stable state token.
`element`	`HTMLUListElement \| null`	Rendered list element.

`AvatarGroupOverflow<Item>`

Source: src/families/layout/avatar-group/avatar-group-overflow.vue

Props

Prop	Type	Default	Description
`count` (required)	`number`	`required`	Number of hidden people announced by the tile.
`items`	`readonly Item[]`	`undefined`	Hidden items forwarded to the slot, e.g. for a tooltip listing names.
`messages`	`AvatarGroupMessageOverrides \| undefined`	`undefined`	Localized overflow strings.

Slots

Slot	Slot props	Description
`default`	`AvatarGroupOverflowSlotState<Item>`	Overflow tile content. Defaults to the `overflowText` message, e.g. "+3".

Exposed

Member	Type	Description
`element`	`HTMLSpanElement \| null`	Rendered overflow element.
`count`	`number`	Hidden count announced by the tile.

Behavior

Normative state x input -> outcome table for avatar-group.vue and avatar-group-overflow.vue (@vizejs/ui/avatar-group). Every row is proven by the named test.

AvatarGroup renders a native <ul> of <li> tiles. The item slot renders each visible person (typically an Avatar). max bounds every tile, including the overflow tile. The overflow tile is role="img" with an accessible "N more" name, and it wraps an aria-hidden Avatar showing "+N".

ID	State	Input	Outcome	Evidence
AG1	no `max`	render	a labelled list renders every item through the `item` slot, `data-state="expanded"`, and no overflow tile	`renders a labelled list of avatars without collapsing by default`
AG2	`max` exceeded	render	`max - 1` items plus one overflow tile render; the tile is `role="img"` named "N more" showing "+N"	`max counts the overflow tile and announces hidden people`
AG3	`total`	render	people beyond `items` join the overflow count, with or without `max`	`total adds server-side people to the overflow count`
AG4	messages/spacing	render	overflow name and text come from typed `messages`; `spacing` publishes `--vize-ui-avatar-group-spacing`	`localized messages, spacing, and empty groups`
AG5	empty	render	`data-state="empty"` and no tiles	`localized messages, spacing, and empty groups`
AG6	custom overflow	`overflow` slot	the slot receives typed hidden items, count, label, and text	`the overflow slot receives hidden items for custom tiles`
AG7	reactive props	`max`/`items` change	the split re-computes; the instance exposes state, visible/hidden items, overflow count, and element	`items and max are reactive and the instance exposes the split`
AG8	pure helpers	`splitAvatarGroup()` etc.	invalid `max`/`total` never collapse; spacing rejects declaration injection	`splits groups, resolves messages, and sanitizes spacing`
AG9	SSR	isolated requests	markup is byte-identical	`renders byte-identical avatar group markup across isolated SSR requests`
AG10	SSR / hydration	hydrate	server markup hydrates without warnings or node replacement	`hydrates avatar group markup without warnings or node replacement`
AG11	types	compile	item types flow from `items` into slots and exposes; states and messages are closed	`avatar-group.types.test-d.ts`