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
avatar · base base · style base-lyraOpen under the product themeA 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.
avatar-initials-from-a-name · base base · style base-lyraOpen under the product themeimport { 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.
avatar-the-fallback-chain · base base · style base-lyraOpen under the product themeimport { 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-buttoninstead. - You are showing a count or a short status word rather than a person.Use
badgeinstead. - You need a round placeholder to hold an avatar's space while its picture is still loading.Use
skeletoninstead. - You are trying to show who wrote a piece of health guidance and on whose authority.Use
source-citationinstead.
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 asaria-label, and the initials or glyph arearia-hidden. - With a picture showing, the image's own
altcarries 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.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the avatar | Not focusable. Inside a button or link, the wrapper is the tab stop. |
| Shift+Tab | Skips the avatar in reverse | Absent from the tab sequence in both directions. |
| Enter | Does nothing here | The avatar captures no key. A wrapping link or button owns Enter. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below 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.