React Avatar component

Preview

import { Avatar } from '@usefragments/ui';

<Avatar
  src="https://i.pravatar.cc/150?u=jane"
  alt="Jane Doe"
  name="Jane Doe"

Usage

Use when

A row, comment, or card needs to say who
Several people belong to one thing — use Avatar.Group

Avoid when

The picture is content, not identity (use Image)
A profile hero at display size (build the layout yourself)

Implementation notes

Pass name even when you pass src — it is the fallback and the label
Hold one size per context; xs (24) for rows, lg (40) at most
Avatar.Group max caps the stack and counts the rest
imageProps carries loading, decoding, referrerPolicy

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import Avatar once, then compose its parts with dot notation.

Avatar.Group

Examples

With Initials

No src, so the name collapses to initials.

import { Avatar } from '@usefragments/ui';

<Avatar name="John Smith" />

Sizes

The control tracks: 24, 28, 32 and 40.

import { Stack } from '@usefragments/ui';

<Stack direction="row" gap="sm" align="center">
  <Avatar name="Jane Doe" size="xs" />
  <Avatar name="Jane Doe" size="sm" />
  <Avatar name="Jane Doe" size="md" />

Group

Overlapping stack with a count for whoever did not fit.

import { Avatar } from '@usefragments/ui';

<Avatar.Group max={3}>
  <Avatar name="Alice Johnson" />
  <Avatar name="Bob Smith" />
  <Avatar name="Carol Williams" />

API reference

Component props
Prop	Type	Default	Description
`alt`	`string \| undefined`		Alt text for the image
`fallback`	`React.ReactNode`	Not set	Visual fallback rendered after initials and before the generic glyph
`Group.children`Required	`React.ReactNode`	Not set	Children (Avatar components)
`Group.max`	`number \| undefined`	Not set	Maximum number of avatars to display; the rest collapse into a +N tile
`Group.size`	`AvatarSize \| undefinedxssmmdlg`	Not set	Size for all avatars in the group
`imageProps`	`Omit<React.ImgHTMLAttributes<HTMLImageElement>, "className" \| "style" \| "src" \| "alt"> \| undefined`	Not set	Additional props for the underlying img element (except src/alt/className/style)
`initials`	`string \| undefined`	Not set	Fallback initials (1-2 characters)
`name`	`string \| undefined`	Not set	Full name - used to generate initials
`size`	`AvatarSize \| undefinedxssmmdlg`	`xs`	The control track: xs 24, sm 28, md 32, lg 40
`src`	`string \| undefined`	Not set	Image source URL

Accessibility

alt describes the person, not the word "avatar"
Initials come from name, so screen readers get the whole name
Purely decorative? Pass alt=""

ImagealternativeUse Image for content pictures that are not a person or entity
BadgesiblingPair with Badge to show presence or role beside a name

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.