Avatar Overview

The avatar component displays user profile pictures, initials, or icons in a circular, rounded, or square container. It's designed to represent users, accounts, or entities in a consistent and accessible way across your application. The component includes intelligent fallback handling, loading states, and interactive capabilities.

When to Use

✅ Use avatars when:

  • Displaying user profiles or account information
  • Showing authors or contributors in content
  • Representing team members or contacts
  • Creating user identification in lists or cards
  • Building navigation or header components

❌ Don't use avatars for:

  • Decorative images unrelated to users
  • Brand logos (use dedicated logo components)
  • Large content images (use image components)
  • Non-profile related icons (use icon components)
Examples Variants & Types

The avatar component supports three main variants with intelligent fallback handling:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Image Avatars</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar src="/img/components/apples.webp" alt="User profile"></dap-ds-avatar>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Initials Avatars</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar variant="initials" initials="John Doe"></dap-ds-avatar>
    <dap-ds-avatar variant="initials" initials="Jane Smith"></dap-ds-avatar>
    <dap-ds-avatar variant="initials" initials="A B"></dap-ds-avatar>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Icon Avatars</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar variant="icon">
      <dap-ds-icon slot="icon" name="user-line"></dap-ds-icon>
    </dap-ds-avatar>
    <dap-ds-avatar variant="icon">
      <dap-ds-icon slot="icon" name="user-fill"></dap-ds-icon>
    </dap-ds-avatar>
    <dap-ds-avatar variant="icon">
      <dap-ds-icon slot="icon" name="cookie-line"></dap-ds-icon>
    </dap-ds-avatar>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Sizes & Scaling

Choose avatar sizes based on the context and visual hierarchy. Larger avatars work well for profile pages, while smaller ones fit into compact layouts:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Image sizes</dap-ds-typography>
  <dap-ds-stack direction="row" align="center">
    <dap-ds-avatar size="lg" src="/img/components/apples.webp" alt="Large avatar"></dap-ds-avatar>
    <dap-ds-avatar size="md" src="/img/components/apples.webp" alt="Medium avatar"></dap-ds-avatar>
    <dap-ds-avatar size="sm" src="/img/components/apples.webp" alt="Small avatar"></dap-ds-avatar>
    <dap-ds-avatar size="xs" src="/img/components/apples.webp" alt="Extra small avatar"></dap-ds-avatar>
    <dap-ds-avatar size="xxs" src="/img/components/apples.webp" alt="Tiny avatar"></dap-ds-avatar>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Initials sizes</dap-ds-typography>
  <dap-ds-stack direction="row" align="center">
    <dap-ds-avatar size="lg" variant="initials" initials="J D"></dap-ds-avatar>
    <dap-ds-avatar size="md" variant="initials" initials="J S"></dap-ds-avatar>
    <dap-ds-avatar size="sm" variant="initials" initials="A B"></dap-ds-avatar>
    <dap-ds-avatar size="xs" variant="initials" initials="C D"></dap-ds-avatar>
    <dap-ds-avatar size="xxs" variant="initials" initials="E F"></dap-ds-avatar>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Shapes & Styles

Different shapes can convey different meanings or match your design aesthetic:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Shape variants</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar shape="circle" src="/img/components/apples.webp" alt="Circle avatar"></dap-ds-avatar>
    <dap-ds-avatar shape="rounded" src="/img/components/apples.webp" alt="Rounded avatar"></dap-ds-avatar>
    <dap-ds-avatar shape="square" src="/img/components/apples.webp" alt="Square avatar"></dap-ds-avatar>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Shape with initials</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar shape="circle" variant="initials" initials="Circle"></dap-ds-avatar>
    <dap-ds-avatar shape="rounded" variant="initials" initials="Round"></dap-ds-avatar>
    <dap-ds-avatar shape="square" variant="initials" initials="S Q"></dap-ds-avatar>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Interactive Avatars

