Avatar

Overview

An avatar identifies a person, an organisation, or a system actor at a glance. It's the smallest piece of identity in the product — a 24 px chip in a comment row, a 72 px hero on a profile page, or anything in between. Five sizes, four content shapes (image, initial, icon, fallback), three optional status badges. The component does identification, not branding; it stays quiet and consistent across surfaces.

Anatomy

Three parts — a circular surface, the content inside, and an optional status badge anchored at the top-right corner. Everything beyond that (a name, a role, a timestamp) is the responsibility of the surrounding row, not the avatar itself.

Sizes

Five sizes — 24 / 32 / 40 / 56 / 72 px. The default is md (40 px) and covers activity feed rows, transfer items, and most product list contexts. Pick a size that matches the type next to the avatar, never the surrounding container.

Content shapes

Four content shapes, ordered by fidelity: image > initial > icon > fallback. Reach for the highest-fidelity shape your data actually supports — don't default to a fallback when you have a name to derive an initial from.

A

?

Status badge

Three status badges — success (green), warning (yellow), danger (red). Each carries a single white glyph at a size proportional to the avatar. The badge is decorative; the meaning belongs to the copy that names the state. A green dot alone is decoration; a green dot next to “Online” is information.

Group

When several people share a context — a project team, the reviewers on a transfer, a multi-author commit — render the avatars as an overlapping stack. Cap visible avatars at four; everything past that becomes a +N pill at the end of the stack.

Avatar block

Avatar + name + secondary metadata (role, timestamp, status) is the most common pairing in the product. The block isn't a separate component — it's a layout pattern: 12 px gap, two-line stack on the right, name in foreground semibold, meta in 12 px muted.

Behavior

• 01Falls through gracefully. When the image fails to load, the avatar falls back to the initial. When there's no initial, it falls back to the icon. When there's no icon, it shows the person glyph. The component never renders empty.
• 02Single character only. Even when the source name is “Anders Holm”, the initial is “A”. Two letters force the type to overflow at smaller sizes; the surrounding label carries the full name.
• 03Square crops only. Images are cropped to the centre square via object-cover before being clipped to the circle. Don't feed pre-cropped non-square images — the avatar will distort.
• 04Group overlap is fixed at 30%. Each avatar in the group sits 30% behind the previous one. Less and the stack reads as separate avatars; more and the faces disappear behind each other.
• 05Avatars don't scale on hover. They're identification, not interaction. If the avatar is a link or button, the wrapping element handles the hover treatment — not the avatar itself.

Accessibility

• Decorative by default. When the avatar pairs with a visible name (the avatar block pattern), the avatar itself is aria-hidden="true" and the name carries identity. Don't announce the same person twice.
• Standalone gets a label. When the avatar is the only thing identifying the person (a comment thread author chip, a hover card trigger), set role="img" and aria-label with the full name.
• Image alt stays empty on the underlying <img> — the wrapping aria-label already names the person. A screen reader doesn't need to hear “photo of Mira” followed by “Mira”.
• Status badgesare paired with copy elsewhere on the surface — “Mira (online)” in the label, never colour alone. The badge itself carries aria-hidden="true" because the meaning lives in the text.
• Groups carry a single label on the wrapping role="group" — “Project team, 12 people” — instead of announcing each avatar separately. Tab moves through interactive avatars inside the group; non-interactive avatars are skipped.
• Touch target:for interactive avatars (a chip that opens a profile, a clickable group member), make the actual hit area at least 44 px regardless of the avatar's visual size. The 24 px and 32 px sizes can't be the entire click target.

Code

One Avatar component handles every content shape. The AvatarGroup wrapper handles the stack + overflow.

import { Avatar, AvatarGroup } from "@flatpay-dk/ui";

// Image — the highest-fidelity shape
<Avatar size="md" src="/avatars/mira.jpg" label="Mira Berg" />

// Initial — derived from the name's first letter, single character only
<Avatar size="md" initial={name[0]} label={name} />

// Icon — for system actors, anonymous users, role-not-person
<Avatar size="md" icon={<RobotIcon />} label="Automation system" />

// Fallback — when there's no name, no image, no role
<Avatar size="md" label="Unknown contributor" />

// Status badge — pairs with copy that names the state
<Avatar size="md" initial="M" status="success" label="Mira (online)" />

// Group with overflow
<AvatarGroup size="md" max={4} total={12} label="Project team">
  {members.map((m) => (
    <Avatar key={m.id} initial={m.name[0]} src={m.photo} label={m.name} />
  ))}
</AvatarGroup>

// Block pattern — avatar + name + meta
<div className="flex items-center gap-3">
  <Avatar size="md" initial="A" label="Anders Holm" />
  <div>
    <p className="text-sm font-semibold">Anders Holm</p>
    <p className="text-xs text-muted-foreground">Repo owner</p>
  </div>
</div>

Best practices

Avatars carry identity at a glance. The defaults below keep them legible and consistent across hundreds of rows.

Props

Avatar

AvatarGroup

Related