/// Media
Avatar
Square user image with a mono-initials fallback.
import { Avatar } from "@protocore/pds";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.
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.
Initials fallback
With no src — or when the image fails to load — the fallback renders. Initials derive from name (first + last), a single word takes its first two letters, and initials overrides the derived value.
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.
Usage
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
- 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 `<img>` 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.
Avatar props
| Prop | Type | Default | Description |
|---|---|---|---|
alt | string | — | Alt text / accessible name for the image. Falls back to `name`. |
className | string | — | |
initials | string | — | Explicit fallback text; overrides the derived initials. |
name | string | — | Full name used to derive the initials fallback (e.g. "Ada Lovelace" → "AL"). |
size | enum | md | Box size: sm 24 · md 32 · lg 40. |
src | string | — | Image URL. When missing or it fails to load, the initials render. |
style | CSSProperties | — |