Skip to content
opsinjs
Edit this page

Components

Avatar

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.

Usage

pnpm dlx shadcn@latest add @opsinjs/avatar

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Avatar } from "@/components/ui/avatar"
<Avatar name="Ada Vance" src="/people/ada-vance.jpg" size="md" />

Examples

Theme
Density
Text
Status
Accent theme
Accent
avatar · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
avatar-initials-from-a-name · base base · style base-lyraOpen under the product theme
avatar-initials-from-a-name.tsx
import { Avatar } from "@/components/ui/avatar"

const NAMES = [
  {
    name: "Ada Vance",
    note: "Two names give two initials, the first and the last.",
  },
  { name: "Sol", note: "A single name gives a single initial." },
  {
    name: "अनीता",
    note: "A non-Latin name keeps its own script; the first character stands in.",
  },
] as const

export default function AvatarInitialsFromAName() {
  return (
    <ul className="m-0 flex list-none flex-col gap-opsin-4 p-0">
      {NAMES.map((person) => (
        <li key={person.name} className="flex items-center gap-opsin-3">
          <Avatar name={person.name} />
          <span className="text-opsin-footnote text-muted-foreground">
            {person.note}
          </span>
        </li>
      ))}
    </ul>
  )
}

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.

Theme
Density
Text
Status
Accent theme
Accent
avatar-the-fallback-chain · base base · style base-lyraOpen under the product theme
avatar-the-fallback-chain.tsx
import { Avatar } from "@/components/ui/avatar"

// A synthetic silhouette, not a photograph of anyone. It exists only to show
// the tier where a picture loads. opsinjs ships no image of a real person.
const SYNTHETIC_IMAGE =
  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='96' height='96'%3E%3Crect width='96' height='96' fill='%23aeb9c2'/%3E%3Ccircle cx='48' cy='38' r='16' fill='%23f4f6f8'/%3E%3Crect x='20' y='58' width='56' height='38' rx='19' fill='%23f4f6f8'/%3E%3C/svg%3E"

// The last row passes an empty name on purpose, to reach the neutral person
// glyph. That warns in development, which is the honest signal for a person
// with no name, so the warning is expected here rather than a defect to
// silence.
const TIERS = [
  {
    name: "Ada Vance",
    src: SYNTHETIC_IMAGE,
    note: "A picture, when the product supplies one.",
  },
  { name: "Bruno Sol", src: undefined, note: "Initials, when there is no picture." },
  {
    name: "",
    src: undefined,
    note: "A neutral person, when there is neither a picture nor a name.",
  },
] as const

export default function AvatarTheFallbackChain() {
  return (
    <ul className="m-0 flex list-none flex-col gap-opsin-4 p-0">
      {TIERS.map((tier) => (
        <li key={tier.note} className="flex items-center gap-opsin-3">
          <Avatar name={tier.name} src={tier.src} size="lg" />
          <span className="text-opsin-footnote text-muted-foreground">
            {tier.note}
          </span>
        </li>
      ))}
    </ul>
  )
}

When to use it

Use it when

  • Beside a person's name in a message, a comment or a care-team list, to tell one author from another.
  • As the fallback identity for a person with no photo, where initials or a neutral glyph stand in without pretending a picture exists.
  • At a small fixed size in a dense list, where a full name would not fit.

Do not use it when

  • You want the mark to open a menu or a profile when it is pressed.Use icon-button instead.
  • You are showing a count or a short status word rather than a person.Use badge instead.
  • You need a round placeholder to hold an avatar's space while its picture is still loading.Use skeleton instead.
  • You are trying to show who wrote a piece of health guidance and on whose authority.Use source-citation instead.

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.
KeyActionNotes
TabSkips the avatarNot focusable. Inside a button or link, the wrapper is the tab stop.
Shift+TabSkips the avatar in reverseAbsent from the tab sequence in both directions.
EnterDoes nothing hereThe avatar captures no key. A wrapping link or button owns Enter.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from AvatarProps in registry/bases/base/avatar.tsx.

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.