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

# Grupo de avatares

> Avatares superpuestos con un indicador de desbordamiento derivado.

## Resumen

`AvatarGroup` recibe avatares renderizados y calcula el recuento oculto. `maxVisible` cuenta los avatares reales; el indicador de desbordamiento es adicional. Ocho avatares proporcionados con `maxVisible={3}` muestran tres avatares y `+5`.

**Light**

[Ocho avatares con tres visibles (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Ocho avatares con tres visibles (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)

## Uso

```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 }}
      />
    ))}
  />
);
```

Proporcione claves estables para mantener montados los avatares que permanecen cuando cambie el límite, el total o el orden de visualización. Los avatares son decorativos de forma predeterminada. Cuando el grupo sea la única representación de sus miembros, proporciona el nombre de cada miembro mediante `imageProps.alt` para etiquetar la imagen y el recurso alternativo predeterminado. Mantén los avatares decorativos cuando el texto visible o una etiqueta de propietario ya proporcione esa identidad.

## Opciones visuales

Compara avatares circulares y cuadrados en cada tamaño. El grupo mantiene tres miembros visibles en esta comparación.

**Light**

[Compara formas y tamaños de avatar (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Compara formas y tamaños de avatar (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)

## Colecciones cargadas parcialmente

Use `total` para el tamaño completo de la colección cuando solo se hayan cargado algunos avatares. Tres avatares proporcionados y visibles con `total={20}` muestran `+17`. Pase todos los avatares cargados y deje que el grupo aplique `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` se redondea hacia abajo y no puede ser menor que el número de avatares renderizables proporcionados. Los totales no finitos usan el recuento proporcionado. El recuento derivado de elementos ocultos siempre es no negativo.

`maxVisible` tiene como valor predeterminado `4`. Los límites finitos se redondean hacia abajo y se restringen a cero, `Infinity` muestra todos los avatares proporcionados y `NaN` no muestra ninguno. Los nodos de React vacíos no cuentan como avatares. Un límite de cero puede mostrar solo el indicador de desbordamiento. Un grupo vacío con un total positivo puede mostrar ese total en su indicador; un grupo vacío sin avatares ocultos no renderiza nada.

**Light**

[Tres miembros cargados de un equipo de veinte (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--partially-loaded\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Tres miembros cargados de un equipo de veinte (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)

## Desbordamiento personalizado

`renderOverflow` recibe el mismo recuento derivado de elementos ocultos que el indicador predeterminado `+N`. Solo se ejecuta cuando ese recuento es positivo. Devuelva `null` para ocultar el indicador sin cambiar qué avatares son visibles.

Use un control explícito cuando el indicador realice una acción. Su nombre accesible debe explicar la acción y el recuento.

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

[Botón de desbordamiento personalizado (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatargroup--custom-overflow\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Botón de desbordamiento personalizado (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)

## Apariencia

Los avatares posteriores siempre se renderizan encima de los anteriores. `overlap` elige el margen físico, `left` o `right`, que lleva el desplazamiento negativo. `overlapOffset` establece ese desplazamiento como una longitud CSS. `overflowShape` establece la forma del indicador numérico predeterminado.

## Personalización de la raíz

Los atributos nativos, los controladores de eventos, `className` y `style` llegan a la raíz. Su elemento predeterminado es un `div`, incluso cuando se proporciona `onClick`. Use elementos interactivos nativos para las acciones, como el botón de desbordamiento anterior.

La raíz acepta una ref y `render`, que puede ser un elemento o una función. Los componentes personalizados deben reenviar las props proporcionadas y la ref a su raíz nativa. Consulte [componentes personalizados](https://docs.twenty.com/es/ui/primitives/overview#custom-components) para conocer los requisitos de composición.

```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 }} />
      ))}
    />
  );
};
```

## "Props"

`AvatarGroupProps` se exporta desde `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.