Avatar

Image with initials fallback (Base UI Avatar handles loading/error states).

Import

import { Avatar, AvatarGroup } from '@marbleui/ui'

Props

<Avatar>

Prop	Type	Default
name *required	`string`	`—`
className	`string`	`—`
shape	`'circle' \| 'square'`	`'circle'`
size	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'md'`
src	`string`	`—`
status	`'online' \| 'away' \| 'busy' \| 'offline'`	`—`

<AvatarGroup>

Prop	Type	Default	Description
children *required	`ReactNode`	`—`
extra	`number`	`—`	Number of hidden people to show as "+N".
size	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'sm'`

Also accepts HTML element props (277).

Accessibility

Keyboard interaction, focus management and ARIA semantics come from the underlying primitive: Base UI Avatar. Follow the primitive's docs for the full keyboard map.

Usage notes

Show a person or entity as a photo with an initials fallback. For a text label or category use Badge; for a bare presence dot without a person use StatusIndicator.

<AvatarGroup extra={5}>
  <Avatar name="Maya Chen" src="/maya.jpg" status="online" />
  <Avatar name="Ada Lovelace" />
</AvatarGroup>

name is required. It becomes the image alt, and the fallback shows up to two initials from it (after a 400 ms delay when src is set).
size is xs, sm, md (default) or lg; shape is circle (default) or square. status is online, away, busy or offline, exposed as a labelled image.
AvatarGroup overlaps its children and renders +N from extra (hidden when it’s 0 or less); its size only affects that +N chip, so set size on each Avatar too.

Example source · show

import { Avatar, AvatarGroup } from './avatar'

const photo = (id: string) => `https://images.unsplash.com/photo-${id}?w=128&h=128&fit=crop&crop=faces&q=80`
const people = [
  { name: 'Maya Chen', src: photo('1494790108377-be9c29b29330') },
  { name: 'Charles Webb', src: photo('1500648767791-00dcc994a43e') },
  { name: 'Ada Lovelace' },
  { name: 'Grace Hopper' },
]

export const styles = {
  Sizes: () => (
    <div className="flex items-end gap-3">
      <Avatar size="xs" {...people[0]!} />
      <Avatar size="sm" {...people[0]!} />
      <Avatar size="md" {...people[0]!} />
      <Avatar size="lg" {...people[0]!} />
    </div>
  ),
  Fallback: () => (
    <div className="flex items-center gap-3">
      <Avatar name="Ada Lovelace" />
      <Avatar name="Grace Hopper" shape="square" />
      <Avatar name="Broken Image" src="https://example.invalid/nope.png" />
    </div>
  ),
  Status: () => (
    <div className="flex items-center gap-4">
      <Avatar {...people[0]!} status="online" />
      <Avatar {...people[1]!} status="away" />
      <Avatar name="Ada Lovelace" status="busy" />
      <Avatar name="Grace Hopper" status="offline" />
    </div>
  ),
  Group: () => (
    <AvatarGroup extra={5}>
      {people.map((p) => (
        <Avatar key={p.name} size="sm" {...p} />
      ))}
    </AvatarGroup>
  ),
}

Source: packages/ui/src/avatar/avatar.tsx

Catalog

Category: data-display
Priority: Foundation
Primitive: base-ui
Base UI: Avatar