Avatar

Server component, no client JS

ImportCopy Anchor Link

import { Avatar, AvatarGroup } from '@nizivo/react/avatar';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/avatar.css';

Static or interactiveCopy Anchor Link

Server. It ships no client JavaScript when a Server Component renders it, in every Next.js build mode; its code is bundled only when a client component (a 'use client' file) imports it. The initials are always in the server HTML and the photo is laid over them with alt="", so in Chromium and Firefox a photo that fails to load shows the initials with no onError handler and no hydration. WebKit (Safari) draws its own broken-image mark over the middle of the initials, and no script-free markup avoids it (D-bf); test/browser/avatar.spec.tsx samples the pixels in all three engines and pins that. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

NamesCopy Anchor Link

The avatar is role="img" named by name; the image inside it has alt="" and the initials are aria-hidden. When the name is printed next to the avatar, pass decorative: the avatar is then aria-hidden. Inside an AvatarGroup every avatar is decorative and the group is one role="img" named by the list of names, joined with Intl.ListFormat in the group's locale.

A photo that fails to load in WebKitCopy Anchor Link

The fallback to the initials needs no script in Chromium and Firefox. WebKit (Safari) is different: when src fails to load it draws its own broken-image mark, a "?" glyph, over the middle of the initials, and nothing script-free avoids it. No CSS can tell a broken image from a loaded one in WebKit; an SVG <image> shows the mark in Chromium and WebKit too, and <object> is blocked by a strict Content Security Policy's object-src (D-bf, kept by the maintainer's decision M42). So:

• pass src (or image) only when the photo is known to load, for example a URL your server has just checked, or one from your own storage;
• when it may be gone, leave src out and the initials render, the same markup in every engine.

ExamplesCopy Anchor Link

GroupCopy Anchor Link

Three faces and a count, read as one item: "Maya Rao, Jonah Okafor, Priya Shah, and 4 more".

MRJOPS+4

Copy Text

import type { JSX } from 'react';
import { Avatar, AvatarGroup } from '@nizivo/react/avatar';

/** A stand-in portrait (an inline SVG), so the example needs no image file. */
const PHOTO =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="#c9b8a6"/>' +
      '<circle cx="32" cy="26" r="12" fill="#8a6f5a"/><rect x="12" y="42" width="40" height="30" rx="20" fill="#8a6f5a"/></svg>',
  );

/** A photo, the initials fallback at every size, and a decorative avatar next to a printed name. */
export function AvatarExample(): JSX.Element {
  return (
    <div>
      <Avatar name="Maya Rao" src={PHOTO} size="lg" />
      <Avatar name="Jonah Okafor" size="sm" />
      <Avatar name="Jonah Okafor" />
      <Avatar name="Jonah Okafor" size="lg" />
      <Avatar name="Jonah Okafor" size="xl" />
      <p>
        <Avatar name="Priya Shah" decorative /> Priya Shah
      </p>
    </div>
  );
}

export function AvatarGroupExample(): JSX.Element {
  return (
    <AvatarGroup total={7}>
      <Avatar name="Maya Rao" src={PHOTO} />
      <Avatar name="Jonah Okafor" />
      <Avatar name="Priya Shah" src={PHOTO} />
    </AvatarGroup>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

AvatarGroupLabels type

import type { AvatarGroupLabels } from '@nizivo/react/avatar'

AvatarGroup's own strings (§16.4): serialisable, English defaults. {count} is replaced by the formatted count, and a PluralLabel ({ one, few, many, other }, the locale's CLDR categories) picks its template by that count through formatLabel.

Name	Type	Default	Description
morerequired	string | PluralLabel	'{count} more'	The count's words in the group's accessible name ("Maya, Jonah, Priya and 4 more").
overflowrequired	string | PluralLabel	'+{count}'	The visible count after the shown avatars.

AvatarGroupProps type

import type { AvatarGroupProps } from '@nizivo/react/avatar'

The props of AvatarGroup, listed above.

AvatarGroupState type

import type { AvatarGroupState } from '@nizivo/react/avatar'

The render state of AvatarGroup, listed above.

AvatarProps type

import type { AvatarProps } from '@nizivo/react/avatar'

The props of Avatar, listed above.

AvatarSize type

import type { AvatarSize } from '@nizivo/react/avatar'

Figma "Size": Sm 24, Md 32, Lg 40, XL 56 px.

type AvatarSize = "sm" | "md" | "lg" | "xl"

AvatarState type

import type { AvatarState } from '@nizivo/react/avatar'

The render state of Avatar, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-avatar, .nz-avatar-group, .nz-avatar-group-more, .nz-avatar-image, .nz-avatar-initials.

AccessibilityCopy Anchor Link

Nothing in this component takes focus or keyboard input.

KeyboardCopy Anchor Link

None.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7370:21, Figma node 7370:26
• Ghost masters: none