Avatar

PreviewCode

Copy

YT

Description

Avatar is a compound component that renders a small, fixed-aspect thumbnail representing a person, team, or entity. The root is a <div> that owns size and shape and broadcasts them to nested layers (AvatarImage, AvatarFallback, AvatarIcon, AvatarBackground, AvatarStroke, AvatarRing, and the AvatarBadge family), so you compose the look from those pieces instead of toggling a dozen props on the root.

Reach for it when you need a stable identity cue next to other content: a row leading cell in a table, the author of a comment, a member chip in a settings card, a presence dot on a sidebar item, or a stacked attendee list with an AvatarGroup. The AvatarRing overlay doubles as a progress or loading indicator without breaking the shape, and the AvatarBadge slot keeps status, count, flag, or verification marks anchored to the thumbnail.

Don't reach for Avatar for non-identity tagging; use Badge for status or count labels. If the surface needs to be interactive, wrap the avatar inside a Button rather than reimplementing focus and hover on the root. For a brand mark or product icon, prefer Logo; for a standalone presence dot with no portrait to anchor it to, use Status Badge.

Installation

pnpm dlx @create-ui/cli add avatar

Anatomy

<Avatar>
  <AvatarImage />
  <AvatarFallback />
  <AvatarIcon />
  <AvatarBackground />
  <AvatarStroke />
  <AvatarRing />
  <AvatarBadge>
    <AvatarBadgeStatus />
  </AvatarBadge>
</Avatar>
 
<AvatarGroup>
  <Avatar />
  <Avatar />
  <AvatarGroupAction />
</AvatarGroup>

Usage

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

<Avatar>
  <AvatarImage src="/avatars/ayla.png" alt="Ayla Karagöz" />
  <AvatarFallback>AK</AvatarFallback>
</Avatar>

Examples

Sizes

size accepts seven values from 2xs to 2xl. The fallback text scale and inner ring/stroke weights adjust automatically with the size, so you don't need to retune typography per breakpoint.

PreviewCode

Copy

Shape

shape="circle" (default) renders a perfect circle; shape="rounded" follows a per-size radius scale (rounded-sm at 2xs through rounded-2xl at xl/2xl) so the corners stay proportional as the avatar grows.

PreviewCode

Copy

Fallback

AvatarFallback renders when no image is provided or when the image fails to load. Pair it with an AvatarBackground tint to inject color without adding a portrait, which is useful for placeholder rows or teams that don't have a photo yet.

Icon

AvatarIcon draws a stylized person glyph for empty profiles. Set color to match the surrounding AvatarBackground, and use variant (base, weak, strong) to dial contrast against the background tone.

Background

AvatarBackground adds a tinted surface behind the fallback or icon. Pick from eleven color options and five variant treatments: gradient, strong, base, weak, and alpha (translucent for layering over photos).

Stroke

AvatarStroke paints a hairline border around the avatar that scales with size: 0.5px at 2xs/xs, 0.75px at sm, and 1px from md and up. Reach for it when the avatar sits on a busy surface and needs separation from the background.

PreviewCode

Copy

Ring

AvatarRing orbits the avatar with a stroke that supports three variants: full (static), progress (driven by value 0–100), and loading (animated). Set color to a semantic token or one of the linear-* gradient presets.

PreviewCode

Copy

Badge Status

AvatarBadgeStatus inside AvatarBadge shows presence. Eight variants cover online, busy, away, offline, do-not-disturb, recording, typing, and invisible, each with its own shape, color, and inner glyph.

PreviewCode

Copy

Badge Content

The badge slot also accepts AvatarBadgeText for counts, AvatarBadgeIcon for round marks, AvatarBadgeFlag for country flags, AvatarBadgeLogo for brand thumbs, and AvatarBadgePolygon for verified-style scalloped marks. They share a common size/shape API so they line up consistently inside the badge wrapper.

PreviewCode

Copy

3

Group

AvatarGroup stacks avatars with a negative horizontal margin and applies a white ring around each child for separation. Pass size once on the group and every nested Avatar inherits it via context, so no per-child prop wiring is required.

PreviewCode

Copy

Group with Action

AvatarGroupAction is the trailing affordance for "+N" overflow or an inline action. It inherits the group's size and shape, renders with the strongest neutral fill, and accepts text or an icon as children.

PreviewCode

Copy

+7

Accessibility

Avatar is a passive display component. It renders as a <div> and is not focusable by default; if you make the surrounding row or card interactive, focus and keyboard behavior come from that outer element.

ARIA notes:

• The root sets no implicit role. When the avatar is the sole identifier of an interactive control, give the control an aria-label with the person's name instead of relying on the image alone.
• AvatarImage requires a meaningful alt. Set alt="" only when an adjacent visible text label already names the person, to avoid duplicate announcements.
• AvatarFallback is announced as text; prefer initials or a short label that pairs with the entity it represents.
• AvatarIcon, AvatarBackground, AvatarStroke, and AvatarRing are purely decorative; their inner ornamental marks are flagged aria-hidden.
• AvatarBadgeStatus is visual only. Convey presence textually elsewhere (e.g. "Ayla, online") for screen readers; the dot itself isn't announced.

