caliper uidocs
DemoSign inGet Pro

Avatar

Free

A person's photo, falling back to initials when there is no image.

Installs components/ui/avatar.tsxDepends on none beyond ReactMotion none in component source
pnpm dlx shadcn@latest add https://caliperui.site/r/avatar.json
  • Priya RamanAdmin · online
  • Rafael AbreuFinance · away
  • Kiara MurayamaOps · do not disturb
  • Tomás FerreiraEditor · offline

When to use #

Use it for

  • Identifying people in lists, comments and menus.
  • Anywhere a name alone is too plain.

Skip it when

  • Decoration with no person behind it.

Installation #

terminal
pnpm dlx shadcn@latest add https://caliperui.site/r/avatar.json

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above. It is built from Avatar and avatarTone.

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

export function PersonAvatars() {
  const people = [
    { name: "Priya Raman", role: "Admin · online", presence: "online" as const },
    { name: "Rafael Abreu", role: "Finance · away", presence: "away" as const },
    { name: "Kiara Murayama", role: "Ops · do not disturb", presence: "busy" as const },
    { name: "Tomás Ferreira", role: "Editor · offline", presence: "offline" as const },
  ];
  return (
    <ul className="grid w-full max-w-xs gap-1">
      {people.map((person) => (
        <li key={person.name} className="flex items-center gap-3 py-1.5">
          <Avatar name={person.name} presence={person.presence} alt="" />
          <span className="grid">
            <span className="text-sm font-medium">{person.name}</span>
            <span className="text-xs text-muted-foreground">{person.role}</span>
          </span>
        </li>
      ))}
    </ul>
  );
}

API reference #

Avatar

component

Also accepts the native props of its root element and a ref.

PropTypeDefaultDescription
name *string—
srcstring—
altstringname
presence"online" | "away" | "busy" | "offline"—Shown as a shape at the corner: filled, half, dash or ring.

avatarTone

component

No props of its own; it accepts the native props of its root element.

Accessibility #

It is built on native elements and keeps aria-hidden and aria-label in step with state.

No custom key handling; Tab and the native activation keys do the work.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.