Skip to content

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

TypeScript

fix(Avatar): AvatarGroupOverflow grows to a pill for long +N counts (#4196)

Cindy Zhang1055df297b6f
diff --git a/.changeset/avatar-group-overflow-pill.md b/.changeset/avatar-group-overflow-pill.md
new file mode 100644
index 0000000000..0c69bee43d
--- /dev/null
+++ b/.changeset/avatar-group-overflow-pill.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `AvatarGroupOverflow` now grows into a pill for long `+N` counts so the number never clips.
+
+The indicator was a fixed-size circle, so wide counts (e.g. `+4912`) overflowed and crowded the edges. It now uses a minimum width equal to the avatar size plus horizontal padding: short counts (`+5`) stay a perfect circle, while longer counts grow horizontally into a stadium/pill and remain legible. No new public props.
+
+@cixzhang
diff --git a/apps/storybook/stories/AvatarGroup.stories.tsx b/apps/storybook/stories/AvatarGroup.stories.tsx
index 93f3efca10..71339c2738 100644
--- a/apps/storybook/stories/AvatarGroup.stories.tsx
+++ b/apps/storybook/stories/AvatarGroup.stories.tsx
@@ -174,6 +174,38 @@ export const LargeOverflowCount: Story = {
),
};
+/**
+ * Short counts stay a circle; long counts grow into a pill.
+ *
+ * The indicator uses a minimum width equal to the avatar size, so a small
+ * `+5` renders as a circle, while a wide `+4912` grows horizontally into a
+ * stadium/pill so the number always fits with comfortable padding.
+ */
+export const CircleToPill: Story = {
+ render: () => (
+ <div {...stylex.props(storyStyles.storyWrapper)}>
+ <div>
+ <h4 {...stylex.props(storyStyles.heading)}>Short count (circle)</h4>
+ <AvatarGroup size="medium">
+ {USERS.slice(0, 3).map(u => (
+ <Avatar key={u.key} src={u.src} name={u.name} />
+ ))}
+ <AvatarGroupOverflow count={5} />
+ </AvatarGroup>
+ </div>
+ <div>
+ <h4 {...stylex.props(storyStyles.heading)}>Long count (pill)</h4>
+ <AvatarGroup size="medium">
+ {USERS.slice(0, 3).map(u => (
+ <Avatar key={u.key} src={u.src} name={u.name} />
+ ))}
+ <AvatarGroupOverflow count={4912} />
+ </AvatarGroup>
+ </div>
+ </div>
+ ),
+};
+
/** Zero overflow count edge case. */
export const ZeroOverflow: Story = {
render: () => (
diff --git a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx b/packages/core/src/AvatarGroup/AvatarGroup.test.tsx
index 4b5ac8aef0..8ba9122cef 100644
--- a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx
+++ b/packages/core/src/AvatarGroup/AvatarGroup.test.tsx
@@ -211,4 +211,18 @@ describe('AvatarGroupOverflow — hardening', () => {
expect(screen.getByText('+999')).toBeInTheDocument();
});
+
+ it('renders the full "+N" text for wide multi-digit counts', () => {
+ // The indicator grows into a pill for long counts, so the entire number
+ // must remain present (nothing clipped away in the DOM).
+ render(
+ <AvatarGroup>
+ <Avatar name="Alice" />
+ <AvatarGroupOverflow count={4912} />
+ </AvatarGroup>,
+ );
+
+ expect(screen.getByText('+4912')).toBeInTheDocument();
+ expect(screen.getByLabelText('4912 more')).toBeInTheDocument();
+ });
});
diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
index aec2269768..45456743ca 100644
--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
@@ -51,7 +51,7 @@ export const docs = {
'AvatarGroupOverflow appears at the end of an AvatarGroup to summarize people who are not shown individually. Use it when a group is sliced to a small number of visible avatars but the hidden count still matters.',
bestPractices: [
{guidance: true, description: 'Pass the real hidden count to `count` so the accessible label matches the visible indicator.'},
- {guidance: true, description: 'Use short custom text such as `+12` or `99+`; the indicator is sized like an avatar.'},
+ {guidance: true, description: 'Use short custom text such as `+12` or `99+`. The indicator is circular for short counts and grows into a pill for wider counts so the number always fits.'},
{guidance: true, description: 'Provide `onClick` when the overflow opens a member list, popover, or detail view.'},
{guidance: false, description: 'Do not use long labels inside the indicator; place longer participant details next to the group instead.'},
],
@@ -104,7 +104,7 @@ export const docsZh = {
'AvatarGroupOverflow 显示在 AvatarGroup 末尾,用来汇总未单独展示的成员。适用于只展示少量头像但仍需要显示隐藏数量的场景。',
bestPractices: [
{guidance: true, description: '向 `count` 传入真实隐藏数量,确保无障碍标签与可见指示器一致。'},
- {guidance: true, description: '使用 `+12` 或 `99+` 等短文本;指示器尺寸与头像相同。'},
+ {guidance: true, description: '使用 `+12` 或 `99+` 等短文本;指示器在计数较短时为圆形,计数较宽时会拉伸为胶囊形,确保数字始终完整显示。'},
{guidance: true, description: '当溢出项会打开成员列表、弹出层或详情视图时提供 `onClick`。'},
{guidance: false, description: '不要在指示器内使用长标签;更长的参与者详情应放在头像组旁边。'},
],
diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx
index 17be7815b0..aa6cffb7be 100644
--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx
+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx
@@ -20,6 +20,7 @@ import {
typographyVars,
fontWeightVars,
radiusVars,
+ spacingVars,
} from '../theme/tokens.stylex';
import {mergeProps} from '../utils';
import {useAvatarGroup} from './AvatarGroupContext';
@@ -67,13 +68,21 @@ const styles = stylex.create({
borderWidth: BORDER_WIDTH,
borderStyle: 'solid',
borderColor: colorVars['--color-background-surface'],
- boxSizing: 'content-box',
+ // border-box so the border and inline padding are included in the box
+ // size: a short "+N" stays a circle at exactly the avatar size, while
+ // longer content pushes past the min width and grows into a pill.
+ boxSizing: 'border-box',
+ // Horizontal breathing room so multi-digit "+N" counts don't crowd the
+ // edges once the indicator grows into a pill.
+ paddingInline: spacingVars['--spacing-2'],
// Neutral tint layer (preserves opaque base underneath)
backgroundImage: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
},
button: {
cursor: 'pointer',
- padding: 0,
+ // Reset the UA button's block padding only; the inline padding from `base`
+ // provides the pill's breathing room and must be preserved.
+ paddingBlock: 0,
// Interactive overlay states layered on top via backgroundImage
backgroundImage: {
default: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
@@ -99,8 +108,15 @@ const styles = stylex.create({
const dynamicStyles = stylex.create({
size: (s: number) => ({
- width: s,
- height: s,
+ // Pin height to the avatar's rendered size and enforce the same value as a
+ // *minimum* width, so short counts (`+5`) render a perfect circle. With
+ // border-box, the inline padding lives inside this size; longer content
+ // (`+4912`) pushes past the min width and grows into a stadium/pill.
+ // The border is added to the declared size (like the avatars' ring, which
+ // uses content-box + a 2px border) to keep the indicator the same overall
+ // size as its sibling avatars.
+ minWidth: s + BORDER_WIDTH * 2,
+ height: s + BORDER_WIDTH * 2,
}),
fontSize: (s: number) => ({
fontSize: s * OVERFLOW_FONT_RATIO,