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, shape, and a single combined variant ({fill}-{color}, e.g. weak-blue) and broadcasts them to nested layers (AvatarImage, AvatarText, AvatarIcon, AvatarRing, and the AvatarBadge family), so you compose the look from those pieces instead of toggling a dozen props on the root. The tinted background and the hairline border are the exceptions — the background renders from variant (toggle with background) and the border is the stroke boolean, both on the root rather than as children.

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 variant="base-inverse">
  <AvatarImage />
  <AvatarText />
  <AvatarIcon />
  <AvatarRing />
  <AvatarBadge>
    <AvatarBadgeStatus />
  </AvatarBadge>
</Avatar>
 
<AvatarGroup>
  <Avatar />
  <Avatar />
  <AvatarGroupAction />
</AvatarGroup>

Usage

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

<Avatar variant="weak-blue">
  <AvatarImage src="/avatars/ayla-karagoz.webp" alt="Ayla Karagöz" />
  <AvatarText>AK</AvatarText>
</Avatar>

Examples

Sizes

size accepts seven values from 2xs to 2xl. The AvatarText 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

Text

AvatarText renders initials or a short label when there's no portrait. Set a variant on the Avatar to tint both the background and the text from one token; the text auto-hides once an AvatarImage loads over it.

Icon

AvatarIcon draws a stylized person glyph for empty profiles. The Avatar variant sets the background; the icon takes its own combined variant token in the same {fill}-{color} shape (fill is base/weak/strong), so it can be tuned independently — e.g. base-red on a weak-red background or strong-red on an alpha-red one.

Variant

The single variant prop combines a fill and a color into one token ({fill}-{color}, e.g. base-inverse) that drives both the root background fill and the AvatarText color (inherited from the root). Eleven colors × five fills: gradient, strong, base, weak, and alpha (translucent for layering over photos). The background renders automatically when variant is set — pass background={false} to keep only the tinted text.

Stroke

The stroke boolean on Avatar paints a hairline border (an inset outline on the root) that scales with size: 0.5px at 2xs/xs, 0.75px at sm, and 1px from md and up. It is on by default outside an AvatarGroup (groups separate avatars with their own ring) — pass stroke={false} to remove it. Because it is an outline, it follows the avatar's radius automatically and never needs a child element.

PreviewCode

Copy

stroke (default)

stroke={false}

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.
• AvatarText is announced as text; prefer initials or a short label that pairs with the entity it represents.
• AvatarIcon, the variant background, the stroke outline, 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>", data-shape="<shape>", data-variant="<variant>", and data-stroke="<boolean>".
• data-slot="avatar-image" on the <img> element.
• data-slot="avatar-text" on the text wrapper.
• data-slot="avatar-icon" on the icon layer, with data-variant="<variant>".
• 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, shape, variant, background, and stroke, and broadcasts size/shape/variant 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

AvatarText

Text fallback shown when no image is provided or the image fails to load. Renders a <span> whose type scale comes from the active size and whose color comes from the avatar variant (or text-primary-base when no variant). Auto-hides once an AvatarImage loads. 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

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, shape, and variant to every nested Avatar (and size/shape to 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