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.
✅ 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)
The avatar component supports three main variants with intelligent fallback handling:
Choose avatar sizes based on the context and visual hierarchy. Larger avatars work well for profile pages, while smaller ones fit into compact layouts:
Different shapes can convey different meanings or match your design aesthetic:
Avatars can be made interactive for user actions like opening profiles or menus:
The avatar component gracefully handles loading and error states:
For displaying multiple avatars together, use the dedicated avatar-group component which provides proper overlap, overflow management, and accessibility:
The avatar component supports extensive customization beyond the default variants. This section demonstrates practical styling techniques and advanced customization patterns.
For simple customizations, use CSS custom properties directly on the component:
Create avatars that automatically adapt to different themes:
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%;
}
Experiment with custom avatar styling using CSS parts and custom properties. Try the presets below or create your own styles:
import { DapDSAvatar } from 'dap-design-system'
import { DapDSAvatarReact } from 'dap-design-system/react'
For optimal bundle sizes, use the tree-shakeable import syntax:
import { DapDSAvatar } from 'dap-design-system/components'
| 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 |
| Name | Description |
|---|---|
icon | The icon to display when variant is 'icon'. |
fallback | Custom fallback content when image fails to load. |
| 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 |
| 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. |
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.
| Property Name | Description |
|---|---|
--dds-avatar-border-radius | The border radius of the avatar. Default is 50%. |
--dds-avatar-background-color | The background color of the avatar. Default is var(--dds-neutral-200). |
--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 var(--dds-text-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 var(--dds-font-weight-bold). |
--dds-avatar-lg-size | The size of the large avatar. Default is var(--dds-avatar-size-lg). |
--dds-avatar-md-size | The size of the medium avatar. Default is var(--dds-avatar-size-md). |
--dds-avatar-sm-size | The size of the small avatar. Default is var(--dds-avatar-size-sm). |
--dds-avatar-xs-size | The size of the extra small avatar. Default is var(--dds-avatar-size-xs). |
--dds-avatar-xxs-size | The size of the extra extra small avatar. Default is var(--dds-avatar-size-xxs). |
--dds-avatar-font-size-lg | The font size for initials in the large avatar. Default is var(--dds-font-2xl). |
--dds-avatar-font-size-md | The font size for initials in the medium avatar. Default is var(--dds-font-lg). |
--dds-avatar-font-size-sm | The font size for initials in the small avatar. Default is var(--dds-font-base). |
--dds-avatar-font-size-xs | The font size for initials in the extra small avatar. Default is var(--dds-font-sm). |
--dds-avatar-font-size-xxs | The font size for initials in the extra extra small avatar. Default is var(--dds-font-xs). |
--dds-avatar-hover-transform | The transform property for the avatar when hovered. Default is scale(1.05). |
--dds-avatar-active-transform | The transform property for the avatar when active. Default is scale(0.95). |
--dds-avatar-focus-ring | The focus ring for the avatar. Default is 0 0 0 2px var(--dds-focus-outer-ring). |
--dds-avatar-loading-background | The background color for the loading state. Default is var(--dds-neutral-100). |
--dds-avatar-error-background | The background color for the error state. Default is var(--dds-negative-100). |
--dds-avatar-error-color | The color for the error state. Default is var(--dds-negative-600). |
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.
| 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 |
| Name | Description |
|---|---|
(default) | The avatars to display in the group. |
| Event Name | Description | Type |
|---|---|---|
dds-overflow-click | Fired when the overflow indicator is clicked. | void |
| Part Name | Description |
|---|---|
base | The main container of the avatar group. |
avatars | The container for the visible avatars. |
overflow | The overflow indicator element. |
| 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. |
