Components / Base

Avatar

An identity mark that shows a photo when available and falls back to initials derived from the name. Two brand variants and an overlapping group with an overflow count.

Installation

bash

npx shadcn add https://raw.githubusercontent.com/levi-putna/elements/main/registry/avatar/registry.json

Variants

default uses an off-white background with forest text. primary uses a forest background with white text for higher emphasis.

default · primary

LPdefault

LPprimary

tsx

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

{/* default: off-white background, forest text */}
<Avatar name="Levi Putna" />

{/* primary: forest background, white text */}
<Avatar name="Levi Putna" variant="primary" />

{/* with a photo: falls back to initials if it fails to load */}
<Avatar name="Ada Lovelace" src="/img/person/1.webp" />

Photo & fallback

Pass src for a photo. If it is missing or fails to load, the avatar falls back to the initials in the chosen variant.

photo · broken src falls back to initials

Shape

square (default) is for system users: managers, staff, and assignees in the app shell. round is for strata roll owners via OwnerAvatar, so proprietors are visually distinct from internal team members in mixed lists.

square (system) · round (owner)

JSsquare · manager

JCround · owner

Initials

Initials are derived from name. Joint proprietors use the first initial of each person and the shared surname. Ampersands and "and" are never included in the initials.

Joint and single owner names

JCJC · James &…

DWDW · Daniel &…

MOMO · Margaret O'Brien…

NSNS · North Shore…

Use getAvatarInitials({ name }) when you need the initials string without rendering an avatar. Preview expected: JC for James & Sarah Chen.

Sizes

sm · md · lg · xl

Avatar group & count

AvatarGroup overlaps its children and rings each one in the surface colour. End with an AvatarGroupCount for a +N overflow chip.

group with overflow count

ALGHAT+12

tsx

import { AvatarGroup, Avatar, AvatarGroupCount } from "@/components/ui/avatar"

<AvatarGroup>
  <Avatar name="Ada Lovelace" src="/img/person/1.webp" />
  <Avatar name="Grace Hopper" src="/img/person/2.webp" />
  <Avatar name="Alan Turing" src="/img/person/3.webp" />
  <AvatarGroupCount count={5} />
</AvatarGroup>

Avatar Props

Prop	Type	Default	Description
src	string	-	Image source. Falls back to initials if absent or if it fails to load.
name	string	-	Person/entity name: used to derive initials and as the image alt text.
fallback	ReactNode	-	Explicit fallback content, overriding the derived initials.
variant	"default" \| "primary"	"default"	default = off-white background with forest text. primary = forest background with white text.
size	"sm" \| "md" \| "lg" \| "xl"	"md"	Avatar dimensions: sm 24px, md 32px, lg 40px, xl 48px.
shape	"square" \| "round"	"square"	square = system users (managers, staff). round = strata owners via OwnerAvatar.

AvatarGroup Props

Prop	Type	Default	Description
ring	"background" \| "secondary" \| "forest"	"background"	Colour of the 2px ring drawn between overlapping avatars; set it to match the surface behind the group.
children	ReactNode	-	Avatar elements, optionally ending with an AvatarGroupCount.

AvatarGroupCount Props

Prop	Type	Default	Description
count	number	-	The overflow number, rendered as +N.
variant	"default" \| "primary"	"default"	Same variants as Avatar.
size	"sm" \| "md" \| "lg" \| "xl"	"md"	Match the sibling avatars' size.