AvatarGroup

Components/Media

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/avatargroup

Overview

Copy

AvatarGroup allows to display a number of avatars (digital representation of a user) as a single entity. It's a building block grouping number of standalone <Avatar/> components.

Do

  • Use it to display a group of 2+ users
  • Use it to display users that have something in common (i.e. belong to a project, are in the same team, attend the same event, etc.)

Don't

  • Don't use it to display single avatar
  • Don't use it to display visual content other than users (i.e. images - use <Image/>)

Feature examples

Size

Controls size of a component. It supports 3 sizes: - `medium` (default)- use in all common cases - `small` - use to de-emphasise the group, also in more dense and narrow layouts - `tiny`

Copy

Group type

Changes density of a group. Component supports 2 types: - `stretched` (default)- use when each user is as important as a group as a whole - `condensed` - use in narrow layouts and in cases where it is important to show the sum of the people rather than individuals

Copy

Divider

Separates first avatar from the rest of the group to highlight the difference of a status or role (i.e. admin, team lead, etc). Component allows to separate single avatar only, which must be a first item on the list.

Copy

Max number of items

Defines the maximum number of items to show before collapsing them. By default component displays up to 5 items. The '+N' indication will replace the last avatar, in case the number exceeds this limit.

Copy

Common use case examples

Assigned users

Use avatar group to display multiple users that are assigned to the same role, group or task.

Copy

Code

Copy

Props

NameTypeDefaultDescription
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
items (required)AvatarItemProps[]—Use to pass an array of avatars.
maxItemsnumber5Sets the maximum number of avatars to be displayed. Avatars that exceed this limit are hidden under the "+N" item.
showDividerboolean—Separates the first avatar with a divider from the rest of the group.
size"small" | "tiny" | "medium"—Changes the size of avatars in the group.
type"stretched" | "condensed"—Changes the way avatars are displayed inside the group.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getVisibleAvatarsCountGets the number Of displayed Avatars
getVisibleAvatarTextContentByIndexGets the text content
getMoreIndicatorContentGets the moreIndicator content
isMoreIndicatorExistChecks whether the moreIndicator exists
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.320.0 (2026-09-03) — feat: the overflow counter now reads "+N" instead of "N+" in all themes. In Harmony (odeditor) the divider is shorter with a rounded 1.5px stroke, the avatar gap tightens to 4px, the condensed ring thins to 1px and the medium counter uses a smaller font with a refined frosted-glass background. Harmony Dark (odeditor-dark) matches: the counter gets its own dark gradient and the divider uses the same shortened rounded geometry. The condensed counter no longer shows a faint light hairline between its ring and its own border when the group sits on a background that differs from the ring colour. Other themes only change the counter text. (#16907) — has visual changes
  • 1.317.0 (2026-08-26) — feat: export the AvatarItemProps type, so the type of the items array entries can be imported directly from @wix/design-system. (#16903)
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.307.0 (2026-08-03) — fix: the "+N" counter now consumes the --wds-avatar-group-counter-* theme tokens. In BM Reimagined (Harmony) and Studio 2.0 it renders per the Figma definition — translucent fill with a subtle gradient, frosted-glass backdrop blur, and a 1px border — while the default, Studio, and Wixel themes keep their existing appearance (the circle's overall size is preserved via border-width padding compensation). (#16694) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — feat: add tiny size for AvatarGroup (#15974)
  • 1.250.0 (2026-01-27) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.99.0 (2024-03-29) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?