---
title: AvatarGroup
description: AvatarGroup
element: vaadin-avatar-group
---

## Description

`<vaadin-avatar-group>` is a Web Component providing avatar group displaying functionality.

To create the avatar group, first add the component to the page:

```html
<vaadin-avatar-group></vaadin-avatar-group>
```

And then use [`items`](/elements/vaadin-avatar-group#items) property to initialize the structure:

```js
document.querySelector('vaadin-avatar-group').items = [
  {name: 'John Doe'},
  {abbr: 'AB'}
];
```

### Styling

The following shadow DOM parts are exposed for styling:

Part name   | Description
----------- | ---------------
`container` | The container element
`overlay`   | The overflow avatar menu overlay
`content`   | The overflow avatar menu overlay content

The following custom CSS properties are available for styling:

Custom CSS property                |
:----------------------------------|
| `--vaadin-avatar-group-gap`      |
| `--vaadin-avatar-group-overlap`  |

See the [`<vaadin-avatar>`](/elements/vaadin-avatar) documentation for the available
state attributes and stylable shadow parts of avatar elements.

See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.

### Internal components

In addition to `<vaadin-avatar-group>` itself, the following internal
components are themable:

- `<vaadin-avatar-group-menu>` - has the same API as [`<vaadin-list-box>`](/elements/vaadin-list-box).
- `<vaadin-avatar-group-menu-item>` - has the same API as [`<vaadin-item>`](/elements/vaadin-item).

## Properties

### i18n

**Type:** `AvatarGroupI18n`

The object used to localize this component. To change the default
localization, replace this with an object that provides all properties, or
just the individual properties you want to change.

The object has the following JSON structure and default values:
```js
{
  // Translation of the anonymous user avatar tooltip.
  anonymous: 'anonymous',
  // Translation of the avatar group accessible label.
  // {count} is replaced with the actual count of users.
  activeUsers: {
    one: 'Currently one active user',
    many: 'Currently {count} active users'
  },
  // Screen reader announcement when user joins group.
  // {user} is replaced with the name or abbreviation.
  // When neither is set, "anonymous" is used instead.
  joined: '{user} joined',
  // Screen reader announcement when user leaves group.
  // {user} is replaced with the name or abbreviation.
  // When neither is set, "anonymous" is used instead.
  left: '{user} left'
}
```

See also: [AvatarGroupI18n](#avatargroupi18n)

### items

**Type:** `AvatarGroupItem[] | undefined`

An array containing the items which will be stamped as avatars.

The items objects allow to configure [`name`](/elements/vaadin-avatar#name),
[`abbr`](/elements/vaadin-avatar#abbr), [`img`](/elements/vaadin-avatar#img)
and [`colorIndex`](/elements/vaadin-avatar#colorindex) properties on the
stamped avatars, and set `className` to provide CSS class names.

#### Example

```js
group.items = [
  {
    name: 'User name',
    img: 'url-to-image.png',
    className: 'even'
  },
  {
    abbr: 'JD',
    colorIndex: 1,
    className: 'odd'
  },
];
```

See also: [AvatarGroupItem](#avatargroupitem)

### maxItemsVisible

**Type:** `number | null | undefined`

The maximum number of avatars to display. By default, all the avatars are displayed.
When _maxItemsVisible_ is set, the overflowing avatars are grouped into one avatar with
a dropdown. Setting 0 or 1 has no effect so there are always at least two avatars visible.

## Types

### AvatarGroupI18n

```ts
export interface AvatarGroupI18n extends AvatarI18n {
  activeUsers?: {
    one?: string;
    many?: string;
  };
  joined?: string;
  left?: string;
}
```

### AvatarGroupItem

```ts
export interface AvatarGroupItem {
  name?: string;
  abbr?: string;
  img?: string;
  colorIndex?: number;
  className?: string;
}
```

### AvatarI18n

```ts
export interface AvatarI18n {
  anonymous?: string;
}
```