Avatars can be made interactive for user actions like opening profiles or menus:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Clickable avatars</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar 
      interactive 
      src="/img/components/apples.webp" 
      alt="Clickable profile"
      label="Open user profile">
    </dap-ds-avatar>
    <dap-ds-avatar 
      interactive 
      variant="initials" 
      initials="JS"
      label="Jane Smith's profile">
    </dap-ds-avatar>
    <dap-ds-avatar 
      interactive 
      variant="icon"
      label="Settings menu">
      <dap-ds-icon slot="icon" name="user-line"></dap-ds-icon>
    </dap-ds-avatar>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="body">
    Click the avatars above to see the interactive behavior. Interactive avatars show hover effects and are keyboard accessible.
  </dap-ds-typography>
</div>
</dap-ds-stack>
</>
Loading & Error States

The avatar component gracefully handles loading and error states:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Loading states</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar loading src="/img/components/slow-image.jpg" alt="Loading avatar"></dap-ds-avatar>
    <dap-ds-avatar loading size="lg" src="/img/components/slow-image.jpg" alt="Large loading avatar"></dap-ds-avatar>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Error handling with fallbacks</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-avatar src="/nonexistent-image.jpg" alt="Broken image"></dap-ds-avatar>
    <dap-ds-avatar src="/nonexistent-image.jpg" initials="FB" alt="Fallback to initials"></dap-ds-avatar>
    <dap-ds-avatar src="/nonexistent-image.jpg" alt="Custom fallback">
      <div slot="fallback" style={{color: 'var(--dds-negative-600)'}}>
        <dap-ds-icon name="error-warning-line"></dap-ds-icon>
      </div>
    </dap-ds-avatar>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Real-World Patterns User Profile Header 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack direction="row" align="center">
  <dap-ds-avatar 
    size="lg" 
    interactive
    src="/img/components/apples.webp" 
    alt="John Doe profile"
    label="View profile details">
  </dap-ds-avatar>
  <dap-ds-stack>
    <dap-ds-typography variant="h3">John Doe</dap-ds-typography>
    <dap-ds-typography variant="body" style={{color: 'var(--dds-text-neutral-subtle)'}}>
      Senior Developer • Online now
    </dap-ds-typography>
    <dap-ds-stack direction="row">
      <dap-ds-button size="sm">Send Message</dap-ds-button>
      <dap-ds-button variant="outline" size="sm">View Profile</dap-ds-button>
    </dap-ds-stack>
  </dap-ds-stack>
</dap-ds-stack>
</div>
Team Members List 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h4">Team Members</dap-ds-typography>
  <dap-ds-stack>
    <dap-ds-stack direction="row" align="center">
      <dap-ds-avatar interactive variant="initials" initials="Alice Johnson" label="Alice Johnson"></dap-ds-avatar>
      <dap-ds-stack spacing="100">
        <dap-ds-typography variant="body" bold>Alice Johnson</dap-ds-typography>
        <dap-ds-typography variant="caption" style={{color: 'var(--dds-text-neutral-subtle)'}}>Product Manager</dap-ds-typography>
      </dap-ds-stack>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" align="center">
      <dap-ds-avatar interactive src="/img/components/80x80.png" alt="Bob Smith" label="Bob Smith"></dap-ds-avatar>
      <dap-ds-stack spacing="100">
        <dap-ds-typography variant="body" bold>Bob Smith</dap-ds-typography>
        <dap-ds-typography variant="caption" style={{color: 'var(--dds-text-neutral-subtle)'}}>UX Designer</dap-ds-typography>
      </dap-ds-stack>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" align="center">
      <dap-ds-avatar interactive variant="initials" initials="Carol Davis" label="Carol Davis"></dap-ds-avatar>
      <dap-ds-stack spacing="100">
        <dap-ds-typography variant="body" bold>Carol Davis</dap-ds-typography>
        <dap-ds-typography variant="caption" style={{color: 'var(--dds-text-neutral-subtle)'}}>Frontend Developer</dap-ds-typography>
      </dap-ds-stack>
    </dap-ds-stack>
  </dap-ds-stack>
</dap-ds-stack>
</div>
Avatar Groups

For displaying multiple avatars together, use the dedicated avatar-group component which provides proper overlap, overflow management, and accessibility:

