Chapter 12: Avatar

Core Idea

An image element with a built-in fallback for representing a user — handles the load/error states images need but native <img> doesn't expose cleanly.

Key Concepts

• Anatomy: Root → Image + Fallback.
• Image: renders only once loaded by default; onLoadingStatusChange gives finer control if needed.
• Fallback: renders while loading or on error; accepts any children (initials, icon, skeleton). delayMs defers its render to avoid a flash for fast connections.

Code Examples

import { Avatar, Tooltip } from "radix-ui";

<Tooltip.Root>
  <Tooltip.Trigger>
    <Avatar.Root>
      <Avatar.Image src="..." />
      <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
    </Avatar.Root>
  </Tooltip.Trigger>
  <Tooltip.Content side="top">Tooltip content<Tooltip.Arrow /></Tooltip.Content>
</Tooltip.Root>

• What it demonstrates: composing Avatar with Tooltip, and using delayMs to skip the fallback flash on fast connections.

Key Takeaways

1. Use Fallback's delayMs (e.g. 400-600ms) to avoid a jarring flash-of-fallback on fast networks where the image loads almost instantly.
2. Fallback covers both the loading state and the error state (broken image URL) with one element — no separate error handling needed.
3. Avatar composes cleanly with other primitives (shown here with Tooltip) since it's just a Root/child structure like everything else in the library.

Connects To

• Tooltip: shown composed with Avatar for a common "show name on hover" pattern.
• Aspect Ratio: another minimal single-purpose primitive.