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:

Image Avatars
Initials Avatars
Icon Avatars
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:

Image sizes
Initials sizes
Shapes & Styles

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

Shape variants
Shape with initials
Interactive Avatars

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

Clickable avatars
Click the avatars above to see the interactive behavior. Interactive avatars show hover effects and are keyboard accessible.
Loading & Error States

The avatar component gracefully handles loading and error states:

Loading states
Error handling with fallbacks
Real-World Patterns User Profile Header
John Doe Senior Developer • Online now Send Message View Profile
Team Members List
Team Members Alice Johnson Product Manager Bob Smith UX Designer Carol Davis Frontend Developer
Avatar Groups

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

Project Collaborators
8 people are working on this project
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:

Theme-Aware Styling

Create avatars that automatically adapt to different themes:

Advanced CSS Classes

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

.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 Per-component import (Recommended)

Import the component by its own subpath. This registers <dap-ds-avatar> (and the components it renders internally) and lets your bundler include only what you use:

import 'dap-design-system/components/avatar'

Need a reference to the class (e.g. to register it manually or extend it)? The same subpath default-exports it:

import DapDSAvatar from 'dap-design-system/components/avatar'
Register everything

Register the whole library at once — convenient, but pulls every component into your bundle:

import 'dap-design-system'
Importing React 
import { DapDSAvatarReact } from 'dap-design-system/react'
Attributes
PropertyTypeDefaultDescription
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
size'xxs', 'xs' , 'sm' , 'md' , 'lg''md'The size of the avatar. Default is md.
sizeMapstringResponsive size map (e.g. "md:lg").
Slots
NameDescription
iconThe icon to display when variant is 'icon'.
fallbackCustom fallback content when image fails to load.
Events
Event NameDescriptionType
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
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
size'xxs', 'xs' , 'sm' , 'md' , 'lg''md'The size of avatars in the group. Default is md. See SizedMixin.
sizeMapstringResponsive size map (e.g. "md:lg"); see SizedMixin.
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))