Avatar

A user avatar with automatic image-load fallback to initials or a default icon, plus an optional status badge.

Overview

Avatar renders a user's picture, falling back gracefully when there isn't one: if src is missing or the image fails to load, it shows the first letter of name instead, and if neither is provided it renders a generic user icon. An optional status Badge can be layered in the corner to show presence (available, away, unavailable, invisible).

Import

import { Avatar } from '@unflow.io/ui/components/Avatar';

Props

Prop	Type	Default	Description
`src`	`string`	—	Image URL. Automatically falls back to initials (or the default icon) if it fails to load
`name`	`string`	—	Used to render the first-letter initial when no image is shown, and as the accessible label of the avatar
`alt`	`string`	—	Alt text for the rendered `<img>` when `src` is set
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'`	`'lg'`	Size of the avatar (and its status badge)
`variant`	`'rounded' \| 'square'`	`'rounded'`	Shape of the avatar
`status`	`'invisible' \| 'away' \| 'available' \| 'unavailable'`	—	Renders a status Badge in the bottom-right corner
`disableStatusBadge`	`boolean`	—	Hides the status badge entirely, regardless of `status`

Image

Pass src (and alt) to render a photo. If the image fails to load, Avatar swaps to the initials/icon fallback automatically.

<Avatar
  src="https://i.pravatar.cc/128"
  alt="Jane Doe profile picture"
  aria-label="Jane Doe"
  status="available"
/>

Initials & fallback icon

Without src (or when the image errors), Avatar shows the first letter of name. Without either src or name, it renders a default user icon.

<div className="flex items-center gap-4">
  <Avatar name="Jane Doe" status="available" />
  <Avatar aria-label="Unknown user" />
</div>

Sizes

size accepts eight steps from xs to 4xl and also scales the status badge to match.

const sizes = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl'] as const;

<div className="flex items-end gap-3">
  {sizes.map((size) => (
    <Avatar key={size} name="Jane Doe" size={size} status="available" />
  ))}
</div>

Status indicator

Set status to render a presence badge, or disableStatusBadge to omit it entirely.

<div className="flex items-center gap-4">
  <Avatar name="Jane Doe" status="available" />
  <Avatar name="Jane Doe" status="away" />
  <Avatar name="Jane Doe" status="unavailable" />
  <Avatar name="Jane Doe" status="invisible" />
  <Avatar name="Jane Doe" disableStatusBadge />
</div>

Customization (slots & slotProps)

Slot	Type	Description
`statusBadge`	`ReactNode`	Replace the status badge element entirely

Slot Prop	Props	Description
`avatarRoot`	`BaseHTMLProps<HTMLDivElement>`	The container wrapping the image, initial, or fallback icon
`avatar`	`BaseImageProps`	The `<img>` element rendered when `src` is set
`letter`	`BaseHTMLProps<HTMLParagraphElement>`	The `<p>` element rendering the initial from `name`
`fallbackIcon`	`Omit<SVGProps<SVGSVGElement>, 'color' \| 'fill' \| 'stroke'>`	The default user icon shown when neither `src` nor `name` is set
`statusBadge`	`Omit<IBadge, 'status' \| 'variant' \| 'size'>`	Props forwarded to the status Badge

Accessibility

The avatar element carries role="img" with an aria-label derived from name (overridable via slotProps.avatarRoot['aria-label']), so screen readers announce who it represents even for initials or icon fallbacks.
Provide aria-label (or name) on every Avatar — a console warning is logged in development if neither is present.
Provide alt whenever src is set — a console warning is logged in development if it's missing.
If the image fails to load, Avatar automatically swaps to the initials/icon fallback instead of leaving a broken image in place.

On this page