> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Группа аватаров

> Перекрывающиеся аватары с производным индикатором переполнения.

## Обзор

`AvatarGroup` получает отрисованные аватары и определяет количество скрытых. `maxVisible` учитывает фактические аватары; индикатор переполнения является дополнительным. При наличии восьми аватаров `maxVisible={3}` отображаются три аватара и `+5`.

**Light**

[Восемь аватаров, три из которых видимы (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Восемь аватаров, три из которых видимы (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatargroup--display)

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

```tsx theme={null}
import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';

export const TeamAvatars = () => (
  <AvatarGroup
    maxVisible={3}
    overflowShape="circle"
    overlap="left"
    overlapOffset="4px"
    avatars={[
      'Ada',
      'Grace',
      'Margaret',
      'Annie',
      'Mary',
      'Dorothy',
      'Katherine',
      'Joan',
    ].map((name) => (
      <Avatar
        key={name}
        name={name}
        shape="circle"
        imageProps={{ alt: name }}
      />
    ))}
  />
);
```

Передавайте стабильные ключи, чтобы оставшиеся аватары оставались смонтированными при изменении лимита, общего количества или порядка отображения. Аватары по умолчанию являются декоративными. Когда группа является единственным представлением своих участников, укажите имя каждого участника через `imageProps.alt`, чтобы добавить подпись к изображению и резервному варианту по умолчанию. Сохраняйте аватары декоративными, когда видимый текст или метка владельца уже указывают на эту личность.

## Визуальные параметры

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

**Light**

[Сравните формы и размеры аватаров (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Сравните формы и размеры аватаров (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatargroup--catalog)

## Частично загруженные коллекции

Используйте `total` для полного размера коллекции, когда загружены только некоторые аватары. Три переданных и видимых аватара с `total={20}` отображают `+17`. Передайте все загруженные аватары и позвольте группе применить `maxVisible`.

```tsx theme={null}
import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';

export const LoadedTeamAvatars = () => (
  <AvatarGroup
    maxVisible={3}
    total={20}
    avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
      <Avatar key={name} name={name} imageProps={{ alt: name }} />
    ))}
  />
);
```

Значение `total` округляется вниз и не может быть меньше количества переданных аватаров, пригодных для рендеринга. Для неконечных итоговых значений используется переданное количество. Вычисленное количество скрытых аватаров всегда неотрицательно.

Значение `maxVisible` по умолчанию равно `4`. Конечные лимиты округляются вниз и ограничиваются нулём, `Infinity` отображает все переданные аватары, а `NaN` не отображает ни одного. Пустые узлы React не считаются аватарами. При нулевом лимите может отображаться только индикатор переполнения. Пустая группа с положительным общим количеством может показывать это количество в своём индикаторе; пустая группа без скрытых аватаров ничего не рендерит.

**Light**

[Три загруженных участника из команды в двадцать человек (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--partially-loaded\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Три загруженных участника из команды в двадцать человек (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--partially-loaded\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatargroup--partially-loaded)

## Пользовательское переполнение

`renderOverflow` получает то же вычисленное количество скрытых аватаров, что и стандартный индикатор `+N`. Он выполняется только при положительном количестве. Верните `null`, чтобы скрыть индикатор, не изменяя набор видимых аватаров.

Используйте явный элемент управления, когда индикатор выполняет действие. Его доступное имя должно описывать действие и количество.

```tsx theme={null}
import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';
import { Button } from 'twenty-ui/primitives/input';

type TeamAvatarsWithActionProps = { onShowAll: () => void };

export const TeamAvatarsWithAction = ({
  onShowAll,
}: TeamAvatarsWithActionProps) => (
  <AvatarGroup
    maxVisible={3}
    total={20}
    avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
      <Avatar key={name} name={name} imageProps={{ alt: name }} />
    ))}
    renderOverflow={(hiddenCount) => (
      <Button
        size="sm"
        aria-label={`Show ${hiddenCount} more members`}
        onClick={onShowAll}
      >
        +{hiddenCount}
      </Button>
    )}
  />
);
```

**Light**

[Пользовательская кнопка переполнения (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--custom-overflow\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Пользовательская кнопка переполнения (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--custom-overflow\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-data-display-avatargroup--custom-overflow)

## Внешний вид

Более поздние аватары всегда отрисовываются поверх более ранних. `overlap` выбирает физическое поле, `left` или `right`, к которому применяется отрицательное смещение. `overlapOffset` задаёт это смещение как длину CSS. `overflowShape` задаёт форму стандартного числового индикатора.

## Настройка корневого элемента

Нативные атрибуты, обработчики событий, `className` и `style` применяются к корневому элементу. Его элементом по умолчанию является `div`, в том числе при передаче `onClick`. Используйте нативные интерактивные элементы для действий, например кнопку переполнения выше.

Корневой элемент принимает ref и `render`, который может быть элементом или функцией. Пользовательские компоненты должны передавать предоставленные props и ref своему нативному корневому элементу. См. [пользовательские компоненты](https://docs.twenty.com/ru/ui/primitives/overview#custom-components), чтобы ознакомиться с требованиями к композиции.

```tsx theme={null}
import { useRef } from 'react';
import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';

export const NamedTeamAvatars = () => {
  const groupRef = useRef<HTMLDivElement>(null);

  return (
    <AvatarGroup
      ref={groupRef}
      role="group"
      aria-label="Project members"
      style={{ marginBlock: 8 }}
      render={<div data-location="project-header" />}
      avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
        <Avatar key={name} name={name} imageProps={{ alt: name }} />
      ))}
    />
  );
};
```

## Свойства

`AvatarGroupProps` экспортируется из `twenty-ui/components/data-display`.

**avatars** `ReactNode[]` *required*

Avatar elements in display order. Empty React nodes are ignored. Supply stable keys to preserve identity when reordering.

**className** `string`

Class applied to the group container.

**maxVisible** `number` (default: 4)

Maximum number of actual avatars to show, excluding the overflow indicator. Floored and clamped to zero; Infinity shows all avatars and NaN shows none.

**overflowShape** `"circle" | "rounded-square" | "square"` (default: square)

Shape of the numeric overflow indicator.

**overlap** `"left" | "right"` (default: right)

Physical margin, left or right, that carries the negative overlap offset. Later avatars always render above earlier ones.

**overlapOffset** `string` (default: 3px)

CSS length of the overlap between avatars.

**ref** `Ref\<HTMLDivElement\>`

Ref to the rendered root element.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Element or render function for the root. Forward the supplied props and ref; the default element is a div.

**renderOverflow** `((hiddenCount: number) =\> ReactNode)`

Called with the derived hidden count when it is positive. Return a custom indicator, or null to hide it.

**total** `number`

Total collection size for partially loaded avatars. Floored and never smaller than the supplied renderable count; nonfinite values use the supplied count.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.