Component

Avatar

A user's picture, with initials as the fallback.

Installation

Import the class, and @use the entry point in your global styles: without it the component renders unstyled.

import { Component } from '@angular/core';
import { WrAvatar } from 'ngwr/avatar';

@Component({ imports: [WrAvatar] })
export class MyComponent {}

Basic usage

Sample
<wr-avatar url="/me.png" alt="Roman" />

Sizes

size takes pixels (48, '48px') or rem, not a percentage.

<wr-avatar url="/me.png" alt="Roman" [size]="32" />
<wr-avatar url="/me.png" alt="Roman" size="4rem" />
<wr-avatar url="/me.png" alt="Roman" size="6rem" />

Shape

shape is rounded (default), square, circle or squircle.

<wr-avatar url="/me.png" alt="Roman" shape="square" />
<wr-avatar url="/me.png" alt="Roman" shape="rounded" />
<wr-avatar url="/me.png" alt="Roman" shape="circle" />
<wr-avatar url="/me.png" alt="Roman" shape="squircle" />

Initials fallback

With no url, the projected content fills the avatar.

RKAB
<wr-avatar [size]="48" shape="circle">RK</wr-avatar>

Initials at every size

Initials shrink to fit the box, up to --wr-avatar-initials-scale of its size (0.375 by default).

ХРХРХРХРХРХРХРХР
ХРХРЖШЖШRKRKWWWW
<wr-avatar shape="circle" [size]="16">ХР</wr-avatar>
<wr-avatar shape="circle" [size]="24">ХР</wr-avatar>
<wr-avatar shape="circle" [size]="40">ХР</wr-avatar>
<wr-avatar shape="circle" size="6rem">ХР</wr-avatar>
.team .wr-avatar {
  --wr-avatar-initials-scale: 0.3;
}

Inside a chip and a tag

In a select, size the avatar by placement: 16px in a chip, 24px in an option row.

Хегай РоманЖуков ШамильWalter White
ХРХегай РоманЖуков ШамильЖуков ШамильWWWalter White
<wr-select
  mode="multi"
  searchable
  virtualScroll
  placeholder="Nobody"
  ariaLabel="Assignees"
  [options]="peopleIds"
  [displayWith]="personName"
  [(value)]="assignees"
>
  <ng-template wrOptionLeading let-personId let-placement="placement">
    <wr-avatar
      shape="circle"
      [size]="placement === 'chip' ? 16 : 24"
      [url]="personPhoto(personId)"
      [alt]="personName(personId)"
      >{{ personInitials(personId) }}</wr-avatar
    >
  </ng-template>
</wr-select>

@for (id of assignees(); track id) {
  <wr-tag>
    <span class="assignee">
      <wr-avatar shape="circle" [size]="16" [url]="personPhoto(id)" [alt]="personName(id)">{{
        personInitials(id)
      }}</wr-avatar>
      <a routerLink="/people">{{ personName(id) }}</a>
    </span>
  </wr-tag>
}

Initials behind an image

Give both a url and initials: the initials show until the image loads.

Roman Khegay
<wr-avatar
  [url]="user.photo"
  alt="Roman Khegay"
  [size]="64"
  shape="circle"
  style="background: var(--wr-color-primary-soft); color: var(--wr-color-primary-ink); font-weight: 600"
>
  RK
</wr-avatar>

Broken image

If url fails to load the initials stay, and a new url tries again.

Roman Khegay
<!-- The request fails, so the initials stay. -->
<wr-avatar
  url="/missing.png"
  alt="Roman Khegay"
  [size]="64"
  shape="circle"
  style="background: var(--wr-color-primary-soft); color: var(--wr-color-primary-ink); font-weight: 600"
>
  RK
</wr-avatar>

Gotchas

  • Projected content sized in em, a <wr-icon> too, shrinks with the initials. Give it a px or rem size.
  • Without alt, the image is announced as "Avatar". Set alt to the person's name.

API

NameDescriptionTypeDefault
urlImage URL. Projected content (e.g. initials) shows while it is unset, loading or broken, and gives way once the image has loaded.string | nullnull
altAlt text for the image. Falls back to avatar.alt, then 'Avatar' — pass the person's name where you have it, since that is what a reader wants. With an alt, projected initials are hidden from assistive technology while an image is in play, so the name is announced once. Without one, the image carries only the generic name, so the initials stay announced beside it — visually hidden once it has loaded, never dropped. alt="" marks the avatar decorative, as it does on an <img>: the image is silent and so are the initials while an image is in play — for an avatar beside a name that is already printed. After a failed load with nothing projected, the alt is still announced, so a broken image never leaves the avatar nameless.string | nullnull
shapeCorner treatment. rounded (default) is a soft rounded square, circle is the classic profile avatar, squircle is the iOS look.WrAvatarShape'rounded'
sizeBox size. See {@link WrAvatarSize} for accepted values. The resolved value is published on the host as --wr-avatar-size.WrAvatarSize'6rem'

CSS variables

Set these on the component's selector or a wrapper, not on :root: the defaults are declared on ngwr/avatar's own element.

VariableDefaultDeclared on
--wr-avatar-img-opacity0.wr-avatar +1 variant override
--wr-avatar-initials-scale0.375.wr-avatar
--wr-avatar-radius10%.wr-avatar +2 variant overrides
--wr-avatar-ringvar(--wr-border-strong).wr-avatar +1 variant override

Dependencies

Built onSpinner

See also

2022 – 2026 © Roman Khegayv15.1.0