> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: AvatarGroup Component

## Article: AvatarGroup Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/media/avatar-group-component.md

## Article Content:

# AvatarGroup

_Components/Media_

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

## Overview

```jsx
() => {
  const alphabet = Array.from(Array(104))
    .map((e, i) => i + 65)
    .map((x) => String.fromCharCode(x));

  return (
    <AvatarGroup
      type="condensed"
      showDivider
      items={alphabet.map((value) => ({ name: `${value} T` }))}
      maxItems={6}
    />
  );
};
```

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\`

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AvatarGroup
    size="medium"
    items={[
      { name: 'first user' },
      { name: 'second user' },
      { name: 'third avatar' },
    ]}
  />
  <AvatarGroup
    size="small"
    items={[
      { name: 'first user' },
      { name: 'second user' },
      { name: 'third avatar' },
    ]}
  />
  <AvatarGroup
    size="tiny"
    items={[
      { name: 'first user' },
      { name: 'second user' },
      { name: 'third avatar' },
    ]}
  />
</StorybookComponents.Stack>;
```

#### 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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AvatarGroup
    type="stretched"
    items={[
      { name: 'first user' },
      { name: 'second user' },
      { name: 'third avatar' },
    ]}
  />
  <AvatarGroup
    type="condensed"
    items={[
      { name: 'first user' },
      { name: 'second user' },
      { name: 'third avatar' },
    ]}
  />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<AvatarGroup
  showDivider
  items={[
    { name: 'first avatar' },
    { name: 'second avatar' },
    { name: 'third avatar' },
  ]}
/>;
```

#### 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.

```jsx
<AvatarGroup
  maxItems={5}
  items={[
    { name: 'first user' },
    { name: 'second user' },
    { name: 'third avatar' },
    { name: 'fourth avatar' },
    { name: 'fifth avatar' },
    { name: 'sixth avatar' },
  ]}
/>;
```

### Common use case examples

#### Assigned users

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

```jsx
() => {
  const renderTableListItem = ({
    title,
    subtitle,
    avatarGroup,
    renderTableActionCell = true,
  }) => (
    <TableListItem
      showDivider
      options={[
        {
          value: (
            <Box direction="vertical">
              <Text weight="normal">{title}</Text>
              <Text size="small" secondary>
                {subtitle}
              </Text>
            </Box>
          ),
          width: '450px',
        },
        {
          value: avatarGroup,
        },
        {
          value: renderTableActionCell ? (
            <TableActionCell
              primaryAction={{
                text: 'Edit',
                skin: 'standard',
                onClick: () => {},
              }}
              secondaryActions={[
                {
                  text: 'Invite Contributor',
                  icon: <Icons.UserAdd />,
                  onClick: () => {},
                },
                {
                  text: 'Duplicate & Edit',
                  icon: <Icons.Duplicate />,
                  onClick: () => {},
                },
                {
                  text: 'Delete',
                  icon: <Icons.Delete />,
                  onClick: () => {},
                },
              ]}
              numOfVisibleSecondaryActions={0}
            />
          ) : null,
        },
      ]}
    />
  );

  return (
    <Card>
      <Card.Header title="System Roles" />
      <Card.Divider />
      {renderTableListItem({
        title: 'Account Owner',
        subtitle:
          'Has full administrative access to the account and can manage all sites.',
        avatarGroup: (
          <AvatarGroup type="condensed" items={[{ name: 'Matt Thompson' }]} />
        ),
        renderTableActionCell: false,
      })}

      {renderTableListItem({
        title: 'Site Admin',
        subtitle:
          'Has full access to the site but cannot edit the payment info, delete or duplicate the site.',
        avatarGroup: (
          <AvatarGroup
            type="condensed"
            items={[{ name: 'Matt Thompson' }, { name: 'Luke Wheeler' }]}
          />
        ),
      })}

      {renderTableListItem({
        title: 'Website Manager',
        subtitle:
          ' Can edit the site, manage settings and apps but cannot access Inbox, contacts and other sensitive info.',
        avatarGroup: (
          <AvatarGroup
            type="condensed"
            items={[
              { name: 'Matt Thompson' },
              { name: 'Emma Pike' },
              { name: 'Julia Maria Rogers' },
              { name: 'Margareth Simmons' },
            ]}
          />
        ),
      })}

      {renderTableListItem({
        title: 'Back-Office Manager',
        subtitle:
          'Can access the Wix Dashboard to manage site settings and apps but cannot edit the site.',
        avatarGroup: (
          <AvatarGroup type="condensed" items={[{ name: 'Emma Pike' }]} />
        ),
      })}
    </Card>
  );
};
```

## Code

```jsx
import { AvatarGroup } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `items` *(required)* | `AvatarItemProps[]` | — | Use to pass an array of avatars. |
| `maxItems` | `number` | `5` | Sets the maximum number of avatars to be displayed. Avatars that exceed this limit are hidden under the "+N" item. |
| `showDivider` | `boolean` | — | 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:

```jsx
// UniDriver
import { AvatarGroupUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { AvatarGroupTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { AvatarGroupTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { AvatarGroupTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `getVisibleAvatarsCount` | Gets the number Of displayed Avatars |
| `getVisibleAvatarTextContentByIndex` | Gets the text content |
| `getMoreIndicatorContent` | Gets the moreIndicator content |
| `isMoreIndicatorExist` | Checks whether the moreIndicator exists |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns 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](invalid-url)) — 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](invalid-url))
- **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](invalid-url)) — 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](invalid-url))
- **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