Avatar
Image with graceful fallback.
Usage
Compose Avatar.Root, Avatar.Image, and Avatar.Fallback together. The fallback renders automatically when the image
is absent or fails to load.
JD
Sizes
Three sizes via the size prop on Avatar.Root.
SM
MD
LG
Shapes
circle (default) or square via the shape prop.
CR
SQ
Fallback
Avatar.Fallback renders when no image is provided or when the image fails
to load. Typically used with initials.
RA
PF
Props
Avatar.Root
| Prop | Type | Default |
|---|---|---|
size | 'sm' | 'md' | 'lg' | 'md' |
shape | 'circle' | 'square' | 'circle' |
class | string | — |
children | Snippet | — |
child bits-ui | Snippet<[{ props: Record<string, unknown>; }]> | undefined | — |
delayMs bits-ui The delay in milliseconds to wait before showing the avatar once the image has loaded. This can be used to prevent sudden flickering of the image if it loads quickly. | number | undefined | 0 |
id bits-ui | string | undefined | — |
loadingStatus bits-ui The loading status of the image. If you are confident that the image exists and will load successfully, you can set this to `"loaded"` to skip the loading process (which shows the fallback) and immediately show the image. | AvatarImageLoadingStatus | undefined | "loading" |
onLoadingStatusChange bits-ui A callback invoked when the loading status of the image changes. | OnChangeFn<AvatarImageLoadingStatus> | undefined | — |
ref bits-ui | HTMLElement | null | undefined | — |
Avatar.Image
| Prop | Type | Default |
|---|---|---|
alt required Required: describes the image for screen readers. Always provide meaningful alt text. | string | — |
class | string | — |
child bits-ui | Snippet<[{ props: Record<string, unknown>; }]> | undefined | — |
children bits-ui | Snippet<[]> | undefined | — |
id bits-ui | string | undefined | — |
ref bits-ui | HTMLElement | null | undefined | — |
src html | string | null | undefined | — |
Avatar.Fallback
| Prop | Type | Default |
|---|---|---|
class | string | — |
children | Snippet | — |
child bits-ui | Snippet<[{ props: Record<string, unknown>; }]> | undefined | — |
id bits-ui | string | undefined | — |
ref bits-ui | HTMLElement | null | undefined | — |
Avatar.Image
Avatar.Fallback