Components

Avatar

Displays a user's profile image with a fallback to initials or an icon when unavailable.

Stable

Anatomy

import {Avatar} from '@staffbase/design';

<Avatar.Group>
  <Avatar.Root>
    <Avatar.Image />
    <Avatar.Fallback />
  </Avatar.Root>
  <Avatar.GroupCount />
</Avatar.Group>;

Examples

Sizes

Pass name to Avatar.Fallback to derive a consistent fallback colour from the user’s name — the same name always maps to the same colour.

JDTBKPLHAW

Icon fallback

Omit name to show a generic icon on a grey background when no user identity is available.

Group

Use Avatar.Group to stack multiple avatars. Use Avatar.GroupCount to show an overflow count.

U1U2U3

API reference

Root

Inherits props fromBase UI Avatar Root

Name	Type	Description
`size`	`4840322416`	The size of the avatar in pixels. Default:`40`

Image

Inherits props fromBase UI Avatar Image

Renders the avatar image. Falls back to Fallback when the image fails to load or has no src.

Name	Type	Description
`src`	`string`	The URL of the avatar image.
`alt`	`string`	Accessible description of the image for screen readers.

Fallback

Inherits props fromBase UI Avatar Fallback

Shown when no image is available or the image fails to load.

Name	Type	Description
`name`	`string`	Derives a consistent fallback colour from the user's name. The same name always maps to the same colour. Omit to show a grey background with no derived colour.
`children`	`ReactNode`	Fallback content — typically two-character initials, or an icon when no user identity is available.

Group

Stacks multiple avatars with overlapping rings.

GroupCount

Displays an overflow count alongside a group of avatars.

When to use

To represent a person in the interface — in comment threads, activity feeds, user lists, or profile areas.
When a compact visual identity helps users scan or recognise people at a glance, such as in cards, table rows, or notification items.
To show the author, assignee, or participant of a content item alongside their name or other identifying information.
To represent a group of collaborators or participants in a compact space using Avatar.Group.

When not to use

Don’t use Avatar for non-person entities such as companies, brands, or content items — use a logo, illustration, or appropriate icon instead.
Don’t use Avatar as an interactive trigger for a menu or navigation — use a Button with an icon instead.
Don’t use Avatar to represent a document, channel, or space — use an appropriate icon or thumbnail instead.

How to use

Structure

Always compose Avatar.Root with at least one Avatar.Fallback child.
Always pair Avatar.Image with Avatar.Fallback inside Avatar.Root — the fallback displays when the image fails to load or has no source.
Don’t use Avatar.Image without Avatar.Fallback — there is no built-in error state without it.

Sizes

Use size 48 for prominent single-user contexts such as a profile page or settings header.
Use size 40 (default) for standard content areas such as cards, list rows, or comment threads.
Use size 32 for compact contexts such as secondary lists or data tables.
Use size 24 for inline references within body text or tight layouts.
Use size 16 only in extreme space constraints; avoid it where legibility matters.

JDTBKPLHAW

Fallback

Pass name to Avatar.Fallback to derive a consistent fallback colour — the same name always maps to the same colour across sessions and contexts.
Use two-character initials as children when the user’s full name is known.
Omit name and pass an icon as children when no user identity is available — the fallback shows a neutral grey background.
Use semantic icons to communicate specific user states: UserDeactivatedIcon for deactivated accounts, UserDeletedIcon for deleted accounts, and UserPendingIcon for pending invitations.

Group

Use Avatar.Group to stack multiple avatars representing collaborators or participants.
Add data-slot="avatar" to each Avatar.Root inside Avatar.Group so the group styles apply correctly.
Use Avatar.GroupCount to display an overflow count when more avatars exist than can be shown.
Show at most 3–5 avatars before switching to an overflow count to keep the group scannable.

U1U2U3

Accessibility

Always provide alt text on Avatar.Image that describes the person depicted for screen readers.
Don’t rely on Avatar fallback colour alone to convey identity — always pair the avatar with a visible name or label nearby.
Avatar is a display-only component — don’t use it as an interactive trigger or a focusable element.
When using an icon-only fallback to represent a user state, ensure the surrounding context provides an accessible label.

Content & UX copy

Use the person’s full name as the alt attribute on Avatar.Image (e.g. “Jane Doe”).
Format initials as exactly two uppercase letters from the first and last name (e.g. “JD” for Jane Doe).
Format overflow counts in Avatar.GroupCount with a “+” prefix and no space (e.g. “+4”, “+12”).
Don’t truncate names or generate initials from a single name part — use two characters from distinct name parts.