Avatar

A small image representing a person or an account, with a text or icon fallback for when there is no picture — or before one loads.

The shape carries the meaning. appearance="circle" is a person; appearance="square" (a rounded square) is one of the things people belong to: an account, workspace, team, or organization. A row that shows both, an account switcher with the signed-in user's photo beside it, stays readable without labels because the two never look alike.

ACJD

1import { Avatar } from "@ngrok/mantle/avatar";2import { UserIcon } from "@phosphor-icons/react/User";3 4export function AccountAndUserAvatars() {⋯5	return (6		<div className="flex items-center gap-4">⋯7			{/* an account: rounded square, color derived from its id */}8			<Avatar.Root appearance="square" colorSeed="acc_acme">⋯9				<Avatar.Fallback name="Acme Corp" />10			</Avatar.Root>11 12			{/* a person with a photo: the fallback covers the load and any failure */}13			<Avatar.Root>⋯14				<Avatar.Image alt="Jane Doe" src="/example-avatar.svg" />15				<Avatar.Fallback name="Jane Doe" />16			</Avatar.Root>17 18			{/* a person with no photo and no name to abbreviate: the avatar names itself */}19			<Avatar.Root aria-label="Your account" className="text-muted" role="img">⋯20				<Avatar.Fallback>⋯21					<UserIcon className="size-4" />22				</Avatar.Fallback>23			</Avatar.Root>24		</div>25	);26}

Composition

Avatar.Root├── Avatar.Image└── Avatar.Fallback

Avatar.Image and Avatar.Fallback are siblings, not alternatives you branch on. The fallback renders in flow; the image is positioned over it. A loading image shows initials through it, a loaded one covers them, and a failed one unmounts itself and reveals them again: no loading state for anyone to handle, and nothing waiting on hydration, because the <img> is in the server-rendered markup. (A transparent image is the one case where initials show through a loaded picture; give it its own backdrop if that matters.)

Polymorphism

Avatar.Root, Avatar.Image, and Avatar.Fallback each accept asChild. Reach for it on Image to swap in a framework image component, on Root when the avatar is itself a link or a button, and on Fallback when the initials want a more specific element (an <abbr title="…">, say).

1import { Avatar } from "@ngrok/mantle/avatar";2 3export function LinkedAvatar() {⋯4	return (5		<Avatar.Root asChild appearance="square" colorSeed="acc_acme">⋯6			<a href="/accounts/acme" title="Acme Corp">⋯7				<Avatar.Fallback name="Acme Corp" />8			</a>9		</Avatar.Root>10	);11}

Appearance

Circles are people, rounded squares are accounts. Nothing enforces it, but keeping the two distinct is what lets a dense row of both stay legible, so pick per subject rather than per screen.

1import { Avatar } from "@ngrok/mantle/avatar";2 3export function Appearances() {⋯4	return (5		<div className="flex items-center gap-6">⋯6			<div className="flex items-center gap-2">⋯7				<Avatar.Root appearance="circle" colorSeed="usr_jane">⋯8					<Avatar.Fallback name="Jane Doe" />9				</Avatar.Root>10				<span className="text-sm">Jane Doe</span>11			</div>12			<div className="flex items-center gap-2">⋯13				<Avatar.Root appearance="square" colorSeed="acc_acme">⋯14					<Avatar.Fallback name="Acme Corp" />15				</Avatar.Root>16				<span className="text-sm">Acme Corp</span>17			</div>18		</div>19	);20}

Deterministic color

colorSeed hashes a stable identifier into one of a fixed set of swatches, so an account is the same color on every device and every session with nothing stored and nothing fetched. Seed it with an id, not a display name: names get edited, and a rename would silently recolor the avatar.

Omit colorSeed for a neutral surface, or set your own bg-* through className to opt out entirely.

