An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:AvatarGroupOverflow authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-26 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/AvatarGroup/AvatarGroupOverflow.test.tsx, packages/core/src/AvatarGroup/AvatarGroup.test.tsx, packages/core/src/theme/themingTargets.test.ts, apps/storybook/rtl-audit/targets.json, apps/storybook/stories/AvatarGroupOverflow.stories.tsx, ] modules: [] families: [] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:internationalization, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-002, spec:AST-009, spec:AST-038]
AvatarGroupOverflow component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | An overflow indicator with a required count, optional onClick, and optional custom children that replace the visible "+N". |
| Behavior | Without onClick it is a named image; with onClick it is a native button in the group's roving set. Its name is the translated count unless a caller aria-labelledby names it. |
| End-user impact | Screen-reader users hear how many people are hidden ("5 more"); keyboard users reach a clickable indicator as the last item in the group. |
| Builder impact | None; the record describes shipped behavior. |
| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact. |
| Review checks | Reject a negative displayed count, a name taken from custom children, a static indicator in the roving set, or an indicator that ignores the group's size or shape. |
| Governing rules | architecture:public-component-api/INV5,INV6,INV8; architecture:component-theming-surface/INV2,INV6; architecture:internationalization/INV1a. |
This table is a review projection; the body below is authoritative.
Intent
AvatarGroupOverflow tells the reader how many members an AvatarGroup does not show, and optionally lets them open the rest. It owns the indicator's count label, its static and button forms, and its geometry within the group.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public prop, default, DOM, accessibility, target, or styling output changes
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Default count outside the catalog (FR2). The visible "+N" is assembled
from the raw number, so it is never locale-formatted: the chip shows "+4912"
where the name reads "4,912 more", and under a locale with its own digits the
digits differ as well (
architecture:internationalizationINV1a). - Overflow button target (AR4). In a 16px group the clickable indicator is 20px tall, below the 24 by 24 CSS pixels of WCAG 2.2 2.5.8.
Ownership boundary
Owns
- The indicator element and its
avatar-group-overflowtarget. - The default visible "+N" content and the translated count name.
- The static image and native button forms.
- The medium, circle, no-overlap presentation used outside an AvatarGroup.
Does not own / non-goals
- Choosing visible avatars and computing the hidden count — owned by the product callsite.
- Avatar rendering and theming — owned by
component:Avatar. - The group's name, context, member order, and roving-focus algorithm — owned
by
component:AvatarGroup; a clickable indicator joins through the item marker. - Caller-supplied children beyond placing them in the indicator.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Count | A number supplied by the caller | Drives the translated name and the default "+N". | Both forms; inside or outside a group | Required | component:AvatarGroupOverflow |
Stable | A negative count is shown and named as zero. |
| Display content | default "+N"; caller children | The visible content; the name stays count-derived. | Both forms | "+N" | component:AvatarGroupOverflow |
Stable | — |
| Activation | static; clickable | onClick selects the button form and is called on activation. |
Both inside and outside a group | static | component:AvatarGroupOverflow |
Stable | — |
| Presentation | group-supplied; standalone | Size, shape, and overlap from AvatarGroup, else medium, circle, and no overlap. | All sizes and shapes; both directions | standalone medium circle | component:AvatarGroupOverflow |
Stable | — |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Without onClick the indicator is a span with role="img", which a caller role replaces. With onClick it is a native button type="button" that calls onClick on activation and draws the shared focus-visible outline and the shared hover and pressed overlays. |
Current source and tests |
| FR2 | A negative count is clamped to zero before both the name and the default content are produced. The name is the translated "{count} more" in both forms and replaces a caller aria-label, while a caller aria-labelledby reaches the root and names it instead; caller children replace only the visible "+N". Runtime counts are formatted through the catalog (architecture:internationalization INV1a). Implementation gap: the default "+N" is assembled outside the catalog, so the visible count is never locale-formatted: grouping separators, and in some locales the digits, differ from the name (Current-state impact). |
Current source and tests |
| FR3 | Inside an AvatarGroup in the same layer (spec:AST-038 FR7, FR8) the indicator uses the group's size, shape, numeric size, and overlap; outside one, including in a layer opened from a group, it uses md, circle, and no overlap. |
Current source and tests |
| FR4 | The indicator is at least the avatar size plus a 2px surface-colored border on each side wide, exactly that tall, grows inline for wider content with --spacing-2 inline padding, and takes the group's negative inline-start overlap. It paints the neutral color over the surface with secondary text, body family, medium weight, and a font size of the larger of --text-supporting-size and 35% of the avatar size. Its radius follows the shape. |
Current source, tests, and stories |
| FR5 | The root carries the avatar-group-overflow target reflecting size and shape. Supported DOM, ARIA, data, and event props and ref reach the root; xstyle, className, and style merge in that order after component styles. |
Current source and tests |
| FR6 | The button form carries the data-avatar-item marker, so AvatarGroup includes it in its roving set; the static form carries no marker, and a caller tabIndex on it is forwarded without adding it to that set. |
Current source and AvatarGroup tests |
Allowed variation
- AV1 — Count and content. The count and caller content vary; wider content grows the indicator inline.
- AV2 — Theme paint. A theme may restyle
avatar-group-overflowpersizeandshapewithout moving the target.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Static count | role="img" span named "{count} more", showing "+N"; not a roving item. |
Count, size, shape. |
| Static custom content | Count-derived name; caller content visible. | Content. |
| Clickable | Button named "{count} more"; last roving item when grouped. | Count, content. |
| Negative count | Named and shown as zero. | Caller content. |
| Wide count | Grows inline at the resolved height. | Width. |
| Standalone | md circle with no overlap. |
Count, activation. |
| Right-to-left | Overlap and order follow the document direction. | — |
Transformation and precedence order
- ORD1 — Presentation. AvatarGroup context →
md,circle, no overlap. - ORD2 — Content. Clamp
countat zero → translated name; caller children → else "+N". - ORD3 — Root attributes. Static:
role="img"→ caller props → name → component class and styles. Button:typeandonClick→ caller props → name and item marker → press markers → component class and styles.
Performance and resources
- PR1 — No local resources. The indicator holds no state, listener, observer, or timer of its own. Both forms install the shared document-level press controller on mount; only the button carries its press marker.
Accessibility contract
- AR1 — Count name. Both forms are named by the translated count, never by
custom children; a caller
aria-labelledbyreaches the root and names either form instead, while a calleraria-labelis replaced. - AR2 — Roles. The static form is an image unless the caller supplies a role; the clickable form is a native button with the shared focus-visible outline.
- AR3 — Group participation. Only the clickable form joins AvatarGroup's roving set.
- AR4 — Target size. A clickable indicator's target is at least 24 by 24
CSS pixels or has the spacing WCAG 2.2 2.5.8 allows. From
xsmup the button is at least 24 by 24 and paints above the avatar it overlaps. Implementation gap: in a group sized 16px the button is 20px tall.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Count label | Compact supporting count on a neutral chip matching the avatars. | Current source and docs | Supporting | FR2, FR4, AR1 |
| Button behavior | Native button with shared overlay and focus-visible treatments. | Current source and shared utilities | Supporting action | FR1, FR6, AR2, AR3 |
Theming: the root is the avatar-group-overflow target; the count label
inherits it. The consumer anatomy names no root part, so no anatomy-theming
block is declared.
Family and system relationships
component:AvatarGroupsupplies size, shape, and overlap and owns the roving set the clickable form joins.architecture:component-theming-surfaceowns target qualification and reflection.architecture:public-component-apiowns passthrough, styling composition, and ref rules.spec:AST-002owns admission of any change to this public surface.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR2 | AvatarGroupOverflow.test.tsx render, role, and callback tests |
Static, caller role, clickable | A wrong element, a lost img role or caller role, a missing button, or a lost callback fails. Gap: the button's type="button", its focus outline and hover and pressed overlays have no automated check. |
audit:AvatarGroupOverflow/behavior |
| FR2, AR1, ORD2 | AvatarGroupOverflow.test.tsx count, content, and locale tests |
Zero, negative, large, custom content, localized | A negative count, a wrong default "+N" or name, missing custom content, or an untranslated name fails. Gap: no test asserts the name with custom children, a caller aria-label being replaced, a caller aria-labelledby, or a locale with its own digits; the large-count test asserts the unformatted "+4912" beside "4,912 more", which is the recorded gap. |
audit:AvatarGroupOverflow/behavior |
| FR3, ORD1 | AvatarGroupOverflow.test.tsx size and shape tests |
Grouped; standalone | Lost group size or shape fails. Gap: no test asserts the standalone md, circle, and no-overlap fallback, or the layer clause. |
audit:AvatarGroupOverflow/layout |
| FR4 | AvatarGroup.test.tsx overlap test; AvatarGroupOverflow.stories.tsx |
Grouped, wide count, every shape | A lost overlap margin fails. Gap: the box size, border, inline growth and padding, paint, font-size floor, and radius are visible only in the rendered fixture. | audit:AvatarGroupOverflow/layout |
| FR5, ORD3 | themingTargets.test.ts; AvatarGroupOverflow.test.tsx ref, className, and caller-role tests |
Both forms | Target drift, a lost ref, a dropped className, or caller props that stop reaching the static form or land before its role="img" fail. Gap: no test covers xstyle, style, the button form's passthrough, or the rest of ORD3's order. |
audit:AvatarGroupOverflow/theming |
| FR6, AR3 | AvatarGroup.test.tsx overflow roving test |
Button after an interactive avatar | A button missing from the roving set fails. Gap: no test asserts that the static form carries no marker or that a caller tabIndex on it is forwarded. |
audit:AvatarGroupOverflow/accessibility |
| Right-to-left | apps/storybook/rtl-audit/targets.json entry |
Grouped overflow in both directions | Gap: the audit lists the fixture, but no automated check fails on an unmirrored avatar-to-overflow order. | audit:AvatarGroupOverflow/i18n-rtl |
| PR1 | Source review | Both forms | Gap: no automated check fails if the indicator adds state, a listener, an observer, or a timer of its own. | audit:AvatarGroupOverflow/behavior |
| AR1, AR2 | Accessibility-tree evidence (spec:AST-009 FR3) |
Static and clickable forms | Gap: no accessibility-tree check proves the image or button role and the count name; the unit tests query the DOM. | audit:AvatarGroupOverflow/accessibility |
| AR4 | AvatarGroupOverflow.stories.tsx in a browser |
Clickable indicator in a group | Gap: no automated target-size check; the 16px group is the recorded gap. | audit:AvatarGroupOverflow/accessibility |
Decision log
None recorded. The record describes shipped behavior.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.