# SvAvatar
A user or entity avatar: an image with an automatic initials-and-color fallback,
plus an optional presence status dot.
`SvAvatar` never shows a broken image. Give it a `name` and, if you have one, a
`src`; when the image is missing or fails to load, it falls back to up-to-two
initials on a stable, name-derived color so the same person always gets the same
tint. Presets cover the common sizes, and a `status` dot marks presence.
Related: [SvAvatarGroup](https://svgrid.com/docs/help/ui-components/sv-avatar-group/) · [SvChip](https://svgrid.com/docs/help/ui-components/sv-chip/) · [Feedback & display overview](https://svgrid.com/docs/help/ui-components/feedback/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvAvatar` starter into your app:
Prefer to see it first? `npx @svgrid/ui try avatar` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvAvatar` ships free in
`@svgrid/grid` (dependency-free):
```ts
import { SvAvatar } from '@svgrid/grid'
```
## Example
> Live demo: Feedback & display: badge, avatar, skeleton, card - https://svgrid.com/demos/333-app-feedback/
```svelte
```
## Props
| Prop | Type | Default | Description |
| -------- | ---------------------------------------------- | -------- | ----------------------------------------------------------------- |
| `name` | `string` | `''` | Drives the initials fallback and the deterministic color. |
| `src` | `string` | - | Image URL. On load error, falls back to initials automatically. |
| `alt` | `string` | - | Accessible name; defaults to `name`. |
| `size` | `sm` \| `md` \| `lg` \| `number` | `md` | Preset (28 / 36 / 48 px) or an explicit pixel size. |
| `shape` | `circle` \| `square` | `circle` | Circle or rounded square. |
| `status` | `online` \| `offline` \| `busy` \| `away` | - | Presence dot in the corner, colored per state. |
| `color` | `string` | - | Overrides the hash-derived fallback color (any CSS color). |
The initials and fallback color come from two pure helpers exported alongside
the component, so you can reuse the same logic outside an avatar:
```ts
import { avatarInitials, avatarColorHue } from '@svgrid/grid'
avatarInitials('Ada Lovelace') // 'AL'
avatarColorHue('Ada Lovelace') // stable hue 0-359 for a matching tint
```
## Examples
### Image with graceful fallback
Always pass `name` even when you have a `src` - it becomes the fallback if the
image fails:
```svelte
```
### Presence
The `status` dot marks online / away / busy / offline state for people rows:
```svelte
```
### Custom sizing and color
Pass a number for an exact size and `color` to pin a brand tint:
```svelte
```
### Reusing the initials and color helpers
The same helpers that drive the fallback are exported, so you can render a
matching initials chip anywhere - for example a compact mention token - without
mounting an avatar:
```svelte
{avatarInitials(name)}
```
Because `avatarColorHue` is a pure hash of the name, the same person always
lands on the same tint here as in every `SvAvatar` and `SvAvatarGroup` on the
page.
## Accessibility
- Renders with `role="img"` and an `aria-label` (from `alt`, else `name`), so it
announces even in initials mode.
- The presence dot is decorative (`aria-hidden`); reflect status in text where it
matters.
- The initials and placeholder glyph are hidden from assistive tech since the
label already conveys the identity.
## See also
- [Feedback overview](https://svgrid.com/docs/help/ui-components/feedback/) - the whole status and display layer at a glance.
- [SvAvatarGroup](https://svgrid.com/docs/help/ui-components/sv-avatar-group/) - stacked avatars with a "+N" overflow.
- [SvChip](https://svgrid.com/docs/help/ui-components/sv-chip/) - entity chips that use an avatar as their leading icon.
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/sv-avatar/ . All docs: https://svgrid.com/llms.txt