Avatar Group

Data displaySince 0.9.0

import { AvatarGroup } from '@absoluteui/components/avatar-group';
import '@absoluteui/components/avatar/style.css';

Using Angular? See Avatar Group for Angular.

What it does

A row of overlapping avatars for the people on a record, with the overflow collapsed into “+N”. AvatarGroup is a named group: each avatar is named by its person (see Avatar), and the overflow chip is announced as “N more”. Size and shape follow the Avatar configuration unless set on the group.

When to use

• Members, assignees, or viewers of a record, project, or document.
• Compact presence of several people in a header or card.

When not to use

• One person: use Avatar.
• A list the user must read in full or act on: use a list or a table.

Examples

Project members with overflow

import { AvatarGroup } from '@absoluteui/components/avatar-group';

const host = document.createElement('div');
document.body.append(host);
AvatarGroup.create(host, {
  label: 'Project members',
  items: [
    { name: 'Ada Lovelace', status: 'online' },
    { name: 'Grace Hopper' },
    { name: 'Alan Turing', status: 'away' },
    { name: 'Barbara Liskov' },
    { name: 'Edsger Dijkstra' },
    { name: 'Donald Knuth' },
  ],
  max: 4,
});

Usage

import { AvatarGroup } from '@absoluteui/components/avatar-group';
import '@absoluteui/components/avatar/style.css';
import '@absoluteui/components/avatar-group/style.css';

const host = document.querySelector<HTMLElement>('#reviewers');
if (host) AvatarGroup.create(host, { label: 'Reviewers', items: [{ name: 'Barbara Liskov' }, { name: 'Donald Knuth' }], size: 'sm' });

More usage

import { AvatarGroup } from '@absoluteui/components/avatar-group';

const host = document.querySelector<HTMLElement>('#watchers');
if (host) {
  const group = AvatarGroup.create(host, { label: 'Watchers', items: [{ name: 'Ada Lovelace' }, { name: 'Grace Hopper' }], max: 3 });
  group.update({ items: [...group.options.items, { name: 'Alan Turing', status: 'online' }] });
}

Anatomy

<div class="aui-avatar-group" role="group" aria-label="Project members">
  <span class="aui-avatar ..." role="img" aria-label="Ada Lovelace">...</span>     (up to max)
  <span class="aui-avatar aui-avatar-group__more" role="img" aria-label="2 more">
    <span class="aui-avatar__visual" aria-hidden="true">+2</span>
  </span>
</div>

API reference

Factory

AvatarGroup.create(host: HTMLElement, options: AvatarGroupOptions): AvatarGroup

Global configuration key: avatarGroup (see Configuration).

Options

Option	Type	Default	Description
label	string		Accessible name of the group, such as ‘Project members’. Required.
items	readonly AvatarGroupItem[]		People: { name, src?, icon?, status? }. Required.
max	number	"4"	Avatars shown before the ‘+N’ chip (1 to 50). Globally configurable.
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'		Avatar size (default: Avatar configuration).
shape	'circle' | 'square'		Avatar shape (default: Avatar configuration).
locale	string	"en-US"	Locale of the overflow count and label. Globally configurable. Inherited from common configuration.

Properties

Property	Type	Description
host	HTMLElement	The host element (role=group).
overflow	number	Number of people behind the ‘+N’ chip.
options	Readonly<AvatarGroupOptions>	Current options.

Methods

Method	Description
update(options: Partial<AvatarGroupOptions>): void	Merge and apply options; an invalid item leaves the previous rendering intact.
destroy(): void	Destroy the avatars and remove rendering, attributes, classes, and subscriptions.

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-avatar-group	Host (role=group).
aui-avatar-group__more	The ‘+N’ overflow chip (an aui-avatar sized like the others).

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-border-width | --aui-color-border-strong | --aui-color-surface | --aui-color-text

TypeScript definitions

interface AvatarGroupConfig { max: number }
interface AvatarGroupItem { name: string; src?: string | null; icon?: IconRef | null; status?: AvatarStatus | null }
interface AvatarGroupOptions extends Partial<AvatarGroupConfig> {
  label: string;
  items: readonly AvatarGroupItem[];
  size?: AvatarSize;
  shape?: AvatarShape;
  locale?: string;
}

Accessibility

Pattern: Named group of images: role=group with aria-label; each avatar is role=img named by its person; the overflow chip is role=img named ‘N more’.

Keyboard

Key	Context	Action
None	Any	Not focusable; read in document order by assistive technology.

Roles

Element	Role
host	group
avatar	img
overflow chip	img

ARIA attributes

Attribute	Element	Value
aria-label	host	the label option
aria-label	overflow chip	‘{count} more’ (localized)

Focus

Never receives or moves focus.

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.1.1 Non-text Content	A
1.3.1 Info and Relationships	A
1.4.3 Contrast (Minimum)	AA
1.4.11 Non-text Contrast	AA

Automated test results: Accessibility and compliance.

Notes and known caveats

• The overflow chip says how many people are not shown; provide the full list elsewhere when users need the names.
• Manual screen-reader verification (NVDA, JAWS, VoiceOver) is pending.

Behavior

States

Within max (every avatar shown); overflow (max avatars and the “+N” chip).

State transitions

From	Trigger	To
any	update({ items, max })	avatars re-created; chip shown when items exceed max
any	Avatar or Avatar Group configuration change	re-rendered with the new size, shape, max, or locale
any	destroy()	host restored to empty

Accessibility notes

• The chip says how many people are not shown, not who they are. Provide the full list elsewhere (for example in a dialog opened by a nearby button) when users need the names.
• The e2e axe run covers three themes; manual screen-reader verification is pending.

Responsive behavior

An inline row in which avatars overlap by a quarter of their size; it does not wrap. Lower max for narrow containers.

Right-to-left

Order and overlap follow the inline direction.

Theming

Avatar tokens apply to every avatar. Forced-colors mode removes the surface rings; each avatar draws a CanvasText boundary.

Global configuration

configureAbsoluteUI({ components: { avatarGroup: { max: 3 }, avatar: { size: 'sm' } } });

Component configuration

Instance max, size, shape, and locale override configuration; configuration changes re-render existing groups.

Icons

Per item icon, as in Avatar.

Security

Every item is validated as Avatar options: unsafe image sources throw AVATAR_OPTIONS. Names and counts are rendered with textContent.

Data handling

Only the avatars’ image elements load their src, without a referrer. No persistence, other network access, or telemetry.

Performance

At most max avatars are created per render; the rest are counted.

Supported data scale

Up to 10,000 items are accepted; up to 50 avatars are rendered.

Edge cases

• An empty items array renders an empty group.
• When items exceed max, exactly max avatars are shown, followed by the chip.
• Safe in renderers that discard nodes without calling destroy(), such as Data Table cells: the configuration subscription holds the instance weakly, so a discarded group is released.

Errors

Code	Category	Cause
AVATAR_GROUP_OPTIONS	configuration	Missing or blank label, or items that are not an array (or more than 10,000).
AVATAR_OPTIONS	configuration	An invalid item (blank name, unsafe src, unknown status).
CFG_INVALID_VALUE / CFG_UNKNOWN_OPTION	configuration	Invalid max, size, shape, or locale configuration.

Invalid options throw before the host is modified; an invalid update() leaves the previous rendering intact.

Known limitations

• The people behind “+N” are not listed.
• Every update re-creates the shown avatars.

Unsupported scenarios

• Clickable avatars or chip: put a button next to the group that opens the full list.
• Wrapping onto several lines.