Avatar
FreeA circular image container representing a user or entity. Displays a profile photo when available and falls back to initials or a generic icon when no image is provided. Available in three sizes (SM 32px, MD 40px, LG 56px) and supports an optional online status dot indicator.
12 variants
Variants
| Variant | Description | When to use |
|---|---|---|
| Image | Avatar displaying a user photo cropped to a circle. | Use when the user has uploaded a profile image. |
| Initials | Avatar showing one or two initials on a coloured background. | Use as a fallback when no profile image is available. |
| Icon | Avatar showing a generic person icon placeholder. | Use for anonymous users or when no name is available for initials. |
| Fallback |
Usage Guidelines
Provide meaningful alt text or aria-label — e.g., "Jane Doe's avatar".
Display broken image links — always implement a fallback.
Use the initials fallback when no image is available rather than leaving it blank.
Use avatars without any accessible label.
Keep initials to 1–2 characters maximum.
Mix avatar sizes within the same list or row.
Use consistent sizes within the same context (lists, headers, etc.).
Use rectangular avatars — the circular shape is the standard convention.
Code
<!-- Image avatar -->
<div class="lex-avatar lex-avatar--md">
<img src="/avatars/jane.jpg" alt="Jane Doe" class="lex-avatar__image" />
</div>
<!-- Initials fallback -->
<div class="lex-avatar lex-avatar--md" aria-label="Jane Doe">
<span class="lex-avatar__initials">JD</span>
</div>
<!-- With status indicator -->
<div class="lex-avatar lex-avatar--md" aria-label="Jane Doe, online">
<img src="/avatars/jane.jpg" alt="" class="lex-avatar__image" />
<span class="lex-avatar__status lex-avatar__status--online" aria-hidden="true"></span>
</div>.lex-avatar {
position: relative;
display: inline-flex;
align-items: center;
justify-content: center;
border-radius: 50%;
overflow: hidden;
background: var(--lex-avatar-bg, var(--lex-bg-surface-subtle));
color: var(--lex-avatar-text, var(--lex-text-secondary));
font-weight: 600;
flex-shrink: 0;
}
.lex-avatar--sm {
width: var(--lex-avatar-size-sm, 32px);
height: var(--lex-avatar-size-sm, 32px);
font-size: var(--lex-avatar-font-sm, 12px);
}
.lex-avatar--md {
width: var(--lex-avatar-size-md, 40px);
height: var(--lex-avatar-size-md, 40px);
font-size: var(--lex-avatar-font-md, 14px);
}
.lex-avatar--lg {
width: var(--lex-avatar-size-lg, 56px);
height: var(--lex-avatar-size-lg, 56px);
font-size: var(--lex-avatar-font-lg, 18px);
}
.lex-avatar__image {
width: 100%;
height: 100%;
object-fit: cover;
}
.lex-avatar__status {
position: absolute;
bottom: 0;
right: 0;
width: 10px;
height: 10px;
border-radius: 50%;
border: 2px solid var(--lex-avatar-status-ring, var(--lex-bg-surface));
}
.lex-avatar__status--online {
background: var(--lex-avatar-status-online, var(--lex-color-success));
}// Using Lexicon CSS classes with React
export function UserAvatar() {
return (
<Avatar
size="md"
src="/avatars/jane.jpg"
alt="Jane Doe"
fallback="JD"
status="online"
/>
);
}Design Tokens
| Token | Value (dark) | Value (light) | CSS property |
|---|---|---|---|
| --lex-avatar-size | — | — | size |
| --lex-avatar-radius | — | — | radius |
| --lex-avatar-bg | — | — | bg |
| --lex-avatar-text | — | — | text |
| --lex-avatar-border | — | — | border |
Accessibility
- Image avatars must have descriptive alt text — "Jane Doe" not "avatar".
- Initials and icon avatars need aria-label on the container.
- Status indicators should not rely on colour alone — include text like "online" in the aria-label.
- Decorative avatars (e.g., next to a name already shown) can use alt="" to avoid redundancy.