CSS-Only

Avatar

Circular avatar component with image support, initials fallback, status indicators, and size variants. Works by default, enhances with data attributes.

Example

User avatar
User avatar 
<div class="omni-avatar" data-size="md">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="md" data-initials="JD" data-variant="primary"></div>
<div class="omni-avatar" data-size="md" data-status="online">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="md" data-initials="AB" data-variant="success" data-status="busy"></div>

Variants

Sizes

Use data-size to adjust avatar dimensions. Status indicators scale proportionally with avatar size:

User avatar
User avatar
User avatar
User avatar
User avatar 
<div class="omni-avatar" data-size="xs">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="sm">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="md">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="lg">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="xl">
  <img src="user.jpg" alt="User avatar">
</div>

Initials Fallback

Use data-initials to show initials when no image is available. Combine with data-variant for semantic colors:

<div class="omni-avatar" data-size="md" data-initials="JD"></div>
<div class="omni-avatar" data-size="md" data-initials="AB" data-variant="primary"></div>
<div class="omni-avatar" data-size="md" data-initials="CD" data-variant="secondary"></div>
<div class="omni-avatar" data-size="md" data-initials="EF" data-variant="success"></div>
<div class="omni-avatar" data-size="md" data-initials="GH" data-variant="warning"></div>
<div class="omni-avatar" data-size="md" data-initials="IJ" data-variant="danger"></div>

Status Indicators

Use data-status to show user presence. Status dots scale proportionally with avatar size:

Online

User avatar
User avatar
User avatar

Offline

User avatar
User avatar
User avatar

Busy

User avatar
User avatar
User avatar 
<div class="omni-avatar" data-size="md" data-status="online">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="md" data-status="offline">
  <img src="user.jpg" alt="User avatar">
</div>
<div class="omni-avatar" data-size="md" data-status="busy">
  <img src="user.jpg" alt="User avatar">
</div>

Status with Initials

Status indicators work with both images and initials fallbacks:

<div class="omni-avatar" data-size="md" data-initials="JD" data-variant="primary" data-status="online"></div>
<div class="omni-avatar" data-size="md" data-initials="AB" data-variant="success" data-status="offline"></div>
<div class="omni-avatar" data-size="md" data-initials="CD" data-variant="warning" data-status="busy"></div>

Avatar Group

Use omni-avatar-group to stack multiple avatars with overlapping edges:

User 1
User 2
User 3 
<div class="omni-avatar-group">
  <div class="omni-avatar" data-size="md">
    <img src="user1.jpg" alt="User 1">
  </div>
  <div class="omni-avatar" data-size="md">
    <img src="user2.jpg" alt="User 2">
  </div>
  <div class="omni-avatar" data-size="md">
    <img src="user3.jpg" alt="User 3">
  </div>
  <div class="omni-avatar" data-size="md" data-initials="+3" data-variant="secondary"></div>
</div>

API Reference

Attribute Values Default Description
data-size xs, sm, md, lg, xl md Avatar dimensions and font size
data-initials any string — Text to display when no image is provided (automatically uppercased)
data-variant primary, secondary, success, warning, danger, info — Semantic color variant for initials background
data-status online, offline, busy — Presence indicator shown as a dot in the bottom-right corner

CSS Custom Properties

These token variables control avatar sizing. Status dots scale proportionally (12.5% of avatar size):

Property Default Description
--omni-avatar-size-xs 1.5rem (24px) Extra small avatar size
--omni-avatar-size-sm 2rem (32px) Small avatar size
--omni-avatar-size 2.5rem (40px) Default (medium) avatar size
--omni-avatar-size-lg 3rem (48px) Large avatar size
--omni-avatar-size-xl 4rem (64px) Extra large avatar size

Accessibility

  • Always include descriptive alt text on avatar images
  • Use empty alt="" if the avatar is purely decorative and adjacent to the user's name
  • Status indicators are visual only - include status in adjacent text or use aria-label on the parent container if critical
  • Initials are automatically uppercased and use sufficient color contrast ratios
  • Consider adding role="img" and aria-label to initials-only avatars for screen readers
  • Avatar groups should be wrapped in appropriate semantic containers with proper labels

Example with Accessibility

<!-- Avatar with descriptive alt text -->
<div class="omni-avatar" data-size="md">
  <img src="user.jpg" alt="Jane Doe, Software Engineer">
</div>

<!-- Decorative avatar next to name -->
<div style="display: flex; align-items: center; gap: 0.5rem;">
  <div class="omni-avatar" data-size="sm">
    <img src="user.jpg" alt="">
  </div>
  <span>Jane Doe</span>
</div>

<!-- Initials with screen reader label -->
<div class="omni-avatar" data-size="md" data-initials="JD" data-variant="primary"
     role="img" aria-label="Jane Doe"></div>

<!-- Status with contextual information -->
<div class="omni-avatar" data-size="md" data-status="online"
     aria-label="Jane Doe, online">
  <img src="user.jpg" alt="">
</div>