Avatar

Container for a user or entity avatar; compose an AvatarImage and AvatarFallback inside, and the fallback shows automatically when the image is missing or fails to load.

Usage

import { Avatar, AVATAR_SIZE_CLASS, AVATAR_SIZE_PX, AvatarBadge, AvatarExtendedSize, AvatarFallback, AvatarGroup, AvatarGroupVariant, AvatarImage, AvatarSize, AvatarStatus } from "@desk/ui/components/avatar";

Best practices

Always render an AvatarFallback child — it is what shows while the image loads and when src is missing or errors; an image-only avatar renders empty on failure.
Give AvatarImage a meaningful alt; the visual is decorative only when the fallback initials already convey the identity.
Keep the default radius="full" for people; use a squared radius for brand/entity logos so they read as objects, not users.

Props

Avatar

Prop	Type	Default	Description
size	`AvatarSize \| undefined`	`"base"`
radius	`"rounded" \| "square" \| "full" \| undefined`		Border radius. Defaults to "full" (circular).
withRing	`boolean \| undefined`	`false`	Show a decorative ring around the avatar.
ringColor	`string \| undefined`	`"ring-primary"`	Tailwind `ring-*` utility for the ring; only applies when `withRing`.

AvatarBadge

Prop	Type	Default	Description
className	`string`		CSS class name
count	`number`		Number shown in the badge; hidden when 0 or omitted unless `dot` is set.
dot	`boolean \| "neutral" \| "brand" \| "danger" \| "warning" \| "success" \| "info"`	`false`	Render a plain dot instead of a number. `true` tints it with the badge's own `tone`; a {@link Tone} value overrides that with the shared dot tint.
max	`number`	`99`	Cap above which the count renders as `{max}+`.
position	`"bottom-right" \| "top-right" \| "bottom-left" \| "top-left"`	`"top-right"`
size	`"base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl"`		Component size
tone	`AvatarBadgeTone`	`"danger"`	Semantic fill tone.

AvatarFallback

Prop	Type	Default	Description
size	`AvatarSize \| undefined`	`"base"`
name	`string \| undefined`		Full name or label used to: - Derive 1–2 letter initials for fallback text (when children not provided) - Seed deterministic background/text color for readability

AvatarGroup

Prop	Type	Default	Description
animate	`boolean \| undefined`		Enable hover animation
children(required)	`ReactNode`		Child elements
className	`string \| undefined`		CSS class name
labels	`string[] \| undefined`		Accessibility labels for each avatar
max	`number \| undefined`		Maximum number of avatars to display before showing surplus
onSelect	`((index: number) => void) \| undefined`		Selection change handler
renderSurplus	`((count: number) => ReactNode) \| undefined`		Custom render function for surplus count
selectable	`boolean \| undefined`		Enable avatar selection
selectedIndex	`number \| undefined`		Selected avatar index
size	`number \| "base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl" \| undefined`	`"base"`	Size as a `ComponentSize` token, or an explicit pixel number.
spacing	`"normal" \| "tight" \| "loose" \| undefined`		Spacing between avatars
variant	`AvatarGroupVariant \| undefined`		Visual variant - controls borders and surplus styling

AvatarImage

Prop	Type	Default	Description
alt(required)	`string`		Accessible alt text describing the avatar. Required for screen readers.

AvatarStatus

Prop	Type	Default	Description
className	`string`		CSS class name
position	`"bottom-right" \| "top-right" \| "bottom-left" \| "top-left"`	`"bottom-right"`
size	`"base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl"`		Component size
status(required)	`AvatarStatusType`
withBorder	`boolean`	`true`	Ring separating the dot from the avatar.

Also exports

constAVATAR_SIZE_CLASS
constAVATAR_SIZE_PX
typeAvatarExtendedSize
typeAvatarGroupVariant
typeAvatarSize

Composition

Builds on

Dot

Used by

MobileNavigationRoot