Avatar

01Preview

Change the controls to try every supported combination. The preview renders the real component and the code updates with it.

import { Avatar } from '@nuton/ui'

<Avatar
  size={56}
  name="Emma Wright"
  color="sky"
  bottomStatus="online" bottomStatusLabel="Online"
/>

Figma's persona photos, memoji and illustrations aren't shipped (provenance, D12). The portraits on this page are free Unsplash photos used only in these docs; the “solid image” ones have their backgrounds removed so the avatar colour shows behind them. Apps pass their own src.

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens

npm install @nuton/ui @nuton/tokens

yarn add @nuton/ui @nuton/tokens

Peer dependencies: react and react-dom 18 or later. The status icons come with @nuton/ui; add @remixicon/react only if you build a company logo from a Remix icon.

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

Initials and counts use the Label and Paragraph type tokens, which read --nu-font-body (Inter). Map it to your loaded font as shown on the Button page. Avatar is a client component (it tracks image load errors), and you can render it from a server component without extra setup.

03Usage

import { Avatar, AvatarGroup } from '@nuton/ui'

export function LessonAuthor({ author }: { author: { name: string; photoUrl?: string } }) {
  return <Avatar size={32} name={author.name} src={author.photoUrl} color="purple" />
}

export function SpaceMembers({ students }: { students: { id: string; name: string }[] }) {
  return (
    <AvatarGroup size={32} max={4} aria-label="Students in this space">
      {students.map((s) => <Avatar key={s.id} name={s.name} />)}
    </AvatarGroup>
  )
}

• The default is 40px, gray. Content comes from the data: src shows the image, name shows initials, and neither shows the placeholder.
• Always pass name when the avatar stands for a person. It names the avatar for screen readers and gives the initials if the image fails.
• Pass a label with every status: topStatusLabel for topStatus, bottomStatusLabel for bottomStatus.
• Give every group an aria-label that says who the people are: “Students in Biology 101”.
• Inside a group, the group's size wins; don't set size on the avatars.

04Variants and sizes

Size, colour and status are props. The content kind (image, solid background, initials or placeholder) isn't a prop: it follows from the data you pass.

Sizes

<Avatar size={80} name="Arthur Taylor" color="blue" />
<Avatar size={72} name="Arthur Taylor" color="blue" />
<Avatar size={64} name="Arthur Taylor" color="blue" />
<Avatar size={56} name="Arthur Taylor" color="blue" />
<Avatar size={48} name="Arthur Taylor" color="blue" />
<Avatar size={40} name="Arthur Taylor" color="blue" /> // default
<Avatar size={32} name="Arthur Taylor" color="blue" />
<Avatar size={24} name="Arthur Taylor" color="blue" />
<Avatar size={20} name="Arthur Taylor" color="blue" />

Measured in the browser; all nine sizes and every group width match Figma exactly. Figma sets initials in remote Poppins styles; code uses the local Nuton Label styles at the same sizes (C22, FC-10).

Content

PreviewCode

SW

Photos and cut-outs

A normal photo fills the circle. A cut-out (transparent background) with solidBackground sits on the colorpalette, like Figma's Solid BG avatars.

PreviewCode

Initials

Initials are the first letter of the first and last word of name, uppercased. They're Unicode-aware, so accented and non-Latin names work. Override them with initials, or call getInitials yourself.

Persona palettes

Figma's 12 personas use six colour pairs. Each is a Foundation /200 background with /950 text.

<Avatar size={48} name="James Brown" color="gray" />
<Avatar size={48} name="Sophia Williams" color="yellow" />
<Avatar size={48} name="Arthur Taylor" color="blue" />
<Avatar size={48} name="Emma Wright" color="sky" />
<Avatar size={48} name="Matthew Johnson" color="purple" />
<Avatar size={48} name="Laura Perez" color="red" />
<Avatar size={48} name="Wei Chen" color="gray" />
<Avatar size={48} name="Lena Müller" color="blue" />
<Avatar size={48} name="Juma Omondi" color="yellow" />
<Avatar size={48} name="Natalia Nowak" color="sky" />
<Avatar size={48} name="Ravi Patel" color="purple" />
<Avatar size={48} name="Nuray Aksoy" color="red" />

