Skip to content
Ndop UI

Avatar

Displays a user's image, with a fallback while it loads or when it fails.

ALGHKJ
import { Component } from '@angular/core';
import { Avatar, AvatarFallback, AvatarImage } from '@/ui/avatar/avatar';

/**
 * A picture kept with the code, so the example loads nothing from the
 * network. Use your users' image URLs.
 */
const PICTURE =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" fill="#a5b4fc"/><circle cx="16" cy="13" r="6" fill="#4338ca"/><path d="M5 32a11 11 0 0 1 22 0z" fill="#4338ca"/></svg>',
  );

/** An avatar with an image, and one that falls back to initials. */
@Component({
  selector: 'example-avatar-demo',
  imports: [Avatar, AvatarFallback, AvatarImage],
  template: `
    <div class="flex items-center gap-4">
      <span ndAvatar>
        <img ndAvatarImage [src]="picture" alt="Ada Lovelace" />
        <span ndAvatarFallback>AL</span>
      </span>
      <span ndAvatar size="lg">
        <img ndAvatarImage alt="Grace Hopper" />
        <span ndAvatarFallback>GH</span>
      </span>
      <span ndAvatar size="sm">
        <span ndAvatarFallback>KJ</span>
      </span>
    </div>
  `,
})
export class AvatarDemoExample {
  protected readonly picture = PICTURE;
}

An avatar shows a user's picture, with a fallback such as their initials until the image loads, or if it fails, so there's never a broken image. The image's alt names the avatar; once it has loaded, the fallback is hidden from screen readers, so the avatar is announced once. Avatars come in three sizes, and a group overlaps them with a count of the rest.

Installation

npx @ndop/cli add avatar

Usage

import { Avatar, AvatarFallback, AvatarImage } from '@/ui/avatar/avatar';
<div class="flex items-center gap-4">
  <span ndAvatar>
    <img ndAvatarImage [src]="picture" alt="Ada Lovelace" />
    <span ndAvatarFallback>AL</span>
  </span>
  <span ndAvatar size="lg">
    <img ndAvatarImage alt="Grace Hopper" />
    <span ndAvatarFallback>GH</span>
  </span>
  <span ndAvatar size="sm">
    <span ndAvatarFallback>KJ</span>
  </span>
</div>

Examples

Avatar group

A team's avatars, with a count and a status badge.

ALGHKJ+3
VMOnline
import { Component } from '@angular/core';
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
} from '@/ui/avatar/avatar';

/**
 * A team's avatars overlapping, with a count of the others and a status
 * badge that says its meaning in text too.
 */
@Component({
  selector: 'example-avatar-group',
  imports: [Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount],
  template: `
    <div class="flex flex-wrap items-center gap-8">
      <div ndAvatarGroup role="group" aria-label="Design team">
        @for (member of team; track member) {
          <span ndAvatar>
            <span ndAvatarFallback>{{ member }}</span>
          </span>
        }
        <span ndAvatarGroupCount>+3</span>
      </div>
      <span ndAvatar size="lg">
        <span ndAvatarFallback>VM</span>
        <span ndAvatarBadge><span class="sr-only">Online</span></span>
      </span>
    </div>
  `,
})
export class AvatarGroupExample {
  protected readonly team = ['AL', 'GH', 'KJ'];
}

Accessibility

Implements the `img` element's pattern of the WAI-ARIA Authoring Practices.

Focus

  • The avatar never receives focus and never changes focus.

Right-to-left

Nothing mirrors.

API reference

Avatar

[ndAvatar]

A user's picture, with a fallback, such as initials, shown until the image loads or when it fails (@ndop/primitives/avatar).

Avatar binding Type Default
[size]
Size.
'default' | 'sm' | 'lg''default'
[class]
Extra classes, merged last so they win.
string''
Data attribute Values
data-slotavatar
data-size —
data-status —

AvatarImage

img[ndAvatarImage]

An avatar's image. It covers the fallback once loaded; its alt names the avatar.

Manages aria-hidden.

AvatarImage binding Type Default
[class]
Extra classes, merged last so they win.
string''
[src]
The image's URL; without one, the fallback shows.
string | null | undefined—
Data attribute Values
data-slotavatar-image
data-status —

AvatarFallback

[ndAvatarFallback]

What an avatar shows until its image loads, or when it fails.

Manages aria-hidden.

AvatarFallback binding Type Default
[class]
Extra classes, merged last so they win.
string''
Data attribute Values
data-slotavatar-fallback
data-status —

AvatarBadge

[ndAvatarBadge]

A status dot on an avatar's corner, such as "online". Say the status in text too, for screen readers.

AvatarBadge binding Type Default
[class]
Extra classes, merged last so they win.
string''
Data attribute Values
data-slotavatar-badge

AvatarGroup

[ndAvatarGroup]

Overlapping avatars, such as a team's.

AvatarGroup binding Type Default
[class]
Extra classes, merged last so they win.
string''
Data attribute Values
data-slotavatar-group

AvatarGroupCount

[ndAvatarGroupCount]

The count of avatars left out of a group, such as "+3".

AvatarGroupCount binding Type Default
[class]
Extra classes, merged last so they win.
string''
Data attribute Values
data-slotavatar-group-count

Agent notes

Do

  • Give the image an alt with the person's name, or alt="" when their name is already next to it.
  • Use initials or an icon as the fallback.
  • Say an avatar badge's meaning in text too, such as an sr-only "Online".

Don't

  • Don't use an avatar as the only way to tell people apart.
  • Don't put interactive controls inside it; wrap it in a link or button.