---
title: Avatar
description: Represent a person or record with an image, initial, or icon.
---

import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';

import AvatarReference from '/snippets/ui/generated/data-display/avatar.mdx';

`Avatar` shows an image with a first-letter fallback. Use it beside a record name or inside a [Chip](/ui/primitives/data-display/chip).

<StoryEmbed storyId="ui-data-display-avatar--app" title="Avatar example" />

## Image and fallback

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

type PersonAvatarProps = { name: string; imageUrl?: string | null };

export const PersonAvatar = ({ name, imageUrl }: PersonAvatarProps) => (
  <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
    <Avatar src={imageUrl} name={name} shape="circle" size="lg" />
    {name}
  </span>
);
```

When the image is absent or fails to load, the fallback shows the first letter of the trimmed name in uppercase. An empty name shows `-`. `colorSeed` chooses stable fallback colors and defaults to `name`; use a record identifier to keep the color stable when the name changes.

The image and fallback are decorative. Keep the visible name beside the avatar, as above. For a standalone avatar that conveys information, supply `role="img"` and an `aria-label`.

## Shape and appearance

`shape` accepts `square`, `rounded-square`, or `circle`. Sizes run from `xs` (12px) to `xl` (40px); `md` is 16px. `variant="outline"` adds a border to the fallback. The `color`, `backgroundColor`, and `borderColor` overrides customize the fallback, while a loaded image keeps its original appearance.

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

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

An `icon` takes precedence over both the image and the first-letter fallback. `pulsing` animates opacity and respects reduced-motion preferences.

## Open a profile

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

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

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

Supplying `onClick` renders a button with pointer, Enter, and Space activation. Use `disabled` to prevent activation. The default accessible name comes from `name`, but an action-specific `aria-label` makes the purpose clearer. When replacing the button through `render`, set `nativeButton={false}` for a non-button element.

## Props

Types and defaults are generated from the public component types. Native attributes and event handlers are also accepted.

<AvatarReference />