Avatar

Shows a person or record as a picture or initials.

Library

Installation

pnpm dlx shadcn@latest add @wisty/avatar

The CLI installs the Radix or Base UI file to match your project.

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

Create an app with AvatarBuild in Wisty to publish inside Salesforce in minutes. Nothing to deploy.Open in Wisty

When to use

Use it

A list, card or header shows who owns a record or wrote a comment.
A record needs a small picture or initials next to its name, like an account in a related list.
A few people share something, like the members of a team. Overlap their avatars in an AvatarGroup.

Don't use it

The picture is content, like a product photo. Use an img.
The record has an object icon in Salesforce, like Account or Opportunity. Use Icon.
The avatar would be the only way to tell people apart. Show the name next to it.

Usage

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

AvatarGroup (optional, for several people)
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge (optional status dot)
└── AvatarGroupCount (optional, like +2)

The fallback shows until the picture loads, and stays when it fails. Next to a name:

<div className="flex items-center gap-3">
  <Avatar shape="circle">
    <AvatarImage src="/people/david-miller.jpg" alt="" />
    <AvatarFallback>DM</AvatarFallback>
  </Avatar>
  <a href="/users/david-miller">David Miller</a>
</div>

Examples

Sizes

Each `size`, with a record's initials in the default shape and a person's as circles.

ACACAC

SCSCSC

Group and badge

An opportunity team in `AvatarGroup` with an `AvatarGroupCount`, and an avatar with an `AvatarBadge` for status.

SCJRLP

API reference

Part	Built on
`Avatar`	Radix Avatar.Root (opens in a new tab)
`AvatarImage`	Radix Avatar.Image (opens in a new tab)
`AvatarFallback`	Radix Avatar.Fallback (opens in a new tab)
`AvatarBadge`	`<span>` (opens in a new tab)
`AvatarGroup`	`<div>` (opens in a new tab)
`AvatarGroupCount`	`<div>` (opens in a new tab)

`Avatar`

Prop	Type	Default
`size`	`"default" \| "sm" \| "lg"`	`"default"`
`shape`	`"default" \| "circle"`	`"default"`

SLDS mapping

Avatar is slds-avatar, with its corners from SLDS's avatar radius hook; shape="circle" is slds-avatar_circle. AvatarFallback is slds-avatar__initials and AvatarGroupCount is slds-avatar__initials_inverse. AvatarImage fills the avatar and takes its corners.

Known gaps:

AvatarBadge and AvatarGroup have no SLDS counterpart. They keep a dot and an overlapping row, in the theme's colors. SLDS's own avatar group, two avatars stacked diagonally, isn't covered.
SLDS's x-small size has no counterpart.
SLDS colors initials by object (slds-icon-standard-account and others). Pass a background class to AvatarFallback for that.

Prop	Value	SLDS	Notes
`size`	`default`	`slds-avatar_medium`	32px.
`size`	`sm`	`slds-avatar_small`	24px.
`size`	`lg`	`slds-avatar_large`	48px. shadcn's lg is 40px.
`shape`	`default` (added)	`slds-avatar`	Round in Cosmos, a 4px rounded square in Lightning Blue, from SLDS's avatar radius hook.
`shape`	`circle` (added)	`slds-avatar_circle`	Round in every theme. Use it for people.

Accessibility

Give AvatarImage an alt with the person's or record's name, or alt="" when the name is shown beside it.
Initials are read as letters. Put the full name next to the avatar.
A badge that only shows color needs role="img" and an aria-label, like "Online".
Give an AvatarGroup role="group" and an aria-label, like "Opportunity team", so it's read as one set.
In Lightning Blue, AvatarGroupCount's gray text on gray is below 4.5:1, the pair Salesforce's own inverse initials use, kept so the count matches.

Responsive behavior

Avatars keep their size and don't shrink in a flex row. The picture is cropped to fit.
Keep initials to two letters. Longer text overflows the avatar.

Rules

Always add an AvatarFallback with one or two initials.
Use shape="circle" for people and the default shape for records.
Don't add rounded or size classes. Use shape and size.