Avatar

Avatars with fallbacks, status badges, grouped stacks, and optional tooltips.

Installation

npx shadcn@latest add @iconiq/avatar

File Structure

Usage

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

export function AvatarDemo() {
  return (
    <div className="flex flex-wrap items-center gap-8">
      <Avatar aria-label="shadcn/ui, online" tooltip="Online now">
        <AvatarImage src="/assets/shadcn.jpg" alt="shadcn/ui" />
        <AvatarFallback>SU</AvatarFallback>
        <AvatarBadge variant="online" />
      </Avatar>

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

Props

Props
Description

Avatar

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

name

Optional display name used by AvatarFallback to auto-generate initials when children are omitted.

Type string

asChild

Merge avatar props onto the child element via Radix Slot, useful for link or button triggers.

Type boolean·Default false

aria-label

Accessible name for the avatar. Defaults to the tooltip string when tooltip is set.

Type string

className

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

Type string

AvatarImage

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

AvatarFallback

children

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

Type ReactNode

className

Merged with the muted circular fallback classes.

Type string

AvatarBadge

variant

Preset status color mapped to theme-friendly green, muted, destructive, and amber tokens.

Type "online" | "offline" | "busy" | "away"·Default "online"

aria-label

Accessible status label. Defaults to the tooltip string or the variant label such as Online or Busy.

Type string

children

Optional icon or status mark. Icons scale down on small avatars instead of disappearing.

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

AvatarGroup

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

AvatarGroupCount

children

Count label or icon shown after the visible avatars.

Type ReactNode

className

Merged with the muted circular count chip classes.

Type string

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react, @radix-ui/react-slot, motion.

Contact

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

Assigned toSUon this release.