Avatar

Avatar represents a user or entity as an image, falling back to initials or an icon when the image is missing or fails to load. It is a compound component: Avatar.Root clips and sizes the box, Avatar.Image renders the picture once it loads, and Avatar.Fallback shows until then.

Playground

Props

shape and size live on Avatar.Root:

Prop	Type	Default	Value
shape	`'circle' \| 'square'`	`'circle'`
size	`'lg' \| 'md' \| 'sm' \| 'xs'`	`'md'`
sx	`StyleRule \| (theme) => StyleRule`	—	—

Usage

import { Avatar } from '@clerk/ui/mosaic/components/avatar';

<Avatar.Root>
  <Avatar.Image
    src='https://github.com/clerk.png'
    alt='@clerk'
  />
  <Avatar.Fallback>CL</Avatar.Fallback>
</Avatar.Root>;

Parts

Part	Slot (`.cl-*`)	Description
`Avatar.Root`	`cl-avatar`	Owns `shape` / `size`, clips its children to the shape.
`Avatar.Image`	`cl-avatar-image`	Renders an `<img>` once the source loads; renders nothing until then.
`Avatar.Fallback`	`cl-avatar-fallback`	Rendered while the image is pending or has failed. Optional `delayMs`.

Examples

Fallback

When the image fails to load, the fallback stays visible.

Sizes

CLCLCLCL

Shapes

CLCL