Avatars are visual representations of users, teams, or entities within interfaces. The ELEVATE Avatar component helps designers and developers create consistent, accessible identity systems that enhance user recognition and provide clear visual identification across all interface contexts.

Overview
Variations
Design Principles
Best Practices
Implementation
Interactive Examples
Accessibility
Changelog

Overview

When to Use Avatars

User identification: Profile areas, user lists, comments sections, and author attribution
Team representation: Member lists, collaboration interfaces, and group displays
Entity representation: Organizations, projects, departments, or system accounts
Navigation elements: User menus, account switching, and profile access points
Social features: Comments, reviews, messaging, and activity feeds
Contact lists: Address books, directory listings, and people browsing

When NOT to Use Avatars

Decorative images: Use Image component for non-representative visuals or illustrations
Large portraits: Use dedicated image layouts for hero content or detailed profile photos
Complex graphics: Use appropriate media components for logos, diagrams, or artwork
Brand representation: Use dedicated logo or brand components for company identification
Non-human entities: Consider appropriate icon or image components for objects or concepts

Variations

Image Avatar

Standard avatar displaying user’s profile photo or uploaded image with automatic fallback to initials.

Image Avatar with Fallback

Interactive ELEVATE components with design tokens will load after hydration

<div style="display: flex; align-items: center; gap: 1rem;">
  <elvt-avatar 
    src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=100&h=100&fit=crop&crop=face" 
    alt="John Doe" 
    initials="JD"
    size="medium">
  </elvt-avatar>
  <elvt-avatar 
    src="invalid-url.jpg"

Initials Avatar

Fallback avatar displaying user’s initials with customizable background colors for visual distinction.

Initials Avatar Variations

Interactive ELEVATE components with design tokens will load after hydration

<div style="display: flex; align-items: center; gap: 1rem;">
  <elvt-avatar 
    initials="JD" 
    name="John Doe"
    size="medium">
  </elvt-avatar>
  <elvt-avatar 
    initials="SW" 
    name="Sarah Wilson"

Size Variations

Multiple size options to match different interface contexts and space requirements.

Avatar Size Options

Interactive ELEVATE components with design tokens will load after hydration

<div style="display: flex; align-items: center; gap: 1rem;">
  <elvt-avatar 
    initials="XS" 
    size="xs"
    title="Extra Small (16px)">
  </elvt-avatar>
  <elvt-avatar 
    initials="SM" 
    size="small"

Shape Variations

Different shape options for various design contexts and branding requirements.

Avatar Shape Options

Interactive ELEVATE components with design tokens will load after hydration

<div style="display: flex; align-items: center; gap: 1rem;">
  <elvt-avatar 
    initials="RD" 
    variant="circular"
    size="large"
    title="Circular (default)">
  </elvt-avatar>
  <elvt-avatar 
    initials="SQ"

Status Indicators

Avatar with status indicators showing online, offline, or activity states for real-time communication.

Avatar with Status Indicators

Interactive ELEVATE components with design tokens will load after hydration

<div style="display: flex; align-items: center; gap: 1rem;">
  <elvt-avatar 
    initials="ON" 
    size="large"
    status="online"
    title="Online status">
  </elvt-avatar>
  <elvt-avatar 
    initials="AW"

Design Principles

Understanding these core principles will help you create avatar systems that enhance user recognition and provide clear identity representation across your application.

Identity Clarity Principle

Avatars should immediately identify users or entities. Users rely on avatars for quick recognition in lists, comments, and collaborative interfaces. Poor image quality or unclear initials slow down user identification and reduce interface efficiency.

Visual Consistency Principle

Similar avatar contexts should use similar visual treatments. Consistent sizing, spacing, and styling across similar interface areas helps users build familiarity with your avatar system and improves recognition speed.

Graceful Degradation Principle

Avatars should work well even when primary content fails to load. Image loading can fail for various reasons, so initials and placeholder states should provide meaningful fallbacks that maintain user identification.

Inclusive Representation Principle

Avatar systems should work for all users regardless of names or image availability. Some users may not have profile photos, and name-based initials should handle various naming conventions and character sets appropriately.

Best Practices

Creating Effective Initials Fallbacks

Why this matters: Poor initials generation creates confusion when images fail to load. Users should be able to identify people by their initials even when profile photos aren’t available.

