Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(AvatarGroup): overflow indicator sizing, first-child overlap, negative count, and doc corrections (#5055)

Cindy Zhang61463fd0878c
diff --git a/.changeset/avatargroup-audit-hardening.md b/.changeset/avatargroup-audit-hardening.md
new file mode 100644
index 0000000000..faae0a468c
--- /dev/null
+++ b/.changeset/avatargroup-audit-hardening.md
@@ -0,0 +1,15 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] AvatarGroup: four defects out of the component audit, three of them in `AvatarGroupOverflow`.
+
+The indicator was `display: flex` on a span, which is a block-level flex container, so the exported component rendered as a full-width bar instead of a circle anywhere outside an `AvatarGroup`: measured 1168px wide in a 1168px parent. It is `inline-flex` now; inside a group nothing changes, because a flex item is blockified either way.
+
+Its label font size was a bare `size * 0.35`, which computes 7px at `xsm` and 8.4px at `sm`. That is under the 12px legibility floor, and the effect is worse than the number suggests: the glyph stroke ends up thinner than a pixel, so it never reaches its own text colour. Decoded from a screenshot, the darkest pixel at `xsm` is `#bebebe` on a `#f0f0f0` field, a contrast of 1.63:1 where 4.5:1 is required. The size now floors at the `--text-supporting-size` role token and scales proportionally above it, so `md` and larger are unchanged.
+
+The indicator also kept its negative overlap margin when it was the first child of a group, hanging 12px outside the group's own box. It now carries the same `:not(:first-child)` guard `Avatar` already had. And a negative `count` rendered the string `+-3` and announced "-3 more"; since the documented shape for the prop is `total - visibleCount`, which goes negative whenever the list is shorter than the slice, it now clamps at zero.
+
+Docs: the guidance told readers to "set max to limit visible avatars", and there is no `max` prop. The API is compositional on purpose, so the consumer slices; the guidance now says that. The keyboard behaviour names the APG roving tabindex technique it implements, and `size` now says that the group's value wins over each child avatar's own `size`, including when the group leaves it at the default.
+
+@cixzhang
diff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.json
index 644230e187..03b3b8b8f1 100644
--- a/.github/a11y-baseline.json
+++ b/.github/a11y-baseline.json
@@ -3,11 +3,6 @@
"version": 1,
"generatedAt": "2026-07-31T09:21:12.717Z",
"entries": [
- {
- "key": "AvatarGroup::Initials Fallback::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
{
"key": "Badge::Status Labels::color-contrast",
"impact": "serious",
diff --git a/apps/storybook/stories/AvatarGroup.stories.tsx b/apps/storybook/stories/AvatarGroup.stories.tsx
index 0a2004f2a1..ad02150ead 100644
--- a/apps/storybook/stories/AvatarGroup.stories.tsx
+++ b/apps/storybook/stories/AvatarGroup.stories.tsx
@@ -31,6 +31,10 @@ const storyStyles = stylex.create({
margin: `0 0 ${spacingVars['--spacing-2']} 0`,
fontFamily: typographyVars['--font-family-body'],
},
+ wrapped: {
+ flexWrap: 'wrap',
+ rowGap: spacingVars['--spacing-2'],
+ },
});
const meta: Meta<typeof AvatarGroup> = {
@@ -41,7 +45,17 @@ const meta: Meta<typeof AvatarGroup> = {
size: {
control: 'select',
options: ['xsm', 'sm', 'md', 'lg', 'xl'],
- description: 'Size applied to all child avatars',
+ description:
+ "Size applied to all child avatars. Wins over each child's own size.",
+ },
+ xstyle: {
+ control: false,
+ description: 'stylex.create() value for layout customization.',
+ },
+ ref: {control: false, description: 'Ref forwarded to the root element.'},
+ 'data-testid': {
+ control: false,
+ description: 'Test selector for automated testing frameworks.',
},
},
};
@@ -298,3 +312,50 @@ export const StaticFacepile: Story = {
</AvatarGroup>
),
};
+
+/**
+ * Right-to-left. The overlap is an inline-margin effect, so it mirrors: the
+ * stack builds from the right and each avatar overlaps the one before it by
+ * the same amount.
+ */
+export const RightToLeft: Story = {
+ globals: {direction: 'rtl'},
+ render: () => (
+ <AvatarGroup size="lg" data-testid="avatar-group-rtl">
+ {USERS.slice(0, 3).map(u => (
+ <Avatar key={u.key} src={u.src} name={u.name} />
+ ))}
+ <AvatarGroupOverflow count={USERS.length - 3} />
+ </AvatarGroup>
+ ),
+};
+
+/**
+ * The overflow indicator on its own, outside any AvatarGroup. It falls back to
+ * the `md` avatar size and stays a circle rather than stretching to its
+ * container.
+ */
+export const StandaloneOverflow: Story = {
+ render: () => <AvatarGroupOverflow count={12} />,
+};
+
+/**
+ * `xstyle` customizes the group's own layout. Here the row wraps instead of
+ * running off the side of a narrow container.
+ */
+export const WrappingLayout: Story = {
+ render: () => (
+ <div style={{width: 220, border: '1px dashed grey', padding: 8}}>
+ <AvatarGroup size="md" xstyle={storyStyles.wrapped}>
+ {Array.from({length: 8}, (_, i) => (
+ <Avatar
+ key={i}
+ name={`User ${i + 1}`}
+ src={`https://i.pravatar.cc/150?img=${i + 1}`}
+ />
+ ))}
+ <AvatarGroupOverflow count={14} />
+ </AvatarGroup>
+ </div>
+ ),
+};
diff --git a/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.doc.mjs b/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.doc.mjs
new file mode 100644
index 0000000000..17ccd6261f
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.doc.mjs
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'AvatarGroup',
+ name: 'AvatarGroup — Interactive',
+ displayName: 'Avatar Group — Interactive',
+ description:
+ 'A facepile whose avatars link to profiles, with an overflow indicator that opens the full member list. The whole group is one Tab stop; arrow keys move between the avatars and the overflow button.',
+ isReady: true,
+ isShowcase: false,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['AvatarGroup', 'Avatar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.tsx b/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.tsx
new file mode 100644
index 0000000000..f4b665c916
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.tsx
@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+
+import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';
+import {Avatar} from '@astryxdesign/core/Avatar';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+const MEMBERS = [
+ {name: 'Alex Daniels', key: 'alex', href: '/team/alex'},
+ {name: 'Ann Smith', key: 'ann', href: '/team/ann'},
+ {name: 'Carol Davis', key: 'carol', href: '/team/carol'},
+];
+
+const TOTAL_MEMBERS = 18;
+
+export default function AvatarGroupInteractive() {
+ return (
+ <Stack direction="vertical" gap={8}>
+ <Stack direction="vertical" gap={3}>
+ <Text type="supporting" color="secondary">
+ Reviewers
+ </Text>
+ <AvatarGroup size="lg" aria-label="Reviewers">
+ {MEMBERS.map(m => (
+ <Avatar key={m.key} name={m.name} href={m.href} />
+ ))}
+ <AvatarGroupOverflow
+ count={TOTAL_MEMBERS - MEMBERS.length}
+ onClick={() => {}}
+ />
+ </AvatarGroup>
+ </Stack>
+ <Stack direction="vertical" gap={3}>
+ <Text type="supporting" color="secondary">
+ Compact, static
+ </Text>
+ <AvatarGroup size="sm" aria-label="Attendees">
+ {MEMBERS.map(m => (
+ <Avatar key={m.key} name={m.name} />
+ ))}
+ <AvatarGroupOverflow count={TOTAL_MEMBERS - MEMBERS.length} />
+ </AvatarGroup>
+ </Stack>
+ </Stack>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupShowcase.doc.mjs b/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupShowcase.doc.mjs
index fb29d484d8..796732ccb5 100644
--- a/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupShowcase.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/AvatarGroup/AvatarGroupShowcase.doc.mjs
@@ -6,7 +6,7 @@ export const doc = {
name: 'AvatarGroup',
displayName: 'Avatar Group',
description:
- 'Overlapping avatar rows with max limit and server-side overflow count. Shows team members in a compact facepile layout.',
+ 'Overlapping avatar rows with a sliced visible set and a server-side overflow count. Shows team members in a compact facepile layout.',
isReady: true,
isShowcase: true,
aspectRatio: 16 / 9,
diff --git a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
index 9b7dd48f4c..73742c0564 100644
--- a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
+++ b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
@@ -11,11 +11,12 @@ export const docs = {
description:
'AvatarGroup displays multiple avatars in an overlapping row with an optional overflow indicator. Uses a compositional API: pass Avatar children directly so each avatar can carry its own props (status dots, click handlers, etc.).',
bestPractices: [
- {guidance: true, description: 'Set max to limit visible avatars when the list is long; 3-5 is typical.'},
+ {guidance: true, description: 'Slice the list yourself and pass only the avatars you want visible; 3-5 is typical. The group renders exactly the children it is given and never slices for you.'},
{guidance: true, description: 'Use AvatarGroupOverflow for custom overflow content like a popover trigger or "add member" button.'},
{guidance: true, description: 'Pass status dots, click handlers, or tooltips directly on each Avatar child.'},
- {guidance: true, description: 'Make avatars interactive with href or onClick to link to profiles. Interactive avatars share a single Tab stop; arrow keys move between them, and the group announces a keyboard hint to assistive tech.'},
+ {guidance: true, description: 'Make avatars interactive with href or onClick to link to profiles. Interactive avatars share a single Tab stop; arrow keys move between them, and the group announces a keyboard hint to assistive tech. This follows the WAI-ARIA APG roving tabindex technique for managing focus in a composite: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex'},
{guidance: false, description: "Don't nest AvatarGroups; use a single group with all avatars."},
+ {guidance: false, description: "Don't set size on the child avatars. The group's size wins over each child's own size prop, including when the group leaves size at its default, so a child's size is silently ignored inside a group."},
],
anatomy: [
{name: 'Avatar children', required: true, description: 'Avatar elements that form the overlapping row. Each can have its own props.'},
@@ -47,7 +48,8 @@ export const docs = {
{
name: 'size',
type: 'AvatarSize',
- description: 'Size applied to all avatars via context.',
+ description:
+ "Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.",
default: "'md'",
},
{
@@ -77,10 +79,11 @@ export const docsZh = {
description:
'AvatarGroup 以重叠排列方式显示多个头像,并可选择显示溢出指示器。使用组合式 API:直接传入 Avatar 子元素,每个头像可携带自己的属性。',
bestPractices: [
- {guidance: true, description: '当列表较长时设置 max 来限制可见头像数量,通常 3-5 个为佳。'},
+ {guidance: true, description: '自行切分列表,只传入需要显示的头像,通常 3-5 个为佳。组件只渲染传入的子元素,不会自动切分。'},
{guidance: true, description: '使用 AvatarGroupOverflow 自定义溢出内容,如弹出触发器或"添加成员"按钮。'},
{guidance: true, description: '直接在每个 Avatar 子元素上传递状态点、点击处理器或工具提示。'},
{guidance: false, description: '不要嵌套 AvatarGroup,使用单个组包含所有头像。'},
+ {guidance: false, description: '不要在子头像上设置 size。分组的 size 会覆盖每个子 Avatar 自身的 size,即使分组使用默认值也是如此。'},
],
},
};
@@ -92,11 +95,12 @@ export const docsDense = {
description:
'Stacked avatar display with overlapping layout. Compositional API: Avatar children with per-avatar props (status dots, clicks). Optional AvatarGroupOverflow slot for custom overflow.',
bestPractices: [
- {guidance: true, description: 'Set max to limit visible avatars (3-5 typical).'},
+ {guidance: true, description: 'Slice the list yourself; pass only visible avatars (3-5 typical). No auto-slicing.'},
{guidance: true, description: 'Use AvatarGroupOverflow for custom overflow (popover, add button).'},
{guidance: true, description: 'Pass status dots / click handlers directly on each Avatar.'},
- {guidance: true, description: 'Interactive avatars (href/onClick) share one Tab stop; arrows rove between them + the overflow button.'},
+ {guidance: true, description: 'Interactive avatars (href/onClick) share one Tab stop; arrows rove between them + the overflow button (APG roving tabindex).'},
{guidance: false, description: "Don't nest AvatarGroups."},
+ {guidance: false, description: "Don't set size on children; the group's size always wins, default included."},
],
},
};
diff --git a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx b/packages/core/src/AvatarGroup/AvatarGroup.test.tsx
index d3393f7cdc..ec7a042a40 100644
--- a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx
+++ b/packages/core/src/AvatarGroup/AvatarGroup.test.tsx
@@ -231,6 +231,31 @@ describe('AvatarGroupOverflow — hardening', () => {
expect(screen.getByLabelText('0 more')).toBeInTheDocument();
});
+ it('clamps a negative count rather than rendering "+-3"', () => {
+ // `count={total - visibleCount}` is the documented shape, and it goes
+ // negative whenever the list is shorter than the slice.
+ render(
+ <AvatarGroup>
+ <Avatar name="Alice" />
+ <AvatarGroupOverflow count={-3} />
+ </AvatarGroup>,
+ );
+
+ expect(screen.queryByText('+-3')).not.toBeInTheDocument();
+ expect(screen.getByText('+0')).toBeInTheDocument();
+ expect(screen.getByLabelText('0 more')).toBeInTheDocument();
+ });
+
+ it('renders outside an AvatarGroup at the md fallback size', () => {
+ render(<AvatarGroupOverflow count={3} data-testid="loose" />);
+
+ const overflow = screen.getByTestId('loose');
+ expect(overflow).toHaveTextContent('+3');
+ // inline-flex, so a standalone indicator stays a circle instead of
+ // stretching to its parent's width.
+ expect(overflow.tagName).toBe('SPAN');
+ });
+
it('handles very large count', () => {
render(
<AvatarGroup>
@@ -400,3 +425,40 @@ describe('AvatarGroup — roving focus + keyboard hint', () => {
expect(screen.getByTestId('bob')).not.toHaveAttribute('tabindex');
});
});
+
+describe('AvatarGroup — size cascade', () => {
+ const sizeClasses = (el: HTMLElement) => el.className.split(/\s+/);
+
+ it("the group's size overrides a child's own size prop", () => {
+ render(
+ <AvatarGroup size="lg">
+ <Avatar name="Alice" size="xsm" data-testid="alice" />
+ </AvatarGroup>,
+ );
+
+ const classes = sizeClasses(screen.getByTestId('alice'));
+ expect(classes).toContain('lg');
+ expect(classes).not.toContain('xsm');
+ });
+
+ it("the group's default size also overrides a child's own size prop", () => {
+ // Known open finding: the group always publishes a size on its context, so
+ // a group that never set one still imposes md on children that did set one.
+ // Pinned here so the behaviour cannot change without a deliberate edit.
+ render(
+ <AvatarGroup>
+ <Avatar name="Alice" size="xl" data-testid="alice" />
+ </AvatarGroup>,
+ );
+
+ const classes = sizeClasses(screen.getByTestId('alice'));
+ expect(classes).toContain('md');
+ expect(classes).not.toContain('xl');
+ });
+
+ it("outside a group the avatar's own size applies", () => {
+ render(<Avatar name="Alice" size="xl" data-testid="alice" />);
+
+ expect(sizeClasses(screen.getByTestId('alice'))).toContain('xl');
+ });
+});
diff --git a/packages/core/src/AvatarGroup/AvatarGroup.tsx b/packages/core/src/AvatarGroup/AvatarGroup.tsx
index b3086100e5..a02bce26dc 100644
--- a/packages/core/src/AvatarGroup/AvatarGroup.tsx
+++ b/packages/core/src/AvatarGroup/AvatarGroup.tsx
@@ -48,7 +48,9 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
*/
children: ReactNode;
/**
- * Size applied to all avatars via context.
+ * Size applied to all avatars via context. This wins over each child
+ * Avatar's own `size` prop, including when it is left at the default, so
+ * set the size here rather than on the children.
* @default 'md'
*/
size?: AvatarSize;
diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx
index 182d24b3b0..73d682ff46 100644
--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx
+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx
@@ -18,11 +18,13 @@ import * as stylex from '@stylexjs/stylex';
import {
colorVars,
typographyVars,
+ typeScaleVars,
fontWeightVars,
radiusVars,
spacingVars,
} from '../theme/tokens.stylex';
import {mergeProps} from '../utils';
+import {resolveSize} from '../Avatar';
import {useAvatarGroup} from './AvatarGroupContext';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
@@ -57,7 +59,10 @@ export interface AvatarGroupOverflowProps extends Omit<
const styles = stylex.create({
base: {
position: 'relative',
- display: 'flex',
+ // inline-flex, not flex: outside an AvatarGroup this span is not a flex
+ // item, and a block-level flex container stretches to its parent's width
+ // instead of staying a circle.
+ display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
borderRadius: radiusVars['--radius-full'],
@@ -96,7 +101,12 @@ const styles = stylex.create({
// Focus ring via focus-visible
},
overlap: {
- marginInlineStart: 'var(--_avatar-group-overlap)',
+ // Matches Avatar's own overlap rule: the first item in the row must not be
+ // pulled outside the group's box.
+ marginInlineStart: {
+ default: null,
+ ':not(:first-child)': 'var(--_avatar-group-overlap)',
+ },
},
});
@@ -113,7 +123,13 @@ const dynamicStyles = stylex.create({
height: s + BORDER_WIDTH * 2,
}),
fontSize: (s: number) => ({
- fontSize: s * OVERFLOW_FONT_RATIO,
+ // Scales with the avatar, but never below the supporting-text role token,
+ // which is the 12px legibility floor. At xsm the bare ratio computes 7px,
+ // where the glyph stroke is thinner than a pixel and never reaches its
+ // own text colour (measured 1.63:1 against a 4.5:1 requirement).
+ fontSize: `max(${typeScaleVars['--text-supporting-size']}, ${
+ s * OVERFLOW_FONT_RATIO
+ }px)`,
}),
overlap: (offset: number) => ({
'--_avatar-group-overlap': `${offset}px`,
@@ -147,11 +163,15 @@ export function AvatarGroupOverflow({
const t = useTranslator();
const group = useAvatarGroup();
const size = group?.size ?? 'md';
- const numericSize = group?.numericSize ?? 36;
+ const numericSize = group?.numericSize ?? resolveSize('md');
const overlap = group?.overlap ?? 0;
- const label = t('@astryx.avatarGroup.overflow', {count});
- const content = children ?? `+${count}`;
+ // count is a plain number, and the documented shape for it is
+ // `total - visibleCount`, which goes negative whenever the list is shorter
+ // than the slice. Clamping keeps that from rendering "+-3".
+ const safeCount = Math.max(0, count);
+ const label = t('@astryx.avatarGroup.overflow', {count: safeCount});
+ const content = children ?? `+${safeCount}`;
if (onClick) {
return (