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.
import { Avatar } from "@nesra/ui/avatar";
export function AvatarBasicExample() { return <Avatar initials="JT" name="Jane Taylor" size="md" />;}Composition
Section titled “Composition”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> );}Examples
Section titled “Examples”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.
import { Avatar } from "@nesra/ui/avatar";
export function AvatarImageExample() { return <Avatar initials="JT" name="Jane Taylor" size="lg" src="/avatar/portrait.png" />;}Initials and icon fallbacks
Section titled “Initials and icon fallbacks”When src is absent or fails to load, initials appear. Omit initials for the person icon.
import { Avatar } from "@nesra/ui/avatar";
export function AvatarFallbacksExample() { return ( <div className="flex items-center gap-nesra-spacing-md"> <Avatar initials="JT" name="Jane Taylor" size="md" /> <Avatar name="Unknown member" size="md" /> </div> );}sm, md, and lg have diameters of 24, 32, and 40px. The default is sm.
import { Avatar } from "@nesra/ui/avatar";
export function AvatarSizesExample() { return ( <div className="flex items-center gap-nesra-spacing-md"> <Avatar initials="JT" name="Jane Taylor" size="sm" /> <Avatar initials="JT" name="Jane Taylor" size="md" /> <Avatar initials="JT" name="Jane Taylor" size="lg" /> </div> );}Action
Section titled “Action”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.
import { Avatar } from "@nesra/ui/avatar";import { useState } from "react";
export function AvatarActionsExample() { const [requests, setRequests] = useState(0);
return ( <div className="flex items-center gap-nesra-spacing-md"> <Avatar actionLabel="Edit Jane Taylor" initials="JT" name="Jane Taylor" onAction={() => setRequests((count) => count + 1)} size="lg" src="/avatar/portrait.png" /> <output aria-live="polite" className="type-nesra-body-small-regular text-nesra-text-support"> Edit requests: {requests} </output> </div> );}Disabled
Section titled “Disabled”disabled mutes an image, initials, or icon. It also prevents an onAction button from activating.
import { Avatar } from "@nesra/ui/avatar";
export function AvatarDisabledExample() { return ( <div className="flex items-center gap-nesra-spacing-md"> <Avatar disabled initials="JT" name="Jane Taylor" size="md" src="/avatar/portrait.png" /> <Avatar disabled initials="OR" name="Olivia Rahman" size="md" /> <Avatar disabled name="Unknown member" size="md" /> <Avatar actionLabel="Edit Jane Taylor" disabled initials="JT" name="Jane Taylor" onAction={() => {}} size="md" /> </div> );}Group of members
Section titled “Group of members”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.
import { Avatar } from "@nesra/ui/avatar";
export function AvatarGroupBasicExample() { return ( <Avatar.Group label="Project members"> <Avatar className="bg-nesra-component-avatar-background-1" name="Member one" size="md" src="/avatar/member-1.png" /> <Avatar className="bg-nesra-component-avatar-background-2" name="Member two" size="md" src="/avatar/member-2.png" /> <Avatar initials="OR" name="Olivia Rahman" size="md" /> </Avatar.Group> );}One to five members
Section titled “One to five members”The Figma group shows one to five visible people. The application chooses which members to render.
import { Avatar } from "@nesra/ui/avatar";
const members = [ { name: "Member one", src: "/avatar/member-1.png", className: "bg-nesra-component-avatar-background-1", }, { name: "Member two", src: "/avatar/member-2.png", className: "bg-nesra-component-avatar-background-2", }, { name: "Member three", src: "/avatar/member-3.png", className: "bg-nesra-component-avatar-background-3", }, { name: "Member four", src: "/avatar/member-4.png", className: "bg-nesra-component-avatar-background-4", }, { name: "Member five", src: "/avatar/member-5.png", className: "bg-nesra-component-avatar-background-5", },];
export function AvatarGroupCountsExample() { return ( <div className="grid gap-nesra-spacing-md"> {members.map((member, index) => ( <div key={member.name} className="flex items-center gap-nesra-spacing-md"> <span className="w-6 type-nesra-body-small-regular text-nesra-text-support"> {index + 1} </span> <Avatar.Group label={`${index + 1} project members`}> {members.slice(0, index + 1).map((visible) => ( <Avatar key={visible.name} {...visible} size="md" /> ))} </Avatar.Group> </div> ))} </div> );}Overflow count
Section titled “Overflow count”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.
import { Avatar } from "@nesra/ui/avatar";
export function AvatarGroupExample() { return ( <Avatar.Group label="Project members" overflowCount={5}> <Avatar className="bg-nesra-component-avatar-background-1" name="Member one" size="md" src="/avatar/member-1.png" /> <Avatar className="bg-nesra-component-avatar-background-2" name="Member two" size="md" src="/avatar/member-2.png" /> <Avatar className="bg-nesra-component-avatar-background-3" name="Member three" size="md" src="/avatar/member-3.png" /> <Avatar initials="OR" name="Olivia Rahman" size="md" /> </Avatar.Group> );}Add action
Section titled “Add action”onAdd displays a separate dashed add button. addLabel names it. This example reports requests;
the application owns any member creation or picker.
import { Avatar } from "@nesra/ui/avatar";import { useState } from "react";
export function AvatarGroupAddExample() { const [requests, setRequests] = useState(0);
return ( <div className="flex items-center gap-nesra-spacing-md"> <Avatar.Group addLabel="Add project member" label="Project members" onAdd={() => setRequests((count) => count + 1)} > <Avatar initials="JT" name="Jane Taylor" size="md" /> <Avatar initials="OR" name="Olivia Rahman" size="md" /> </Avatar.Group> <output aria-live="polite" className="type-nesra-body-small-regular text-nesra-text-support"> Add requests: {requests} </output> </div> );}Light and Dark
Section titled “Light and Dark”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-primaryandIcon/icon-brand-primaryonSurface/card-bg-brand-primary-50, with aStroke/stroke-dividerborder. The overflow count uses the same roles. - Disabled avatars use
Surface/card-bg-graywithText/text-disabledandIcon/icon-disabled. - The action badge is a
Foundation/bg-neutralcircle withBox Shadow/shadow-sm, so it matches the page in both modes. Its plus icon usesIcon/icon-brand-primary, orIcon/icon-disabledwhen disabled. - The group add button uses
Surface/popover-bg-neutral, a dashedStroke/stroke-border, and anIcon/icon-mutedplus. - Keyboard focus shows
Box Shadow/Focus ring offseton an avatar action andBox Shadow/Focus ringon 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.
Accessibility
Section titled “Accessibility”namelabels a static avatar. Its photo has an emptyaltto avoid repeating the name.- With
onAction, the avatar is a native button named byactionLabel; the visual avatar and badge are decorative to assistive technology. Provide a label that describes the action. Avatar.Grouprequireslabelfor the group andaddLabelwhenonAddis present. Each child Avatar retains its own name. The add control is a native button.- Keep member names and
overflowCountaccurate as application data changes.
API reference
Section titled “API reference”Avatar
Section titled “Avatar”| 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.
Avatar.Group
Section titled “Avatar.Group”| 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.