Gray initials sit on gray/200, but Figma's gray “Solid BG” uses slate/200. Code follows Figma until design picks one (FC-11). Gray initials use Text/Strong-950, the same value as Figma's static black.

Top status

<Avatar size={56} name="Emma Wright" color="sky" topStatus="verified" topStatusLabel="Verified" />
<Avatar size={56} name="Emma Wright" color="sky" topStatus="pin" topStatusLabel="Pinned" />
<Avatar size={56} name="Emma Wright" color="sky" topStatus="favorite" topStatusLabel="Favourite" />
<Avatar size={56} name="Emma Wright" color="sky" topStatus="add" topStatusLabel="Add" />
<Avatar size={56} name="Emma Wright" color="sky" topStatus="remove" topStatusLabel="Remove" />
<Avatar size={56} name="Emma Wright" color="sky" topStatus="notification" topStatusLabel="New notification" />

Bottom status

<Avatar size={56} name="Ravi Patel" color="purple" bottomStatus="online" bottomStatusLabel="Online" />
<Avatar size={56} name="Ravi Patel" color="purple" bottomStatus="offline" bottomStatusLabel="Offline" />
<Avatar size={56} name="Ravi Patel" color="purple" bottomStatus="busy" bottomStatusLabel="Busy" />
<Avatar size={56} name="Ravi Patel" color="purple" bottomStatus="away" bottomStatusLabel="Away" />
<Avatar
  size={56} name="Ravi Patel" color="purple"
  bottomStatus="company" bottomStatusLabel="Nuton staff"
  companyLogo={<SpaceLogo />} // your own logo element
/>

No brand assets ship in @nuton/ui (C15). Apps pass the logo through companyLogo; the purple building above is an example. Badges can be combined: one top and one bottom status on the same avatar.

Avatar group

Overlapping avatars, each with a 2px white ring, and a “+N” bubble on Weak-50 when there are more people. All nine sizes:

<AvatarGroup size={80} max={4} extra={5} aria-label="Space members">
  <Avatar name="James Brown" color="gray" />
  <Avatar name="Sophia Williams" color="yellow" />
  <Avatar name="Arthur Taylor" color="blue" />
  <Avatar name="Emma Wright" color="sky" />
</AvatarGroup>
// …and the same group at size 72, 64, 56, 48, 40, 32, 24 and 20

“+N” counts the children beyond max plus extra (people you haven't rendered, for example because they aren't loaded). Here each group renders 4 avatars and adds extra={5}, so it shows +5.

Compact avatar group

Avatars and a “+N” count in a white pill. Two appearances, three sizes. By default it shows 3 avatars.

<CompactAvatarGroup size={40} extra={4} aria-label="Reviewers">
  <Avatar name="James Brown" color="gray" />
  <Avatar name="Sophia Williams" color="yellow" />
  <Avatar name="Arthur Taylor" color="blue" />
</CompactAvatarGroup>
// size={32}, size={24}, and the same three with appearance="stroke"

appearance="default" has a shadow only; "stroke" adds a 1px Stroke/Soft-200 border. Measured 1–2px wider than Figma because the count is set in Inter rather than DM Sans (C22). Figma labels the Default variants Size=4 / 3 / 2 and the Stroke variants 40 / 32 / 24, and the frame holding the avatars is named “Buttons” (FC-14).

05States and fallbacks

Avatar isn't interactive, so it has no hover, focus or disabled state. Its states are about content: what shows when an image loads, fails or is missing.

JO

No loading style

06Composition examples

Space members

Add and remove students: the group shows four and counts the rest. The count is also written out as text next to the group.

<AvatarGroup size={32} max={4} aria-label="Students in Biology 101">
  {members.map((s) => <Avatar key={s.id} name={s.name} color={s.color} />)}
