# AvatarGroup
An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count.
Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx
## Guidance
{
"summary": "An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count.",
"guidance": [
{
"heading": "Overview",
"body": "An overlapping cluster of `Avatar`s for a \"many identities together\" pattern: connected\naccounts, report participants, shared brands. Use a single `Avatar` when only one identity\nis shown."
},
{
"heading": "Use when",
"body": "Each avatar gets a separating ring so the overlap reads cleanly. The ring must match the\nbackground behind the group, so set `surface` to the container it sits on.\n\n`max` caps the rendered avatars and collapses the rest into a trailing \"+N\" chip. For a\ncustom, non-token background, override `ringColor` and `overflowColor` directly."
}
],
"usage": [
{
"variant": "surface",
"use": "The group sits on a raised white Card; the ring is white. The default.",
"axis": "Surface"
},
{
"variant": "page",
"use": "The group sits on the cream page feed; the ring matches the page canvas.",
"axis": "Surface"
}
],
"examples": [],
"source": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.mdx",
"status": "local-preview",
"note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}
## Contract and public API
```json
{
"props": [
{
"name": "avatars",
"type": "AvatarGroupAvatar[]",
"declared_type": "AvatarGroupAvatar[]",
"required": true,
"description": "Avatars in visual order; the first renders leftmost and on top.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 26
}
},
{
"name": "size",
"type": "AvatarSize",
"declared_type": "AvatarSize",
"required": true,
"description": "Size applied to every avatar in the group.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 28
},
"values": [
"lg",
"md",
"sm",
"xl"
],
"values_complete": true
},
{
"name": "max",
"type": "number | undefined",
"declared_type": "number",
"required": false,
"description": "Caps rendered avatars; any extras collapse into a trailing \"+N\" chip.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 30
}
},
{
"name": "surface",
"type": "AvatarGroupSurface | undefined",
"declared_type": "AvatarGroupSurface",
"required": false,
"description": "Background the group sits on, used for the separating ring. Defaults to `surface`.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 32
},
"values": [
"page",
"surface"
],
"values_complete": true,
"default": "'surface'",
"default_kind": "source-expression"
},
{
"name": "ringColor",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Overrides the separating ring color for custom backgrounds.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 34
}
},
{
"name": "overflowColor",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Overrides the overflow avatar background color.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 36
}
},
{
"name": "overflowTextColor",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Overrides the overflow avatar text color.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 38
}
},
{
"name": "className",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 39
}
},
{
"name": "style",
"type": "React.CSSProperties | undefined",
"declared_type": "React.CSSProperties",
"required": false,
"description": "",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 40
}
},
{
"name": "ariaLabel",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Accessible label for the avatar cluster.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 42
}
},
{
"name": "testId",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Selector for the group wrapper. The overflow chip derives `${testId}-overflow`.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 44
}
}
],
"prop_shapes": {},
"api": {
"method": "typescript-type-checker",
"typescript_version": "5.9.3",
"public_export": "AvatarGroup",
"public_path": "AvatarGroup",
"import_path": "@cloakedinc/design-system",
"root_kind": "component",
"entrypoints": [
{
"name": "AvatarGroup",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 50
},
"props_type": "AvatarGroupProps",
"props": [
{
"name": "avatars",
"type": "AvatarGroupAvatar[]",
"declared_type": "AvatarGroupAvatar[]",
"required": true,
"description": "Avatars in visual order; the first renders leftmost and on top.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 26
}
},
{
"name": "size",
"type": "AvatarSize",
"declared_type": "AvatarSize",
"required": true,
"description": "Size applied to every avatar in the group.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 28
},
"values": [
"lg",
"md",
"sm",
"xl"
],
"values_complete": true
},
{
"name": "max",
"type": "number | undefined",
"declared_type": "number",
"required": false,
"description": "Caps rendered avatars; any extras collapse into a trailing \"+N\" chip.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 30
}
},
{
"name": "surface",
"type": "AvatarGroupSurface | undefined",
"declared_type": "AvatarGroupSurface",
"required": false,
"description": "Background the group sits on, used for the separating ring. Defaults to `surface`.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 32
},
"values": [
"page",
"surface"
],
"values_complete": true,
"default": "'surface'",
"default_kind": "source-expression"
},
{
"name": "ringColor",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Overrides the separating ring color for custom backgrounds.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 34
}
},
{
"name": "overflowColor",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Overrides the overflow avatar background color.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 36
}
},
{
"name": "overflowTextColor",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Overrides the overflow avatar text color.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 38
}
},
{
"name": "className",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 39
}
},
{
"name": "style",
"type": "React.CSSProperties | undefined",
"declared_type": "React.CSSProperties",
"required": false,
"description": "",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 40
}
},
{
"name": "ariaLabel",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Accessible label for the avatar cluster.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 42
}
},
{
"name": "testId",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Selector for the group wrapper. The overflow chip derives `${testId}-overflow`.",
"source": {
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 44
}
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
}
],
"type_sources": [
{
"path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx",
"line": 6,
"name": "AvatarType",
"code": "export type AvatarType = 'icon' | 'initials' | 'brand' | 'image';"
},
{
"path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx",
"line": 8,
"name": "AvatarSize",
"code": "export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';"
},
{
"path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx",
"line": 10,
"name": "AvatarBrandFrame",
"code": "export type AvatarBrandFrame = 'ring' | 'none';"
},
{
"path": "packages/design-system/src/components/primitives/Avatar/Avatar.tsx",
"line": 16,
"name": "AvatarProps",
"code": "export interface AvatarProps {\n /**\n * Which avatar is rendered. `brand` insets the mark and contains it inside the circle; `image`\n * crops to fill. `icon` and `initials` take `icon`/`initial` instead of `src`.\n */\n type: AvatarType;\n /** Named size, mapped to the sizing token scale. */\n size: AvatarSize;\n /** Rendered as-is for `type='icon'`. The avatar sets no size on it, so size the node yourself. */\n icon?: React.ReactNode;\n /**\n * Initials text for `type='initials'`, and what a `brand`/`image` avatar renders once no source\n * can be shown — omit it and those render nothing. Uppercased by CSS.\n */\n initial?: string;\n /** Background color for initials avatars. */\n color?: string;\n /** Initials text color. Defaults to `--cds-text-on-bold`. */\n initialTextColor?: string;\n /**\n * Edge treatment for `brand` avatars. Use `none` only for a mark you ship and have looked at;\n * a runtime-resolved mark has an unknowable silhouette, so it keeps the ring.\n */\n brandFrame?: AvatarBrandFrame;\n /** Image source for `brand` and `image` avatars. */\n src?: string;\n /** Secondary image tried before initials when the primary source is unavailable. */\n fallbackSrc?: string;\n /** Minimum loaded image dimension before falling back to initials. */\n minImageNaturalWidth?: number;\n /** Minimum loaded fallback image dimension before falling back to initials. */\n fallbackMinImageNaturalWidth?: number;\n /** Maximum loaded image aspect ratio (longer / shorter side) before falling back; rejects wide wordmarks. */\n maxImageAspectRatio?: number;\n /** Maximum loaded fallback image aspect ratio before falling back to initials. */\n fallbackMaxImageAspectRatio?: number;\n /** Accessible image description. */\n alt?: string;\n /** Accessible label for non-image avatars. */\n ariaLabel?: string;\n /** Class hook for composite styling. Applied to the avatar root for every type. */\n className?: string;\n /** Class applied only to the `![]()
` of `brand`/`image` avatars (never the initials fallback). */\n imageClassName?: string;\n style?: React.CSSProperties;\n /** Optional test selector. Applied to the avatar root, including a standing-in initials element. */\n testId?: string;\n}"
},
{
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 8,
"name": "AvatarGroupSurface",
"code": "export type AvatarGroupSurface = 'page' | 'surface';"
},
{
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 9,
"name": "AvatarGroupAvatar",
"code": "export type AvatarGroupAvatar = Omit;"
},
{
"path": "packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.tsx",
"line": 24,
"name": "AvatarGroupProps",
"code": "export interface AvatarGroupProps {\n /** Avatars in visual order; the first renders leftmost and on top. */\n avatars: AvatarGroupAvatar[];\n /** Size applied to every avatar in the group. */\n size: AvatarSize;\n /** Caps rendered avatars; any extras collapse into a trailing \"+N\" chip. */\n max?: number;\n /** Background the group sits on, used for the separating ring. Defaults to `surface`. */\n surface?: AvatarGroupSurface;\n /** Overrides the separating ring color for custom backgrounds. */\n ringColor?: string;\n /** Overrides the overflow avatar background color. */\n overflowColor?: string;\n /** Overrides the overflow avatar text color. */\n overflowTextColor?: string;\n className?: string;\n style?: React.CSSProperties;\n /** Accessible label for the avatar cluster. */\n ariaLabel?: string;\n /** Selector for the group wrapper. The overflow chip derives `${testId}-overflow`. */\n testId?: string;\n}"
}
],
"defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
},
"spec": {
"$schema": "../../../specs/component-spec.schema.json",
"identity": {
"name": "AvatarGroup",
"status": "preview",
"version": "1.0.0",
"summary": "An overlapping cluster of same-size identity marks with a surface-matched separating ring and optional overflow count."
},
"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."
}
],
"allowedDesignChoices": {
"variants": {
"base": {
"label": "Base",
"description": "The group has one overlapping-avatar treatment."
}
},
"sizes": {
"sm": {
"label": "Small"
},
"md": {
"label": "Medium"
},
"lg": {
"label": "Large"
},
"xl": {
"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",
"appliesTo": [
"ring",
"avatar",
"overflow"
]
},
{
"id": "overlap",
"label": "Avatar overlap",
"kind": "exact",
"value": 22,
"unit": "%",
"appliesTo": [
"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."
]
},
"typographyAndColor": {
"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."
}
],
"contentAdaptation": [
{
"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."
}
],
"motionHaptics": {
"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."
}
]
},
"platformDifferences": []
},
"platforms": {
"implemented": [
"web"
],
"native": "Imported design guidance only; no native implementation or parity verification in this preview.",
"react": {
"implementation": "local",
"status": "preview",
"parity": "web-reference"
},
"vue": {
"implementation": "absent",
"parity": "not-verified",
"status": "reference-only"
},
"swift": {
"implementation": "absent",
"parity": "not-verified",
"status": "reference-only"
},
"kotlin": {
"implementation": "absent",
"parity": "not-verified",
"status": "reference-only"
}
},
"tokens": [
{
"name": "--cds-border-width-emphasis",
"light": "2px",
"dark": "2px"
},
{
"name": "--cds-type-body-small-size",
"light": "0.875rem",
"dark": "0.875rem"
},
{
"name": "--cds-bg-page",
"light": "#f3f1ed",
"dark": "#141410"
},
{
"name": "--cds-bg-surface",
"light": "#ffffff",
"dark": "#1b1b18"
},
{
"name": "--cds-text-secondary",
"light": "#646260",
"dark": "#ffffff99"
}
],
"review": {
"local_status": "not-reviewed",
"source_approval": null,
"imported_spec_status": "approved",
"spec_origin": "imported-adapted",
"local_spec_source_status": "approved",
"imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
"note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
},
"missing_facts": [
{
"code": "human-review-pending",
"detail": "This local preview has no recorded human design or engineering sign-off."
},
{
"code": "platform-parity-unverified",
"detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
},
{
"code": "figma-mapping-unverified",
"detail": "No current component-level Figma node and immutable revision have been verified for this contract."
}
]
}
```
## Visual states
- [Playground](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [Brands](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--brands&viewMode=story) | export: Brands | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [People](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--people&viewMode=story) | export: People | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [Overflow](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--overflow&viewMode=story) | export: Overflow | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [On Page](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--on-page&viewMode=story) | export: OnPage | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [Custom Background](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--custom-background&viewMode=story) | export: CustomBackground | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [Styled And Labeled](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--styled-and-labeled&viewMode=story) | export: StyledAndLabeled | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [Sizes](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--sizes&viewMode=story) | export: Sizes | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-primitives-avatargroup--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/primitives/AvatarGroup/AvatarGroup.stories.tsx
Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.