Avatar

Usage

import {
  Avatar,
  AvatarImage,
  AvatarFallback,
  AvatarGroup,
} from '@acronis-platform/ui-react';

Avatar wraps Base UI's Avatar primitive — AvatarImage is hidden until the image loads, revealing AvatarFallback (typically initials). Stack several in AvatarGroup for an overlapping cluster. The fallback color is set by the color prop and themed by the --ui-avatar-* tokens.

For the common no-photo case, variant/label/icon are a shortcut so you don't have to compose AvatarFallback by hand: variant="text" (the default) shows label (defaults to 'SB'); variant="icon" shows icon. Composing AvatarImage/AvatarFallback as children always takes precedence over both.

The shortcut only applies when you pass no children. An explicit null child is treated as a deliberate "render nothing" and leaves the circle empty rather than falling back to 'SB' — which is what lets a conditional child ({icon ?? (initials ? <AvatarFallback>{initials}</AvatarFallback> : null)}) render a blank avatar.

There is no size prop: the avatar is a fixed 32px circle (--ui-avatar-global-avatar-size). The 2px separator ring (--ui-avatar-global-avatar-border-border-width / -border-color) is drawn outside that circle as a box-shadow, matching Figma's strokeAlign: OUTSIDE — so the colored circle is the full 32px and the layout box stays 32px. Don't swap it for a border-* utility: a CSS border is drawn inside the border-box and would shrink the visible circle to 28px.

Examples

An avatar with an image and an initials fallback:

<Avatar>
  <AvatarImage src="/users/jane.png" alt="Jane Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Initials only, with a color (default is teal):

<Avatar color="violet">
  <AvatarFallback>AB</AvatarFallback>
</Avatar>
<Avatar color="orange">
  <AvatarFallback>CD</AvatarFallback>
</Avatar>

// Equivalent, via the `label` convenience prop:
<Avatar color="violet" label="AB" />

An icon avatar, for a non-personal entity (a team, a bot, a system actor):

import { UserIcon } from '@acronis-platform/icons-react/stroke-mono';

<Avatar color="gray" variant="icon" icon={<UserIcon size={16} />} />;

An overlapping group:

<AvatarGroup>
  <Avatar color="teal">
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar color="violet">
    <AvatarFallback>AB</AvatarFallback>
  </Avatar>
  <Avatar color="red">
    <AvatarFallback>+3</AvatarFallback>
  </Avatar>
</AvatarGroup>

Every avatar after the first is offset by the negative --ui-avatar-global-avatar-group-gap, so the rings form the layered look and later avatars paint above earlier ones. The offset is logical, so the stack mirrors automatically under dir="rtl".

AvatarGroup composes any number of avatars — pair it with a trailing label (e.g. "On this ticket") using --ui-avatar-global-container-gap for the spacing and --ui-avatar-global-text-color for the label color:

<div className="flex items-center gap-[var(--ui-avatar-global-container-gap)]">
  <AvatarGroup>
    <Avatar color="teal">
      <AvatarFallback>SN</AvatarFallback>
    </Avatar>
    <Avatar color="violet">
      <AvatarFallback>GA</AvatarFallback>
    </Avatar>
  </AvatarGroup>
  <span className="text-sm leading-6 text-[var(--ui-avatar-global-text-color)]">
    On this ticket
  </span>
</div>

API Reference

Avatar

AvatarGroup