<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h4">Project Collaborators</dap-ds-typography>
  <div style={{display: 'flex', alignItems: 'center'}}>
    <dap-ds-avatar-group 
      max="3" 
      interactive-overflow
      label="Project team members"
      overflow-label="View all team members">
      <dap-ds-avatar src="/img/components/apples.webp" alt="Project Lead"></dap-ds-avatar>
      <dap-ds-avatar variant="initials" initials="JS" alt="Jane Smith"></dap-ds-avatar>
      <dap-ds-avatar variant="initials" initials="AB" alt="Alex Brown"></dap-ds-avatar>
      <dap-ds-avatar variant="initials" initials="CD" alt="Charlie Davis"></dap-ds-avatar>
      <dap-ds-avatar variant="initials" initials="EF" alt="Eve Franklin"></dap-ds-avatar>
      <dap-ds-avatar variant="icon" alt="Additional Team Member">
        <dap-ds-icon slot="icon" name="user-line"></dap-ds-icon>
      </dap-ds-avatar>
      <dap-ds-avatar variant="initials" initials="GH" alt="Grace Hall"></dap-ds-avatar>
      <dap-ds-avatar variant="initials" initials="IJ" alt="Ian Johnson"></dap-ds-avatar>
    </dap-ds-avatar-group>
    <dap-ds-typography variant="body" style={{marginLeft: 'var(--dds-spacing-300)'}}>
      8 people are working on this project
    </dap-ds-typography>
  </div>
</dap-ds-stack>
</div>
Custom Styling

The avatar component supports extensive customization beyond the default variants. This section demonstrates practical styling techniques and advanced customization patterns.

Quick Customization with Inline Styles

For simple customizations, use CSS custom properties directly on the component:

<dap-ds-stack direction="row">
<dap-ds-avatar 
  variant="initials" 
  initials="B C"
  style={{
    '--dds-avatar-background-color': 'var(--dds-brand-600)',
    '--dds-avatar-text-color': 'var(--dds-white-100)',
    '--dds-avatar-border-width': 'var(--dds-border-width-base)',
    '--dds-avatar-border-color': 'var(--dds-brand-800)',
  }}>
</dap-ds-avatar>
<dap-ds-avatar 
  variant="initials" 
  initials="G S"
  shape="rounded"
  style={{
    '--dds-avatar-background-color': 'var(--dds-positive-200)',
    '--dds-avatar-text-color': 'var(--dds-positive-900)',
    '--dds-avatar-border-width': 'var(--dds-border-width-base)',
    '--dds-avatar-border-color': 'var(--dds-positive-600)',
  }}>
</dap-ds-avatar>
<dap-ds-avatar 
  variant="icon"
  shape="square"
  style={{
    '--dds-avatar-background-color': 'var(--dds-warning-200)',
    '--dds-avatar-text-color': 'var(--dds-warning-800)',
  }}>
  <dap-ds-icon slot="icon" name="star-fill"></dap-ds-icon>
</dap-ds-avatar>
</dap-ds-stack>
Theme-Aware Styling

Create avatars that automatically adapt to different themes:

<dap-ds-stack direction="row">
<dap-ds-avatar 
  variant="initials" 
  initials="T A"
  style={{
    '--dds-avatar-background-color': 'var(--dds-brand-1000)',
    '--dds-avatar-text-color': 'var(--dds-text-neutral-inverted)',
    '--dds-avatar-border-width': '1px',
    '--dds-avatar-border-color': 'var(--dds-border-neutral-strong)',
  }}>
</dap-ds-avatar>
<dap-ds-avatar 
  variant="initials" 
  initials="A B"
  interactive
  style={{
    '--dds-avatar-background-color': 'var(--dds-neutral-100)',
    '--dds-avatar-text-color': 'var(--dds-text-neutral-strong)',
    '--dds-avatar-hover-transform': 'scale(1.1)',
    '--dds-avatar-transition': 'all 0.3s ease',
  }}>
</dap-ds-avatar>
</dap-ds-stack>
Advanced CSS Classes

For more complex styling, use CSS classes that work with the component's CSS parts:

<dap-ds-stack direction="row">
<dap-ds-avatar 
  class="custom-avatar-brand"
  variant="initials" 
  initials="BG">
</dap-ds-avatar>
<dap-ds-avatar 
  class="custom-avatar-status"
  variant="initials" 
  initials="OS">
</dap-ds-avatar>
</dap-ds-stack>

