Skip to content
werewolf-ui
Components

Avatar

A circle that stands for a person, team or workspace: their photo, or one or two initials on a hue pair when there is no photo or it fails to load. Soft by default; solid inside a Token or on a photo or gradient.

Preview

AL

Props

  • variant
  • color
  • size
  • photo
  • initials
  • icon
import { Avatar } from "@/components/ui/avatar"

const user = { name: "Ada Lovelace" }

<Avatar alt={user.name}>AL</Avatar>

Usage

When to use

  • Show who a piece of content belongs to: a comment author, an assignee, the members of a team.
  • Stand in for a missing or slow photo with one or two initials on a soft hue.

When not to use

  • A logo, a product image or a picture in content. Use a native img.
  • A person picked as a value, such as a recipient in a field. Use Token with a leading avatar.
  • A status such as online or busy. Use Badge next to the name.
  • The only place a name appears in a list or comment. Write the name next to the avatar.

Variants

variant

soft: background-<hue> with text-<hue>, for lists and comment headers. solid: the <hue> solid with text-on-<hue>, inside a Token or on a photo or gradient where the soft fill would not stand out.

  • AL

    softdefault

  • AL

    solid

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

const user = { name: "Ada Lovelace" }

<Avatar alt={user.name}>AL</Avatar>
<Avatar variant="solid" alt={user.name}>AL</Avatar>

color

The hue pair behind the initials. Never the accent. To keep one person's color across a page, pick the hue from something stable, such as their user id.

  • AL

    graydefault

  • AL

    red

  • AL

    orange

  • AL

    yellow

  • AL

    green

  • AL

    teal

  • AL

    blue

  • AL

    purple

  • AL

    pink

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

const user = { name: "Ada Lovelace" }

<Avatar alt={user.name}>AL</Avatar>
<Avatar color="red" alt={user.name}>AL</Avatar>
<Avatar color="orange" alt={user.name}>AL</Avatar>
<Avatar color="yellow" alt={user.name}>AL</Avatar>
<Avatar color="green" alt={user.name}>AL</Avatar>
<Avatar color="teal" alt={user.name}>AL</Avatar>
<Avatar color="blue" alt={user.name}>AL</Avatar>
<Avatar color="purple" alt={user.name}>AL</Avatar>
<Avatar color="pink" alt={user.name}>AL</Avatar>

size

sm 24px for dense lists and table rows, md 32px for comment headers and member lists, lg 40px for profile headers.

  • AL

    sm

  • AL

    mddefault

  • AL

    lg

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

const user = { name: "Ada Lovelace" }

<Avatar size="sm" alt={user.name}>AL</Avatar>
<Avatar alt={user.name}>AL</Avatar>
<Avatar size="lg" alt={user.name}>AL</Avatar>

Examples

Default

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

<Avatar alt="Ada Lovelace">AL</Avatar>

With photo

The initials show until the photo loads, and stay if it fails.

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

<Avatar src="/avatars/ada.jpg" alt="Ada Lovelace" color="blue">AL</Avatar>

Next to a name

The name is written next to the avatar, so alt is empty and the avatar is hidden from screen readers.

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

<div className="flex items-center gap-sm">
  <Avatar alt="" color="teal" size="sm">GH</Avatar>
  <span className="text-sm text-text-primary">Grace Hopper</span>
</div>

Without a name

An icon on the soft variant, for a guest or a deleted account.

import { IconUser } from "@tabler/icons-react"
import { Avatar } from "@/components/ui/avatar"

<Avatar alt="Guest">
  <IconUser size={16} />
</Avatar>

Do and don't

Do

  • Pass the person's name as alt, or alt="" when the name is written next to the avatar.
  • Always pass initials as children, even with src, so a slow or broken photo still shows something.
  • Use solid inside a Token or on a photo or gradient; use soft everywhere else.
  • Keep one hue per person across the page.

Don't

  • Don't put an icon on a solid avatar; there is no icon token for a hue solid.
  • Don't use the accent or a status color as the fill.
  • Don't let the avatar replace a visible name in lists, comments or assignee fields.
  • Don't use it for logos or product images; use a native img.

Props

NameTypeValuesDefaultDescription
variantenumsoft | solidsoftsoft: background-<hue> with text-<hue>, for lists and comment headers. solid: the <hue> solid with text-on-<hue>, inside a Token or on a photo or gradient where the soft fill would not stand out.
colorenumgray | red | orange | yellow | green | teal | blue | purple | pinkgrayThe hue pair behind the initials. Never the accent. To keep one person's color across a page, pick the hue from something stable, such as their user id.
sizeenumsm | md | lgmdsm 24px for dense lists and table rows, md 32px for comment headers and member lists, lg 40px for profile headers.
srcstring--Photo URL. The initials show until it loads, and stay if it fails.
alt requiredstring--Name of the person, team or workspace: Ada Lovelace. Pass an empty string when the name is written next to the avatar.

Slots

NameRequiredDescription
fallbackyesOne or two initials, such as AL. On the soft variant, an icon for someone without a name.

Anatomy

PartDescription
rootThe circle: radius-full, the hue fill, and the name of the avatar. 24, 32 or 40px.
imageThe photo, cropped to fill the circle. Rendered only once it has loaded, then it fades in with duration-medium (no fade under reduced motion).
fallbackThe children: one or two initials in medium weight, shown until the photo loads and when it fails or is missing.
iconOptional Tabler icon as the fallback on the soft variant, 12px in sm, 16px in md, 20px in lg.

Accessibility

Role: img

  • alt names the avatar on the root (role img with aria-label), so the name is the same whether the photo loads or the initials show, and the initials are never read out letter by letter. The type requires alt.
  • When the name is written next to the avatar, as in a comment header or a member list, pass alt="": the avatar is hidden from screen readers, so the name is not read twice.
  • Avatar is not interactive. To open a profile, put the avatar and the name inside one link, and name the link.
  • The hue is decoration. Never let it carry meaning such as a role or a status on its own.
  • Solid initials use text-on-<hue>, which meets 4.5:1 on every hue in both modes. There is no icon token for a hue solid, so an icon fallback is for the soft variant only.

Install

npx shadcn add https://werewolf-ui.vercel.app/r/avatar.json

This also adds styles/werewolf.css, the tokens every component uses, and any other component it needs. Import that file once in your root CSS, after @import "tailwindcss", with a path relative to that CSS file (from app/globals.css it is @import "../styles/werewolf.css").