Avatar | Fragments

Preview

import { Avatar } from '@/components/Avatar';

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

Installation

npx @usefragments/cli add avatar

Writes src/fragments/ui/components/Avatar plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Avatar is a compound: import the root and reach its parts through dot notation.

Avatar.Group

Examples

With Initials

No src, so the name collapses to initials.

import { Avatar } from '@/components/Avatar';

<Avatar name="John Smith" />

Sizes

Five steps, xs through xl — pick one per context and stick to it.

import { Avatar } from '@/components/Avatar';
import { Stack } from '@/components/Stack';

<Stack direction="row" gap="sm" align="center" wrap>
  <Avatar name="XS" size="xs" />
  <Avatar name="SM" size="sm" />

Custom Size

customSize takes any number when the scale does not fit.

import { Avatar } from '@/components/Avatar';

<Avatar name="Conan McNicholl" customSize={36} />

Square Shape

Squares read as products or orgs, circles as people.

import { Avatar } from '@/components/Avatar';

<Avatar name="App" shape="square" />

Group

Overlapping stack with a count for whoever did not fit.

import { Avatar } from '@/components/Avatar';

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

API

Component props
Prop	Type	Default	Description
`src`	`string`	Not set	Image source URL
`alt`	`string`		Alt text for the image
`initials`	`string`	Not set	Fallback initials (1-2 characters)
`name`	`string`	Not set	Full name - used to generate initials
`size`	`enumxssmmdlgxl`	`md`	Size variant
`customSize`	`union`	Not set	Custom avatar size (number in px or CSS size string like "2.25rem"), overrides size width/height
`shape`	`enumcirclesquare`	`circle`	Shape variant
`color`	`string`	Not set	Custom background color for fallback avatar
`imageStyle`	`object`	Not set	Inline style object applied to the underlying image element
`imageProps`	`object`	Not set	Additional props for the underlying img element (except src/alt/className/style)
`style`	`object`	Not set	—
`fallback`	`node`	Not set	Visual fallback rendered after initials/name and before the generic icon

Accessibility

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

Guidance

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)

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 contractThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.