# Avatar
- **Category:** Media (`media`)
- **Slug:** `media/avatar`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { Avatar } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/media/avatar
> Square user image with a mono-initials fallback.
## When to use it
Reach for **Avatar** to represent a **person or an account** — a commit author, a team member, an API key's owner. It is identity, not status: for a health or state signal use **StatusDot**; for a role or permission label use **RoleChip**; for the product mark use **Logo**. Avatar always resolves to *something* visible (image or initials), so it is safe in dense tables and lists where a missing photo must not leave a gap.
## Props
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `alt` | `string` | no | — | Alt text / accessible name for the image. Falls back to `name`. |
| `className` | `string` | no | — | — |
| `initials` | `string` | no | — | Explicit fallback text; overrides the derived initials. |
| `name` | `string` | no | — | Full name used to derive the initials fallback (e.g. "Ada Lovelace" → "AL"). |
| `size` | `enum` | no | `md` | Box size: sm 24 · md 32 · lg 40. |
| `src` | `string` | no | — | Image URL. When missing or it fails to load, the initials render. |
| `style` | `CSSProperties` | no | — | — |
## Examples
### Basics
Pass a `src` and a `name`. The image is square with sharp corners — no circle crop — and `name` supplies the accessible label when `alt` is omitted.
```tsx
import { Avatar, HStack } from "@protocore/pds";
// Inline SVG data-URI portraits — self-contained, so the avatars render with
// no network access (no external image host).
function portrait(bg: string, fg: string, glyph: string): string {
const svg =
``;
return `data:image/svg+xml,${encodeURIComponent(svg)}`;
}
export default function Demo() {
return (
);
}
```
### Sizes
Three fixed boxes: `sm` 24, `md` 32 (default), `lg` 40. Avatars never scale fluidly — pick the size that matches the row height it sits in.
```tsx
import { Avatar, HStack } from "@protocore/pds";
export default function Demo() {
return (
);
}
```
## Do & don't
**Do**
- Always pass `name` (or `alt`) so the fallback has initials and screen readers have a label.
- Use one consistent size within a single list or table column.
- Let the initials fallback stand in when you have no image — it is the designed default, not a failure state.
- Keep the square shape; it is a deliberate house signature.
**Don't**
- Don't round Avatar into a circle with `className` overrides — corners stay sharp.
- Don't use Avatar for non-human entities like a service or a chain; use Logo or an Icon.
- Don't stuff more than two initial characters — the fallback caps at two.
- Don't rely on color alone inside the avatar to convey status; that belongs on a StatusDot beside it.
## Accessibility
**Notes**
- Built on Radix Avatar: the image only replaces the fallback once it has actually loaded, so there is no flash of broken image.
- When `src` is present the `![]()
` gets `alt` (falling back to `name`). Decorative avatars with no meaningful name should pass `alt=""`.
- The initials fallback is plain text and is fully readable by assistive tech.
- Avatar is not focusable on its own — when it labels an interactive element (a link to a profile), put the accessible name on that control.
## Related
`icon`, `logo`, `status-dot`, `role-chip`
---
© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/