Misc

Avatar

Shows a person or an organisation as a round picture, or as their initials when there is no picture.

Import

import { Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup, AvatarGroupCount } from "@booleanpress/ui/avatar"

Usage

Put an AvatarImage and an AvatarFallback inside Avatar. The image is requested first; the fallback shows until it has loaded, and stays if it fails or if there is no src.

import { Avatar, AvatarFallback, AvatarImage } from "@booleanpress/ui/avatar"

export function Person() {
  return (
    <Avatar>
      <AvatarImage src="/people/ada.png" alt="Ada Lovelace" />
      <AvatarFallback>AL</AvatarFallback>
    </Avatar>
  )
}

size is sm (24 px), default (32 px) or lg (40 px). AvatarBadge adds a small dot or icon at the bottom corner at the inline end (for presence); AvatarGroup overlaps avatars in a row, and AvatarGroupCount is the "+4" chip at its end.

The fallback is the consumer's: the component does not derive initials. Use AvatarFallback's delayMs to hold it back for a moment, so fast images do not flash it.

Examples

Image

A picture, with the initials as the fallback. This one is an inline SVG, so it needs no network.

Fallback

Initials with no image, and initials under an image that has no source.

GHLT

Sizes

sm, the default and lg.

ALALAL

With a badge

A presence dot at the bottom corner, named for screen readers.

Group

Overlapping avatars with a count chip.

ALGHLT

Accessibility

Semantics: A span root, an img for the image once it has loaded, and a span for the fallback. The image renders only after it loads, so an avatar that failed to load has no img.
Labels: Give AvatarImage an alt with the person's name. Where the name is written next to the avatar, use alt="" so it is not read twice. Initials in the fallback are read as letters: add the name, visibly or with aria-label on the avatar, when nothing else names the person. Give a badge and a count chip a visually hidden text.
Focus: An avatar takes no focus and has no keyboard behaviour of its own, so it has no keyboard rows. Wrap it in a link or a button when it is interactive.
Known limits: The picture is not cropped by the component: aspect-square and the round mask do it, so a non-square image is cut.
In a small size the badge is a plain dot (its icon is hidden at sm), so meaning cannot be in the icon.

Keyboard

Keyboard
Key	Behaviour

API

Avatar

Renders Radix Avatar.Root and passes it every other prop.

Avatar props
Prop	Type	Default	Description
`asChild`	`boolean`
`size`	`"default" \| "sm" \| "lg"`	`default`	`sm` 24 px, `default` 32 px or `lg` 40 px. Also set as `data-size`, which the badge and the group read.

AvatarImage

Renders Radix Avatar.Image and passes it every other prop.

AvatarImage props
Prop	Type	Default	Description
`asChild`	`boolean`
`onLoadingStatusChange`	`((status: ImageLoadingStatus) => void)`		Called with `loading`, `loaded` or `error` as the image's state changes.

AvatarFallback

Renders Radix Avatar.Fallback and passes it every other prop.

AvatarFallback props
Prop	Type	Default	Description
`asChild`	`boolean`
`delayMs`	`number`		Wait this many milliseconds before showing the fallback, so a fast image never flashes it.

AvatarBadge

Renders a span and passes it every other prop.

AvatarGroup

Renders a div and passes it every other prop.

AvatarGroupCount

Renders a div and passes it every other prop.

Every part takes className, merged with its defaults by cn(), and ref, which reaches the element it renders.

Data attributes: data-slot="avatar" (Avatar), data-slot="avatar-image" (AvatarImage), data-slot="avatar-fallback" (AvatarFallback), data-slot="avatar-badge" (AvatarBadge), data-slot="avatar-group" (AvatarGroup), data-slot="avatar-group-count" (AvatarGroupCount), and data-size.

Theming

The fallback is --muted with --muted-foreground text; the badge is --primary, and the ring that separates avatars is --background. Pass a className on the badge to use another token, as the badge example does with bg-success.

The tokens its classes read. Change their values in your theme, and it follows.

Theme tokens
Token	Used for
`--background`	focus ring
`--muted`	background
`--muted-foreground`	text
`--primary`	background
`--primary-foreground`	text