Layout & navigation

AppAvatar

Represents a person — their photo, or their initials when there is no photo. One shape for a user everywhere.

<app-avatar name="Jane Doe" />

An avatar stands in for a person — their profile photo when there is one, their initials when there isn't. <app-avatar> is the single component for that, so the topbar, the account panel and the Team list can't drift into three different ideas of what a user looks like.

Its look comes entirely from the shared @webority/theme, so the Razor <app-avatar> and the React <AppAvatar> render identically — a person looks the same on every Webority surface.

Playground

Every attribute, live. Each change re-renders the real tag helper on the server, so the markup underneath is the exact call that produced the avatar above it.

name src size custom size (px, overrides size) shape tone status ring icon badge label href tooltip tooltip-placement

<app-avatar name="Jane Doe" />

Razor has no live fallback swapPick src → broken in the playground: the tag helper still emits the <img>, and with no client state to react to the 404, the browser's own broken-image icon sits over the fallback face instead of React's onError swap removing it. See the Every option section below.

Initials

With no photo, the avatar shows initials — a compact stand-in for the person that keeps the round shape intact.

Initials from a name

Pass name and no src; the component derives the initials and the alt text from it.

Show code

<app-avatar name="Jane Doe" />
<app-avatar name="Ravi" />
<app-avatar name="Server Room" />

Always pass the nameEven when you expect a photo, pass name. It becomes the image's alt text, and it's the fallback the avatar shows when there's no photo — without it an avatar can only render a bare “?”.

Photo

Give a src and the avatar renders the profile photo, cropped to the same round shape as the initials.

A profile photo

src is expected to be a data or object URL — photo blobs are private and fetched through the authenticated client.

Show code

<app-avatar src="@photoUrl" name="Jane Doe" />

In context

An avatar rarely stands alone — it pairs with a name and often a role, forming the identity row that recurs across the product.

Avatar beside a name

The avatar anchors the person; the text carries the detail.

Jane Doe

Reviewer

Show code

<div class="d-flex align-items-center gap-2">
    <app-avatar src="@photoUrl" name="Jane Doe" />
    <div>
        <div class="fw-semibold">Jane Doe</div>
        <div class="text-body-secondary wui-text-sm">Reviewer</div>
    </div>
</div>

Sizes

Six presets from xs to 2xl, or a custom pixel size when a preset doesn't fit — the initials scale with the disc.

Preset sizes and a custom one

Pass a preset name, or a number / CSS length for a custom size.

Show code

<app-avatar name="Jane Doe" size="xs" />
<app-avatar name="Jane Doe" size="lg" />
<app-avatar name="Jane Doe" size="2xl" />
<app-avatar name="Jane Doe" size="72" />

Colour tone

Initials avatars take a tone. Use a semantic tone to carry meaning, or auto to give each person a stable, distinct colour derived from their name.

Semantic tones and auto colour

Each name maps to a stable hue under tone="auto".

Show code

<app-avatar name="Jane Doe" tone="success" />
<app-avatar name="Ravi Kumar" tone="auto" />

Shape and ring

Circle is the default; rounded and square suit denser, app-like surfaces. A ring marks an active or selected avatar.

Shapes, and a ring

Show code

<app-avatar src="@photoUrl" name="Jane Doe" shape="rounded" />
<app-avatar src="@photoUrl" name="Jane Doe" ring="true" />

Presence status

A status dot marks whether the person is around — online (which quietly pulses), away, busy, or offline.

Presence dots

Show code

<app-avatar src="@photoUrl" name="Jane Doe" status="online" />

Hover label

Give a label and the avatar reveals a tooltip above it on hover or focus — useful in a compact stack where names would otherwise be hidden.

A labelled avatar (hover it)

Show code

<app-avatar src="@photoUrl" name="Jane Doe" label="Jane Doe · Reviewer" />

AppIcon fallback and a corner badge

Without a name or photo, an icon face reads better than a bare “?”. A corner badge marks a count. The photo (when present) loads over the face, so a slow/broken image never leaves a blank disc.

Icon face and a badge

3 9+

Show code

<app-avatar icon="user" size="lg" />
<app-avatar src="@photoUrl" name="Jane Doe" badge="3" />

