---
title: "Avatar"
description: "A picture or initials standing for a person, with the person's name as its accessible label and a neutral fallback when there is no picture."
url: "https://opsinjs.pensievelabs.org/docs/components/avatar"
source: "https://opsinjs.pensievelabs.org/docs/components/avatar.md"
section: "Components"
status: "shipped"
kind: "component"
category: "utility"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["profile picture", "initials", "user image"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="avatar"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured for the initials ink or the person glyph on the muted fill this component draws.&#x22;,
  &#x22;Nobody has listened to it in a screen reader, so whether the name reads cleanly through role=\&#x22;img\&#x22; is unverified.&#x22;,
  &#x22;Initials are taken by code point, not grapheme cluster, so a first character with a combining mark can lose the mark.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="avatar" unbuilt="false" importPath="@/components/ui/avatar" dependencies="[&#x22;lucide-react&#x22;]" />

```tsx
import { Avatar } from "@/components/ui/avatar"
```

```tsx
<Avatar name="Ada Vance" src="/people/ada-vance.jpg" size="md" />
```

## Examples [#examples]

<ComponentPreview name="avatar" />

### A name becomes its initials [#a-name-becomes-its-initials]

`name` drives the initials. A two-part name gives first and last, a single name
gives one, and a non-Latin name keeps its own script rather than a transliterated guess.

<ComponentPreview name="avatar-initials-from-a-name" kind="example" align="start" />

### The fallback chain, one tier at a time [#the-fallback-chain-one-tier-at-a-time]

`src` and `name` decide the tier: a picture that loads, initials when there is no
picture, and a neutral person glyph when there is neither.

<ComponentPreview name="avatar-the-fallback-chain" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Beside a person's name in a message, a comment or a care-team list, to tell one author from another.&#x22;,
  &#x22;As the fallback identity for a person with no photo, where initials or a neutral glyph stand in without pretending a picture exists.&#x22;,
  &#x22;At a small fixed size in a dense list, where a full name would not fit.&#x22;,
]"
  avoid="[
  { case: &#x22;You want the mark to open a menu or a profile when it is pressed.&#x22;, instead: &#x22;icon-button&#x22; },
  { case: &#x22;You are showing a count or a short status word rather than a person.&#x22;, instead: &#x22;badge&#x22; },
  { case: &#x22;You need a round placeholder to hold an avatar's space while its picture is still loading.&#x22;, instead: &#x22;skeleton&#x22; },
  { case: &#x22;You are trying to show who wrote a piece of health guidance and on whose authority.&#x22;, instead: &#x22;source-citation&#x22; },
]"
/>

## Accessibility [#accessibility]

The audit fixed one defect: a picture with a missing or blank name rendered an empty
`alt`, so a screen reader announced nothing while a sighted reader saw a face. The
picture tier now requires a usable name too, so a nameless avatar falls through to the
neutral person glyph. On every commit `pnpm run check:a11y` confirms every colour is a
role token, no type size is in `px` and no banned word appears.

* The avatar takes no focus and is not a tab stop. Inside a button or a link, that
  control owns the focus and the name.
* With a fallback showing, the root is `role="img"` with the name as `aria-label`,
  and the initials or glyph are `aria-hidden`.
* With a picture showing, the image's own `alt` carries the name and the root stays a
  plain container, so the name is announced once.

**Residual items.**

* An empty name warns in development, draws the person glyph and leaves the circle
  unlabelled, because the component cannot invent a label.
* The initials and the glyph take their contrast on the muted fill from shared role
  tokens. The rendered pass found no violation, but no ContrastReport data exists yet
  for this pair.
* Initials are taken by code point rather than grapheme cluster, so a combining mark
  can be lost.

<KeyboardTable
  name="avatar"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the avatar&#x22;,
    notes: &#x22;Not focusable. Inside a button or link, the wrapper is the tab stop.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the avatar in reverse&#x22;,
    notes: &#x22;Absent from the tab sequence in both directions.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Does nothing here&#x22;,
    notes: &#x22;The avatar captures no key. A wrapping link or button owns Enter.&#x22;,
  },
]"
/>

<ContrastReport component="avatar" />

## Props interface [#props-interface]

<PropsTable name="AvatarProps" />

`name` is required, but an empty string still compiles. It warns in development and
falls back to the person glyph. A missing or broken `src` is a fallback, not an error.
`size` defaults to `md`, and an unknown value is repaired to `md` with a warning.