.custom-avatar-brand {
  --dds-avatar-background-color: linear-gradient(135deg, var(--dds-brand-600), var(--dds-brand-800));
  --dds-avatar-text-color: var(--dds-white-100);
  --dds-avatar-border-radius: var(--dds-radius-large);
  --dds-avatar-border-width: var(--dds-border-width-base);
  --dds-avatar-border-color: var(--dds-brand-300);
}

.custom-avatar-status::part(base) {
  position: relative;
}

.custom-avatar-status::part(base)::after {
  content: '';
  position: absolute;
  bottom: 0;
  right: 0;
  width: var(--dds-spacing-400);
  height: var(--dds-spacing-400);
  background: var(--dds-positive-600);
  border: var(--dds-border-width-base) solid var(--dds-white-100);
  border-radius: 50%;
}
Advanced Styling with CSS Parts

Experiment with custom avatar styling using CSS parts and custom properties. Try the presets below or create your own styles:

Select a presetElevated ShadowStatus IndicatorGradient BackgroundRing EffectNeon Glow
Copy CSSFormat CSSResetLightDark
CSS Editor
Live Preview
Importing 
import { DapDSAvatar } from 'dap-design-system'
Importing React 
import { DapDSAvatarReact } from 'dap-design-system/react'
Tree-Shakeable Imports

For optimal bundle sizes, use the tree-shakeable import syntax:

import { DapDSAvatar } from 'dap-design-system/components'
Attributes
PropertyTypeDefaultDescription
size'xxs', 'xs' , 'sm' , 'md' , 'lg''md'The size of the avatar
shape'circle', 'rounded' , 'square''circle'The shape of the avatar
variant'image', 'initials' , 'icon''image'The variant type of the avatar
srcstringThe source of the avatar image
altstringThe alt text of the avatar
initialsstringThe initials to display when variant is 'initials'
labelstringAccessible label for the avatar
loadingbooleanfalseLoading state indicator
interactivebooleanfalseWhether the avatar is interactive (clickable)
widthnumberThe width of the avatar. This will override the size
heightnumberThe height of the avatar. This will override the size
Slots
NameDescription
iconThe icon to display when variant is 'icon'.
fallbackCustom fallback content when image fails to load.
Events
Event NameDescriptionType
dds-clickFired when the avatar is clicked (only when interactive).void
dds-loadFired when the image loads successfully.void
dds-errorFired when the image fails to load.void
CSS Parts
Part NameDescription
baseThe main avatar container.
imgThe avatar image.
initialsThe initials container.
iconThe icon container.
fallbackThe fallback content container.
loadingThe loading indicator.
How to Use CSS Parts

You can style CSS parts using the ::part() pseudo-element selector:

/* Target a specific part */
.my-custom-dap-ds-avatar::part(base) {
  /* Your custom styles */
}

/* Target multiple parts */
.my-custom-dap-ds-avatar::part(base),
.my-custom-dap-ds-avatar::part(img) {
  /* Shared styles */
}

Example usage:

<dap-ds-avatar class="my-custom-dap-ds-avatar">
  Avatar
</dap-ds-avatar>