</AvatarGroup>
<Button size="sm" appearance="stroke" leadingIcon={<RiUserMinusLine />} onClick={removeStudent}>Remove</Button>
<Button size="sm" appearance="stroke" leadingIcon={<RiUserAddLine />} onClick={addStudent}>Add student</Button>
<p role="status">{members.length} students in Biology 101</p>

Presence with text

Where status matters, write it out. The badge is a quick cue; the text is what everyone can read (C22).

<ul>
  <li>
    <Avatar size={32} name="Lena Müller" color="blue" bottomStatus="online" bottomStatusLabel="Online" />
    <span><span>Lena Müller</span><span>Online</span></span>
  </li>
  <li>
    <Avatar size={32} name="Ravi Patel" color="purple" bottomStatus="busy" bottomStatusLabel="Busy" />
    <span><span>Ravi Patel</span><span>Busy, teaching until 3 pm</span></span>
  </li>
  <li>
    <Avatar size={32} name="Natalia Nowak" color="sky" bottomStatus="away" bottomStatusLabel="Away" />
    <span><span>Natalia Nowak</span><span>Away</span></span>
  </li>
</ul>

Here the screen reader hears the status twice (once in the avatar's name, once in the text). If that's too noisy, drop name and the status label from the avatar so it becomes decorative, and keep the visible text.

Avatar next to a visible name

When the person's name is already on screen, don't name the avatar again. Pass initials (or an image src) without name: with no name the avatar is hidden from assistive tech, and the visible name does the work.

<p className="byline">
  <Avatar size={24} initials={getInitials('Juma Omondi')} color="yellow" />
  Lesson by Juma Omondi
</p>

Reviewers in a lesson card

<CompactAvatarGroup size={32} appearance="stroke" extra={2} aria-label="Reviewers of Photosynthesis basics">
  <Avatar name="Wei Chen" color="gray" />
  <Avatar name="Nuray Aksoy" color="red" />
  <Avatar name="Matthew Johnson" color="purple" />
</CompactAvatarGroup>

Opening a profile

Avatar renders a <span> and isn't focusable. To open a profile, put the avatar and the visible name inside a link, and leave the avatar unnamed so the link isn't announced twice.

<a href="/students/ravi-patel">
  <Avatar size={32} initials="RP" color="purple" />
  Ravi Patel
</a>

07API reference

Avatar props

AvatarGroup props

CompactAvatarGroup props

getInitials

function getInitials(name: string): string
// First letter of the first and last word, uppercased with toLocaleUpperCase.
// Returns '' for an empty or blank name.

Exported types: AvatarProps, AvatarSize, AvatarColor, AvatarTopStatus, AvatarBottomStatus, AvatarGroupProps, CompactAvatarGroupProps, CompactAvatarGroupSize.

Styling hooks

Avatar renders .nu-avatar with data-size, data-color, data-kind (image, text or icon), data-solid and data-in-group. Groups render .nu-avatar-group and .nu-avatar-compact with data-size (and data-appearance). Use props rather than styling these attributes. The component tokens below are the supported override points.

Accessibility

You must: pass name for every person; pass a label with every status; give every group an aria-label; show status as text where it matters.

Figma mapping

Figma binds remote libraries (06-Foundations, 01-Tokens) and remote text styles (Poppins, DM Sans). Code uses the identical local Nuton Foundation colours, State tokens and Label and Paragraph styles; re-binding the Figma file is queued (C22, FC-10).

08Guidelines and related components

Do and don't

Common mistakes

• Setting a status without its label, so screen readers never hear it (a development warning fires).
• Naming the avatar and showing the same name next to it, so screen readers read it twice.
• Leaving moreLabel as the English default in a localised app.
• Shipping Figma's persona photos or a brand logo inside the package (D12, C15). Apps pass their own images.

Related components

• ButtonActions next to a member list, like inviting a student.
• Dropdown menuAccount menus opened from a profile avatar.
• Link buttonLinks to a person’s profile or a full member list.
• ColourThe Foundation hues behind the persona palettes.