Avatar
A person's round picture, or their initials when there's none or it fails to load.
import { Avatar } from "@butteryui/react";Demo
When to use it
Use it for
- A person next to their name: a table's customer column, an account menu's user row, a comment
- People shown by face alone, such as who's working on something (give each a label)
- People listed beside workspace tiles, with shape="rounded" so their corners match
Not for
- A workspace, team or company: use InitialsTile, which is square
- A decorative illustration: use an image
Examples
Avatar sizes
The four sizes, from a 20px avatar in a dense table to a 40px one in a profile header, round and rounded.
xs, 20px, circle
sm, 24px, circle
md, 32px, circle
lg, 40px, circle
xs, 20px, rounded
sm, 24px, rounded
md, 32px, rounded
lg, 40px, rounded
Collaborators
Who's working on an order, by avatar alone, so each is named for screen readers; joining adds yours.
2 people on this order
Person row
A person's picture beside their name and role; the name is written, so the avatar stays decorative.
Head roaster
Variants and states
Sizes
20, 24, 32 and 40, with a picture and with initials.
Circle and rounded
Round by default; rounded squares the corners to an InitialsTile's at each size, 6px up to sm and 8px from md, for people shown beside workspace tiles.
A picture that fails
The initials stay when the picture can't load, at the same size.
Props
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
namerequired | string | The person's name: their initials show while the picture loads, and when it fails or there's none. | |
src | string | The picture's address. | |
size | "xs" | "sm" | "md" | "lg" | "sm" | How big it is: xs 20, sm 24, md 32 or lg 40. Defaults to "sm". |
shape | "circle" | "rounded" | "circle" | "circle" (the default), or "rounded", a square with 6px corners up to sm and 8px from md, the
corners an InitialsTile of its size has, for people shown beside workspace tiles. |
label | string | Names the avatar for screen readers when the person's name isn't written beside it. Without one, it's decorative. |
It also takes Omit<ComponentPropsWithRef<"span">, "children">.
Accessibility
Decorative by default, since the person's name is usually written beside it; give it a label when it stands alone, and it becomes an image named by it. The picture's own alt is empty, so the name is never read twice.
It takes no keyboard input of its own.
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
A circle, or with shape="rounded" a square with an InitialsTile's corners, of a fixed size that never grows or shrinks in a row: 20px at xs, 24px at sm (the default), 32px at md or 40px at lg. The picture covers the same shape the initials sit in, so nothing moves when it loads, and it takes no presses of its own.