Avatar group

An avatar group displays a number of avatars grouped together in a stack or grid.

Neutral selected states

When the platform-dst-tokens-finesse feature flag is enabled, this component uses the new neutral treatment for selected states.

Motion in Early Access

Motion updates for this component are in Early Access and available behind the platform-dst-motion-uplift feature flag.

Installation

Package installation information
Installyarn add @atlaskit/avatar-group
SourceBitbucket.org, (opens new window)
npm@atlaskit/avatar-group, (opens new window)
Bundleunpkg.com, (opens new window)

Props

appearance

Description

Indicates the layout of the avatar group. Avatars will either be overlapped in a stack, or laid out in an even grid formation. Defaults to "stack".

Default"stack"
Type"grid" | "stack"

avatar

Description

Component used to render each avatar.

DefaultAvatar
TypeAvatarComponent | React.ElementType<AvatarProps, keyof React.JSX.IntrinsicElements>

borderColor

Description

Typically the background color that the avatar is presented on. Accepts any color argument that the CSS border-color property accepts.

Typestring

boundariesElement

Description

Element the overflow popup should be attached to. Defaults to "viewport".

Type"viewport" | "window" | "scrollParent"

data

Required
Description

An array of avatar prop data, that are spread onto each avatar component.

For further usage information on AvatarPropTypes, the supported props for avatar, refer to Avatar's prop documentation.

Type(AvatarPropTypes & { name: string; key?: string | number; })[]

isTooltipDisabled

Description

Disables tooltips.

Typeboolean

label

Description

Text to be used as aria-label for the list of avatars. Screen reader announcement with default label, which is avatar group, is list, avatar group, X items.

The label should describe the AvatarGroup's entities, for instance:

  • label="team members", screen reader announcement would be list team members, X items
  • label="reviewers" screen reader announcement would be list reviewers, X items

When there are several AvatarGroups on the page you should use a unique label to let users distinguish different lists.

Default"avatar group"
Typestring

maxCount

Description

The maximum number of avatars allowed in the list. Defaults to 5 when displayed as a stack, and 11 when displayed as a grid.

Typenumber

moreIndicatorLabel

Description

Text to be used as aria-label for the more indicator. If provided, this will be used exactly as-is for the aria-label. If not provided, but an aria-label is provided via showMoreButtonProps, that will be used instead. If neither is provided, the aria-label will default to "N more people" where N is the number of people that are not visible (e.g. "5 more people").

Typestring

onAvatarClick

Description

Handle the click event on the avatar item. Note that if an onClick prop is provided as part of avatar data, it will take precedence over onAvatarClick.

Type(event: React.MouseEvent<Element, MouseEvent>, analyticsEvent: AnalyticsEvent, index: number) => void

onMoreClick

Description

Take control of the click event on the more indicator. This will cancel the default dropdown behavior.

Type(event: React.MouseEvent<Element, MouseEvent>) => void

overrides

Description

Custom overrides for the composed components.

TypeAvatarGroupOverrides

shouldPopupRenderToParent

Description

Determines whether the 'show more' popup has shouldRenderToParent applied.

Defaultfalse
Typeboolean

showMoreButtonProps

Description

Provide additional props to the MoreButton. Example use cases: altering tab order by providing tabIndex; adding onClick behaviour without losing the default dropdown

Default{}
Type{ defaultChecked?: boolean; defaultValue?: string | number | readonly string[]; suppressContentEditableWarning?: boolean; suppressHydrationWarning?: boolean; accessKey?: string; autoCapitalize?: (string & {}) | ... 5 more ... | "characters"; ... 257 more ...; onTransitionEndCapture?: React.TransitionEventHandler<......

size

Description

Defines the size of the avatar. Defaults to "medium".

Note: The "xxsmall" (16px), legacy "xsmall", and "UNSAFE_xsmall" (20px) sizes that exist on Avatar are not supported here because elements such as the more indicator cannot be displayed in an accessible manner at those sizes.

Default"medium"
Type"small" | "medium" | "large" | "xlarge" | "xxlarge"

testId

Description

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.,Will set these elements when defined:

  • Container element - {testId}--avatar-group
  • Avatar items - {testId}--avatar-{index}
  • Overflow menu button - {testId}--overflow-menu--trigger
  • Overflow menu content - {testId}--overflow-menu--content
Typestring

tooltipPosition

Description

Where the tooltip should appear relative to its target. Defaults to tooltip position "bottom".

Default"bottom"
Type"top" | "bottom"
Was this page helpful?
We use this feedback to improve our documentation.
© 2026 AtlassianTrademark, (opens new window)Privacy, (opens new window)License