Avatar

Avatar shows a picture of a person or an agent, or their initials when there is no picture. AvatarGroup stacks several of them and folds the rest into a “+N” avatar.

Demos

Basic

size is small, medium or large (the same heights as buttons, so they line up in a row), or a number of pixels.

Shape and border

Avatars follow the theme’s corners: square in Brutal, softly rounded in Elegant. round makes a circle; bordered adds an ink border in Brutal and a quiet one in Elegant.

Text

Text starts at 40% of the avatar’s side and shrinks to fit when it is longer, so a full name still fits. Type to try it.

Color

color sets the background; set style.color for the text on it. The color roles work well for telling agents from people, and an icon works as well as initials.

Fallback

When src fails, the avatar tries fallbackSrc, then shows renderFallback or its children. The children also show while the image loads.

With a badge

Wrap the avatar in a Badge for an unread count or a status dot.

Group

AvatarGroup overlaps its avatars and borders them so they stay apart. With max, the ones that don’t fit become a “+N” avatar. size and round on the group apply to every avatar inside. Avatars can also be passed as children, and Avatar and PixelAvatar mix freely. expandOnHover spreads the stack out under the pointer; vertical stacks it top to bottom.

The group itself opens nothing: renderAvatar wraps each avatar in a Tooltip with the name, and renderRest replaces the “+N” with a Dropdown that lists the hidden people on click.

Lazy loading

lazy alone uses the browser’s native lazy loading. With intersectionObserverOptions the image loads once it scrolls into the given root, and renderPlaceholder shows until then.

Avatar props

Name	Type	Default	Description	Version
`src`	`string`	`undefined`	The image URL.	Unreleased
`alt`	`string`	`undefined`	The image’s text alternative. Without it the image is decorative.	Unreleased
`children`	`ReactNode`	`undefined`	Text or an icon. Shown without `src`, while the image loads and when every image failed. Text shrinks to fit.	Unreleased
`size`	`small \| medium \| large \| number`	`medium`	Named size or side length in px. Inside a group, the group’s size is the default.	Unreleased
`round`	`boolean`	`false`	A circle instead of the theme’s shape.	Unreleased
`bordered`	`boolean`	`false`	Adds a border. Always on inside a group.	Unreleased
`color`	`string`	`undefined`	Background color.	Unreleased
`objectFit`	`fill \| contain \| cover \| none \| scale-down`	`cover`	How the image fills the avatar.	Unreleased
`fallbackSrc`	`string`	`undefined`	Tried when `src` fails.	Unreleased
`renderFallback`	`() => ReactNode`	`undefined`	Shown when every image failed. Defaults to `children`.	Unreleased
`renderPlaceholder`	`() => ReactNode`	`undefined`	Shown while the image loads. Defaults to `children`.	Unreleased
`lazy`	`boolean`	`false`	Loads the image only near the viewport.	Unreleased
`intersectionObserverOptions`	`{ root?, rootMargin?, threshold? }`	`undefined`	With `lazy`, load once the avatar enters this root. `root` can be an element or a selector.	Unreleased
`imgProps`	`ImgHTMLAttributes`	`undefined`	Props for the `<img>` element.	Unreleased
`onLoad`	`(event) => void`	`undefined`	Called when the image has loaded.	Unreleased
`onError`	`(event) => void`	`undefined`	Called when `src` or `fallbackSrc` fails to load.	Unreleased

Avatar also accepts native span attributes and a ref. An avatar that shows only an icon should get role="img" and an aria-label.

AvatarGroup props

Name	Type	Default	Description	Version
`options`	`{ src: string; alt?: string }[]`	`[]`	The avatars to show. The option type is generic.	Unreleased
`max`	`number`	`undefined`	Shows at most this many avatars; when there are more, the last one becomes “+N”.	Unreleased
`maxStyle`	`CSSProperties`	`undefined`	Style for the “+N” avatar.	Unreleased
`size`	`small \| medium \| large \| number`	`undefined`	Default size for the avatars inside.	Unreleased
`round`	`boolean`	`undefined`	Default `round` for the avatars inside.	Unreleased
`vertical`	`boolean`	`false`	Stacks the avatars top to bottom.	Unreleased
`expandOnHover`	`boolean`	`false`	Spreads the stack out while the pointer is over it.	Unreleased
`renderAvatar`	`({ option }) => ReactNode`	`undefined`	Renders one option.	Unreleased
`renderRest`	`({ options, rest }) => ReactNode`	`undefined`	Renders the “+N” avatar.	Unreleased
`children`	`ReactNode`	`undefined`	Avatars placed before the ones from `options`.	Unreleased

AvatarGroup renders a div with role="group"; give it an aria-label that says who is in it. The “+N” avatar reads as “N more”.

#Demos

#Basic

#Shape and border

#Text

#Color

#Fallback

#With a badge

#Group

#Name tooltips and a rest menu

#Lazy loading

#Avatar props

#AvatarGroup props