Styling

Tailwind override: pass className to merge Tailwind classes with the component's CVA classes (via cn()):

<Avatar className="outline-primary-base outline outline-2">…</Avatar>

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="avatar" on the root element, with data-size="<size>" and data-shape="<shape>".
• data-slot="avatar-image" on the <img> element.
• data-slot="avatar-fallback" on the fallback text wrapper.
• data-slot="avatar-icon" on the icon layer, with data-color="<color>" and data-variant="<variant>".
• data-slot="avatar-background" on the background layer.
• data-slot="avatar-stroke" on the hairline border layer.
• data-slot="avatar-ring" on the ring overlay.
• data-slot="avatar-badge" on the badge positioner.
• data-slot="avatar-badge-text" on the numeric badge child.
• data-slot="avatar-badge-icon" on the icon badge child.
• data-slot="avatar-badge-flag" on the flag badge child.
• data-slot="avatar-badge-logo" on the logo badge child.
• data-slot="avatar-badge-polygon" on the polygon badge child.
• data-slot="avatar-badge-status" on the presence badge, with data-variant="<variant>".
• data-slot="avatar-group" on the group wrapper, with data-size and data-shape.
• data-slot="avatar-group-action" on the trailing action chip, with data-size and data-shape.

Target a specific state in CSS:

[data-slot="avatar"][data-size="lg"] {
  /* … */
}

Related Components

• Badge: passive label for status, count, or category; use when the cue is textual instead of identity-based.
• Status Badge: standalone colored dot when there's no avatar to anchor presence to.
• Logo: brand mark or product icon; reach for it instead of an Avatar with an image when representing a product or company.
• Tooltip: pair with an avatar to surface the full name on hover when initials alone aren't enough.

API Reference

Avatar

The root container. Renders a <div> with data-slot="avatar", owns size and shape, and broadcasts them to nested layers and badges via context. Extends React.ComponentProps<"div">, so any standard div attribute (id, role, aria-*, onClick, etc.) is accepted.

Props

Variants

AvatarImage

The portrait layer. Renders a native <img> positioned to fill the avatar with object-cover. Extends React.ComponentProps<"img">.

Props

AvatarFallback

Text fallback shown when no image is provided or the image fails to load. Renders a <span> and pulls its type scale from the active size via the parent context. Extends React.ComponentProps<"span">.

Props

AvatarIcon

Stylized person glyph for empty profiles. Renders a <span> with two decorative shape marks (head + shoulders) under aria-hidden. Extends React.ComponentProps<"span"> minus children.

Props

Variants

AvatarBackground

Tinted background layer behind the fallback or icon. Renders a <div> covering the full avatar surface. Extends React.ComponentProps<"div">.

Props

Variants

AvatarStroke

Hairline border drawn on top of the avatar layers. Renders a <div> with --color-medium border and size-aware widths. Extends React.ComponentProps<"div">.

Props

AvatarRing

Stroke orbiting the avatar. Supports static, progress, and animated loading modes. Renders an inline SVG circle sized relative to the avatar's pixel dimensions; stroke width and gap auto-pick from the active size. Extends React.ComponentProps<"div">.

Props

Variants

AvatarBadge

Positioner for a status, count, icon, flag, logo, or polygon mark anchored to the avatar's corner. Renders a <span> placed absolutely at the chosen corner. Extends React.ComponentProps<"span">.

Props

Variants

AvatarBadgeText

Numeric or short text badge, pill-rounded with a ring against the avatar. Renders a <span>. Extends React.ComponentProps<"span">.

Props

Variants

AvatarBadgeIcon

Round icon badge with a colored fill. Renders a <span> and sizes its child SVG automatically. Extends React.ComponentProps<"span">.

Props

Variants

AvatarBadgeFlag

Flag thumbnail badge, typically wrapping a country flag <img> or SVG. Renders a <span>. Extends React.ComponentProps<"span">.

Props

Variants

AvatarBadgeLogo

Brand logo badge with a white background and object-contain so logos sit cleanly inside. Renders a <span>. Extends React.ComponentProps<"span">.

Props

Variants

AvatarBadgePolygon

Scalloped "verified" badge. Renders a custom SVG polygon with a centered icon child. Extends React.ComponentProps<"span">.

Props

Variants

AvatarBadgeStatus

Presence indicator with eight visual variants covering common availability and activity states. Renders a <span>. Extends React.ComponentProps<"span">.

Props

Variants

AvatarGroup

Stacks multiple Avatars with a negative horizontal margin and a white separator ring. Broadcasts size and shape to every nested Avatar and AvatarGroupAction via context, so child props become optional. Extends React.ComponentProps<"div">.

Props

Variants

AvatarGroupAction

Trailing affordance for "+N" overflow indicators or inline actions, sized to match the group. Renders a <span> with the strongest neutral fill. Extends React.ComponentProps<"span">.

Props

Variants