Skip to content

Avatar

⋯

Avatar renders the Figma single-person image, initials, or icon anatomy. Avatar.Group renders the 32px overlapping group shown in Figma with data supplied by the consuming application.

import { Avatar } from "@nesra/ui/avatar";
export function TeamMember() {
return <Avatar initials="JT" name="Jane Taylor" size="md" />;
}

Avatar is also exported from @nesra/ui.

Nest visible members inside Avatar.Group. Each member remains an independently named Avatar.

import { Avatar } from "@nesra/ui/avatar";
export function ProjectMembers() {
return (
<Avatar.Group label="Project members">
<Avatar initials="JT" name="Jane Taylor" size="md" />
<Avatar initials="OR" name="Olivia Rahman" size="md" />
</Avatar.Group>
);
}

src shows a circular photo. The photo is decorative; name labels the avatar. The image below is a Figma example asset. Replace its URL with an image URL from your application.

When src is absent or fails to load, initials appear. Omit initials for the person icon.

sm, md, and lg have diameters of 24, 32, and 40px. The default is sm.

onAction makes the entire avatar a button with a circle-plus badge. actionLabel names the button. This example reports clicks; the application owns the actual edit behavior.

Edit requests: 0

disabled mutes an image, initials, or icon. It also prevents an onAction button from activating.

Avatar.Group overlaps its children. Give each Avatar a name and size="md" to match Figma’s 32px group. These photos are Figma example assets; replace their URLs and names with application data.

The Figma group shows one to five visible people. The application chooses which members to render.

1
2
3
4
5

overflowCount is the number of additional members beyond the rendered children. The initials avatar in this example is a visible member, while +5 represents five more members.

+5

onAdd displays a separate dashed add button. addLabel names it. This example reports requests; the application owns any member creation or picker.

Add requests: 0

Avatar follows the page theme. Dark applies when an ancestor has the dark class or data-theme="dark".

  • Initials and the person icon use Text/text-brand-primary and Icon/icon-brand-primary on Surface/card-bg-brand-primary-50, with a Stroke/stroke-divider border. The overflow count uses the same roles.
  • Disabled avatars use Surface/card-bg-gray with Text/text-disabled and Icon/icon-disabled.
  • The action badge is a Foundation/bg-neutral circle with Box Shadow/shadow-sm, so it matches the page in both modes. Its plus icon uses Icon/icon-brand-primary, or Icon/icon-disabled when disabled.
  • The group add button uses Surface/popover-bg-neutral, a dashed Stroke/stroke-border, and an Icon/icon-muted plus.
  • Keyboard focus shows Box Shadow/Focus ring offset on an avatar action and Box Shadow/Focus ring on the add button.
  • Photos are not recolored. The bg-nesra-component-avatar-background-* backdrops in the group examples keep the same color in both modes.
  • name labels a static avatar. Its photo has an empty alt to avoid repeating the name.
  • With onAction, the avatar is a native button named by actionLabel; the visual avatar and badge are decorative to assistive technology. Provide a label that describes the action.
  • Avatar.Group requires label for the group and addLabel when onAdd is present. Each child Avatar retains its own name. The add control is a native button.
  • Keep member names and overflowCount accurate as application data changes.
Prop Type Default Description
name string required Accessible name for a static avatar.
src string — Image URL. Failed images show the fallback.
initials string — Fallback text; otherwise a person icon appears.
size "sm" | "md" | "lg" "sm" Diameter of 24, 32, or 40px.
disabled boolean false Muted appearance; also disables the action.
onAction button click handler — Makes the whole avatar a button.
actionLabel string — Required accessible name when onAction is used.
className string — Adds or overrides classes.

Other Base UI Avatar Root span props are forwarded. A ref points to that span.

Prop Type Default Description
label string required Accessible name for the group.
children ReactNode required Visible Avatar members.
overflowCount number 0 Count of additional members beyond the children.
onAdd button click handler — Shows the add button.
addLabel string — Required accessible name when onAdd is used.
className string — Adds or overrides classes.

The group uses the AvatarGroupProps type. Other native div props are forwarded. A ref points to the group div. Colors use the Light and Dark semantic color roles.