JD

SW

MJ

Use clear, readable initials with sufficient contrast and logical derivation

J

??

USER

Don't use unclear initials or poor contrast that makes identification difficult

Maintaining Appropriate Sizing Context

Why this matters: Wrong avatar sizing breaks visual hierarchy and makes interfaces feel unbalanced. Avatar size should match the importance and space constraints of its context.

JS

Comment by Jane Smith

JD

John Doe - Profile Header

Use appropriate sizes that match content hierarchy and available space

JS

Small comment text

JD

Main Profile Header

Don't use oversized or undersized avatars that break visual hierarchy

Implementation

Getting Started

npm install @inform-elevate/elevate-core-ui
Copy to clipboard

Basic Usage

<elvt-avatar 
  src="/path/to/image.jpg" 
  alt="John Doe"
  initials="JD">
</elvt-avatar>
Copy to clipboard

With Fallback Initials

<elvt-avatar 
  initials="JD" 
  name="John Doe">
</elvt-avatar>
Copy to clipboard

With Status Indicator

<elvt-avatar 
  src="/path/to/image.jpg" 
  alt="John Doe"
  status="online">
</elvt-avatar>
Copy to clipboard

Different Shapes

<elvt-avatar 
  initials="JS" 
  variant="square"
  size="large">
</elvt-avatar>
Copy to clipboard

Key Properties

The most commonly used properties for design and development:

Property	Options	Description
src	URL string	Avatar image source with automatic fallback
initials	String (1-3 chars)	Fallback initials when image unavailable
name	String	Full name for auto-generating initials
size	xs , small , medium , large , xl	Avatar size for different contexts
variant	circular , rounded , square	Shape treatment for design needs
status	online , offline , away , busy	Status indicator for communication apps
alt	String	Alternative text for accessibility

For complete API reference including all properties, events, and methods, see the Storybook documentation.

Interactive Examples

Live Avatar Playground

Experience how avatars behave in realistic contexts. All examples use actual ELEVATE components.

Team Directory Interface

Interactive ELEVATE components with design tokens will load after hydration

<div style="max-width: 500px; padding: 1.5rem; border: 1px solid #e0e0e0; border-radius: 8px;">
  <h3 style="margin-top: 0; margin-bottom: 1rem;">Development Team</h3>
  
  <div style="display: flex; flex-direction: column; gap: 1rem;">
    <!-- Team Lead -->
    <div style="display: flex; align-items: center; gap: 1rem; padding: 0.75rem; border-radius: 8px; background: #f8f9fa;">
      <elvt-avatar 
        src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=100&h=100&fit=crop&crop=face" 
        alt="John Doe"

Accessibility

Essential Accessibility Practices

Proper image semantics are critical:

<!-- Good: Meaningful alt text and proper labeling -->
<elvt-avatar 
  src="/path/to/image.jpg"
  alt="John Doe, Team Lead"
  initials="JD">
</elvt-avatar>

<!-- Bad: Missing or generic alt text -->
<elvt-avatar 
Copy to clipboard

Screen reader support:

Images announce the full user name from alt text
Initials avatars announce the name or derived identity
Status indicators are communicated through appropriate ARIA attributes
Failed image loads gracefully fall back to initials with proper announcements

Keyboard navigation:

Tab moves focus to interactive avatars (when clickable)
Enter and Space activate clickable avatars
Focus indicators are clearly visible
Non-interactive avatars are not focusable

Visual accessibility:

Initials have sufficient color contrast (4.5:1 minimum)
Status indicators don’t rely solely on color
Focus indicators meet WCAG contrast requirements
Avatars work in high contrast mode

Inclusive naming:

Initials generation handles various naming conventions
Non-Latin characters are supported appropriately
Missing names gracefully fall back to generic placeholders
Names are announced correctly by screen readers

Changelog

Version 0.0.26-alpha (July 16, 2025)

Current version in active development

Version 0.0.7-alpha (April 11, 2025)

Fixed: Fix Initials Size in Avatar

Version 0.0.4-alpha (March 28, 2025)

New: Add Square Avatar Shape

Version 0.0.1-alpha (March 14, 2025)

New: Add Avatar Component (initial implementation)

Edit this page on GitHub

Components: Application

Components: Badge