Cloaked Design SystemPrimitives

AvatarGroup

An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

9 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { AvatarGroup } from '@cloakedinc/design-system';

AvatarGroupAvatarGroupProps

packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx:50

Prop	Type	Presence	Notes
`avatars`	`AvatarGroupAvatar[]`	Required	Avatars in visual order; the first renders leftmost and on top.
`size`	`AvatarSize`	Required	Size applied to every avatar in the group.
`max`	`number \| undefined`	Optional	Caps rendered avatars; any extras collapse into a trailing "+N" chip.
`surface`	`AvatarGroupSurface \| undefined`	Optional	Background the group sits on, used for the separating ring. Defaults to `surface`.Source default: `'surface'`
`ringColor`	`string \| undefined`	Optional	Overrides the separating ring color for custom backgrounds.
`overflowColor`	`string \| undefined`	Optional	Overrides the overflow avatar background color.
`overflowTextColor`	`string \| undefined`	Optional	Overrides the overflow avatar text color.
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`ariaLabel`	`string \| undefined`	Optional	Accessible label for the avatar cluster.
`testId`	`string \| undefined`	Optional	Selector for the group wrapper. The overflow chip derives `${testId}-overflow`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

An overlapping cluster of Avatars for a "many identities together" pattern: connected accounts, report participants, shared brands. Use a single Avatar when only one identity is shown.

Use when

Each avatar gets a separating ring so the overlap reads cleanly. The ring must match the background behind the group, so set surface to the container it sits on.

max caps the rendered avatars and collapses the rest into a trailing "+N" chip. For a custom, non-token background, override ringColor and overflowColor directly.

Usage by variant

Choice	Use when	Avoid when
`Surface: surface`	The group sits on a raised white Card; the ring is white. The default.
`Surface: page`	The group sits on the cream page feed; the ring matches the page canvas.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: group
Label: Group
Description: Contains the ordered overlapping identity marks.

Id: avatar
Label: Avatar
Description: Reuses Avatar at one shared size for every visible identity.

Id: ring
Label: Separating ring
Description: Matches the host surface so overlapping circles remain distinct.

Id: overflow
Label: Overflow count
Description: Replaces hidden identities with a final +N circle.

Allowed Design Choices

Variants

Base

Label: Base
Description: The group has one overlapping-avatar treatment.

Sizes

Label: Small

Label: Medium

Label: Large

Label: Extra large

Surfaces

Page

Label: Page
Description: Matches the separating ring to the page background.

Surface

Label: Surface
Description: Matches the separating ring to a card or other raised surface.

Variants

Id: base
Label: Base
Description: One overlapping-avatar treatment whose ring follows the selected surface axis.
Platforms: ios
android
web

Sizes

Id: sm
Label: Small
Description: Applies the 24-unit Avatar size to every item.

Id: md
Label: Medium
Description: Applies the 40-unit Avatar size to every item.

Id: lg
Label: Large
Description: Applies the 56-unit Avatar size to every item.

Id: xl
Label: Extra large
Description: Applies the 80-unit Avatar size to every item.

Measurements

Id: separating-ring-width
Label: Separating ring width
Kind: exact
Token: --cds-border-width-emphasis
Value: 2
Unit: px
Applies To: ring
avatar
overflow

Id: overlap
Label: Avatar overlap
Kind: exact
Value: 22
Unit: %
Applies To: avatar
overflow
Notes: Each item after the first shifts left by 22% of the selected Avatar size.

Layout

Alignment: All circles share a center line and one selected diameter.
Flow: Items overlap horizontally; the first identity remains visually on top.
Notes: The group isolates its stacking order from surrounding content.
The overflow count occupies the same circle geometry as an Avatar.

Typography And Color

Typography

Label: Overflow count
Description: The +N count uses the body-small text ramp.
Token: --cds-type-body-small-size

Colors

Label: Page ring
Description: Separates overlapping circles on the page canvas.
Token: --cds-bg-page

Label: Surface ring
Description: Separates overlapping circles on a raised surface.
Token: --cds-bg-surface

Label: Overflow text
Description: Uses secondary text emphasis for the collapsed count.
Token: --cds-text-secondary

States

Id: complete
Label: Complete
Description: Shows every provided Avatar when no maximum truncates the group.

Id: overflow
Label: Overflow
Description: Shows the first maximum identities followed by the hidden-count circle.

Id: empty
Label: Empty
Description: Renders an empty group when no identities are supplied.

Behavior

Label: Ordering
Description: Preserve source order and keep the first identity leftmost and on top.

Label: Maximum
Description: Collapse only identities after the configured maximum into the +N count.

Accessibility

Label: Cluster label
Description: Provide one accessible group label when the identities have collective meaning.

Label: Identity labels
Description: Keep meaningful Avatar alt text or labels; decorative marks may remain unnamed.

Content Adaptation

Label: Large sets
Description: Use a maximum to keep dense groups readable and expose the remaining count.

Label: Custom backgrounds
Description: Override the ring role only when neither page nor surface matches the host background.

Motion Haptics

Motion

Label: Image loading
Description: Each image Avatar keeps its own loading and reduced-motion behavior.

Haptics

Label: No feedback
Description: The group is not interactive and does not request haptic feedback.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1