Skip to content
Nexus Application Design nadesign

Avatar

<Avatar> renders the portrait of a person or entity. If the image fails to load (or hasn’t loaded yet), the fallback shows — almost always initials.

import from "@na/ui/components/avatar" ▶ Open in Storybook packages/ui/src/components/avatar.tsx

When to use

  • A person attached to a record (deal owner, comment author).
  • The current workspace identity in a header.
  • Any list row where seeing the human helps the scan.

Don’t use Avatar for: a logo (use a plain <img> or <Logo> if it exists), a generic decorative icon (use @na/icons).

Sizes

SMMDLG
 
<Avatar size="sm" />   {/* 24px */}
<Avatar />             {/* 32px — default */}
<Avatar size="lg" />   {/* 40px */}

Image + fallback

The fallback shows automatically when the image is unavailable — no manual error handling required.

ALBO
 
<Avatar>
  <AvatarImage src="https://…" alt="Alice" />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>

With badge

<AvatarBadge> is a small dot or icon overlaid on the avatar — common for online status, verification ticks, or unread indicators.

AL 
<Avatar>
  <AvatarFallback>AL</AvatarFallback>
  <AvatarBadge><IconCheck /></AvatarBadge>
</Avatar>

Group

<AvatarGroup> overlaps avatars with a ring matching the surface. Use <AvatarGroupCount> for the truncation marker.

ALBOCA
+4
 
<AvatarGroup>
  <Avatar><AvatarFallback>AL</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>BO</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>CA</AvatarFallback></Avatar>
  <AvatarGroupCount>+4</AvatarGroupCount>
</AvatarGroup>

API

Avatar

Prop Type Default Description
size "sm" | "default" | "lg" "default" 24 / 32 / 40 px square.
className string — Forwarded.

AvatarImage

Prop Type Default Description
src * string — Image URL.
alt * string — Alt text — the person/entity name. Never empty.

AvatarFallback

Prop Type Default Description
children ReactNode — Usually initials. 1–2 characters.
delayMs number — Wait this long before showing the fallback (avoids flash for images that load fast).

Design guidelines

✓ Do

  • Always supply an AvatarFallback. Network is unreliable; the image will fail eventually.
  • Initials = first letter of first and last name. "Alice Lee" → AL.
  • Use AvatarGroup when more than 2 people share a row item — anything else is visual noise.

✗ Don't

  • Use Avatar for a brand logo. Avatars are for people; logos are flat.
  • Color initials by hash. The contrast floor (4.5:1) is hard to guarantee — stick to bg-muted text-muted-foreground.
  • Stack avatars without ringing them against the background. The ring is what makes overlap readable.

Accessibility

  • <AvatarImage alt="…"> is required — never empty.
  • The fallback is aria-hidden since the alt text on the image carries the person’s name.
  • <AvatarBadge> is decorative — wrap meaningful badges in a tooltip or surround text instead of relying on color.
  • Tooltip — Wrap an Avatar to show the full name on hover in tight rows.
  • HoverCardPreview — For richer entity previews.

▶ Open Avatar stories in Storybook