Avatar

Initials

Display user initials as a text-based avatar

AB

<div class="nds-avatar nds-lg">
  <span class="nds-label">AB</span>
</div>

Icon

Use an icon as the avatar content for generic user placeholders

<div class="nds-avatar nds-lg">
  <i class="nds-icon nds-icon-avatar" aria-hidden="true"></i>
</div>

Image

Display a user photo with optional image border

<div class="nds-avatar nds-lg">
  <img src="path/to/avatar.jpg" alt="User Avatar">
</div>

Link

Wrap in an anchor tag for clickable profile navigation

<a href="/user/profile" class="nds-avatar nds-lg">
  <i class="nds-icon nds-icon-avatar" aria-hidden="true"></i>
</a>

Dropmenu Trigger

Avatar as a dropmenu trigger for user menus and profile actions


<div class="nds-dropmenu">
    <button type="button" class="nds-avatar nds-lg nds-dropmenu-trigger" aria-label="Open user menu">
        <i class="nds-icon nds-icon-avatar" aria-hidden="true"></i>
    </button>
    <div class="nds-dropmenu-menu" hidden>
        <div class="nds-dropmenu-scroll">
            <a href="#" class="nds-btn nds-subtle nds-dropmenu-item">
                <span class="nds-label">Profile</span>
            </a>
            <a href="#" class="nds-btn nds-subtle nds-dropmenu-item">
                <span class="nds-label">Settings</span>
            </a>
            <a href="#" class="nds-btn nds-subtle nds-dropmenu-item">
                <span class="nds-label">Sign out</span>
            </a>
        </div>
    </div>
</div>

Group

Stack multiple avatars together with overlapping or spaced layouts

+99


<div class="nds-avatar-group nds-stacked nds-md">
    <div class="nds-avatar">
        <img src="path/to/avatar1.jpg" alt="User 1">
    </div>
    <div class="nds-avatar">
        <img src="path/to/avatar2.jpg" alt="User 2">
    </div>
    <div class="nds-avatar">
        <img src="path/to/avatar3.jpg" alt="User 3">
    </div>
    <div class="nds-avatar">
        <img src="path/to/avatar4.jpg" alt="User 4">
    </div>
    <div class="nds-avatar">
        <img src="path/to/avatar5.jpg" alt="User 5">
    </div>
    <div class="nds-avatar">
        <span class="nds-label">+99</span>
    </div>
</div>

Built-in Features

Pure CSS

No JavaScript required. Renders immediately from HTML markup.

Seven Sizes

From 24px (XS) to 120px (3XL). Font and icon scale proportionally.

Element Agnostic

Works on div, a, or button elements for display, navigation, or actions.

Group Layout

Stack avatars with overlapping or spaced arrangement and overflow count.

Usage Guidelines

Best Practices

Use initials when no profile image is available. Two letters from the user's name
Use icon avatars for anonymous or system-level users where no identity is needed
Use image avatars when a real photo is available. Always include alt text describing the person
Use groups to show participants, collaborators, or team members in a compact space
Choose the size based on context: XS/SM for inline mentions, MD/LG for cards, XL+ for profile headers
For icon-only avatars used as buttons or links, add aria-label to describe the action or person (for example, aria-label="Open user menu")
For image avatars, write alt text that names the person or conveys context. Use an empty alt="" only when the avatar is purely decorative and the name appears nearby in text

Modifier Classes

Class	Element	Description
`nds-square`	`.nds-avatar`	Applies a small border-radius for a rounded-square shape instead of a circle
`nds-image-border`	`.nds-avatar`	Adds a subtle inset outline on image avatars to separate the photo from the background
`nds-stacked`	`.nds-avatar-group`	Overlaps avatars so each one shifts behind the previous, creating a compact layered group

CSS Custom Properties

Property	Default	Description
`--avatar-size`	`40px`	Width and height of the avatar. Overridden by each size modifier class
`--avatar-gap`	`6px`	Spacing between avatars inside `.nds-avatar-group`
`--avatar-background`	`--colors-neutral-100`	Fill color of initials and icon avatars
`--avatar-color`	`--icon-default`	Foreground color for initials text and icons
`--avatar-border`	`--colors-base-white`	Border color applied to 3XL avatars and 3XL group members