Skip to content
flyingsalmon

Avatar

An avatar is the identity mark for one person: a photo when there is one, initials when there is not.

Brian NguyenLTMP

Installation

npx shadcn@latest add @flyingsalmon/avatar

Usage

import type { AvatarColor } from '@/components/ui/avatar'
import { Avatar } from '@/components/ui/avatar'

interface Traveller {
  name: string
  photoUrl?: string
  color: AvatarColor
}

export function TravellerAvatar({ traveller }: { traveller: Traveller }) {
  return (
    <Avatar
      src={traveller.photoUrl}
      name={traveller.name}
      color={traveller.color}
    />
  )
}

Examples

Sizes

Default sits in a toolbar or a menu; small fits a dense row such as a comment list or a table cell.

Brian NguyenBrian NguyenBNBN

Fallback chain

From left: a photo, a photo that failed to load, initials from a long name, initials from a one-word name, and an empty coloured circle when there is no name. The avatar keeps its box while an image loads, so a row never shifts.

Brian NguyenLinh TranHLM

Colours

Pick the colour from a stable key such as a traveller's id, so the same person keeps the same colour everywhere. With no colour the circle is neutral.

BNLTMPHLAVKDG

Name beside the avatar

Pass alt="" when the name is already written next to the avatar. The avatar leaves the accessibility tree and a screen reader reads the name once.

Linh Tran

Inside a button

An avatar never takes focus, so a click target wraps it. The button owns the focus ring and the keyboard path.

Guidelines

When to use

  • To mark one person: the signed-in traveller in the sidebar, an author on a comment, an assignee on a row.
  • Beside the person’s name, or alone when the name appears elsewhere on the screen.

When not to use

  • Use Avatar group to show several people as one cluster, because it overlaps the faces and folds the rest into a count.
  • Use Badge for a status or a count, because an avatar is a person and never reads as a state.
  • Use Button when a click must do something, by wrapping the avatar rather than using it bare.

Do and don’t

  • Do
    Give a person the same colour on every screen.A person whose colour changes between pages reads as a different person.
  • Don’t
    Colour an avatar when nobody on the screen needs telling apart.Colour exists to separate people. One person beside their name needs none, and the neutral circle keeps the eye on the name.
  • Do
    Use the small avatar beside a name in navigation and list rows, and the default size where the person is the subject.In a row the name identifies the person and the face is a glance, so it stays below the height of the text beside it.
  • Don’t
    Use an orange or a status colour for a person.Orange is the brand and the status hues report state, so the six group colours leave them out and an avatar never reads as an action or a warning.

Accessibility

The avatar takes no focus and sits in no tab order. A photo uses alt as its alt text; the initials fallback carries role="img" with the same label, so a screen reader names the person either way. alt defaults to name. Pass alt="" when the name is written beside the avatar, and the avatar then drops out of the accessibility tree.

The avatar is a mark, not a control. When a click must do something, wrap it in a button or a link, and the wrapper owns the focus ring and the tab stop.

Contrast on the six colours and the neutral circle passes WCAG AA.

API

Avatar

Also takes every <span> attribute except color.

PropTypeDefaultDescription
srcstring–The image URL. The image shows once it loads; until then, and if it fails, the avatar shows the fallback.
namestring–The person’s name. Feeds the default alt text and the initials: the first letters of the first and last words, one letter for a one-word name. Pass it even with a photo, so a failed image still identifies the person.
altstringnameThe accessible name. Pass an empty string when the name sits beside the avatar as text.
colorAvatarColor–Sky, Pink, Teal, Fuchsia, Cyan, or Blue. Colours the fallback circle only; with no colour the circle is neutral. Derive it from a stable key, such as a user id, so a person keeps one colour.
sizeAvatarSizeAvatarSize.DefaultDefault or Small.

avatarVariants is exported too, to draw the avatar circle in its sizes on an element of your own.

  • Avatar group

    Overlaps several avatars and folds the rest into a count.
  • Button

    The wrapper that makes an avatar clickable.
  • Badge

    The marker for a status or a count.
  • Accessibility

    How the registry measures contrast and keyboard paths.
  • Colours

    The six group colours an avatar draws from.