Data

Avatar

User avatar with image, fallback initials, and status badge.

Preview

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from '@brika/clay/components/avatar';
/** Default avatar with a remote image and initials fallback. */
export default function AvatarDefaultDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://api.dicebear.com/9.x/initials/svg?seed=Alicia" alt="Alicia Reyes" />
      <AvatarFallback>AR</AvatarFallback>
    </Avatar>
  );
}

01 Installation

Install

Pull Avatar from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { Avatar } from "@brika/clay";

tsxGranular1 line

import { Avatar } from "@brika/clay/components/avatar";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxAvatar.tsx14 lines

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from '@brika/clay/components/avatar';
/** Default avatar with a remote image and initials fallback. */
export default function AvatarDefaultDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://api.dicebear.com/9.x/initials/svg?seed=Alicia" alt="Alicia Reyes" />
      <AvatarFallback>AR</AvatarFallback>
    </Avatar>
  );
}

03 Examples

Avatar, every way

Badge

AvatarBadge overlays a status indicator in the bottom-right corner.

GitHub

import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
} from '@brika/clay/components/avatar';
import { Circle } from 'lucide-react';

/** AvatarBadge overlays a status indicator in the bottom-right corner. */
export default function AvatarBadgeDemo() {
  return (
    <div className="flex items-center gap-4">
      <Avatar>
        <AvatarFallback>AR</AvatarFallback>
        <AvatarBadge className="bg-success" aria-label="Online">
          <Circle className="fill-current" />
        </AvatarBadge>
      </Avatar>
      <Avatar>
        <AvatarFallback>TH</AvatarFallback>
        <AvatarBadge className="bg-muted-foreground" aria-label="Away" />
      </Avatar>
    </div>
  );
}

Fallback

When the image URL fails or is omitted, initials render in the fallback slot.

GitHub

import {
  Avatar,
  AvatarFallback,
} from '@brika/clay/components/avatar';
/** When the image URL fails or is omitted, initials render in the fallback slot. */
export default function AvatarFallbackDemo() {
  return (
    <div className="flex items-center gap-2">
      <Avatar>
        <AvatarFallback>TR</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>YT</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>DV</AvatarFallback>
      </Avatar>
    </div>
  );
}

Group

Stacked AvatarGroup with a count bubble for the remaining members.

GitHub

import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from '@brika/clay/components/avatar';
/** Stacked AvatarGroup with a count bubble for the remaining members. */
export default function AvatarGroupDemo() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarImage src="https://api.dicebear.com/9.x/initials/svg?seed=Alicia" alt="Alicia" />
        <AvatarFallback>AR</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>TH</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>YT</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+4</AvatarGroupCount>
    </AvatarGroup>
  );
}

Sizes

Three preset sizes, `sm` (24px), `default` (32px), and `lg` (40px).

GitHub

import {
  Avatar,
  AvatarFallback,
} from '@brika/clay/components/avatar';
/** Three preset sizes, `sm` (24px), `default` (32px), and `lg` (40px). */
export default function AvatarSizesDemo() {
  return (
    <div className="flex items-center gap-3">
      <Avatar size="sm">
        <AvatarFallback>SM</AvatarFallback>
      </Avatar>
      <Avatar size="default">
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>LG</AvatarFallback>
      </Avatar>
    </div>
  );
}

04 Accessibility

Accessibility

AvatarImage requires an alt attribute; use the user's name, or alt="" for decorative use.
AvatarFallback is visible only when the image fails or is missing; AT reads the fallback text.
Status badge text should be wrapped in an aria-label when it conveys meaning (e.g. "Online").

05 Tokens 8 theme-overridable

Theme tokens

Every CSS variable Avatar reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Avatar without touching component code.

Avatar tokens

8 tokens

ColorFill, border, and text colors.5

--avatar-fallback-containercolorvar(--muted)
components.avatar.fallbackContainer
Background of the avatar fallback (and the `<AvatarGroupCount>` chip).
--avatar-fallback-labelcolorvar(--muted-foreground)
components.avatar.fallbackLabel
Text color (initials) of the avatar fallback.
--avatar-badge-containercolorvar(--primary)
components.avatar.badgeContainer
Background of the small `<AvatarBadge>` indicator pinned to the bottom-right corner.
--avatar-badge-labelcolorvar(--primary-foreground)
components.avatar.badgeLabel
Foreground (icon / count) color of the `<AvatarBadge>` indicator.
--avatar-ring-colorcolorvar(--background)
components.avatar.ringColor
Color of the 2px ring drawn around the avatar badge and around grouped avatars to separate them from the surrounding surface.

GeometrySizes, lengths, and corner radii.3

--avatar-sizesize2rem
components.avatar.size
Avatar diameter at the default size.
--avatar-group-spacingsize0.5rem
components.avatar.groupSpacing
Negative inline overlap between adjacent avatars inside an `<AvatarGroup>`. Larger values pull stacked avatars further apart.
--avatar-radiusradius9999px
components.avatar.radius
Avatar corner radius. Default is fully circular.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.avatar, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "avatar": {
      "radius": "9999px"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-avatar-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Avatar. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

<Avatar />

1 prop

sizedefault 'default'
'default' | 'sm' | 'lg'
Preset diameter.