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.

Install

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

Example

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

alt

Type: 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

Type: string

Layout only: margins, grid placement (ms-2). Appearance classes warn in development; use size.

color

Type: "colorful" | "brand" | "neutral"

Default: "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

Type: 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

Type: 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

Type: 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)

Type: 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

Type: string

Default: "Name loading"

What screen readers hear while name is null, for other languages.

ref

Type: Ref<HTMLSpanElement>

Reaches the rendered element.

shape

Type: "circle" | "square" | "hexagon"

Default: "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

Type: "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | "3xl"

Default: "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

Type: 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

presence (required)

Type: "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)

Type: 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

presenceLabel

Type: 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.