Avatar
A person as a picture, or as initials when there is none, with a status badge and a group with a count.
An avatar shows a person or an organisation as a small round picture. While the picture loads, or when it is missing or fails, the fallback shows instead, usually the initials. It is built on Base UI's avatar, which tracks the loading of the image.
// apps/docs/examples/ui/avatar.tsx'use client';
import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage,} from '@workspace/active-ui/components/primitives/avatar';
// A portrait drawn inline, so the example loads nothing from elsewhere.const PORTRAIT = 'data:image/svg+xml,' + encodeURIComponent( '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40"><rect width="40" height="40" fill="#c7d2fe"/><circle cx="20" cy="15" r="7" fill="#4338ca"/><path d="M6 38c2-9 8-13 14-13s12 4 14 13z" fill="#4338ca"/></svg>', );
// An image that cannot be decoded, as a missing photo would fail to load.const BROKEN = 'data:image/png;base64,AAAA';
/** * A person as a picture, or as initials when there is no picture or it * fails to load. Three sizes, a status badge, and a group that ends in a * count of the rest. */export default function AvatarExample() { return ( <div className="flex flex-col items-center gap-6"> <div className="flex items-center gap-4"> <Avatar size="sm"> <AvatarImage src={PORTRAIT} alt="Sam de Vries" /> <AvatarFallback>SV</AvatarFallback> </Avatar> <Avatar> <AvatarImage src={PORTRAIT} alt="Sam de Vries" /> <AvatarFallback>SV</AvatarFallback> </Avatar> <Avatar size="lg"> <AvatarImage src={BROKEN} alt="Noor Jansen" /> <AvatarFallback>NJ</AvatarFallback> </Avatar> <Avatar size="lg"> <AvatarFallback>AB</AvatarFallback> <AvatarBadge className="bg-tone-success" role="img" aria-label="Online" /> </Avatar> </div> <AvatarGroup> {['SV', 'NJ', 'AB'].map((initials) => ( <Avatar key={initials}> <AvatarFallback>{initials}</AvatarFallback> </Avatar> ))} <AvatarGroupCount>+9</AvatarGroupCount> </AvatarGroup> </div> );}Usage#
import { Avatar, AvatarFallback, AvatarImage,} from '@workspace/active-ui/components/primitives/avatar';
<Avatar> <AvatarImage src={person.photoUrl} alt={person.name} /> <AvatarFallback>{person.initials}</AvatarFallback></Avatar>;Anatomy#
Avatar: the circle.size:sm,defaultorlg.Avatar: the picture, shown once it has loaded.Image Avatar: shown until then, or instead when there is no image or it fails.Fallback Avatar: a small dot on the edge, for a status. Give it a colour withBadge classand, when it carries meaning,Name role="img"with anaria-.label AvatarandGroup Avatar: avatars that overlap, ending in a count of the rest.Group Count
What your application provides#
The image URL and the
alttext: the person's name, oralt=""when the name is written next to the avatar anyway.The initials or another fallback; the package does not derive initials from a name, because that depends on the language and the name.
Accessibility#
An avatar with a visible name beside it is decoration: give the image
alt="".A status shown only as a coloured dot needs a text alternative (
aria-withlabel role="img").
API#
Avatar#
Import from @workspace/
Props marked Base UI are behaviour of the Base UI part this component is built on.
Props
- Type
"default""lg""sm"- Default
'default'
The diameter: sm, default or lg.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Other parts#
AvatarImage
All props come from the Base UI part this component is built on.
Props
- Type
boolean- Default
false
Whether the image element stays mounted and loads in place instead of being preloaded. Supports loading="lazy" and optimized image components such as next/.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Events
Called by the component when something happens.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
AvatarFallback
All props come from the Base UI part this component is built on.
Props
- Type
number- Default
0
How long to wait before showing the fallback. Specified in milliseconds.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Parts that take only their element’s attributes
Avatar: the attributes of aGroup <div>, with className and ref.Avatar: the attributes of aGroup Count <div>, with className and ref.Avatar: the attributes of aBadge <span>, with className and ref.
This page adapts the Avatar documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.