Avatar
FreeUser avatar with initials fallback, status indicator, size and shape variants.
Complexity tier: Primitive Presents a value: held to semantic markup and contrast, with its right-to-left and print gaps recorded and the right-to-left debt allowed only to shrink.
import { SvAvatarComponent } from '@styloviz/avatar';Demo & usage
Basic usage
Usage example — open the gallery for the full interactive demo.
An interactive demo for this component lives in the gallery.
Open live demoMore examples
Image with badge count
<sv-avatar src="/u/ada.jpg" name="Ada Lovelace" [badgeCount]="3" shape="rounded" />
Verified, clickable
<sv-avatar name="Grace H." [verified]="true" [clickable]="true" (avatarClick)="openProfile()" />
Presence, said in more than one way
Green, grey, amber and red at ten pixels across is a colour code with no second channel — deuteranopia alone makes the green and the amber the same mark, and online/away is exactly the pair a reader has to tell apart before sending a message. Each state now has a form as well: online is solid, busy carries the do-not-disturb bar, away is a crescent, offline is a hollow ring (a grey fill on a white card is nearly the card, so "offline" and "no dot" looked the same). statusLabel replaces the wording, and showStatusText puts it beside the avatar wherever there is room for three words.
<sv-avatar name="Ada Lovelace" status="busy" statusLabel="In a meeting until 3" [showStatusText]="true" />
The fallback is a layer, not a replacement
The shell used to drop its colour the moment src was set, so a slow image left an empty hole and a broken one snapped from that hole to initials — a flash on every failure and a blank square on every slow connection. The initials are what the image sits on top of, and it fades in once it has decoded. While both layers are present the img alt carries the name and the initials underneath are hidden from assistive tech, so nothing is announced twice.
<sv-avatar src="/u/ada.jpg" name="Ada Lovelace" />
When to use
- Representing a user or entity by image, with a reliable initials fallback.
- You want a status dot, verified mark or notification badge on the avatar.
- For multiple users, stack avatars to show a group.
Async states
None — this component has nothing to load, so it has no loading, empty or error state to drive.
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
| src | string | '' | URL of the avatar image. When blank or broken, falls back to initials/icon. |
| name | string | '' | Full name — used to generate initials and auto-assign a palette color. |
| alt | string | '' | Alt text for the image; falls back to `name`. |
| size | AvatarSize | 'md' | Avatar size. |
| shape | AvatarShape | 'circle' | Border-radius style. |
| status | AvatarStatus | 'none' | Presence status indicator rendered as a small dot. Set to `'none'` to hide it entirely. |
| statusLabel | string | '' | Wording for the presence state — "In a meeting", "Back at 3pm", "Do not disturb". Falls back to the capitalised `status`. |
| showStatusText | boolean | false | Render the presence state in words beside the avatar. |
| color | AvatarColor | 'auto' | Color palette for the initials background. `'auto'` derives a consistent hue from the name string. |
| verified | boolean | false | Show a verified checkmark badge in the bottom-right corner. Overridden by `badgeCount` when that is > 0. |
| badgeCount | number | 0 | Notification count shown in the top-right corner. Set to 0 to hide. |
| badgeMax | number | 9 | Cap for the badge count display (e.g. 9 → shows "9+"). |
| customClass | string | '' | Additional CSS classes merged onto the root wrapper. |
| clickable | boolean | false | Makes the avatar interactive (adds cursor-pointer, hover/focus styles, and emits `avatarClick`). |
Outputs
| Event | Payload type | Description |
|---|---|---|
| avatarClick | Event | Emitted when the avatar is activated (click or keyboard) and `clickable` is true. |
<sv-avatar-pro>
Also in this family — SvAvatarProComponent from @styloviz-pro/avatar.
Async states
None — this component has nothing to load, so it has no loading, empty or error state to drive.
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
| src | string | '' | URL of the avatar image. When blank or broken, falls back to initials/icon. |
| name | string | '' | Full name — used to generate initials and auto-assign a palette color. |
| alt | string | '' | Alt text for the image; falls back to `name`. |
| size | AvatarSize | 'md' | Avatar size. |
| shape | AvatarShape | 'circle' | Border-radius style. |
| status | AvatarStatus | 'none' | Presence status indicator rendered as a small dot. Set to `'none'` to hide it entirely. |
| statusLabel | string | '' | Wording for the presence state — "In a meeting", "Back at 3pm", "Do not disturb". Falls back to the capitalised `status`. |
| showStatusText | boolean | false | Render the presence state in words beside the avatar. |
| color | AvatarColor | 'auto' | Color palette for the initials background. `'auto'` derives a consistent hue from the name string. |
| ring | boolean | false | Show a ring (border) around the avatar — useful in avatar stacks or to highlight the current user. |
| ringColor | string | '' | Ring color class override (any Tailwind ring-color utility). |
| verified | boolean | false | Show a verified checkmark badge in the bottom-right corner. Overridden by `badgeCount` when that is > 0. |
| badgeCount | number | 0 | Notification count shown in the top-right corner. Set to 0 to hide. |
| badgeMax | number | 9 | Cap for the badge count display (e.g. 9 → shows "9+"). |
| customClass | string | '' | Additional CSS classes merged onto the root wrapper. |
| clickable | boolean | false | Makes the avatar interactive (adds cursor-pointer, hover/focus styles, and emits `avatarClick`). |
Outputs
| Event | Payload type | Description |
|---|---|---|
| avatarClick | Event | Emitted when the avatar is activated (click or keyboard) and `clickable` is true. |
Customization & theming
- Image with graceful initials fallback — the initials are the layer underneath, so a slow image never leaves a blank square and a broken one never flashes.
- Online/away/busy/offline status dot with a distinct shape per state, plus size and shape options; `statusLabel` and `showStatusText` add words.
- Group avatars into stacks.
Best practices
- Do: Always pass `name` so initials and alt text work when the image fails.
- Do: Convey status with the dot plus text, not colour alone — the dot already carries a distinct shape per state, and `showStatusText` adds the words wherever there is room.
- Tip: Cap `badgeCount` with `badgeMax` (e.g. 9+) to keep the badge compact.
- Do: Use `statusLabel` for wording your users recognise — "In a meeting until 3" is worth more than "Busy", and it is what gets announced.
Accessibility
- Alt text derived from the name; broken images fall back to initials/icon.
- A `clickable` avatar exposes `role="button"`, is focusable, and activates on Enter/Space (Space is prevented from scrolling).
- Status dot and notification badge are individually labelled; decorative initials/icon are hidden from assistive tech.
- Presence is never colour alone: online is solid, busy carries a bar, away is a crescent and offline is a hollow ring — all four readable in greyscale. The dot is announced in words ("Status: In a meeting until 3"), not the raw enum value.
- While an image is still loading, the `alt` carries the name and the initials underneath are `aria-hidden`, so the same person is not announced twice.
Feedback on Avatar
Spotted a gap in this page, or something that didn't work as described? Comments are GitHub Discussions in the public styloviz/community repo, so posting needs a GitHub account.