Avatar webcomponent - DÁP Szolgáltatások

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:

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

Property	Type	Default	Description
`shape`	`'circle'`, `'rounded'` , `'square'`	`'circle'`	The shape of the avatar
`variant`	`'image'`, `'initials'` , `'icon'`	`'image'`	The variant type of the avatar
`src`	`string`		The source of the avatar image
`alt`	`string`		The alt text of the avatar
`initials`	`string`		The initials to display when variant is 'initials'
`label`	`string`		Accessible label for the avatar
`loading`	`boolean`	`false`	Loading state indicator
`interactive`	`boolean`	`false`	Whether the avatar is interactive (clickable)
`width`	`number`		The width of the avatar. This will override the size
`height`	`number`		The height of the avatar. This will override the size
`size`	`'xxs'`, `'xs'` , `'sm'` , `'md'` , `'lg'`	`'md'`	The size of the avatar. Default is `md`.
`sizeMap`	`string`		Responsive size map (e.g. "md:lg").

Slots

Name	Description
`icon`	The icon to display when variant is 'icon'.
`fallback`	Custom fallback content when image fails to load.

Events

Event Name	Description	Type
`dds-load`	Fired when the image loads successfully.	void
`dds-error`	Fired when the image fails to load.	void

CSS Parts

Part Name	Description
`base`	The main avatar container.
`img`	The avatar image.
`initials`	The initials container.
`icon`	The icon container.
`fallback`	The fallback content container.
`loading`	The 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 Name	Description
`--dds-avatar-border-radius`	The border radius of the avatar (default: 50%)
`--dds-avatar-background-color`	The background color of the avatar (default: var(--dds-neutral-200))
`--dds-avatar-border-width`	The border width of the avatar (default: 0)
`--dds-avatar-border-color`	The color of the avatar's border (default: transparent)
`--dds-avatar-border-style`	The style of the avatar's border (default: solid)
`--dds-avatar-transition`	The transition property for the avatar (default: all 0.2s ease-in-out)
`--dds-avatar-text-color`	The text color for initials (default: var(--dds-text-neutral-strong))
`--dds-avatar-font-weight`	The font weight for initials (default: var(--dds-font-weight-bold))
`--dds-avatar-lg-size`	Size for large avatars (default: var(--dds-avatar-size-lg))
`--dds-avatar-md-size`	Size for medium avatars (default: var(--dds-avatar-size-md))
`--dds-avatar-sm-size`	Size for small avatars (default: var(--dds-avatar-size-sm))
`--dds-avatar-xs-size`	Size for extra small avatars (default: var(--dds-avatar-size-xs))
`--dds-avatar-xxs-size`	Size for extra extra small avatars (default: var(--dds-avatar-size-xxs))
`--dds-avatar-font-size-lg`	Font size for large avatars (default: var(--dds-font-2xl))
`--dds-avatar-font-size-md`	Font size for medium avatars (default: var(--dds-font-lg))
`--dds-avatar-font-size-sm`	Font size for small avatars (default: var(--dds-font-base))
`--dds-avatar-font-size-xs`	Font size for extra small avatars (default: var(--dds-font-sm))
`--dds-avatar-font-size-xxs`	Font size for extra extra small avatars (default: var(--dds-font-xs))
`--dds-avatar-hover-transform`	Transform applied on hover for interactive avatars (default: scale(1.05))
`--dds-avatar-active-transform`	Transform applied when active for interactive avatars (default: scale(0.95))
`--dds-avatar-focus-ring`	Focus ring style for interactive avatars (default: 0 0 0 2px var(--dds-focus-outer-ring))
`--dds-avatar-loading-background`	Background color when loading (default: var(--dds-neutral-100))
`--dds-avatar-error-background`	Background color when image fails to load (default: var(--dds-negative-100))
`--dds-avatar-error-color`	Text 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

