General

Avatar

Copy page

View as Markdown

Open in ChatGPT

Open in Claude

An image element with a fallback for representing the user.

Usage#

app.component.ts

import { WDS_AVATAR } from '@wds/angular/avatar';

Examples#

Default#

src sets the image and alt names the avatar. The content (initials) is the fallback, shown until the image loads.

Show code

avatar-default.ts

import { Component } from '@angular/core';
import { WdsAvatarComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-default-demo',
  imports: [WdsAvatarComponent],
  template: `
    <wds-avatar src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
  `,
})
export class AvatarDefaultDemo {}

Fallback#

Without src, or when the image fails to load, the avatar shows its content: initials or an icon. With alt the avatar is still read by its name, not by the initials.

Show code

avatar-fallback.ts

import { Component } from '@angular/core';
import { WdsAvatarComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-fallback-demo',
  imports: [WdsAvatarComponent],
  template: `
    <div class="flex flex-wrap items-center gap-4">
      <wds-avatar alt="Mira Stone">MS</wds-avatar>
      <wds-avatar alt="Unknown user">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" /><circle cx="12" cy="7" r="4" /></svg>
      </wds-avatar>
    </div>
  `,
})
export class AvatarFallbackDemo {}

Badge#

wds-avatar-badge adds a dot in the bottom corner; change its color with a background class. A badge is decorative, so put the status in alt as well.

Show code

avatar-badge.ts

import { Component } from '@angular/core';
import { WdsAvatarBadgeComponent, WdsAvatarComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-badge-demo',
  imports: [WdsAvatarComponent, WdsAvatarBadgeComponent],
  template: `
    <wds-avatar src="https://github.com/octocat.png" alt="@octocat, online">
      CN
      <wds-avatar-badge class="bg-green-600 dark:bg-green-800"></wds-avatar-badge>
    </wds-avatar>
  `,
})
export class AvatarBadgeDemo {}

Badge with icon#

An icon inside the badge. On the sm avatar the icon is hidden.

Show code

avatar-badge-icon.ts

import { Component } from '@angular/core';
import { WdsAvatarBadgeComponent, WdsAvatarComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-badge-icon-demo',
  imports: [WdsAvatarComponent, WdsAvatarBadgeComponent],
  template: `
    <wds-avatar class="grayscale" src="https://github.com/pranathip.png" alt="@pranathip">
      PP
      <wds-avatar-badge>
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12h14" /><path d="M12 5v14" /></svg>
      </wds-avatar-badge>
    </wds-avatar>
  `,
})
export class AvatarBadgeIconDemo {}

Avatar group#

wds-avatar-group overlaps the avatars and gives each a ring in the page background color.

Show code

avatar-group.ts

import { Component } from '@angular/core';
import { WdsAvatarComponent, WdsAvatarGroupComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-group-demo',
  imports: [WdsAvatarGroupComponent, WdsAvatarComponent],
  template: `
    <wds-avatar-group class="grayscale">
      <wds-avatar src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
      <wds-avatar src="https://github.com/maxleiter.png" alt="@maxleiter">LR</wds-avatar>
      <wds-avatar src="https://github.com/evilrabbit.png" alt="@evilrabbit">ER</wds-avatar>
    </wds-avatar-group>
  `,
})
export class AvatarGroupDemo {}

Avatar group count#

wds-avatar-group-count at the end of the group shows how many people are not shown.

Show code

avatar-group-count.ts

import { Component } from '@angular/core';
import { WdsAvatarComponent, WdsAvatarGroupComponent, WdsAvatarGroupCountComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-group-count-demo',
  imports: [WdsAvatarGroupComponent, WdsAvatarComponent, WdsAvatarGroupCountComponent],
  template: `
    <wds-avatar-group class="grayscale">
      <wds-avatar src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
      <wds-avatar src="https://github.com/maxleiter.png" alt="@maxleiter">LR</wds-avatar>
      <wds-avatar src="https://github.com/evilrabbit.png" alt="@evilrabbit">ER</wds-avatar>
      <wds-avatar-group-count>+3</wds-avatar-group-count>
    </wds-avatar-group>
  `,
})
export class AvatarGroupCountDemo {}

Avatar group with icon#

The count can hold an icon instead of a number; name it with aria-label.

Show code

avatar-group-count-icon.ts

import { Component } from '@angular/core';
import { WdsAvatarComponent, WdsAvatarGroupComponent, WdsAvatarGroupCountComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-group-count-icon-demo',
  imports: [WdsAvatarGroupComponent, WdsAvatarComponent, WdsAvatarGroupCountComponent],
  template: `
    <wds-avatar-group class="grayscale">
      <wds-avatar src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
      <wds-avatar src="https://github.com/maxleiter.png" alt="@maxleiter">LR</wds-avatar>
      <wds-avatar src="https://github.com/evilrabbit.png" alt="@evilrabbit">ER</wds-avatar>
      <wds-avatar-group-count>
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" role="img" aria-label="Add people"><path d="M5 12h14" /><path d="M12 5v14" /></svg>
      </wds-avatar-group-count>
    </wds-avatar-group>
  `,
})
export class AvatarGroupCountIconDemo {}

Size#

size is sm, default or lg. In a group, give wds-avatar-group-count the same size as the avatars. --wds-avatar-size sets any other size.

Show code

avatar-size.ts

