Avatar

An image with a fallback, alone or stacked.

Base UI AvatarSource

Sizes

Use md (the default) in most places, sm in lists and dense UI, and lg in profile headers. Set size on Avatar.Root.

NHsm · lists
NHmd · default
NHlg · profiles

Fallback

Avatar.Fallback shows when the image fails or when there is none.

Image loads
Image fails
JJNo image

Stacked group

Use a group for the people on a team or in a thread. Avatar.Group stacks its avatars and sets their size. max shows the first avatars and a "+N" count.

md
NHSHMHJJ+2 more
lg
NHSHMHJJ+2 more

Reverse stacking

Set reverse to keep the first avatar above later avatars. The visible order stays the same.

default
NHSHJJ+1 more
reverse
NHSHJJ+1 more

Usage

These are defaults, not laws. Break one when you have a good reason, or when it makes the design more cohesive or more interesting.

  • Always add Avatar.Fallback with initials. Images can fail or load slowly.
  • Give Avatar.Group an aria-label, such as "Team members".
  • max counts direct children, so a fragment of avatars counts as one.

API

Props that the library adds. Avatar.Root, Avatar.Image, and Avatar.Fallback also take all the Base UI props. Avatar.Group is a site part and takes all the props of a <div>.

Avatar.Root

PropTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Diameter and text size. Inside an Avatar.Group, the group sets the size.

Avatar.Group

PropTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Sets the size of every avatar.
reversebooleanfalsePlaces later avatars underneath earlier avatars. Does not change reading order.
maxnumber–The number of avatars to show. A "+N" count replaces the rest. Without max, all show.