Component · 19

Avatar

A person's picture that never leaves a hole: if the image is missing or fails to load, their initials take its place. Flat and ruled, because an avatar is not something you press. Built on Base UI.

Picture and initials

The first has a picture; the second has none; the third points at an image that does not exist, so it falls back too.

tsx

<Avatar alt="Ada Lovelace" src={picture} />
<Avatar alt="Nguyễn Đại Dương" />
<Avatar alt="Alan Turing" src="/missing.png" />

Sizes and shapes

tsx

<Avatar alt="Ada Lovelace" size="sm" />
<Avatar alt="Ada Lovelace" size="md" />
<Avatar alt="Ada Lovelace" size="lg" />
<Avatar alt="Ada Lovelace" size="xl" shape="square" />

A group

Overlapping, each cut out of the one beneath by a ring in the colour of what it sits on (set --gu-avatar-ring). Give the group a name that says who they are.

tsx

<AvatarGroup aria-label="Reviewers" style={{ "--gu-avatar-ring": "var(--gu-surface)" }}>
  <Avatar alt="Ada Lovelace" src={picture} />
  <Avatar alt="Alan Turing" />
  <Avatar alt="Grace Hopper" />
  <Avatar alt="3 more reviewers" fallback="+3" />
</AvatarGroup>

Folding the rest into a count

With max, the others become one avatar that says how many are left, and is named, for example, 3 more.

tsx

<AvatarGroup aria-label="Reviewers" max={3} size="lg">
  {people.map((name) => <Avatar key={name} alt={name} />)}
</AvatarGroup>

Beside a name

When the name is already written next to it, mark the avatar decorative so it is not read twice.

Ada Lovelace

tsx

<div className="flex items-center gap-3">
  <Avatar alt="Ada Lovelace" decorative />
  <span>Ada Lovelace</span>
</div>

Props

Prop	Type	Default	Description
alt	string	required	The name. It is the avatar's accessible name whether or not the picture loads.
src	string	-	The picture. Missing or failing to load shows the initials.
fallback	string	from alt	Initials to show instead. By default the first letters of the first and last words of alt.
size	"sm" \| "md" \| "lg" \| "xl"	"md"	2rem, 2.5rem, 3.5rem or 5rem.
shape	"circle" \| "square"	"circle"	Square uses the system's near-square corners.
decorative	boolean	false	Hide it from assistive tech, when the name is already written beside it.
AvatarGroup max	number	all	Show at most this many, then one "+N" avatar named "N more".
AvatarGroup size / shape	-	-	Defaults for every avatar in the group. An avatar's own size or shape wins.

All other props of <span> are passed through. The helper initialsOf(name) is exported if you need the same initials elsewhere.