Components
Avatar
Base UI avatars with images, fallbacks, status indicators, and overlapping groups.
Avatar represents a person or entity with an image, initials, or an icon. It also provides presence
status and overlapping groups.
The image and fallback are built on Base UI Avatar, which owns loading status, cached image detection,
and fallback timing. Import the components from @orkest/ui/client.
Live preview#
import {
Avatar,
AvatarFallback,
AvatarImage,
} from '@orkest/ui/client';
export function Example() {
return (
<Avatar size="lg" status="online">
<AvatarImage src="/avatar.jpg" alt="Alex Morgan" />
<AvatarFallback>{'AM'}</AvatarFallback>
</Avatar>
);
}Image and fallback#
AvatarFallback is visible while the image loads, when no image is provided, and after a load
failure. By default the image stays mounted while loading or failed, but is hidden from assistive
technology until it loads, so the fallback remains the accessible content.
import {
Avatar,
AvatarFallback,
AvatarImage,
} from '@orkest/ui/client';
export function Example() {
return (
<Avatar size="lg">
<AvatarImage src="/avatar.jpg" alt="Alex Morgan" />
<AvatarFallback>{'AM'}</AvatarFallback>
</Avatar>
);
}Initials#
Use one or two characters in AvatarFallback. Initials scale with the avatar size.
import { Avatar, AvatarFallback } from '@orkest/ui/client';
export function Example() {
return (
<>
<Avatar size="xs"><AvatarFallback>{'XS'}</AvatarFallback></Avatar>
<Avatar size="sm"><AvatarFallback>{'SM'}</AvatarFallback></Avatar>
<Avatar size="md"><AvatarFallback>{'MD'}</AvatarFallback></Avatar>
<Avatar size="lg"><AvatarFallback>{'LG'}</AvatarFallback></Avatar>
<Avatar size="xl"><AvatarFallback>{'XL'}</AvatarFallback></Avatar>
</>
);
}Shapes#
Circles are the default. Square avatars use a size-aware corner radius.
import { Avatar, AvatarFallback } from '@orkest/ui/client';
export function Example() {
return (
<Avatar size="lg" shape="square">
<AvatarFallback>{'SQ'}</AvatarFallback>
</Avatar>
);
}Icon#
Icons inherit the avatar size and color. Set label on Avatar when the fallback is decorative, so
the avatar keeps an accessible name.
import { Bot } from 'lucide-react';
import { Avatar, AvatarFallback } from '@orkest/ui/client';
export function Example() {
return (
<Avatar size="lg" label="Orkest assistant">
<AvatarFallback>
<Bot aria-hidden="true" />
</AvatarFallback>
</Avatar>
);
}Status#
Add status to show a presence indicator in the bottom-right corner. Every status includes
visually hidden text; use statusLabel to customize it.
import { Avatar, AvatarFallback } from '@orkest/ui/client';
export function Example() {
return (
<Avatar status="online" statusLabel="Online">
<AvatarFallback>{'AM'}</AvatarFallback>
</Avatar>
);
}Avatar group#
AvatarGroup overlaps its children. size and shape cascade to avatars that do not set their own,
and spacing controls the overlap using a spacing token step.
import { Avatar, AvatarFallback, AvatarGroup } from '@orkest/ui/client';
export function Example() {
return (
<AvatarGroup size="md" spacing={2}>
<Avatar><AvatarFallback>{'AM'}</AvatarFallback></Avatar>
<Avatar><AvatarFallback>{'JL'}</AvatarFallback></Avatar>
<Avatar><AvatarFallback>{'SK'}</AvatarFallback></Avatar>
<Avatar><AvatarFallback>{'TW'}</AvatarFallback></Avatar>
</AvatarGroup>
);
}Overflow#
Set max to keep the first N avatars and replace the rest with a count. The group preserves child
order, so place the avatars that must stay visible first. overflowLabel customizes the accessible
text and defaults to N more avatars.
import { Avatar, AvatarFallback, AvatarGroup } from '@orkest/ui/client';
export function Example() {
return (
<AvatarGroup max={3} size="md">
<Avatar><AvatarFallback>{'AM'}</AvatarFallback></Avatar>
<Avatar><AvatarFallback>{'JL'}</AvatarFallback></Avatar>
<Avatar><AvatarFallback>{'SK'}</AvatarFallback></Avatar>
<Avatar><AvatarFallback>{'TW'}</AvatarFallback></Avatar>
<Avatar><AvatarFallback>{'RB'}</AvatarFallback></Avatar>
</AvatarGroup>
);
}Props#
Avatar#
| Prop | Type | Default |
|---|---|---|
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' |
| Avatar size. Inherits from AvatarGroup when omitted. | ||
shape | 'circle' | 'square' | 'circle' |
| Corner shape. Inherits from AvatarGroup when omitted. | ||
status | 'online' | 'away' | 'offline' | 'busy' | — |
| Presence indicator rendered at the bottom-right corner. | ||
statusLabel | string | 'Online' | 'Away' | 'Offline' | 'Busy' |
| Visually hidden status text announced to assistive technology. | ||
label | string | — |
| Accessible name. When set, the visual image or fallback is hidden from assistive technology. | ||
native attributes | Base UI Avatar Root props | — |
| ARIA attributes, event handlers, className, style, and ref are forwarded. | ||
AvatarImage#
| Prop | Type | Default |
|---|---|---|
src | string | — |
| Image source. Use a square image for the best crop. | ||
alt | string | — |
| Accessible description of the image. Use an empty string only when the avatar is decorative. | ||
onLoad | ReactEventHandler<HTMLImageElement> | — |
| Called after the image loads. | ||
onError | ReactEventHandler<HTMLImageElement> | — |
| Called when the image fails to load. The fallback takes over. | ||
keepMounted | boolean | true |
| Keeps the image mounted while it loads. Set to false to preload off-screen before mounting. | ||
onLoadingStatusChange | (status: 'idle' | 'loading' | 'loaded' | 'error') => void | — |
| Called when the Base UI image loading status changes. | ||
native attributes | Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'alt'> | — |
| Image attributes, className, style, and ref are forwarded. | ||
AvatarFallback#
| Prop | Type | Default |
|---|---|---|
children | ReactNode | — |
| Initials, an icon, or other fallback content. | ||
delay | number | 0 |
| How long to wait before showing the fallback, in milliseconds. | ||
native attributes | HTMLAttributes<HTMLSpanElement> | — |
| ARIA attributes, className, style, and ref are forwarded. | ||
AvatarGroup#
| Prop | Type | Default |
|---|---|---|
max | number | — |
| Maximum visible avatars before the overflow indicator replaces the rest. | ||
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' |
| Size applied to child avatars that do not set their own size. | ||
shape | 'circle' | 'square' | 'circle' |
| Shape applied to child avatars that do not set their own shape. | ||
spacing | 0 | 1 | 2 | 3 | 4 | 2 |
| Overlap between avatars as a spacing token step. | ||
overflowLabel | (count: number) => string | `N more avatars` |
| Accessible label for the overflow indicator. | ||
native attributes | HTMLAttributes<HTMLSpanElement> | — |
| ARIA attributes, event handlers, className, style, and ref are forwarded. | ||
Accessibility#
AvatarImagerequiresalt. Describe the person or entity, or pass an empty alt when the avatar is purely decorative.- Use
labelonAvatarwhen the fallback is an icon or another visual without a text name. The visual content is hidden from assistive technology and the label becomes the accessible name. - Status indicators always include visually hidden text. Default labels are Online, Away, Offline,
and Busy; use
statusLabelfor product-specific wording. - Do not communicate status with color alone. The status text is part of the accessible name, and surrounding UI should provide a visible equivalent when status is important.
- The group overflow indicator announces
N more avatarsby default. Customize it withoverflowLabel. - Avatars are not interactive. Wrap them in a Button or use Tag for clickable chips.