<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# Avatar

A person's picture, or their initials until it loads or when it fails, in a color picked from the name. `name` is required: screen readers hear it, and the initials come from it. `presence` adds a status dot that says what it shows (`presenceLabel`), and `shape="square"` marks a team, a channel, an app or a bot, and `shape="hexagon"` an AI agent. Built on Base UI's Avatar, so server HTML holds the initials and the picture replaces them at full strength the moment it loads, with no fade: a picture already in the browser's cache is there on the avatar's first frame.

```tsx
import { Avatar } from "@/components/ouro/avatar/avatar";
```

## Example

```tsx
<Avatar name="Ana Lind" src={user.photoUrl} presence="busy" presenceLabel="In a meeting" />
<Avatar name="Grace Hopper" size="lg" idForColor={user.id} />
<Avatar name="Design reviews" shape="square" />
<Avatar name="Halden" shape="hexagon" src={agent.photoUrl} />
<span className="flex items-center gap-2"><Avatar name={user.name} alt="" size="sm" />{user.name}</span>
```

## Usage

The initials are drawn, not written: CSS generated content from a data attribute, which paints exactly as text did but is no text in the page. So a link or button that wraps the avatar and names itself (`<a aria-label="Ana Lind's profile">`) shows no visible text its name must hold, and passes axe's `label-content-name-mismatch` (WCAG 2.5.3, Label in Name); without a name of its own, it takes the avatar's: the person's name, never the letters. In a test, find an avatar by its role and name (`getByRole("img", { name: "Ana Lind" })`), not by its letters.

## Use instead when

- Use `AvatarGroup` instead to stack several, and `Badge` for a status label that isn't a person.

## Props

The props the modes share. Type: `AvatarProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` | `string` |  | What screen readers hear, when it should differ from `name`. Pass `alt=""` when the name is already written next to the avatar, so it isn't read twice. |
| `className` | `string` |  | Layout only: margins, grid placement (`ms-2`). Appearance classes warn in development; use `size`. |
| `color` | `"colorful" \| "brand" \| "neutral"` | `"colorful"` | How the initials are colored. `"colorful"` picks one of eight hues from `idForColor` (else `name`), so the same person always gets the same one, and the initials keep at least 4.5:1 against it in light and dark. `"brand"` tints with the theme's primary; `"neutral"` is the plain secondary surface. The hues are the theme tokens `--avatar-1` to `--avatar-8` (`ouro-base`). |
| `icon` | `ReactNode` |  | An icon to show in place of the initials, such as a calendar for a meeting or a note for notes to self. It is decorative: the avatar's label stays `name`. |
| `idForColor` | `string` |  | What `color="colorful"` picks the hue from, when it should not be `name`: a stable id, so people who share a name can differ and a rename keeps the color. |
| `initials` | `string` |  | The letters to show instead of the ones taken from `name`, such as "AnL". Like the initials taken from `name`, they are drawn (CSS generated content), not written as text. |
| `name` (required) | `string \| null` |  | The person's or thing's name. Screen readers hear it, and the initials come from it (the first letters of the first and last words) until the image loads, or when it fails. Required, so no avatar is silent. Pass `null` while the name is still loading: the avatar keeps its size and shape and shimmers as a Skeleton, and screen readers hear `nameLoadingLabel`. |
| `nameLoadingLabel` | `string` | `"Name loading"` | What screen readers hear while `name` is `null`, for other languages. |
| `ref` | `Ref<HTMLSpanElement>` |  | Reaches the rendered element. |
| `shape` | `"circle" \| "square" \| "hexagon"` | `"circle"` | `"circle"` for a person, `"square"` (rounded on the theme's radius) for a team, a channel, an app or a bot, `"hexagon"` (with rounded corners) for an AI agent, as Teams draws agents. The initials, icon or picture fill the shape, centered. A hexagon shows no presence dot: an agent has no presence. |
| `size` | `"sm" \| "md" \| "lg" \| "xs" \| "xl" \| "2xl" \| "3xl"` | `"md"` | 24, 32, 40, 48, 64, 72 or 112px (`2xl` and `3xl` for profile pages); the initials and the presence dot grow with it. Inside an `AvatarGroup`, the group's size applies. |
| `src` | `string` |  | The image URL. Until it loads, and if it fails, the initials show. |

## Modes

`AvatarProps` is a union: pass the props of exactly one mode. Mixing them is a type error.

### With `presence` and `presenceLabel`

| Prop | Type | Description |
| --- | --- | --- |
| `presence` (required) | `"offline" \| "available" \| "busy" \| "away" \| "do-not-disturb" \| "out-of-office"` | The person's presence, as a dot on the lower end corner. Each state has its own shape and a named tone (available: success; busy and do not disturb: destructive; away: warning; offline: muted; out of office: primary). The dot's ring takes the surface's color, `--ouro-avatar-ring` (default `--background`): set it on a card, `[--ouro-avatar-ring:var(--card)]`. The dot lies over the corner and takes no room, so the initials, icon or picture stay in the middle with or without it, and the dot stays below the letters at every size. |
| `presenceLabel` (required) | `string` | What the dot says, such as "Busy" or "In a meeting": screen readers hear it after the name ("Ana Lind, Busy"). Required with `presence`, so no dot is silent. |

### With `presenceLabel`

| Prop | Type | Description |
| --- | --- | --- |
| `presenceLabel` | `string` | Read only with `presence`. |

Not in this mode (typed `never`):

- `presence`: Leave it out for no dot; pass it with `presenceLabel` to show one.

## Native attributes

Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `children`: Not a prop. The initials come from `name`, or pass `initials`: `<Avatar name="Ana Lind" initials="AL" />`.
- `fallback`: Not a prop. The initials come from `name`, or pass `initials`: `<Avatar name="Ana Lind" initials="AL" />`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: Avatar merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

[^layout-classes]: test:registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > forwards a ref and lets app layout classes win verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > forwards a ref and lets app layout classes win)