Property	Type	Default	Description
`layout`	`'stack'`, `'grid'`	`'stack'`	Layout type for the avatar group
`max`	`number`	`3`	Maximum number of avatars to show before showing overflow
`showTotal`	`boolean`	`false`	Whether to show the total count in overflow indicator
`interactiveOverflow`	`boolean`	`false`	Interactive overflow indicator
`label`	`string`		Accessible label for the avatar group
`overflowLabel`	`string`		Accessible label for the overflow indicator
`size`	`'xxs'`, `'xs'` , `'sm'` , `'md'` , `'lg'`	`'md'`	The size of avatars in the group. Default is `md`. See SizedMixin.
`sizeMap`	`string`		Responsive size map (e.g. "md:lg"); see SizedMixin.

Slots

Name	Description
`(default)`	The avatars to display in the group.

Events

Event Name	Description	Type
`dds-overflow-click`	Fired when the overflow indicator is clicked.	void

CSS Parts

Part Name	Description
`base`	The main container of the avatar group.
`avatars`	The container for the visible avatars.
`overflow`	The overflow indicator element.

CSS Custom Properties

Property Name	Description
`--dds-avatar-group-gap`	Gap between avatars in grid layout (default: 0)
`--dds-avatar-group-overlap`	Overlap amount for stacked layout (default: -8px)
`--dds-avatar-group-border-width`	Border width for avatars (default: var(--dds-border-width-base))
`--dds-avatar-group-border-color`	Border color for avatars (default: var(--dds-border-neutral-divider))
`--dds-avatar-group-overflow-bg`	Background color for overflow indicator (default: var(--dds-neutral-300))
`--dds-avatar-group-overflow-color`	Text color for overflow indicator (default: var(--dds-neutral-700))
`--dds-avatar-group-overflow-border`	Border for overflow indicator (default: var(--dds-avatar-group-border-width) solid var(--dds-avatar-group-border-color))
`--dds-avatar-group-size-lg`	Size for large avatars (default: var(--dds-spacing-2000))
`--dds-avatar-group-size-md`	Size for medium avatars (default: var(--dds-spacing-1600))
`--dds-avatar-group-size-sm`	Size for small avatars (default: var(--dds-spacing-1200))
`--dds-avatar-group-size-xs`	Size for extra small avatars (default: var(--dds-spacing-800))
`--dds-avatar-group-size-xxs`	Size for extra extra small avatars (default: var(--dds-spacing-400))

Avatar

Overview

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:

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

Property	Type	Default	Description
`shape`	`'circle'`, `'rounded'` , `'square'`	`'circle'`	The shape of the avatar
`variant`	`'image'`, `'initials'` , `'icon'`	`'image'`	The variant type of the avatar
`src`	`string`		The source of the avatar image
`alt`	`string`		The alt text of the avatar
`initials`	`string`		The initials to display when variant is 'initials'
`label`	`string`		Accessible label for the avatar
`loading`	`boolean`	`false`	Loading state indicator
`interactive`	`boolean`	`false`	Whether the avatar is interactive (clickable)
`width`	`number`		The width of the avatar. This will override the size
`height`	`number`		The height of the avatar. This will override the size
`size`	`'xxs'`, `'xs'` , `'sm'` , `'md'` , `'lg'`	`'md'`	The size of the avatar. Default is `md`.
`sizeMap`	`string`		Responsive size map (e.g. "md:lg").

Slots

Name	Description
`icon`	The icon to display when variant is 'icon'.
`fallback`	Custom fallback content when image fails to load.

Events

Event Name	Description	Type
`dds-load`	Fired when the image loads successfully.	void
`dds-error`	Fired when the image fails to load.	void

CSS Parts

