Avatar

Show a user. Fall back gracefully when there's no picture.

import { Avatar } from '@dashforge/tw';

<Avatar src="/avatars/jane.png" alt="Jane Doe" />

Quick Start

<Avatar src="/u/jane.png" alt="Jane Doe" />        {/* image */}
<Avatar name="Jane Doe" />                          {/* initials: "JD" */}
<Avatar name="Jane Doe" fallbackIcon={<User />} /> {/* custom fallback */}
<Avatar />                                           {/* generic SVG */}

Examples

Fallback chain (4 steps)

Avatar resolves in this order, falling back on each failure:

1. src (image) — if it loads
2. name → auto-generated initials (first letter of the first 2 whitespace-separated words, uppercased)
3. fallbackIcon (custom ReactNode)
4. Generic SVG (built-in person silhouette)

1. src

2. initials

3. icon

4. generic

Show code

StackBlitzCopy

import { Avatar, Stack } from '@dashforge/tw';
import { Building } from 'lucide-react';

<Stack direction="row" gap={3} wrap align="center">
  <Avatar src="/avatars/jane.png" alt="Jane Doe" name="Jane Doe" />     {/* step 1: src loads */}
  <Avatar src="/avatars/missing.png" alt="Jane Doe" name="Jane Doe" /> {/* step 2: initials "JD" */}
  <Avatar fallbackIcon={<Building size={18} />} />                       {/* step 3: custom icon */}
  <Avatar />                                                              {/* step 4: generic SVG */}
</Stack>

Shape variants

<Avatar name="Jane" shape="circle" />   {/* default */}
<Avatar name="Jane" shape="rounded" />  {/* soft corners */}
<Avatar name="Jane" shape="square" />   {/* hard corners */}

Override with explicit radius (Box-style token) for custom shapes:

<Avatar name="Jane" shape="rounded" radius="lg" />

Sizes

Five-step scale:

import { Avatar, Stack } from '@dashforge/tw';

<Stack direction="row" gap={3} align="center">
  <Avatar name="Jane Doe" size="xs" color="primary" />
  <Avatar name="Jane Doe" size="sm" color="primary" />
  <Avatar name="Jane Doe" size="md" color="primary" />
  <Avatar name="Jane Doe" size="lg" color="primary" />
  <Avatar name="Jane Doe" size="xl" color="primary" />
</Stack>

Color + tone (type-safe palette access)

For the no-image case (initials/icon), color and tone resolve to the Dashforge token palette — fully type-safe:

<Avatar name="Jane" color="primary"   tone={500} />
<Avatar name="Jane" color="success"   tone={600} />
<Avatar name="Jane" color="danger"    tone={500} />
<Avatar name="Jane" color="neutral"   tone={300} />

color is constrained to the palette keys (primary, secondary, success, ...). tone is constrained to the scale steps (50, 100, 200, ..., 900). Invalid combinations fail to compile.

For colors outside the palette: fall back to sx / className override (escape hatch).

Decorative onError handler

Custom fallback on image load failure:

<Avatar
  src="/u/maybe.png"
  alt="Maybe Jane"
  name="Maybe Jane"
  onError={(e) => analytics.track('avatar.load.error', { src: e.currentTarget.src })}
/>

The default onError swaps to step 2 (initials) automatically — your handler runs in addition, not instead.

AvatarGroup — overflow with size propagation

<AvatarGroup> wraps Avatar children, applies the same size to all, and shows a +N indicator when the count exceeds max.

import { Avatar, AvatarGroup } from '@dashforge/tw';

<AvatarGroup max={3}>
  <Avatar name="Alice Smith" color="primary" />
  <Avatar name="Bob Lee"     color="success" />
  <Avatar name="Carla Vega"  color="warning" />
  <Avatar name="David Park"  color="info" />
  <Avatar name="Erin Kim"    color="danger" />
</AvatarGroup>
{/* Renders: A · B · C · +2 */}

<AvatarGroup size="lg" max={4}>
  {/* size="lg" propagates to all children via cloneElement */}
  <Avatar name="Alice" /> <Avatar name="Bob" /> <Avatar name="Carla" /> <Avatar name="David" />
</AvatarGroup>

AvatarGroup withRing

By default each avatar in the group gets a ring-neutral-50 ring — a subtle separator. Disable for a flush stack:

<AvatarGroup withRing={false} max={4}>
  {/* ... */}
</AvatarGroup>

The ring uses ring-neutral-50 (NOT dark:ring-neutral-100) because the neutral palette auto-inverts via the CSS var swap. Same pattern as the rest of the catalog — see Design decisions.

Bridge integration

<Avatar name="Jane Doe"
  access={{ requires: 'workspace.admin', when: 'denied:hide' }}
/>

<Avatar src="/u/me.png"
  visibleWhen={(engine) => engine.getValue('showAuthor') === true}
/>

API

<Avatar> props

<AvatarGroup> props

Notes

• Auto-initials algorithm: takes the first letter of the first 2 whitespace-separated words of name, uppercased. "Jane Doe" → "JD". "Madonna" → "M". " jane van der meer " → "JV".
• a11y: when the inner <img> renders, it has alt="" (decorative) — the parent <span> carries the accessible name via aria-label. Avoids double-announce in screen readers.
• Color palette type-safety: color and tone are constrained at the type level to the tokens declared in @dashforge/tw-tokens. Adding a new palette key in the tokens package immediately surfaces as a new valid color value here.
• For colors outside the palette: use sx / className override on the no-image background. The constraint is on color/tone props only — the className escape hatch is unrestricted.