Skip to content

Avatar

Avatar represents a person that contains an image or initials which can also be presented in a group with multiple avatars.

Variants and colors

The avatar applies Joy UI's global variant tokens-which has soft and neutral as default values for variant and color, respectively.

Cindy Baker
IN

Variants

Color

Image

Image avatar can be created by passing standard html img props (e.g. src or srcSet) to the component.

Remy Sharp
Travis Howard
Cindy Baker
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
<Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
<Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />

Initials

Pass a string as children prop to the avatar to display initials.

RE
<Avatar>RE</Avatar>

Sizes

The avatar has three standard sizes: sm, md (default), and lg.

Remy Sharp
Remy Sharp
Remy Sharp
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="sm" />
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="md" />
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="lg" />

Fallbacks

If an error occurs while loading the avatar image, the component will fall back to alternatives in the following order:

  1. The provided children
  2. The first letter of the alt text
  3. A generic avatar icon
Remy Sharp
Remy Sharp
<Avatar alt="Remy Sharp" src="/broken-image.jpg">
  B
</Avatar>
<Avatar alt="Remy Sharp" src="/broken-image.jpg" />
<Avatar src="/broken-image.jpg" />

Group

Use AvatarGroup component to group multiple avatars together.

Remy Sharp
Travis Howard
Cindy Baker
+3
<AvatarGroup>
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar>+3</Avatar>
</AvatarGroup>

Max and total avatars

The AvatarGroup does not provide built-in props to control the maximum and the total avatars. This is because customization is broader if you have full control of the logic.

Here's a common example of what you'll find most applications out there:

Trevor Henderson
Agnes Walker
Travis Howard
Remy Sharp
+20
<AvatarGroup>
  {avatars.map((avatar) => (
    <Avatar key={avatar.alt} {...avatar} />
  ))}
  {!!surplus && <Avatar>+{surplus}</Avatar>}
</AvatarGroup>

Ellipsis action

The Avatar exposes meaningful CSS variables to communicate with the AvatarGroup. You can apply those variables to other components to mimic the avatar appearance inside the group. This customization technique makes your interface resilient to changes.

Here is an example of using IconButton component to create an ellipsis action:

Remy Sharp
Travis Howard
Cindy Baker

Overlapping order

By default, the first avatar in the group stays behind the second and so on. You can reverse the overlapping order by reversing avatars position and providing CSS flex-direction: row-reverse to the AvatarGroup.

+3
Cindy Baker
Travis Howard
Remy Sharp
<AvatarGroup sx={{ flexDirection: 'row-reverse' }}>
  <Avatar>+3</Avatar>
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
</AvatarGroup>

Vertical

If you need to render the avatar grouped vertically, add the CSS writing-mode: vertical-rl property to the AvatarGroup and rotate the extra element, if existent, by -90 degrees.

Remy Sharp
Travis Howard
Cindy Baker
+3
<AvatarGroup sx={{ writingMode: 'vertical-rl' }}>
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar sx={{ transform: 'rotate(-90deg)' }}>+3</Avatar>
</AvatarGroup>

Component variables

The AvatarGroup contains CSS variables to control the gap and the ring size of the avatars. You can override these variables via the sx prop.

Remy Sharp
Travis Howard
Cindy Baker
+3

CSS variables

px

Default as -8px

px

Default as 40px

px

Default as 4px

<AvatarGroup>
  ...avatars
</AvatarGroup>

With badge

Remy Sharp
Travis Howard
Remy Sharp