Avatar v2

The same avatar with a different fallback: no image renders a circular [blobatar](https://blobatar.dev) hue-locked to the person's brand color, instead of their initials. `version="v2-initials"` keeps that circle but falls back to the initials chip, for dense surfaces where a drawn character is noise.

Installation

$Terminal

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

Usage

Same component and same props as v1 — pass `version="v2"` to swap the initials fallback for a blobatar.

TSImport

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

TSExample

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

// Same props as v1. src still wins; with no src you get a blobatar instead of
// initials, in the same brand color the initials would have used.
export function Example() {
  return (
    <div className="flex items-center gap-4">
      <Avatar version="v2" src="/images/avatar/sarah.jpg" name="Sarah Hill" />
      <Avatar version="v2" name="Jordan Blake" />
      <Avatar version="v2" name="Jordan Blake" color="coral" />
    </div>
  );
}

Composition

One flat component; `version` picks the fallback treatment.

TXTAnatomy

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.

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`.

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).

Avatar group

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

How it works

What v2 changes, and what it deliberately doesn't.

Circular only

The blob is drawn round, so `isSquare` is ignored on v2 — a squircle crops it.

Brand colored

Each name hashes to one of the 12 squad brand colors exactly as it does on v1, and the blob wears that swatch: body and eyes are the same hex pair the v1 chip uses for its background and initials, so a person is the same color in both. Pin one with `color`.

Deterministic

The same `name` always renders the same blobatar, so a person is the same creature everywhere they appear. Nothing is stored and no request is made — the SVG is generated in-process.

Animated by default

v2 blobatars idle — a soft breathe, a bob, a blink and the occasional glance, all timed off the name so a grid reads as a crowd rather than a drill team. Pass `animate="hover"` to animate one at a time, or `animate={false}` for a static one: an animated blobatar is inline SVG where a static one is a single `<img>`, which matters in a list of hundreds. `prefers-reduced-motion` goes static on its own.

Bigger than the frame

A blobatar body only fills about two thirds of its own 100×100 frame, so at the same `size` it would read much smaller than a v1 initials chip. v2 scales it up to fill the circle instead — a round blob inside a round clip, so nothing shows an edge. Override with `[--avatar-blob-scale:1]` in `className`.

Groups

`people` clusters work the same. The `+N` overflow chip stays a text chip on v2 — it is a count, not a person.

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. Ignored on `v2`, which is circular only.
`version`	"v1" \| "v2" \| "v2-initials"	"v1"	Fallback treatment. `v1` renders initials on a squircle-capable solid brand chip; `v2` renders a circular brand-hued blobatar; `v2-initials` keeps v2's circle but falls back to that initials chip — for dense surfaces (grid cells, tables, menus) where a drawn character is noise and a name has to read at 20px. `src` wins on all three.
`animate`	"always" \| "hover" \| false	"always"	`v2` only — the blobatar's idle motion. `"hover"` animates one at a time and `false` goes static; both are worth it for a long list, since an animated blobatar is inline SVG rather than a single `<img>`. Respects `prefers-reduced-motion` either way.
`className`	string	—	Extra classes on the avatar (or the group wrapper in `people` mode).