import { Component } from '@angular/core';
import { WdsAvatarComponent, WdsAvatarGroupComponent, WdsAvatarGroupCountComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-size-demo',
  imports: [WdsAvatarComponent, WdsAvatarGroupComponent, WdsAvatarGroupCountComponent],
  template: `
    <div class="flex flex-wrap items-center gap-6">
      <div class="flex items-center gap-2">
        <wds-avatar size="sm" src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
        <wds-avatar src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
        <wds-avatar size="lg" src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
      </div>
      <wds-avatar-group class="grayscale">
        <wds-avatar size="lg" src="https://github.com/octocat.png" alt="@octocat">OC</wds-avatar>
        <wds-avatar size="lg" src="https://github.com/maxleiter.png" alt="@maxleiter">LR</wds-avatar>
        <wds-avatar-group-count size="lg">+3</wds-avatar-group-count>
      </wds-avatar-group>
    </div>
  `,
})
export class AvatarSizeDemo {}

An avatar inside a wds-button as a wds-dropdown trigger. The button has the label, so the avatar does not need alt.

My account

Profile

Billing

Settings

Log out

Show code

avatar-dropdown.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownLabelComponent, WdsDropdownSeparatorComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';
import { WdsAvatarComponent } from '@wds/angular/avatar';

@Component({
  selector: 'app-avatar-dropdown-demo',
  imports: [WdsDropdownComponent, WdsDropdownLabelComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent, WdsButtonComponent, WdsAvatarComponent],
  template: `
    <wds-dropdown align="end">
      <wds-button slot="trigger" variant="ghost" size="icon" shape="circle" label="Account">
        <wds-avatar src="https://github.com/octocat.png">OC</wds-avatar>
      </wds-button>
      <wds-dropdown-label>My account</wds-dropdown-label>
      <wds-dropdown-item value="profile">Profile</wds-dropdown-item>
      <wds-dropdown-item value="billing">Billing</wds-dropdown-item>
      <wds-dropdown-item value="settings">Settings</wds-dropdown-item>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-item value="logout" variant="destructive">Log out</wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class AvatarDropdownDemo {}

API References#

wds-avatar#

An image that represents a user, with a fallback (initials or an icon) shown until the image loads or when it fails.

Attributes

Attribute	Type	Default	Description
src	string \| undefined		Image address. Without it (or when it fails) the fallback is shown.
alt	string	''	Alternative text: the name of the avatar for screen readers, also when the fallback is shown.
size	WdsAvatarSize	'default'	Size: `sm` (24px), `default` (32px) or `lg` (40px).

Slots

Slot	Description
(default)	Fallback: initials or an icon, shown without `src`, while the image loads and when it fails.
badge	A `wds-avatar-badge` in the bottom corner.

CSS parts (::part)

Part	Description
root	The circle.
image	The `<img>`.
fallback	The fallback container.

CSS custom properties

Property	Description
--wds-avatar-size	Custom size (instead of `size`).
--wds-avatar-font-size	Size of the fallback text (with a custom `--wds-avatar-size`).
--wds-avatar-radius	Corner radius (default a circle), e.g. `var(--wds-radius-lg)` for a rounded square.

wds-avatar-badge#

A status dot in the bottom corner of wds-avatar (goes to its badge slot by itself). Change the color with a background class, e.g. bg-green-600. An icon inside is hidden on the sm avatar.

Slots

Slot	Description
(default)	Optional icon (`<svg>`).

wds-avatar-group#

Overlapping avatars, each with a ring in the page background color. End it with wds-avatar-group-count.

Slots

Slot	Description
(default)	`wds-avatar` elements and an optional `wds-avatar-group-count`.

CSS parts (::part)

Part	Description
base	The container.

CSS custom properties

Property	Description
--wds-avatar-group-overlap	How much each avatar covers the previous one (default 8px).

wds-avatar-group-count#

The last circle of wds-avatar-group: the number of the remaining people (e.g. +3) or an icon.

Attributes

Attribute	Type	Default	Description
size	WdsAvatarSize	'default'	Size: match the avatars of the group.

Slots

Slot	Description
(default)	Text or an icon (`<svg>`).

CSS parts (::part)

Part	Description
root	The circle.

CSS custom properties

Property	Description
--wds-avatar-size	Custom size (instead of `size`).
--wds-avatar-radius	Corner radius (default a circle).

Accessibility#

With alt the avatar is one image (role="img") named by alt, both with the photo and with the fallback. Without alt screen readers read the fallback text (e.g. the initials).

Inside a named control (a button with label, a link with text) leave alt out, so the name is not read twice.

wds-avatar-badge is decorative: describe the status in alt, e.g. Mira Stone, online.

An icon in wds-avatar-group-count needs role="img" and aria-label; a number such as +3 is read as text.

Keyboard support#

Avatars are not focusable and have no keyboard interaction. Inside a button or a link they follow its keyboard support.

Usage#

Examples#

Default#

Fallback#

Badge#

Badge with icon#

Avatar group#

Avatar group count#

Avatar group with icon#

Size#

Dropdown#

API References#

wds-avatar#

Attributes

Slots

CSS parts (::part)

CSS custom properties

wds-avatar-badge#

Slots

wds-avatar-group#

Slots

CSS parts (::part)

CSS custom properties

wds-avatar-group-count#

Attributes

Slots

CSS parts (::part)

CSS custom properties

Accessibility#

Screen reader#

Keyboard support#