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="BC"
  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="GS"
  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%;
}

CSS Parts for Sophisticated Styling

Use CSS parts to style specific elements within the avatar:

<dap-ds-stack direction="row">
<dap-ds-avatar 
  class="avatar-gradient"
  variant="initials" 
  initials="BG">
</dap-ds-avatar>
<dap-ds-avatar 
  class="avatar-shadow"
  variant="initials" 
  initials="OS">
</dap-ds-avatar>
</dap-ds-stack>

.avatar-gradient::part(initials) {
  background: linear-gradient(45deg, var(--dds-violet-600), var(--dds-pink-600));
  -webkit-background-clip: text;
  background-clip: text;
  -webkit-text-fill-color: transparent;
  font-weight: var(--dds-font-weight-black);
}

.avatar-shadow::part(base) {
  box-shadow: 0 var(--dds-spacing-200) var(--dds-spacing-400) rgba(0, 0, 0, 0.15);
  transition: box-shadow 0.3s ease;
}

.avatar-shadow::part(base):hover {
  box-shadow: 0 var(--dds-spacing-400) var(--dds-spacing-800) rgba(0, 0, 0, 0.2);
}

Importing

import { DapDSAvatar } from 'dap-design-system/dist/dds'

Importing React

import { DapDSAvatarReact } from 'dap-design-system/dist/react'

Attributes

Property	Type	Default	Description
`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
`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

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-click`	Fired when the avatar is clicked (only when interactive).	void
`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.

CSS Custom Properties

Property Name	Description
`--dds-avatar-border-radius`	The border radius of the avatar. Default varies by shape.
`--dds-avatar-background-color`	The background color of the avatar. Default is neutral.
`--dds-avatar-border-width`	The width of the avatar's border. Default is 0.
`--dds-avatar-border-color`	The color of the avatar's border. Default is transparent.
`--dds-avatar-border-style`	The style of the avatar's border. Default is solid.
`--dds-avatar-transition`	The transition property for the avatar. Default is 'all 0.2s ease-in-out'.
`--dds-avatar-text-color`	The color of initials text. Default is neutral strong.
`--dds-avatar-font-size`	The font size for initials. Calculated based on size.
`--dds-avatar-font-weight`	The font weight for initials. Default is semibold.
`--dds-avatar-size-lg`	The size of the large avatar. Default is 80px.
`--dds-avatar-size-md`	The size of the medium avatar. Default is 64px.
`--dds-avatar-size-sm`	The size of the small avatar. Default is 48px.
`--dds-avatar-size-xs`	The size of the extra small avatar. Default is 32px.
`--dds-avatar-size-xxs`	The size of the extra extra small avatar. Default is 24px.

Components

Avatar Group

<dap-ds-avatar-group/>

Attributes

Property	Type	Default	Description
`size`	`'xxs'`, `'xs'` , `'sm'` , `'md'` , `'lg'`	`'md'`	The size of avatars in the group
`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

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 is 0.
`--dds-avatar-group-overlap`	Overlap amount for stacked layout. Default is -8px.
`--dds-avatar-group-border-width`	Border width for avatars. Default is 2px.
`--dds-avatar-group-border-color`	Border color for avatars. Default is white.
`--dds-avatar-group-overflow-bg`	Background color for overflow indicator.
`--dds-avatar-group-overflow-color`	Text color for overflow indicator.
`--dds-avatar-group-overflow-border`	Border for overflow indicator.
`--dds-avatar-group-size-lg`	Size for large avatars. Default is 80px.
`--dds-avatar-group-size-md`	Size for medium avatars. Default is 64px.
`--dds-avatar-group-size-sm`	Size for small avatars. Default is 48px.
`--dds-avatar-group-size-xs`	Size for extra small avatars. Default is 32px.
`--dds-avatar-group-size-xxs`	Size for extra extra small avatars. Default is 24px.