Add variant & shape props to AvatarStack component

[chanakyav]

• https://github.com/github/authz-exp/issues/817

Note

• This PR is attempting to achieve similar goals as Evenly space AvatarStack #5911

Changelog

Added/Changed

This PR adds new functionality to the AvatarStack component through 2 new props: variant & shape

• variant - Options: cascade (default) & stacked. Cascade will retain the existing functionality with respect to spacing and opacity. The stacked option will more evenly space out the avatars and remove the opacity for them.
• shape - Options: circle (default) & square. The new square option will render the avatars as squares by passing the square prop down to the avatar children components.

AvatarStack with shape='circle' and varying avatar counts, and alignments:

Screen.Recording.2025-08-04.at.10.50.15.AM.mov

AvatarStack with shape='square' and varying avatar counts, and alignments:

Screen.Recording.2025-08-04.at.10.52.00.AM.mov

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: ac76175

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

👋 Hi, this pull request contains changes to the source code that github/github depends on. If you are GitHub staff, we recommend testing these changes with github/github using the integration workflow. Thanks!

[github-actions]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	90.25 KB (+0.15% 🔺)
packages/react/dist/browser.umd.js	90.48 KB (+0.07% 🔺)

[chanakyav]

👋🏽 Hello, reviewers!

Its my first primer/react PR so I'm looking for some guidance on updating docs/storybook examples. I have quite a few examples as you can see in the PR description. Please let me know what places these examples need to go in the storybook and any other docs:

The current features list has a tab for each variation, with these new additions I wanted to double check the structure we want to go for before adding more to the list vs. combining features based on variant type and have less tabs.

Thanks!

[github-actions]

Uh oh! @chanakyav, at least one image you shared is missing helpful alt text. Check #6420 (comment) to fix the following violations:

• Images should have meaningful alternative text (alt text) at line 5

Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image.

Learn more about alt text at Basic writing and formatting syntax: images on GitHub Docs.

🤖 Beep boop! This comment was added automatically by github/accessibility-alt-text-bot.

[Copilot]

Pull Request Overview

This PR adds variant and shape customization options to the AvatarStack component to provide more flexible rendering styles.

Key changes:

• Added variant prop with options cascade (default) and stacked for different avatar spacing and opacity behaviors
• Added shape prop with options circle (default) and square to control avatar shape rendering
• Updated CSS to support the new variant and shape combinations with appropriate styling rules

Reviewed Changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
AvatarStack.tsx	Added new props and logic to pass shape to child avatars
AvatarStack.module.css	Extensive CSS updates for variant/shape combinations and styling rules
AvatarStack.test.tsx.snap	Updated snapshot to reflect new CSS classes and data attributes
Popover/__snapshots__/Popover.test.tsx.snap	Removed all snapshot content (unrelated to PR purpose)
Link/__tests__/__snapshots__/Link.test.tsx.snap	Removed all snapshot content (unrelated to PR purpose)

[lukasoppermann]

Please inform me when this gets merged so we can update the Figma component as well.