Avatar

Avatars with fallbacks, status badges, and grouped stacks.

Assigned toSUand reviewed by

A1A3A2

on this release.

Installation

npx shadcn@latest add @iconiq/avatar

Props

Avatar

8 props

Base UI avatar root with shared sizing and an optional tooltip for hover or focus status hints.

childrenReactNode

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

size"default" | "sm" | "lg"

Default"default"

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

tooltipstring

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

tooltipSide"top" | "bottom" | "left" | "right"

Default"right"

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

tooltipDelaynumber

Default0.15

Delay in seconds before the avatar tooltip opens.

tooltipClassNamestring

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

reducedMotionboolean

Forces the avatar tooltip onto its calmer motion path while still respecting system reduced-motion preferences when unset.

classNamestring

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

Notes

The root renders data-slot="avatar" and data-size so grouped stacks and badges can respond to the selected size.

The root keeps a circular border overlay with dark/light blend handling and accepts the full Base UI Root props surface.

AvatarImage

3 props

Image slot for the compound avatar, backed by Base UI's image loading behavior.

srcstring

Required

Image URL passed to the underlying Base UI image primitive.

altstring

Required

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

classNamestring

Merged with the full-size rounded image classes.

AvatarFallback

2 props

Fallback slot shown by Base UI while the image is loading, missing, or failed.

childrenReactNode

Required

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

classNamestring

Merged with the muted circular fallback classes.

AvatarBadge

7 props

Absolute green status badge that scales with the root Avatar size. Add tooltip to Avatar when the whole avatar should expose the status hint.

childrenReactNode

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

tooltipstring

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

tooltipSide"top" | "bottom" | "left" | "right"

Default"right"

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

tooltipDelaynumber

Default0.15

Delay in seconds before the tooltip opens.

tooltipClassNamestring

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

reducedMotionboolean

Forces the badge tooltip onto its calmer motion path while still respecting system reduced-motion preferences when unset.

classNamestring

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

AvatarGroup

2 props

Stack wrapper for overlapping avatars and matching overflow count chips.

childrenReactNode

Required

Avatar and AvatarGroupCount children rendered in an overlapping row.

classNamestring

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

AvatarGroupCount

2 props

Overflow count part that follows the largest avatar size used in the group.

childrenReactNode

Required

Count label or icon shown after the visible avatars.

classNamestring

Merged with the muted circular count chip classes.