Avatar
Introduction
An image-based user profile element that displays custom graphical identifiers. It falls back gracefully to formatted name initials or a universal placeholder icon when image sources are omitted, loading, or fail to load. Primarily used for profile navigation triggers, messaging lists, reviews, and community directories.
The Avatar component is fully integrated as an avatar block in the Page Builder, allowing content authors and developers to easily configure profile paths, sizing scales, and visual themes directly within the CMS.
Usage
These examples illustrate how content editors bind and structure avatar components.
1. High-Fidelity Profile Avatar (With Image Src)
Loads a high-resolution user image. Automatically handles background network loading and animates into view once resolved.
{
"type": "avatar",
"src": "https://images.unsplash.com/photo-1534528741775-53994a69daeb?q=80&w=200&auto=format&fit=crop",
"name": "Jane Doe",
"size": "lg",
"interactive": true
}
2. Accented Initials Fallback (Without Image Src)
When the profile image is absent, the Avatar automatically parses the user's name property to calculate and render correct capital initials (e.g., "Jane Doe" -> "JD") over an accented color theme.
{
"type": "avatar",
"name": "Jane Doe",
"variant": "solid",
"colorPalette": "blue",
"size": "md",
"interactive": true
}
3. Rounded Placeholder Avatar
Renders a standard rounded user icon when neither image paths nor usernames are supplied.
{
"type": "avatar",
"shape": "rounded",
"size": "md",
"interactive": true
}
Props
| Property | CMS Field Type | Default | Description / Supported Options |
|---|---|---|---|
Profile Image (src) | image | - | Image URL or relative asset path. Supplying this prompts Tier-2 hydration. |
User Name (name) | string | - | Account username. Parses first and last characters into visual initials. |
Alt Details (alt) | string | - | Alternative textual descriptions of the photo for screen readers. |
Size Scale (size) | select | "md" | Controls the avatar's height, width, and initials text scale. • Options: "2xs", "xs", "sm", "md", "lg", "xl", "2xl". |
Visual Variant (variant) | select | "subtle" | Style overlay applied to fallback initials background. • Options: "solid", "surface", "subtle", "outline". |
Corner Shape (shape) | select | "full" | Curving of avatar boundaries. • Options: "square", "rounded", "full". |
Color Theme (colorPalette) | select | "blue" | Accent color used for fallback background themes. • Options: blue, green, red, purple, orange, amber, cyan, slate. |
Force Interactive (interactive) | boolean | true | Ensures immediate client-side load monitoring and smooth transition fallbacks. |
Developer Notes & Accessibility
- Hydration Island: The Avatar executes as a Tier-2 conditional island. If no image
srcis specified, it compiles directly to light static markup with zero client JS footprint. If asrcis supplied, it hydrates on the client to automatically manage asynchronous load cycles (loading->loaded/error). - WAI-ARIA Compliance: Under the hood, fallback initials and icons operate inside semantic
<span>tags. If the avatar serves a purely decorative role, ensure thealtattribute is omitted or blank so screen readers skip it.