Avatar

A person as a round badge of initials, or their photo.

Overview

Marking who did something or who owns something, next to their name.

Identity

Do
import { Avatar, Cluster } from "@hackcove/ui";

<Cluster>
  <Avatar name="Ada Lovelace" />
  <Avatar name="Ada Lovelace" size="lg" />
  <Avatar name="Grace Hopper" />
</Cluster>
Give the person's full name every time: the same name gets the same colour and initials in every list and header.
Don't
import { Avatar, Cluster } from "@hackcove/ui";

<Cluster>
  <Avatar name="Ada" />
  <Avatar name="A. Lovelace" />
</Cluster>
The colour comes from the name, so "Ada" in one place and "A. Lovelace" in another read as two different people.

Beside

Do
Ada Lovelace
import { Avatar, BodyStrong, Cluster } from "@hackcove/ui";

<Cluster>
  <Avatar name="Ada Lovelace" />
  <BodyStrong>Ada Lovelace</BodyStrong>
</Cluster>
The initials are hidden from a screen reader, so the person's name sits beside the Avatar as text.
Don't
import { Avatar } from "@hackcove/ui";

<Avatar name="Ada Lovelace" />
An initials Avatar on its own is aria-hidden: it names no one to a screen reader. Put the name beside it.

Usage

  • Pass the person's full name, the same string everywhere: the colour and the initials are worked out from it, so one person looks the same in every list and header.
  • size is sm, md (default), lg, xl or 2xl; use sm or md in a row and a larger one at the head of a profile.
  • src is the person's photo, as a path your app serves. It replaces the initials, and the Avatar never loads an image from another server on its own, so use your own local image.
  • ring is for a stack of overlapping Avatars: each one overlaps the one before it, with a ring in the page colour. Leave it off a single Avatar.
  • Put the person's name beside the Avatar as text; the Avatar is a mark, not a label.

Accessibility

  • Initials are drawn in a <span> with aria-hidden="true" and a title of the name, so a screen reader skips them: the name has to be on the page as text.
  • With src the Avatar is an <img> whose alt and title are the name.
  • aria-* and data-* props go on the root element.

API

Avatar

A person as a round badge of initials, or as their photo when src is given. It never loads a remote image on its own: that is a request to another server for decoration, and it makes a screenshot depend on the network. src is the app's own local path.

name required
Type
string
ring

A ring in the page colour, for a stack of overlapping avatars.

Type
boolean
Default
false
size
Type
"sm" | "md" | "lg" | "xl" | "2xl"
Default
md
src

The person's photo, a local path. It replaces the initials and is announced as name.

Type
string

Functions

  • initialsOf The up to two letters or digits of a name, upper-cased, or ? when it has none: the same initials Avatar draws, for where you need them as text.
  • avatarColourClass The background class Avatar picks for a name, so the same name always gets the same colour. Avatar applies it for you; pass name to Avatar instead of using it.