Avatar

An image element with a fallback for representing the user.

Preview Code
Interactive

Features

  • Automatic and manual control over when the image renders.
  • Fallback part accepts any children.
  • Optionally delay fallback rendering to avoid content flashing.

Installation

Install the component from your command line.

Angular CLInpmpnpmyarnbun
Bash
ng g @ng-cn/core:c avatar

Anatomy

Import all parts and piece them together.

Typescript
import {
  Avatar,
  AvatarImage,
  AvatarFallback
} from '@/ui/avatar';
Html
<Avatar>
  <AvatarImage />
  <AvatarFallback />
</Avatar>

API Reference

Root

Contains all the parts of an avatar.

PropTypeDefault
class string —
Additional CSS classes to apply to the avatar root.

Data Attributes

AttributeValues
[data-slot]"avatar"

Image

The image to render. By default it will only render when it has loaded. You can use the onLoadingStatusChange handler if you need more control.

PropTypeDefault
src *string —
The source URL of the image to display.
alt *string —
The alternate text for the image.
class string —
Additional CSS classes to apply to the image.

Data Attributes

AttributeValues
[data-slot]"avatar-image"

Fallback

An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error. If you notice a flash during loading, you can provide a delayMs prop to delay its rendering so it only renders for those with slower connections.

PropTypeDefault
delayMs number —
Delay in milliseconds before showing the fallback. Useful to avoid flashing during fast loads.
class string —
Additional CSS classes to apply to the fallback.

Data Attributes

AttributeValues
[data-slot]"avatar-fallback"

Examples

Basic

A simple avatar with image and fallback initials.

Html
<Avatar>
  <AvatarImage
    src="https://github.com/shadcn.png"
    alt="@shadcn"
  />
  <AvatarFallback>SC</AvatarFallback>
</Avatar>

With delay on fallback

Use the delayMs prop to delay the fallback rendering and avoid content flashing.

Html
<Avatar>
  <AvatarImage
    src="https://github.com/shadcn.png"
    alt="@shadcn"
  />
  <AvatarFallback [delayMs]="600">SC</AvatarFallback>
</Avatar>

Fallback only

Avatar can be used with only a fallback when no image is provided.

Html
<Avatar>
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Multiple avatars

Display multiple avatars in a group.

Html
<div class="flex gap-2">
  <Avatar>
    <AvatarImage
      src="https://github.com/shadcn.png"
      alt="@shadcn"
    />
    <AvatarFallback>SC</AvatarFallback>
  </Avatar>

  <Avatar>
    <AvatarImage
      src="https://github.com/vercel.png"
      alt="@vercel"
    />
    <AvatarFallback>VL</AvatarFallback>
  </Avatar>

  <Avatar>
    <AvatarFallback>AC</AvatarFallback>
  </Avatar>
</div>

Avatar with tooltip

Compose the Avatar with a Tooltip to display extra information.

Html
<Tooltip>
  <TooltipTrigger>
    <Avatar>
      <AvatarImage
        src="https://github.com/shadcn.png"
        alt="@shadcn"
      />
      <AvatarFallback>SC</AvatarFallback>
    </Avatar>
  </TooltipTrigger>

  <TooltipContent side="top">
    User Profile
    <TooltipArrow />
  </TooltipContent>
</Tooltip>

Avatar sizes

Use the class prop to customize avatar sizes using Tailwind classes.

Html
<div class="flex items-center gap-4">
  <!-- Small -->
  <Avatar class="size-6">
    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
    <AvatarFallback>SC</AvatarFallback>
  </Avatar>

  <!-- Medium (default) -->
  <Avatar>
    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
    <AvatarFallback>SC</AvatarFallback>
  </Avatar>

  <!-- Large -->
  <Avatar class="size-12">
    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
    <AvatarFallback class="text-lg">SC</AvatarFallback>
  </Avatar>
</div>

Accessibility

Adheres to the Avatar .

Keyboard Interactions

KeyDescription
Tab Avatar can receive focus if it's interactive (e.g., wrapped in a button or link).