Part Name	Description
`base`	The main avatar container.
`img`	The avatar image.
`initials`	The initials container.
`icon`	The icon container.
`fallback`	The fallback content container.
`loading`	The 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 Name	Description
`--dds-avatar-border-radius`	The border radius of the avatar (default: 50%)
`--dds-avatar-background-color`	The background color of the avatar (default: var(--dds-neutral-200))
`--dds-avatar-border-width`	The border width of the avatar (default: 0)
`--dds-avatar-border-color`	The color of the avatar's border (default: transparent)
`--dds-avatar-border-style`	The style of the avatar's border (default: solid)
`--dds-avatar-transition`	The transition property for the avatar (default: all 0.2s ease-in-out)
`--dds-avatar-text-color`	The text color for initials (default: var(--dds-text-neutral-strong))
`--dds-avatar-font-weight`	The font weight for initials (default: var(--dds-font-weight-bold))
`--dds-avatar-lg-size`	Size for large avatars (default: var(--dds-avatar-size-lg))
`--dds-avatar-md-size`	Size for medium avatars (default: var(--dds-avatar-size-md))
`--dds-avatar-sm-size`	Size for small avatars (default: var(--dds-avatar-size-sm))
`--dds-avatar-xs-size`	Size for extra small avatars (default: var(--dds-avatar-size-xs))
`--dds-avatar-xxs-size`	Size for extra extra small avatars (default: var(--dds-avatar-size-xxs))
`--dds-avatar-font-size-lg`	Font size for large avatars (default: var(--dds-font-2xl))
`--dds-avatar-font-size-md`	Font size for medium avatars (default: var(--dds-font-lg))
`--dds-avatar-font-size-sm`	Font size for small avatars (default: var(--dds-font-base))
`--dds-avatar-font-size-xs`	Font size for extra small avatars (default: var(--dds-font-sm))
`--dds-avatar-font-size-xxs`	Font size for extra extra small avatars (default: var(--dds-font-xs))
`--dds-avatar-hover-transform`	Transform applied on hover for interactive avatars (default: scale(1.05))
`--dds-avatar-active-transform`	Transform applied when active for interactive avatars (default: scale(0.95))
`--dds-avatar-focus-ring`	Focus ring style for interactive avatars (default: 0 0 0 2px var(--dds-focus-outer-ring))
`--dds-avatar-loading-background`	Background color when loading (default: var(--dds-neutral-100))
`--dds-avatar-error-background`	Background color when image fails to load (default: var(--dds-negative-100))
`--dds-avatar-error-color`	Text 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

Property	Type	Default	Description
`layout`	`'stack'`, `'grid'`	`'stack'`	Layout type for the avatar group
`max`	`number`	`3`	Maximum number of avatars to show before showing overflow
`showTotal`	`boolean`	`false`	Whether to show the total count in overflow indicator
`interactiveOverflow`	`boolean`	`false`	Interactive overflow indicator
`label`	`string`		Accessible label for the avatar group
`overflowLabel`	`string`		Accessible label for the overflow indicator
`size`	`'xxs'`, `'xs'` , `'sm'` , `'md'` , `'lg'`	`'md'`	The size of avatars in the group. Default is `md`. See SizedMixin.
`sizeMap`	`string`		Responsive size map (e.g. "md:lg"); see SizedMixin.

Slots

Name	Description
`(default)`	The avatars to display in the group.

Events

Event Name	Description	Type
`dds-overflow-click`	Fired when the overflow indicator is clicked.	void

CSS Parts

Part Name	Description
`base`	The main container of the avatar group.
`avatars`	The container for the visible avatars.
`overflow`	The overflow indicator element.

CSS Custom Properties

Property Name	Description
`--dds-avatar-group-gap`	Gap between avatars in grid layout (default: 0)
`--dds-avatar-group-overlap`	Overlap amount for stacked layout (default: -8px)
`--dds-avatar-group-border-width`	Border width for avatars (default: var(--dds-border-width-base))
`--dds-avatar-group-border-color`	Border color for avatars (default: var(--dds-border-neutral-divider))
`--dds-avatar-group-overflow-bg`	Background color for overflow indicator (default: var(--dds-neutral-300))
`--dds-avatar-group-overflow-color`	Text color for overflow indicator (default: var(--dds-neutral-700))
`--dds-avatar-group-overflow-border`	Border for overflow indicator (default: var(--dds-avatar-group-border-width) solid var(--dds-avatar-group-border-color))
`--dds-avatar-group-size-lg`	Size for large avatars (default: var(--dds-spacing-2000))
`--dds-avatar-group-size-md`	Size for medium avatars (default: var(--dds-spacing-1600))
`--dds-avatar-group-size-sm`	Size for small avatars (default: var(--dds-spacing-1200))
`--dds-avatar-group-size-xs`	Size for extra small avatars (default: var(--dds-spacing-800))
`--dds-avatar-group-size-xxs`	Size for extra extra small avatars (default: var(--dds-spacing-400))