---
description: Компонент для отображения группы аватаров пользователей с возможностью добавления сопроводительного текста.
tags: list, media
---

<Overview group="data-display">

# UsersStack [tag:component]

Компонент для отображения группы аватаров пользователей с возможностью добавления сопроводительного текста.
Оптимален для визуализации участников чата, подписчиков или коллаборативной работы.

</Overview>

{/* @example-description: Базовый `UsersStack` с аватарами пользователей и сопровождающим текстом. */}
<Playground>
  ```jsx
  <UsersStack
    photos={[
      'https://avatars.githubusercontent.com/u/14944123?s=50',
      'https://avatars.githubusercontent.com/u/5850354?s=50',
    ]}
  >
    Даниил и Ином подписаны
  </UsersStack>
  ```
</Playground>

## Использование

Для отображения аватаров передавайте ссылки на изображения в свойство `photos`, которое принимает массив ссылок.
Дополнительно есть возможность передать массив объектов, каждый объект состоит также из ссылки на изображение и
пользовательского [компонента-обёртки](#wrappers) для каждого элемента.

## Положение аватаров [#avatar-position]

Помимо положения аватаров перед или после текста (`avatarsPosition="inline-start"` и `avatarsPosition="inline-end"` соответственно),
есть возможность задать блочное расположение - аватары над текстом (`avatarsPosition="block-start"`).
В таком случае оптимальным будет совместное использование со свойством `size="m"`:

{/* @example-description: Пример `UsersStack` с `avatarsPosition="block-start"` и счётчиком участников. */}
<Playground>
  ```jsx
  <UsersStack
    avatarsPosition="block-start"
    size="m"
    visibleCount={2}
    count={3}
    photos={[
      'https://avatars.githubusercontent.com/u/7431217?s=50',
      'https://avatars.githubusercontent.com/u/61377022?s=50',
    ]}
  >
    Виктория, Эльдар и ещё 3 человека пойдут на это мероприятие
  </UsersStack>
  ```
</Playground>

## Счётчик

Если в свойство `photos` передаётся количество элементов большее, чем указано в свойстве `visibleCount`,
то рядом с аватарами появляется счётчик, который по умолчанию отображает количество оставшихся элементов.
С помощью числового свойства `count` можно переопределить число, которое будет показано.
Если число окажется больше `99`, то счётчик скрывается.
Пример можно увидеть в разделе [Положение аватаров](#avatar-position).

## Кастомизация аватаров [#wrappers]

Аватарки можно оборачивать в кастомный компонент для добавления дополнительного функционала
с помощью свойства `renderWrapper` у элемента списка `photos`. В примере ниже при наведении на
аватар появляется подсказка с именем пользователя:

{/* @example-description: Кастомные обёртки аватаров в `UsersStack` с `Tooltip` и интерактивным элементом. */}
<Playground>
  ```jsx
  <UsersStack
    size="l"
    photos={[
      {
        src: 'https://avatars.githubusercontent.com/u/14944123?s=50',
        renderWrapper: (props) => (
          <Tooltip description="Даниил Суворов">
            <Tappable onClick={() => {}}>{props.children}</Tappable>
          </Tooltip>
        ),
      },
      {
        src: 'https://avatars.githubusercontent.com/u/5850354?s=50',
        renderWrapper: (props) => (
          <Tooltip description="Ином Мирджамолов">
            <Tappable onClick={() => {}}>{props.children}</Tappable>
          </Tooltip>
        ),
      },
    ]}
  />
  ```
</Playground>

## Ограничения

- Максимальное число в счётчике: 99, иначе счётчик скрывается.
- При `size="s"` счётчик не отображается.
- Рекомендуется использовать `avatarsPosition="block-start"` вместе с `size="m"`.

## Свойства и методы [#api]

| Свойство | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `avatarsPosition` | `"inline-start" \| "block-start" \| "inline-end"` | `inline-start` | Определяет положение аватаров Режим `block-start` рекомендуется использовать с размером `m`. |
| `count` | `number` | `Math.max(0, photos.length - visibleCount)` | Число, которое будет указано в счетчике. По умолчанию высчитывается по формуле `photos.length - visibleCount`. Если число больше 99, то счетчик скроется. |
| `getRootRef` | `Ref<HTMLDivElement>` | `-` |  |
| `photos` | `string[] \| UsersStackPhoto[]` | `[]` | Массив ссылок на фотографии либо массив структур типа `UsersStackPhoto`. |
| `size` | `"s" \| "m" \| "l"` | `m` | Размер аватарок. |
| `visibleCount` | `number` | `3` | Количество аватарок, которые будут показаны. Если в массиве `photos` больше элементов и не используется размер `s`, то будет показано количество остальных элементов. |