coss.com ui

Avatar

An image element with a fallback for representing the user.

API Reference

Installation

Usage

Use keepMounted when the image relies on native lazy loading or an optimized image component. The fallback remains visible while the image loads or if it fails:

Sizing

Every dimension of an avatar comes from one inherited custom property, --avatar-size. It defaults to 32px, and the font size, the group overlap, the gap and the initials nudge are all derived from it.

Set it on the avatar, on a group, or on any ancestor:

A size-* utility still resizes a single avatar, because tailwind-merge replaces the base size utility. It does not update --avatar-size, so the font size and any group geometry stay at the inherited value. Prefer --avatar-size and reach for size-* only when you want the box to change and nothing else.

Because the property is inherited, one declaration on a container sizes every avatar inside it.

API Reference

Avatar

Root component. Styled wrapper for Avatar.Root from Base UI, round by default and sized from --avatar-size.

It declares no props of its own; everything from Avatar.Root passes through, including className and render.

It renders a <span>. To make an avatar interactive, use render rather than wrapping it:

An interactive avatar needs an accessible name. AvatarImage's alt supplies one; a fallback-only avatar does not, so add aria-label.

AvatarImage

Image element. Styled wrapper for Avatar.Image from Base UI.

AvatarFallback

Shown while the image loads or when it fails, and whenever no image is given. Base UI unmounts it once the image loads.

It inherits its font size from the avatar, so it scales automatically. Override it on the fallback when a specific size is needed:

AvatarGroup

Lays out overlapping avatars. Each avatar is masked with a circle matching its neighbour, so the avatars are separated by a transparent gap rather than a ring. The stack therefore holds its shape on gradients, images and translucent panels, where a ring tinted with the page background would not.

Geometry is derived from the inherited --avatar-size, so sizing a stack is the same gesture as sizing one avatar. Three further properties tune the layout, and all of them inherit:

Constraints worth knowing:

  • Every avatar in a group must be the same size. The mask is positioned from the group's --avatar-size, so a per-avatar override misplaces the cut. Set the size on the group.
  • A status dot or badge on a clipped avatar is clipped with it, and is cropped to the circle. Put one on the avatar that stays whole — the first with topmost="first", the last with topmost="last".
  • Browsers without mask-composite (Chrome and Edge 111–119) fall back to a plain overlap with no gap. Nothing else degrades.

AvatarGroupCount

The "+N" chip that ends a group. It is an Avatar with a fallback, so it is sized, overlapped and clipped like its neighbours; its label uses text-muted-foreground.

Examples

Fallback Only

Different Radius

Group Avatars

Last Avatar On Top

Set topmost="last" for the conventional order, where the last avatar is the one left intact.

Changelog

  • October 18, 2026 — AvatarGroup and AvatarGroupCount added; overlapping avatars are separated by a transparent clipped gap instead of a ring. Avatar now derives its box, type and group geometry from the inherited --avatar-size. AvatarFallback moves from bg-muted to bg-border, and Avatar no longer paints bg-background.

coss.com ui

Built by and for the team of Cal.com, Inc. — the leading commercial open source company (“coss”).