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

# Avatar

> Represente a una persona o un registro con una imagen, inicial o icono.

## Resumen

`Avatar` muestra una imagen con una alternativa de primera letra. Úselo junto al nombre de un registro o dentro de un [Chip](https://docs.twenty.com/es/ui/primitives/data-display/chip.md). Su raíz predeterminada es un `span` de presentación.

**Light**

[Ejemplo de Avatar (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Ejemplo de Avatar (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--display\&viewMode=story\&globals=colorScheme:dark)

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

## "Uso"

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

export const WorkspaceAvatar = () => (
  <Avatar
    name="Acme"
    colorSeed="acme-app"
    shape="square"
    variant="outline"
    size="md"
  />
);
```

Cuando la imagen no está presente o no se puede cargar, la alternativa muestra en mayúscula la primera letra del nombre sin espacios al inicio ni al final. Un nombre vacío muestra `-`. `colorSeed` elige colores de alternativa estables y su valor predeterminado es `name`; use un identificador de registro para mantener el color estable cuando cambie el nombre.

La imagen y el respaldo predeterminado son decorativos. `name` proporciona la inicial visual y los colores de respaldo sin añadir una etiqueta accesible. Cuando el avatar es la única representación de una persona o un registro, establece `imageProps={{ alt: name }}` para etiquetar tanto la imagen como el respaldo predeterminado. Mantén el avatar como decorativo cuando un nombre visible o un propietario etiquetado ya proporcionen esa información.

`imageProps` acepta el contrato completo de imagen, incluidos `srcSet`, `sizes`, `crossOrigin`, `referrerPolicy`, eventos nativos, refs y `render`. Su `src` anula la abreviatura `src`. `fallbackProps` acepta el contrato completo de respaldo, incluidos `delay`, elementos secundarios, etiquetado, refs y `render`. Un `render` de respaldo personalizado gestiona su semántica de accesibilidad; establece explícitamente `aria-hidden` cuando sea decorativo.

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

type RecordAvatarProps = {
  name: string;
  imageUrl?: string;
  initials: string;
};

export const RecordAvatar = ({
  name,
  imageUrl,
  initials,
}: RecordAvatarProps) => (
  <Avatar
    name={name}
    src={imageUrl}
    size="lg"
    imageProps={{ alt: name, decoding: 'async', referrerPolicy: 'no-referrer' }}
    fallbackProps={{ children: initials, delay: 150 }}
  />
);
```

## Compón las partes

Usa `Avatar.Root`, `Avatar.Image` y `Avatar.Fallback` cuando controles la anatomía. Root proporciona el tamaño, la forma y la apariencia del respaldo; no genera elementos secundarios ni etiquetas accesibles.

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

type ContactAvatarProps = {
  name: string;
  imageUrl?: string;
  initials: string;
};

export const ContactAvatar = ({
  name,
  imageUrl,
  initials,
}: ContactAvatarProps) => (
  <Avatar.Root name={name} shape="circle" size="xxl">
    <Avatar.Image src={imageUrl} alt={name} decoding="async" />
    <Avatar.Fallback role="img" aria-label={name} delay={150}>
      {initials}
    </Avatar.Fallback>
  </Avatar.Root>
);
```

**Light**

[Partes del avatar (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--parts\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Partes del avatar (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--parts\&viewMode=story\&globals=colorScheme:dark)

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

Las partes comparten el estado de carga de imágenes de Base UI. Image procesa un `img` después de una carga correcta de forma predeterminada, y Fallback procesa un `span` mientras la imagen está ausente, cargándose o ha fallado. `delay` pospone la visualización inicial del respaldo en milisegundos y su valor predeterminado es `0`. Una fuente modificada se vuelve a cargar y puede reemplazar la imagen actual o el respaldo.

`Avatar.Image` expone `onLoadingStatusChange` con los valores de estado `idle`, `loading`, `loaded` y `error`. La devolución de llamada se ejecuta cuando Base UI informa de un cambio de estado distinto de inactivo; desmontar la parte Image restablece el estado raíz compartido a `idle`. Root, Image y Fallback aceptan funciones de `className`, `style` y `render` que reconocen el estado con `imageLoadingStatus`; Image también expone `transitionStatus`.

Usa `keepMounted` en Image cuando la imagen procesada deba cargarse en su lugar, incluido `loading="lazy"` o un componente de imagen optimizado. Reenvía los atributos nativos, los eventos y la ref desde procesadores de imágenes personalizados. Una imagen montada aún puede estar cargándose o haber fallado; inspecciona el estado de carga en lugar de considerar su presencia como un éxito.

El procesador del componente frontal actualmente admite la ruta de precarga predeterminada con `src`. Su imagen host no recibe `srcSet`, `sizes`, `loading`, `decoding` ni `referrerPolicy`. Una función `render` personalizada cambiante con `keepMounted` puede dejar oculta una imagen decodificada porque el trabajador no puede leer su estado de finalización ni sus dimensiones. Usa allí la precarga predeterminada hasta que esas capacidades del procesador estén disponibles.

Los tipos públicos `AvatarRootProps`, `AvatarImageProps`, `AvatarFallbackProps`, `AvatarRootState`, `AvatarImageState`, `AvatarFallbackState` y `AvatarImageLoadingStatus` se exportan desde `twenty-ui/primitives/data-display`. Las refs se dirigen al elemento DOM procesado: `span`, `img` y `span` de forma predeterminada, o al elemento proporcionado mediante `render`.

## Forma y apariencia

**Light**

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

**Dark**

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

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

`shape` acepta `square`, `rounded-square` o `circle`. Los tamaños son `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px) y `xxl` (40px). Tanto `xl` como `xxl` usan texto alternativo de 16px.

El anterior tamaño `xl` de 40px ahora es `xxl`. Actualiza los usos existentes de `size="xl"` a `size="xxl"` cuando deban seguir siendo de 40px.

`variant="outline"` añade un borde a la alternativa. Las anulaciones de `color`, `backgroundColor` y `borderColor` personalizan la alternativa, mientras que una imagen cargada mantiene su apariencia original.

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

export const ContactIcon = () => (
  <Avatar
    icon={<IconUser />}
    shape="rounded-square"
    size="xxl"
    role="img"
    aria-label="Contact"
  />
);
```

Un `icon` tiene prioridad sobre la imagen y la alternativa de primera letra. El icono en sí es decorativo, así que etiqueta la raíz cuando transmita información. `pulsing` anima la opacidad y respeta las preferencias de movimiento reducido.

## Abrir un perfil

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

type ProfileAvatarProps = {
  onOpenProfile: () => void;
  disabled?: boolean;
};

export const ProfileAvatar = ({
  onOpenProfile,
  disabled = false,
}: ProfileAvatarProps) => (
  <Avatar
    name="Jane"
    shape="circle"
    size="lg"
    render={
      <button
        type="button"
        disabled={disabled}
        aria-label="Open Jane's profile"
        onClick={onOpenProfile}
      />
    }
  />
);
```

**Light**

[Avatar compuesto como botón (light)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--button-composition\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Avatar compuesto como botón (dark)](https://storybook.twenty.com/iframe.html?id=ui-data-display-avatar--button-composition\&viewMode=story\&globals=colorScheme:dark)

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

Compón un botón nativo para las acciones. Gestiona el foco, la activación con Intro y Espacio, y el comportamiento deshabilitado. Proporciona un nombre accesible específico para la acción. Coloca `onClick` y `disabled` en el botón procesado; el Avatar abreviado no tiene la prop `onClick`, `disabled` ni `nativeButton`.

Para la navegación, compón un ancla con un `href` o un enlace de enrutador que preserve la semántica de ancla. Los enlaces nativos se activan con Intro. Mantén la navegación y el comportamiento deshabilitado con el enlace o componente interactivo que compongas.

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

export const ProfileLink = () => (
  <Avatar
    name="Jane"
    shape="circle"
    size="lg"
    render={<a href="/people/jane" aria-label="Open Jane's profile" />}
  />
);
```

## Migra los avatares en los que se puede hacer clic

Compón un botón nativo mediante `render` para las acciones, o un ancla o enlace de enrutador para la navegación. Mueve `onClick` y `disabled` a ese propietario y elimina `nativeButton`. Proporciona al propietario un nombre accesible útil y evita anidar elementos interactivos. `Avatar.Root` y las demás partes explícitas conservan el contrato completo de eventos de Base UI.

Los avatares abreviados son decorativos de forma predeterminada. `name` no da nombre a la imagen, al respaldo ni al propietario interactivo. Usa un `imageProps.alt` no vacío solo cuando el avatar transmita una identidad que no esté ya proporcionada por texto visible o una etiqueta del propietario. Con partes explícitas, proporciona tú mismo el texto alternativo de la imagen y las etiquetas de respaldo o los atributos decorativos, y conserva el contenido traducido en tu aplicación.

## "Props"

Los tipos y valores predeterminados se generan a partir de los tipos de componentes públicos. Las partes explícitas aceptan atributos nativos y controladores de eventos. El Avatar abreviado omite `onClick`; proporciónalo en el propietario pasado mediante `render`.

**backgroundColor** `string`

Background color override for a first-letter fallback.

**borderColor** `string`

Border color override for the outline fallback.

**className** `string | ((state: AvatarRootState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**color** `string`

Text color override for a first-letter fallback.

**colorSeed** `string`

Stable value used to choose fallback colors. Defaults to `name`.

**fallbackProps** `AvatarFallbackProps`

Complete `Avatar.Fallback` props, including caller-owned children, labeling, refs, `render`, and fallback `delay` in milliseconds.

**icon** `ReactNode`

Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information.

**imageProps** `AvatarImageProps`

Complete `Avatar.Image` props, including native image attributes, refs, `render`, `keepMounted`, and `onLoadingStatusChange`. Alternative text defaults to an empty string. Supply a nonempty `alt` to label the image and default fallback.

**name** `string`

Name used for the first-letter fallback and fallback colors. Does not add an accessible label.

**pulsing** `boolean` (default: false)

Animates the avatar opacity. Respects reduced-motion preferences.

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

Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.

**ring** `boolean` (default: false)

Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.

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

Shape of the avatar and its fallback.

**size** `"lg" | "md" | "sm" | "xl" | "xs" | "xxl"` (default: md)

Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px).

**src** `string | null`

Image URL. A missing or failed image shows the fallback. `imageProps.src` overrides this value.

**style** `CSSProperties | ((state: AvatarRootState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**variant** `"outline" | "soft"` (default: soft)

Visual treatment of the fallback.

### Avatar.Root

**Root.backgroundColor** `string`

Background color override for a first-letter fallback.

**Root.borderColor** `string`

Border color override for the outline fallback.

**Root.children** `ReactNode`

Caller-owned Image, Fallback, and other content.

**Root.className** `string | ((state: AvatarRootState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Root.color** `string`

Text color override for a first-letter fallback.

**Root.colorSeed** `string`

Stable value used to choose fallback colors. Defaults to `name`.

**Root.name** `string`

Name used to choose fallback colors. Does not add children or accessible labels.

**Root.pulsing** `boolean` (default: false)

Animates the avatar opacity. Respects reduced-motion preferences.

**Root.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, AvatarRootState\>`

Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.

**Root.ring** `boolean` (default: false)

Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.

**Root.shape** `"circle" | "rounded-square" | "square"` (default: square)

Shape of the avatar and its fallback.

**Root.size** `"lg" | "md" | "sm" | "xl" | "xs" | "xxl"` (default: md)

Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), `xl` (32px), or `xxl` (40px).

**Root.style** `CSSProperties | ((state: AvatarRootState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**Root.variant** `"outline" | "soft"` (default: soft)

Visual treatment of the fallback.

### Avatar.Image

**Image.alt** `string`

Caller-owned alternative text. Use an empty string for decorative images.

**Image.className** `string | ((state: AvatarImageState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Image.crossOrigin** `"" | "anonymous" | "use-credentials"`

Native image cross-origin policy, also used during preloading.

**Image.keepMounted** `boolean` (default: false)

Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown.

**Image.loading** `"eager" | "lazy"`

Native eager or lazy loading. Use keepMounted for lazy loading.

**Image.onLoadingStatusChange** `((status: ImageLoadingStatus) =\> void)`

Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback.

**Image.referrerPolicy** `"" | "no-referrer-when-downgrade" | "no-referrer" | "origin-when-cross-origin" | "origin" | "same-origin" | "strict-origin-when-cross-origin" | "strict-origin" | "unsafe-url"`

Native image referrer policy, also used during preloading.

**Image.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<DetailedHTMLProps\<ImgHTMLAttributes\<HTMLImageElement\>, HTMLImageElement\>, AvatarImageState\>`

Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref.

**Image.sizes** `string`

Native responsive image sizes used with srcSet.

**Image.src** `string`

Image URL. Image renders after a successful load unless keepMounted is enabled.

**Image.srcSet** `string`

Native responsive image source candidates.

**Image.style** `CSSProperties | ((state: AvatarImageState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### Avatar.Fallback

**Fallback.children** `ReactNode`

Caller-owned fallback content, such as initials or an icon.

**Fallback.className** `string | ((state: AvatarFallbackState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Fallback.delay** `number` (default: 0)

Milliseconds before the initial fallback is shown. Defaults to 0.

**Fallback.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, AvatarFallbackState\>`

Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes.

**Fallback.style** `CSSProperties | ((state: AvatarFallbackState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.


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