Avatar

Round (or rounded / square) user picture with five sizes, an automatic initials fallback when the image fails or is still loading, and a paired AvatarGroup for stacked rows with a built-in +N overflow pill.

JSAB🎵

ARMSILCT+3

Usage

import { Avatar, AvatarGroup } from '@bwo-ui/react';

<Avatar src="/me.jpg" alt="Cristian Cuna" fallback="CC" />
<Avatar fallback="JS" size="lg" />

<AvatarGroup max={3}>
  <Avatar fallback="AR" />
  <Avatar fallback="MS" />
  <Avatar fallback="IL" />
  <Avatar fallback="CT" />
  <Avatar fallback="DV" />
</AvatarGroup>

Sizes

Five sizes — xs (24 px) → xl (80 px). xs is built for inline-with-text density (mentions, comment rails); sm and md are general purpose; lg reads as a profile callout; xl is the hero size for profile pages and onboarding.

<Avatar size="xs" fallback="AR" />
<Avatar size="sm" fallback="AR" />
<Avatar             fallback="AR" />  {/* md, default */}
<Avatar size="lg" fallback="AR" />
<Avatar size="xl" fallback="AR" />

Shapes

The default circle works for human avatars. rounded (8 px radius) reads better for brand / company / product avatars; square is the editorial choice — handy for project-thumbnail rows that want a hard-edged look.

circle

rounded

square

<Avatar shape="circle"  src="/u.jpg" fallback="WK" />
<Avatar shape="rounded" src="/u.jpg" fallback="WK" />
<Avatar shape="square"  src="/u.jpg" fallback="WK" />

Image + fallback

Pass an src and Avatar will render the image once it loads. While loading, the fallback is shown after a brief delay (fallbackDelay, default 300 ms) to avoid a flicker on fast networks. If the image errors, the fallback persists.

The fallback prop accepts anything — initials (the convention), an emoji, an inline SVG icon. If you don't pass it, children are used instead.

image

ARinitials

broken → fallback

🎵emoji

icon

{/* Initials (most common) */}
<Avatar src="/u.jpg" alt="Ana Radu" fallback="AR" />

{/* Loading delay tuned for slow networks */}
<Avatar src="/large.jpg" fallback="AR" fallbackDelay={600} />

{/* Decorative emoji */}
<Avatar fallback="🎵" />

{/* Custom icon */}
<Avatar
  fallback={<UserIcon />}
  style={{ background: 'var(--bwo-grey-4)' }}
/>

For coloured initial bubbles like a directory listing, set the background and color via inline style — Avatar forwards every native span attribute.

<Avatar
  fallback="AR"
  style={{ background: '#ff481f', color: '#fff' }}
/>

AvatarGroup

Stack avatars in an overlapping row. Use max to cap the visible count — any extras collapse into a +N pill. Every member gets a 2 px white ring so the overlap reads cleanly even on tinted backgrounds. The size and shape on the group cascade to children that don't set their own.

{/* No cap — show every avatar */}
<AvatarGroup>
  <Avatar fallback="AR" />
  <Avatar fallback="MS" />
  <Avatar fallback="IL" />
  <Avatar fallback="CT" />
</AvatarGroup>

{/* Cap at 3 — extras become +N */}
<AvatarGroup max={3}>
  <Avatar fallback="AR" />
  <Avatar fallback="MS" />
  <Avatar fallback="IL" />
  <Avatar fallback="CT" />
  <Avatar fallback="DV" />
  <Avatar fallback="AP" />
  <Avatar fallback="EV" />
</AvatarGroup>

{/* Large size cascades to children */}
<AvatarGroup max={5} size="lg">
  {/* … */}
</AvatarGroup>

{/* Explicit total when children are only a sample */}
<AvatarGroup max={2} size="sm" total={28}>
  <Avatar fallback="AR" />
  <Avatar fallback="MS" />
</AvatarGroup>

Hover an avatar in the stack to lift it forward — every member animates independently, which is useful for revealing names on hover via a tooltip layer.

Status indicator (recipe)

Avatars commonly carry a tiny status dot (online / idle / busy / offline). There's no dedicated prop — the avatar's overflow: hidden would clip any absolutely-positioned child anyway — so the canonical recipe is to wrap the avatar in a positioned span and drop a coloured dot at the bottom-right corner. The dot wears a 2 px white ring so it pops off the avatar even on busy photos.

function AvatarWithStatus({ status, ...avatarProps }) {
  const color = {
    online:  '#16a34a',
    idle:    '#ffc446',
    busy:    '#ff481f',
    offline: 'var(--bwo-grey-3)',
  }[status];
  return (
    <span style={{ position: 'relative', display: 'inline-flex' }}>
      <Avatar {...avatarProps} />
      <span
        aria-hidden
        style={{
          position: 'absolute',
          bottom: 0,
          right: 0,
          width: 12,
          height: 12,
          borderRadius: '50%',
          background: color,
          boxShadow: '0 0 0 2px var(--bwo-white)',
        }}
      />
    </span>
  );
}

Comment / message recipe

The classic comment-row layout: md avatar on the left, a name + relative timestamp on the first line, body text on the second. xs works well here when the surrounding text is dense.

<div style={{ display: 'flex', gap: 12 }}>
  <Avatar fallback="AR" style={{ background: '#ff481f', color: '#fff' }} />
  <div style={{ flex: 1 }}>
    <div style={{ display: 'flex', gap: 8, alignItems: 'baseline' }}>
      <span style={{ fontWeight: 600 }}>Ana Radu</span>
      <span style={{ fontSize: 11, color: 'var(--bwo-text-body)' }}>2 min ago</span>
    </div>
    <p>Pushed the new IconButton parity branch…</p>
  </div>
</div>

Accessibility

• Always pair src with a meaningful alt. Avatar forwards alt directly to the inner <img>.
• When the avatar is purely decorative (e.g. it sits next to the person's name), pass alt="" so screen readers don't double-announce.
• For initials-only avatars, the visible letters carry the meaning — they're inside a <span>, not an image, so screen readers will read them. If they should be skipped, wrap them in a parent with aria-hidden.
• For status indicators, use aria-hidden="true" on the dot and convey the state with adjacent text (the dot is a visual aid, not the source of truth). The recipe above follows this rule.
• AvatarGroup's overflow pill carries aria-label="{N} more" so screen readers announce the hidden count.

Avatar props

AvatarGroup props