Avatar
An image element with a fallback for representing the user.
Installation
Install the following dependencies:
Set up the token layer and the StyleX compiler, if you have not already. See
Installation. The avatar also needs interop.css, which
sizes the icon inside a badge or a count.
Copy and paste the following code into your project.
Update the import paths to match your project setup.
Usage
Composition
Basic
An avatar with an image and a fallback. The fallback shows while the image loads and stays if it fails.
Badge
Use AvatarBadge for a dot in the avatar's bottom corner. Pass xstyle to
color it.
Badge with icon
Put an icon inside AvatarBadge at default or lg.
At sm the badge is 8px across and sizes any icon to nothing. Use a plain dot
at that size.
Avatar group
Use AvatarGroup to overlap a set of avatars. Each member sits under the one
before it, with a ring that separates the two.
The ring, and the one around AvatarBadge, is drawn in the page colour. On
another surface, such as a card or a popover, set --carbon-avatar-cutout to
that surface's fill on the group or any ancestor.
Avatar group count
Use AvatarGroupCount for the members the group does not show.
Avatar group with icon
An icon works in the count too.
Sizes
Use the size prop to change the size of the avatar. AvatarGroup takes the
same prop and sizes every member that does not name its own.
Dropdown
Render a DropdownMenu trigger as a Button
and put the avatar inside it.
Give an avatar-only trigger an aria-label. There is no text for a screen
reader to announce.
API reference
Pass render to replace a part's element or compose it with another component.
Avatar, AvatarImage and AvatarFallback wrap the Base UI Avatar part of
the same name and accept its props. See the
Base UI reference. Every part
also takes xstyle and className.
Avatar
Renders a span.
| Prop | Type | Default |
|---|---|---|
size | "sm" | "default" | "lg" | the group's, else "default" |
xstyle | StyleXStyles | — |
className | string | — |
The sizes are 24px, 32px and 40px. The avatar passes the resolved size to the fallback and the badge through context.
AvatarImage
Renders an img. Takes src, alt and onLoadingStatusChange.
AvatarFallback
Renders a span. delay is the number of milliseconds to wait before showing
it, so initials never flash before a fast image.
AvatarBadge
Renders a span, positioned in the avatar's bottom corner and sized from the
avatar's size.
AvatarGroup
Renders a div.
| Prop | Type | Default |
|---|---|---|
size | "sm" | "default" | "lg" | "default" |
AvatarGroupCount
Renders a div, sized from the group's size.
avatarStyles
The style maps behind the component. Spread them onto any element.
| Key | What it is |
|---|---|
base | The circle, the hairline over the image |
sizes | One entry per size |
image | The cover fit and the circle |
fallback | The flat fill behind initials |
fallbackSizes | The fallback's type, keyed by size |
badge | The dot in the corner |
badgeSizes | The dot's size and icon size, keyed by size |
group | The group's row |
count | The tally's fill, hairline and shape |
countSizes | The tally's size and type, keyed by size |
member | The overlap and ring a member in a group draws |
Data attributes
| Attribute | On | Effect |
|---|---|---|
data-slot="avatar" | the root | Marks a member of a group |
data-slot="avatar-group-count" | the tally | Marks a member of a group |
data-size | every part | Reflects the resolved size |
data-slot="avatar-image" | the image | Targets the image from a parent |
data-slot="avatar-fallback" | the fallback | Targets the fallback from a parent |
data-slot="avatar-badge" | the badge | Targets the badge from a parent |
data-slot="avatar-group" | the group | Targets the group from a parent |
The first member in a group keeps its leading margin, and that exemption is
keyed on data-slot rather than :first-child, so anything else you put first
in the group does not claim it.
CSS variables
| Variable | On | Effect |
|---|---|---|
--carbon-icon-size | badge and tally | The icon's size, read by interop.css |