iconiq
—Open GitHub

Avatar

Avatars with fallbacks, status badges, and grouped stacks.

Installation

npx shadcn@latest add @iconiq/avatar

Props

Avatar

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

Default 0.15

Delay in seconds before the avatar tooltip opens.
tooltipClassNamestring
Merged onto the tooltip bubble when the avatar tooltip is enabled.
classNamestring
Merged onto the Base UI avatar root. Use it for local radius, ring, or size overrides.

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

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

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

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

Default 0.15

Delay in seconds before the tooltip opens.
tooltipClassNamestring
Merged onto the tooltip bubble when the badge tooltip is enabled.
classNamestring
Merged with the green status badge background, foreground, and ring classes.

AvatarGroup

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

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.

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, motion.