On this page
@addTagHelper *, Webority.Ui.RazorInitials
Show a person's initials when there is no photo, always passing the name so the face is never blank.
Photo
Add a profile photo when there is one; it loads over the initials, which stay as the fallback.
In context
Place an avatar beside a name in a list or a header, so the person reads at a glance.
Sizes
Use a preset from xs to 2xl for most places, or a pixel size when a layout needs an exact figure.
Colour and shape
Pick a semantic tone, or auto for a stable colour per person, and choose a circle, rounded or square shape.
Presence and badges
Mark availability with a status dot, and count unread items with a corner badge.
Clickable
Make an avatar a link when tapping it should open that person's profile.
Every option
Every value of every prop, one cell each.
name
name="Jane Doe"
no name (bare "?")
src
src="photoUrl"
src="" (empty string, falls back to initials)
src="brokenUrl" (falls back to initials)
size
size="xs"
size="sm"
size="md" (default)
size="lg"
size="xl"
size="2xl"
size="72"
shape
shape="circle" (default)
shape="rounded"
shape="square"
tone
tone="primary" (default)
tone="neutral"
tone="success"
tone="warning"
tone="danger"
tone="info"
tone="auto"
status
status="none" (default)
status="online"
status="offline"
status="away"
status="busy"
ring
ring="false" (default)
ring="true"
label
label="Jane Doe, Reviewer" (tooltip on hover or focus)
icon
icon="user"
icon="user" + src (icon stays behind the photo)
icon={node} (React only, drawn as given)
iconVariant
icon-variant="linear" (default)
icon-variant="outline"
icon-variant="bold"
icon-variant="bulk"
icon-variant="broken"
icon-variant="twotone"
badge
badge="3"
badge="9+"
badge={node} (React only, drawn as given)
href
onClick
onClick={fn}, no href (React only, renders a button)
linkComponent
tooltip
tooltip="Jane Doe, Reviewer" (hover or focus to see it)
tooltipPlacement
tooltip-placement="auto" (default)
tooltip-placement="top"
tooltip-placement="bottom"
tooltip-placement="start"
tooltip-placement="end"
className
class="..." (adds classes to the avatar, no visible change)
photoLabel
photo-label="Photo of Jane Doe" (read by screen readers, no visible change)
Guidance
What to do, and what to avoid.
Use it when
- You are showing who a person is, such as a topbar account, a comment author or 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. → AppImagePicker
Always pass a name
A name is always supplied, so the avatar shows meaningful initials and correct alt text.
With no name and no photo the avatar can only render a bare question mark, which is useless to the eye and to a screen reader.
Beside the name it shows
The avatar sits next to the name it represents, so identity reads as one unit.
On its own the avatar names no one, so the reader cannot tell whose row it is.
Use AppAvatar, not a plain image
AppAvatar keeps the shared shape and falls back to initials when the photo is missing.
A hand-rolled round <img> drifts from the shared avatar shape and skips the initials fallback.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
19 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| namedefault - | string | - | The person's name. Used for the initials fallback and the image alt text. |
| srcdefault - | string | - | The profile photo URL, usually a data or object URL. When set, the photo shows over the initials. |
| sizedefault md | xs | sm | md | lg | xl | 2xl | md | A preset from xs to 2xl. |
| shapedefault circle | Circle | Rounded | Square | circle | The disc shape. |
| tonedefault primary | Primary | Neutral | Success | Warning | Danger | Info | Auto | primary | The colour of the initials face. auto gives each name a stable colour. |
Less common 14 props
| Prop | Type | Default | Description |
|---|---|---|---|
| size-pxdefault - | number | - | The size in pixels, instead of a preset. |
| statusdefault none | None | Online | Offline | Away | Busy | none | A presence dot at the lower right. |
| ringdefault false | bool | false | A ring around the avatar. |
| labeldefault - | string | - | Text shown as a tooltip above the avatar on hover or focus. It is also the accessible name of a link or button avatar. |
| icondefault - | string | - | The face shown instead of initials when there is no photo: a library icon name or any node. |
| icon-variantdefault linear | Linear | Outline | Bold | Bulk | Broken | Twotone | linear | The icon style of a named icon. A node icon is drawn as given. |
| badgedefault - | string | - | A small count or marker in the top-right corner. |
| hrefdefault - | string | - | Makes the avatar a link. |
| onClickdefault - | - | - | Razor has no server-side click handler; use href to make the avatar a link instead. |
| linkComponentdefault - | - | - | Not a tag-helper attribute. Razor's href always renders a plain anchor. |
| tooltipdefault - | string | - | A tooltip on hover or focus that flips to stay on screen. Distinct from label, which is a fixed bubble. |
| tooltip-placementdefault auto | Auto | Top | Bottom | Start | End | auto | The preferred tooltip side. auto picks the side with the most room. |
| photo-labeldefault Profile photo | string | Profile photo | Replaces the built-in English text, for other languages. |
| classdefault - | string | - | Extra classes on the avatar, merged with the component classes. |
Screen reader
3 notes- A plain initials avatar is announced as an image named by label, else name; with a photo, the photo's alt text is the name, or 'Profile photo' when there is no name.
- With href or onClick the whole avatar is one link or button named by label, else name, and the photo's alt text is empty.
- With no name or label the avatar is hidden from assistive technology; the initials face, presence dot, badge and label bubble are always hidden from it.
Do and avoid
3 pairsAlways pass a name
A name is always supplied, so the avatar shows meaningful initials and correct alt text.
With no name and no photo the avatar can only render a bare question mark, which is useless to the eye and to a screen reader.
Beside the name it shows
The avatar sits next to the name it represents, so identity reads as one unit.
On its own the avatar names no one, so the reader cannot tell whose row it is.
Use AppAvatar, not a plain image
AppAvatar keeps the shared shape and falls back to initials when the photo is missing.
A hand-rolled round <img> drifts from the shared avatar shape and skips the initials fallback.