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.
Variants
Color
Image
Image avatar can be created by passing standard html img props (e.g. src or srcSet) to the component.
<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>RE</Avatar><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:
- The provided children
- The first letter of the
alttext - A generic avatar icon
<Avatar alt="Remy Sharp" src="/broken-image.jpg">
B
</Avatar>
<Avatar alt="Remy Sharp" src="/broken-image.jpg" />
<Avatar src="/broken-image.jpg" /><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:
<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:
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.
<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.
<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.
CSS variables
px
Default as -8px
px
Default as 40px
px
Default as 4px
<AvatarGroup>
...avatars
</AvatarGroup>