1import { Avatar } from "@ngrok/mantle/avatar";2 3const accounts = [⋯4	{ id: "acc_acme", name: "Acme Corp" },5	{ id: "acc_atlas", name: "Atlas Industries" },6	{ id: "acc_globex", name: "Globex" },7	{ id: "acc_initech", name: "Initech" },8	{ id: "acc_umbrella", name: "Umbrella Group" },9];10 11export function SeededAvatars() {⋯12	return (13		<div className="flex flex-wrap items-center gap-4">⋯14			{accounts.map((account) => (15				<div key={account.id} className="flex items-center gap-2">⋯16					<Avatar.Root appearance="square" colorSeed={account.id}>⋯17						<Avatar.Fallback name={account.name} />18					</Avatar.Root>19					<span className="text-sm">{account.name}</span>20				</div>21			))}22		</div>23	);24}

Sizing

An avatar is size-7 and shrink-0: a fixed-size visual that the flex rows it usually sits in (a switcher row, a table cell, a comment header) must not be able to squeeze. Override the size with className, which merges last and wins, and scale the text with it so initials stay proportional.

1import { Avatar } from "@ngrok/mantle/avatar";2 3export function Sizes() {⋯4	return (5		<div className="flex items-end gap-4">⋯6			<Avatar.Root className="size-5 text-[0.625rem]" colorSeed="usr_jane">⋯7				<Avatar.Fallback name="Jane Doe" />8			</Avatar.Root>9			<Avatar.Root colorSeed="usr_jane">⋯10				<Avatar.Fallback name="Jane Doe" />11			</Avatar.Root>12			<Avatar.Root className="size-10 text-sm" colorSeed="usr_jane">⋯13				<Avatar.Fallback name="Jane Doe" />14			</Avatar.Root>15			<Avatar.Root className="size-16 text-lg" colorSeed="usr_jane">⋯16				<Avatar.Fallback name="Jane Doe" />17			</Avatar.Root>18		</div>19	);20}

Accessibility

An avatar is almost always redundant with text beside it, and mantle defaults to that reading:

• Initials derived from name are aria-hidden. They abbreviate a name the page already carries, so announcing them would read it twice ("A C Acme Corp"). Children are not hidden; you own their semantics.
• When the avatar is the only thing naming its subject (a collapsed rail, a bare stack of members), name the root: role="img" plus aria-label="Acme Corp". A bare <span> is role="generic", where accessible names are prohibited, so the role is what makes the label count.
• alt on Avatar.Image is required, and mantle makes it required deliberately: an <img> with no alt announces its URL. Pass "" when adjacent text already names the subject. What alt cannot do is name the avatar in every state: that <img> is absent whenever there is no src, the load fails, or the page is server-rendered, so an avatar that must always be named needs the role="img" + aria-label above as well.

Composing with MediaObject

For a name and a secondary line beside the avatar, compose MediaObject rather than hand-rolling the row.

1import { Avatar } from "@ngrok/mantle/avatar";2import { MediaObject } from "@ngrok/mantle/media-object";3 4export function MemberRow() {⋯5	return (6		<MediaObject.Root className="max-w-sm">⋯7			<MediaObject.Media>⋯8				<Avatar.Root className="size-9" colorSeed="usr_jane">⋯9					<Avatar.Fallback name="Jane Doe" />10				</Avatar.Root>11			</MediaObject.Media>12			<MediaObject.Content>⋯13				<p className="text-strong text-sm font-medium">Jane Doe</p>14				<p className="text-muted text-sm">jane@acme.com</p>15			</MediaObject.Content>16		</MediaObject.Root>17	);18}

API Reference

Avatar.Root

The sizing, shape, and surface. Renders a <span>, so it stays valid inside a switcher row's <button>. Accepts all <span> props (asChild, className, style, ref, data-*, aria-*, role), plus:

Data attributes

Avatar.Image

The picture, layered over the fallback. A plain <img>, so the server renders it and a cached image needs no hydration to appear. A failed load unmounts it, revealing the fallback. Accepts all <img> props (srcSet, sizes, loading, referrerPolicy, crossOrigin, asChild, …), plus:

Data attributes

Avatar.Fallback

What shows when there is no image — while one loads, when it fails, or when there was never one. Renders a <span> that is always present, behind Avatar.Image. Accepts all <span> props (asChild, className, ref, aria-*), plus exactly one source of content:

Data attributes