Avatar

Avatars with fallbacks, status badges, and grouped stacks.

Installation

npx shadcn@latest add @iconiq/avatar

File Structure

Usage

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

export function AvatarDemo() {
  return (
    <div className="flex items-center gap-10">
      <Avatar size="lg" tooltip="online">
        <AvatarImage src="/assets/shadcn.jpg" alt="shadcn/ui" />
        <AvatarFallback>SU</AvatarFallback>
        <AvatarBadge />
      </Avatar>

      <AvatarGroup>
        <Avatar size="lg">
          <AvatarImage src="/assets/av1.png" alt="Avatar 1" />
          <AvatarFallback>A1</AvatarFallback>
        </Avatar>
        <Avatar size="lg">
          <AvatarImage src="/assets/av3.png" alt="Avatar 3" />
          <AvatarFallback>A3</AvatarFallback>
        </Avatar>
        <Avatar size="lg">
          <AvatarImage src="/assets/av2.png" alt="Avatar 2" />
          <AvatarFallback>A2</AvatarFallback>
        </Avatar>
      </AvatarGroup>
    </div>
  );
}

Props

Props
Description
children

Compose AvatarImage, AvatarFallback, and an optional AvatarBadge inside the root.

Type ReactNode

size

Controls the root size and drives badge/fallback sizing through data-size selectors.

Type "default" | "sm" | "lg"·Default "default"

tooltip

Optional short label shown in the Iconiq tooltip surface when the entire avatar is hovered or focused.

Type string

tooltipSide

Preferred side for the avatar tooltip bubble. The default collision order is right, left, top, then bottom.

Type "top" | "bottom" | "left" | "right"·Default "right"

tooltipDelay

Delay in seconds before the avatar tooltip opens.

Type number·Default 0.15

tooltipClassName

Merged onto the tooltip bubble when the avatar tooltip is enabled.

Type string

className

Merged onto the Base UI avatar root. Use it for local radius, ring, or size overrides.

Type string

src

Image URL passed to the underlying Base UI image primitive.

Type string

alt

Accessible text for the image. Pass an empty string only when the avatar is decorative.

Type string

className

Merged with the full-size rounded image classes.

Type string

children

Initials, icon, or other compact fallback content centered inside the avatar.

Type ReactNode

className

Merged with the muted circular fallback classes.

Type string

children

Optional icon or status mark. Small avatars hide nested SVGs automatically.

Type ReactNode

tooltip

Optional short label shown in the Iconiq tooltip surface when only the badge should be the trigger.

Type string

tooltipSide

Preferred side for the tooltip bubble. The default collision order is right, left, top, then bottom.

Type "top" | "bottom" | "left" | "right"·Default "right"

tooltipDelay

Delay in seconds before the tooltip opens.

Type number·Default 0.15

tooltipClassName

Merged onto the tooltip bubble when the badge tooltip is enabled.

Type string

className

Merged with the green status badge background, foreground, and ring classes.

Type string

children

Avatar and AvatarGroupCount children rendered in an overlapping row.

Type ReactNode

className

Merged with the negative-space group classes and child avatar rings.

Type string

children

Count label or icon shown after the visible avatars.

Type ReactNode

className

Merged with the muted circular count chip classes.

Type string

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

Assigned toSUand reviewed by

A1A3A2
on this release.