Avatar

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add avatar

Usage#

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

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
      <AvatarFallback>JE</AvatarFallback>
    </Avatar>
  )
}

Anatomy#

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

<Avatar>
  <AvatarImage />
  <AvatarFallback />
  <AvatarStatus />
  <AvatarBadge />
</Avatar>

Sizes#

Five fixed sizes, from xs (24px) to xl (64px). The status dot and fallback text scale with the box.

Shape#

Circular by default; set shape="square" for a rounded-square avatar (e.g. organizations).

Fallback#

When no image is provided or it fails to load, Radix shows the fallback. Use delayMs to avoid a flash while a valid image loads.

The fallback adapts to the box. A small avatar (xs/sm) shows a single initial so the glyph never crowds the silhouette; md and up show two. Pass the same two-letter string everywhere and let the size decide, or override per instance with maxInitials.

Color#

color tints the initials fallback with a soft background and strong text from a single categorical token - the same palette as the Badge hues, so it re-themes across all four themes. Use it to distribute initials across users, teams, or tags. It only paints the fallback; an image, when present, covers it.

Status#

AvatarStatus adds a presence dot that sits outside the silhouette and reuses the status tokens (online/away/busy/offline).

The position prop controls which corner the dot occupies - useful when another element (icon, badge) already occupies the default bottom-right corner.

Logo badge#

AvatarBadge is the same corner overlay as AvatarStatus, but it holds a brand or app mark instead of a presence dot. Drop an <img> or icon inside and it fits the coin, which carries a ring-background gap so it reads off the photo behind it. Use it to tag who someone is on another platform, an org badge, or a verified mark.

PreviewCode

S

F

S

D

The coin's shape is its own, independent of the avatar: keep the round coin or set shape="square" for the classic app-icon look.

PreviewCode

JE

JE

It scales with the avatar and takes the same position prop as the status dot, so you can move it off the default bottom-right corner.

PreviewCode

J

J

JE

JE

JE

Stack#

AvatarGroup stacks collaborators into one cluster. It owns the overlap, the ring-background separation, and the hover lift, so the children stay plain Avatars with no per-instance ring or z-index. Cap the visible count with max and the rest collapse into a +N chip; pass total when the real count exceeds the avatars you render. Match the group's size to its children; the overlap tightens as the box grows.

Reach for renderOverflow to swap the default chip for a richer affordance, like a Tooltip that names the people the stack hides. See the full API on the Avatar Group page.

Examples#

Common patterns where avatars appear in product UI - combined with other components.

API reference#

FAQ#