Avatar

An image with a fallback for a person or entity.

Overview

Avatar groups an image and a fallback. AvatarImage is a native img. AvatarFallback is initials or other content.

The fallback is visible until the image loads, and it stays visible if the image fails. A loaded image replaces the fallback, so the two are not both exposed to assistive technology.

Preview

JD

Customize

Status

Installation

Add the component with the CLI. It copies the files in and installs anything they depend on.

npx vinyaas add avatar

Usage

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

export function Profile() {
  return (
    <Avatar>
      <AvatarImage src="/avatars/portrait.svg" alt="Sarang Kumar" />
      <AvatarFallback>SK</AvatarFallback>
    </Avatar>
  );
}

Examples

Image

The image names the person. The fallback stays out of the accessibility tree while the image is available.

Sarang KumarSK

Fallback initials

Initials show when the image is missing. After the error, the image is hidden so the initials are the only name.

Sarang KumarSK

Fallback content

Fallback can be any content. With no image, that content is visible and accessible.

Guest

Status dot

AvatarBadge without children anchors a dot to the bottom-right corner. Use status to show online, offline, away, or busy.

SKALPSGU

Text badge

Pass children to show a short label, such as a tier or role, instead of a dot.

SKProALAdmin

Symbol in the dot

Pass a single icon to AvatarBadge to show a symbol inside the dot, such as a verified check or an owner crown. Name it with aria-label.

SKALPS

Decorative image

An empty alt marks the image as decorative. The fallback text is the name only if the image fails.

SK

In practice

A team header pairs Avatar rows with role badges and an Invite action.

Design system

3 people with access to this project.

  • SK

    Sarang Kumar

    sarang@example.com

    Owner
  • AL

    Ada Lovelace

    ada@example.com

    Editor
  • PS

    Priya Shah

    priya@example.com

    Viewer

API

Other attributes for the underlying element are passed through.

NameTypeDefaultDescription
srcstring—AvatarImage. Native image source.
altstring—AvatarImage. Name the person when the image conveys identity. Use an empty string when the image is decorative.
childrenReactNode—Avatar content. AvatarFallback children are initials or other fallback content, shown until the image loads and after it fails.
status"online" | "offline" | "away" | "busy" | "default""default"AvatarBadge. Picks the badge color. Without children the badge is a status dot named by its status (or aria-label); with children it is a text label such as PRO.
classNamestring—Merged with cn on Avatar, AvatarImage, AvatarFallback, and AvatarBadge.

Accessibility

Give the image a meaningful alt when it identifies a person. Use alt="" when the image is decorative.

  • While the image is loading or has loaded, the fallback is hidden from assistive technology so the name is not repeated.
  • If the image fails, the image is removed from the accessibility tree and the fallback becomes the name.
  • With no image, the fallback content is the accessible content.