Clickable

Give an href and the whole avatar becomes a link — to a profile, say. The accessible name comes from label (or name).

An avatar that links to a profile

Show code

<app-avatar src="@photoUrl" name="Jane Doe" href="/people/jane" label="Jane Doe" />

When to use

Use it when

You are showing who a person is — a topbar account, a comment author, a team-list row.
A list of people needs a compact, recognisable identity marker.
A photo may be missing and you still want a stable, on-brand placeholder.

Reach for something else when

You need a status marker, not a person. → AppStatusBadge
It is a decorative or brand image, not a person. → a plain <img>
You are showing a company logo. → AppLogoPicker / a logo image

Best practices

A name is always supplied, so the avatar shows meaningful initials and correct alt text.

Don't

With no name and no photo the avatar can only render a bare “?” — useless to the eye and to a screen reader.

Ravi Kumar

The avatar sits next to the name it represents — identity read as one unit.

Don't

A hand-rolled round <img> drifts from the shared avatar shape and skips the initials fallback.

Every option

The whole surface of the component, one cell per value — including the states a normal example doesn't show: an empty-string src, a broken image, and no name/photo/icon at all.

size — every preset, plus a custom pixel size

size="xs"

size="sm"

size="md"

size="lg"

size="xl"

size="2xl"

size="72"

shape — every value

shape="circle"

shape="rounded"

shape="square"

tone — every value

tone="primary"

tone="neutral"

tone="success"

tone="warning"

tone="danger"

tone="info"

tone="auto"

status — every presence dot

status="online"

status="offline"

status="away"

status="busy"

state and combinations

ring

icon="user" (no name/photo)

icon + photo (icon stays behind the photo)

badge="3"

badge="9+" (no photo)

label (hover/focus to see the tooltip)

src="" (empty string — falls back to initials)

broken src (Razor has no onError swap — see the playground callout)

no name, no photo, no icon (bare "?")

clickable — link vs button

href — renders <a> (this surface)

onClick — React-only; Razor has no client-side handler, use href for a link-shaped avatar

href + label (label wins as the accessible name)

Attributes

Attribute	Type	Default	Description
name	`string`	—	The person's name. Used for the initials fallback and the image alt text.
src	`string`	—	The profile photo URL (data/object URL). When set, the photo renders instead of initials.
size	`xs \| sm \| md \| lg \| xl \| 2xl \| <px>`	md	A preset, or a custom pixel size (a number, or any CSS length).
shape	`circle \| rounded \| square`	circle	The disc shape.
tone	`primary \| neutral \| success \| warning \| danger \| info \| auto`	primary	The initials fill. `auto` derives a stable colour from the name.
status	`none \| online \| offline \| away \| busy`	none	A presence dot at the lower-right; online quietly pulses.
ring	`bool`	false	A tone-coloured ring with a surface gap around the disc.
label	`string`	—	Text shown as a tooltip above the avatar on hover/focus.
icon	`string`	—	An icon-name fallback face, used instead of initials when there is no photo.
badge	`string`	—	A small count/marker in the top-right corner.
href	`string`	—	Makes the whole avatar a link.
onClick	`—`	—	React-only. Razor has no server-side click handler; use `href` to make the avatar a link instead.
linkComponent	`—`	—	React-only (a router link component). Razor's `href` always renders a plain <a>.
tooltip	`string`	—	A collision-aware hover/focus tooltip (Bootstrap/Popper, same engine as `<app-tooltip>`) that flips to stay on-screen. Distinct from `label`, the fixed CSS bubble.
tooltip-placement	`auto \| top \| bottom \| start \| end`	auto	Preferred tooltip side; `auto` picks the side with the most room.
class	`string`	—	Extra classes on the avatar, merged with the component classes (React `className`).

Playground

Initials

Photo

In context

Sizes

Colour tone

Shape and ring

Presence status

Hover label

AppIcon fallback and a corner badge

Clickable

When to use

Use it when

Reach for something else when

Best practices

Every option

size — every preset, plus a custom pixel size

shape — every value

tone — every value

status — every presence dot

state and combinations

clickable — link vs button

Attributes

Related