CatalystAvatarv1.1.3Ready for Production
Display user avatars with automatic fallback handling and solid color styling for product interfaces.
Prefer AI-assisted development?
Catalyst Avatar extends Radix's Avatar primitive with built-in design tokens, CVA variants, and accessibility defaults — so you get a production-ready avatar with automatic fallback handling and zero config.
Installation
npm install @pmi/catalyst-avatarimport { AvatarRoot, AvatarImage, AvatarFallback } from '@pmi/catalyst-avatar';Color Variants
Color variants offer four solid color options: aqua, saddle, tangerine, and violet. Each provides clean, professional styling suitable for application interfaces.
Aqua
Aqua color variant for avatars without an image source.
Saddle
Saddle color variant for avatars without an image source.
Tangerine
Tangerine color variant for avatars without an image source.
Violet
Default color variant for avatars without an image source.
Sizes
Choose from three sizes optimized for marketing interfaces:
Common Patterns
Basic Avatar with Fallback
When no image is provided or the image fails to load, the fallback content (typically initials) is displayed with a solid color background.
With Loaded Image
When an image URL is provided and successfully loads, it displays the image instead of the fallback.
Icon Fallback
Instead of initials, you can use icons from @pmi/catalyst-icons in the fallback. Use size="full" to ensure proper scaling.
API Reference
AvatarRoot
The container component that applies styling and manages the avatar's appearance.
Accepts all standard Radix Avatar Root props and forwards ref to the underlying Radix Avatar Root element.
Prop
Type
AvatarImage
The image component that displays the user's profile picture.
Accepts all standard Radix Avatar Image props and forwards ref to the underlying Radix Avatar Image element.
Prop
Type
AvatarFallback
The fallback component displayed when the image fails to load or during loading.
Accepts all standard Radix Avatar Fallback props and forwards ref to the underlying Radix Avatar Fallback element.
Prop
Type
Accessibility
ARIA attributes
AvatarRoot,AvatarImage, andAvatarFallbackdo not add ARIA roles or labels of their own.- Provide meaningful
alttext forAvatarImageso screen readers can identify the user or subject. - Use
alt=""only when the avatar is decorative or when another element provides the accessible name. - Keep fallback content short and understandable; initials or a simple icon are usually best.
- If you make the avatar interactive, apply the accessible name to the wrapper element rather than the avatar itself.
- Catalyst chooses fallback text colors for each avatar variant to preserve readable contrast in both light and dark modes.
- Catalyst adds the visual avatar styling, color variants, and fallback presentation; Radix provides the underlying accessibility semantics.
See the Radix Avatar docs for inherited baseline behavior.
Choosing the Right Component
Use Avatar when you need a user/profile visual with automatic image fallback and consistent solid-color styling.
Reach for a different option when:
| If you need… | Use instead |
|---|---|
| a reusable avatar with image loading, fallback initials/icon content, and built-in styling | Avatar |
| a plain image without avatar-specific fallback behavior or circular framing | a native img element or your framework's image component |
| a clickable or navigable avatar | wrap the avatar in Button or Link |
| a simple initials or icon placeholder without image loading logic | render the content directly, or use an icon from @pmi/catalyst-icons |
Related
Video Player
A Brightcove video player component with customizable controls and comprehensive styling options. Built on Brightcove React Player Loader with full support for captions, chapters, audio tracks, and picture-in-picture.
Badge
Display status indicators, labels, and counts for categorization and information hierarchy in product interfaces.