A person, merchant or bank as an image, with initials while it loads or if it fails.

Sizes and shapes

sm, md and lg are 24, 32 and 40px, with initials at 12, 14 and 16px. The small one is bolder, because 12px is the floor for short uppercase text.

  • circle: a person. It takes the pill radius.
  • square: a merchant's or a bank's logo, so it reads as a tile and not a face. It takes the micro radius.

Both follow the shape axis. A 1px ring edges the box, so a white logo on a white card keeps its edge.

Example

Follows the page theme and corners
import { Avatar } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { LOGO, PORTRAIT } from './avatar-images';

export default function AvatarSizes(): ReactElement {
  return (
    <div className="stack" style={{ justifyItems: 'center' }}>
      <div className="row">
        <Avatar name="Ada Lovelace" src={PORTRAIT} size="sm" />
        <Avatar name="Ada Lovelace" src={PORTRAIT} />
        <Avatar name="Ada Lovelace" src={PORTRAIT} size="lg" />
      </div>
      <div className="row">
        <Avatar name="Northwind" src={LOGO} shape="square" size="sm" />
        <Avatar name="Northwind" src={LOGO} shape="square" />
        <Avatar name="Northwind" src={LOGO} shape="square" size="lg" />
      </div>
    </div>
  );
}

Initials

With no image, or while it loads, or if it fails, the avatar shows the first character of the first two words of name: Grace Hopper is GH and Northwind is N. Pass initials to set them yourself, such as WF for a bank. A failed image is removed, leaving the initials under it, so the box never moves and no broken-image icon shows.

The fallback is one neutral look for everyone: bone with ink initials. There is no color per name, because the name already identifies the person, and such a palette would need colors the system does not have.

Example

Follows the page theme and corners
import { Avatar } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { BROKEN } from './avatar-images';

export default function AvatarFallback(): ReactElement {
  return (
    <div className="row" style={{ justifyContent: 'center' }}>
      <Avatar name="Grace Hopper" size="lg" />
      <Avatar name="Northwind" size="lg" shape="square" />
      <Avatar name="Willowford Bank" initials="WF" size="lg" shape="square" />
      {/* The image fails, so the initials it covered stay. */}
      <Avatar name="Mary Ann Evans" src={BROKEN} size="lg" />
    </div>
  );
}

Beside a name

When the name is in the text beside the avatar, pass isDecorative. The avatar is then hidden from assistive technology, so the row is read once.

Example

Ada Lovelace
Follows the page theme and corners
import { Avatar } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { PORTRAIT } from './avatar-images';

export default function AvatarBesideName(): ReactElement {
  return (
    <div className="row" style={{ justifyContent: 'center' }}>
      {/* The name is in the text beside it, so the avatar is decorative and the row is read once. */}
      <Avatar name="Ada Lovelace" src={PORTRAIT} isDecorative />
      <span>Ada Lovelace</span>
    </div>
  );
}

Usage

name is required. It gives the initials and, unless the avatar is decorative, the accessible name. Serve the image from your own origin. Avatar is a client component for one piece of state: whether the image failed. The image stays hidden until it is known to have loaded, so a page shows the initials until it hydrates.

import { Avatar } from '@snapshot-ui/react';

<Avatar name="Ada Lovelace" src="/people/ada.png" size="lg" />
<Avatar name="Northwind" src="/logos/northwind.svg" shape="square" />

Props

An Avatar accepts every attribute of an HTML element.

className
string

initials
string

Replaces the initials from name, such as "WF" for a bank. One or two characters. Blank uses name's.

isDecorative
boolean

The name is already beside it in text, so the avatar is hidden from assistive technology.

Default: false

name
string

The person's or the organization's name. Gives the initials and, unless isDecorative, the accessible name.

shape
"circle" | "square"

circle for a person, square for a merchant's or a bank's logo.

Default: 'circle'

size
"lg" | "md" | "sm"

Default: 'md'

src
string

The image. When absent, or when it fails to load, the initials show.

Accessibility

An avatar is an image named by name. The initials and the image inside it are hidden, so it is read once by its name, never as letters. With isDecorative, the whole avatar is hidden. It takes no focus and has no keys.

Design rules

What keeps avatars in the system.

Use a square for a merchant or a bank, and a circle for a person.

Pass isDecorative when the name is beside the avatar in text.

Serve the image from your own origin.

Never give each name a color of its own. The fallback is one neutral look for everyone.

Never make the initials the only name. The name is the accessible name, or it is in the text beside the avatar.

Never draw more than two initials.

esc
↑ ↓ to move↵ to open