Basel Standard / Docs

Avatar

Identity primitive for people, initials, and compact profile markers.

BWALMK

Avatars give a compact visual anchor to people-centered surfaces such as author rows, reviewer lists, participant stacks, and account menus. In this system they stay restrained so nearby text can carry the actual identity and role.

Installation

Install

Purchase access, then open /account/install to issue a registry token.

Usage

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"

<Avatar>
  <AvatarImage src="/team/byron.jpg" alt="Byron Wall" />
  <AvatarFallback>BW</AvatarFallback>
</Avatar>

Why This Primitive Exists

Identity markers appear in many layouts, but they should still follow one consistent frame and fallback treatment. The avatar primitive gives you that shared baseline without dictating the surrounding text or metadata pattern.

Use it for authors, operators, collaborators, and lightweight ownership cues.
Pair it with text labels so initials are not the only identifier.
Avoid using an avatar where a product image, icon, or badge would communicate the subject more accurately.

Examples

Basic Avatar Sizes

The root accepts custom sizing through className, while the default shape and fallback styling stay consistent.

BWALMK

<Avatar className="size-14">
  <AvatarFallback>AL</AvatarFallback>
</Avatar>

Fallback States

Fallback content matters because remote images fail, delay, or do not exist.

JD?OP

<Avatar>
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

In Context

An avatar is usually only one part of an identity row.

Author row

Avatars work best when identity and nearby text do the heavy lifting together.

Byron Wall

Studio notes, launch systems, and editorial mechanics.

Guidance

Let Nearby Text Carry Meaning

Show the person's name or role next to the avatar whenever possible.
Treat initials as a fallback, not a complete identity model.
Keep the avatar quiet enough that job titles and metadata stay readable.

Size By Surface Density

Use the default size for toolbars, comments, and compact metadata rows.
Increase size on author cards or profile headers where identity needs more weight.
Keep repeated avatar lists uniform unless one participant truly needs emphasis.

Plan For Missing Images

Always provide AvatarFallback.
Use short initials or a clear placeholder glyph.
Do not assume image availability in editorial or imported data flows.

API Reference

Exported Parts

Export	Renders	Notes
`Avatar`	`AvatarPrimitive.Root`	Framed identity container.
`AvatarImage`	`AvatarPrimitive.Image`	Full-size image layer with object-cover styling.
`AvatarFallback`	`AvatarPrimitive.Fallback`	Centered uppercase fallback content.

Common Props

Prop	Applies To	Notes
`className`	all exports	Adjust sizing or local presentation.
`src`, `alt`	`AvatarImage`	Standard image props.
`delayMs`	`AvatarFallback`	Available through the underlying Radix fallback props.

All exports keep the underlying Radix Avatar props, so image loading and fallback timing can still be controlled when needed.

Previous: Aspect Ratio Next: Badge