.my-custom-dap-ds-avatar::part(base) {
  border-radius: 12px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.

 CSS Custom Properties
Property NameDescription
--dds-avatar-border-radiusThe border radius of the avatar (default: 50%)
--dds-avatar-background-colorThe background color of the avatar (default: var(--dds-neutral-200))
--dds-avatar-border-widthThe border width of the avatar (default: 0)
--dds-avatar-border-colorThe color of the avatar's border (default: transparent)
--dds-avatar-border-styleThe style of the avatar's border (default: solid)
--dds-avatar-transitionThe transition property for the avatar (default: all 0.2s ease-in-out)
--dds-avatar-text-colorThe text color for initials (default: var(--dds-text-neutral-strong))
--dds-avatar-font-weightThe font weight for initials (default: var(--dds-font-weight-bold))
--dds-avatar-lg-sizeSize for large avatars (default: var(--dds-avatar-size-lg))
--dds-avatar-md-sizeSize for medium avatars (default: var(--dds-avatar-size-md))
--dds-avatar-sm-sizeSize for small avatars (default: var(--dds-avatar-size-sm))
--dds-avatar-xs-sizeSize for extra small avatars (default: var(--dds-avatar-size-xs))
--dds-avatar-xxs-sizeSize for extra extra small avatars (default: var(--dds-avatar-size-xxs))
--dds-avatar-font-size-lgFont size for large avatars (default: var(--dds-font-2xl))
--dds-avatar-font-size-mdFont size for medium avatars (default: var(--dds-font-lg))
--dds-avatar-font-size-smFont size for small avatars (default: var(--dds-font-base))
--dds-avatar-font-size-xsFont size for extra small avatars (default: var(--dds-font-sm))
--dds-avatar-font-size-xxsFont size for extra extra small avatars (default: var(--dds-font-xs))
--dds-avatar-hover-transformTransform applied on hover for interactive avatars (default: scale(1.05))
--dds-avatar-active-transformTransform applied when active for interactive avatars (default: scale(0.95))
--dds-avatar-focus-ringFocus ring style for interactive avatars (default: 0 0 0 2px var(--dds-focus-outer-ring))
--dds-avatar-loading-backgroundBackground color when loading (default: var(--dds-neutral-100))
--dds-avatar-error-backgroundBackground color when image fails to load (default: var(--dds-negative-100))
--dds-avatar-error-colorText color when image fails to load (default: var(--dds-negative-600))
How to Use CSS Custom Properties

CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:

Method 1: Inline styles (Quick customization)

<dap-ds-avatar
  style="--dds-avatar-border-radius: value; --dds-avatar-background-color: value;">
  Avatar
</dap-ds-avatar>

Method 2: CSS classes (Reusable styles)

.my-custom-dap-ds-avatar {
  --dds-avatar-border-radius: value;
  --dds-avatar-background-color: value;
  --dds-avatar-border-width: value;
}

<dap-ds-avatar class="my-custom-dap-ds-avatar">
  Avatar
</dap-ds-avatar>

Method 3: Global theme customization

/* Apply to all instances */
dap-ds-avatar {
  --dds-avatar-border-radius: value;
  --dds-avatar-background-color: value;
}

CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.

 Components Avatar Group <dap-ds-avatar-group/> Attributes
PropertyTypeDefaultDescription
size'xxs', 'xs' , 'sm' , 'md' , 'lg''md'The size of avatars in the group
layout'stack', 'grid''stack'Layout type for the avatar group
maxnumber3Maximum number of avatars to show before showing overflow
showTotalbooleanfalseWhether to show the total count in overflow indicator
interactiveOverflowbooleanfalseInteractive overflow indicator
labelstringAccessible label for the avatar group
overflowLabelstringAccessible label for the overflow indicator
Slots
NameDescription
(default)The avatars to display in the group.
Events
Event NameDescriptionType
dds-overflow-clickFired when the overflow indicator is clicked.void
CSS Parts
Part NameDescription
baseThe main container of the avatar group.
avatarsThe container for the visible avatars.
overflowThe overflow indicator element.
CSS Custom Properties
Property NameDescription
--dds-avatar-group-gapGap between avatars in grid layout (default: 0)
--dds-avatar-group-overlapOverlap amount for stacked layout (default: -8px)
--dds-avatar-group-border-widthBorder width for avatars (default: var(--dds-border-width-base))
--dds-avatar-group-border-colorBorder color for avatars (default: var(--dds-border-neutral-divider))
--dds-avatar-group-overflow-bgBackground color for overflow indicator (default: var(--dds-neutral-300))
--dds-avatar-group-overflow-colorText color for overflow indicator (default: var(--dds-neutral-700))
--dds-avatar-group-overflow-borderBorder for overflow indicator (default: var(--dds-avatar-group-border-width) solid var(--dds-avatar-group-border-color))
--dds-avatar-group-size-lgSize for large avatars (default: var(--dds-spacing-2000))
--dds-avatar-group-size-mdSize for medium avatars (default: var(--dds-spacing-1600))
--dds-avatar-group-size-smSize for small avatars (default: var(--dds-spacing-1200))
--dds-avatar-group-size-xsSize for extra small avatars (default: var(--dds-spacing-800))
--dds-avatar-group-size-xxsSize for extra extra small avatars (default: var(--dds-spacing-400))