Avatar

An image element with a name-based fallback and a size scale from `xs` to `9xl`.

Installation

$Terminal

npx shadcn@latest add https://sdk-components.thesqd.com/r/avatar.json

Usage

Wrap AvatarImage and AvatarFallback inside an Avatar. The fallback shows until the image resolves.

TSImport

import { Avatar } from "@/components/ui/avatar";

TSExample

import { Avatar } from "@/components/ui/avatar";

export function Example() {
  // Either src or name is required; with neither, a UserIcon shows.
  return <Avatar name="Sarah Hill" />;
}

Composition

Six exports — root, image, fallback, badge, group, group count.

Avatar  — single element, prop-driven
├── src         — image URL (rendered when set)
├── name        — generates the initials fallback + a deterministic brand color
├── initials    — explicit initials override (defaults to those from name)
├── color       — explicit brand color override (defaults to one from name)
├── alt         — accessible label
├── size        — xs · sm · md · lg · xl · 2xl … 9xl  (default: md)
├── isSquare    — rounded-square instead of circle (default: false)
├── caption     — renders the avatar beside its name label + this caption
└── people[]    — { name?, src?, initials?, alt? }: one → single avatar,
                  many → overlapping cluster (cap with max → "+N")

With no src and no name, a neutral UserIcon placeholder renders.

Default

Pass `src` for an image; `name` is the fallback if it's missing.

Name → initials

With no `src`, the `name` renders as initials in a brand color picked from the name.

SHJBAK

Fallbacks

`src` wins, then `name` → initials, and with neither a neutral `UserIcon` placeholder shows.

Brand colors

Each name maps deterministically to one of the 12 squad brand colors. Pin one with `color`.

JBAKRSCLDPSRMETQ

With caption

Pass `caption` to render the avatar beside its `name` label and a caption line — for list rows, menus, and headers.

Sarah HillProduct Designer

Shape

By default the avatar is a circle. `isSquare` switches it to a rounded square.

Size

`size` ranges from `xs` (20px) all the way to `9xl` (168px).

KVKVKVKV

Avatar group

Pass `people` an array — one renders a single avatar, many an overlapping cluster with a `+N` chip (cap with `max`).

JDTP+3

API Reference

Props for each export.

Prop	Type	Default	Description
`src`	string \| null	null	Image URL. Takes precedence over the name/initials fallback.
`name`	string	—	Generates the initials fallback and a deterministic brand color.
`initials`	string	—	Explicit initials, overriding those derived from `name`.
`color`	AvatarColor	—	Pin a brand color (brand, indigo, coral, purple, amber, magenta, lavender, lilac, pink, cream, blush, peach) instead of the auto one.
`caption`	ReactNode	—	Render the avatar beside its `name` label and this caption line.
`people`	{ name?, src?, initials?, alt? }[]	—	Group mode — one entry renders a single avatar; multiple render an overlapping cluster.
`max`	number	—	Cap the visible avatars in a `people` group; the rest collapse into a `+N` chip.
`alt`	string	—	Accessible label for the image / fallback.
`size`	"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" … "9xl"	"md"	Diameter via a CSS variable. Range from 20px (xs) to 168px (9xl).
`isSquare`	boolean	false	Rounded square instead of a circle.
`className`	string	—	Extra classes on the avatar (or the group wrapper in `people` mode).