Skip to Content
BBRICKSv0.7.4
KitPrimitives

Avatar

A photo (alt empty: the name sits beside it) or initials. Decorative either way.

import { Avatar } from '@ergasti/bricks';

Examples

Initials and sizes

With no picture an avatar draws the name's initials on a tone chosen by seed, so the same person keeps the same colour.

Code
import { Avatar } from '@ergasti/bricks';

function Sizes() {
  return (
    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
      <Avatar name="Laila Saeed" seed={0} size="sm" />
      <Avatar name="Karim Hosny" seed={1} />
      <Avatar name="Salma Hosny" seed={2} size="lg" />
      <Avatar name="سارة علي" seed={3} size="lg" />
    </div>
  );
}

Pictures

src replaces the initials; if the picture fails to load the initials come back.

Code
import { Avatar } from '@ergasti/bricks';
import { blocksData } from './sample-data';

function Pictures() {
  return (
    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
      <Avatar name="Laila Saeed" seed={0} size="lg" src={blocksData.photo(0)} />
      <Avatar name="Broken link" seed={1} size="lg" src="data:image/png;base64,AAAA" />
    </div>
  );
}

Avatar stack

Overlapping avatars with a "+N" count past max; total counts people beyond the faces you have (5 sent, 12 in the group: "+8"); more={false} draws the faces only, where a count is said nearby.

Code
import { AvatarStack } from '@ergasti/bricks';
import { blocksData } from './sample-data';

function Stack() {
  const people = ['Laila Saeed', 'Karim Hosny', 'Salma Hosny', 'Mariam Adel', 'Youssef Saeed', 'Hana Hosny', 'Ali Hosny'].map((name, id) => ({ id, name, avatarUrl: blocksData.photo(id) }));
  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <AvatarStack people={people} />
      <AvatarStack people={people} max={3} />
      <AvatarStack people={people.slice(0, 5)} total={12} />
      <AvatarStack people={people} max={3} more={false} />
    </div>
  );
}

Props

Prop

Type

Design guidance

How the BRICKS design system uses Avatar. Written in docs/content/components/Avatar.md; the props above are read from the code, which wins where the two disagree.

A round person avatar showing a photo or, when there is none, the name's initials on a colour picked from a stable seed; use it beside a person's name in cells, cards and menus.

Avatar is the mock's .av: a circle with Jakarta 800 initials on one of five pastel tone pairs (raspberry, lime, butter, sky, lilac). The same seed (usually the row id) always gets the same pair, so a creator keeps their colour across the dashboard. A photo covers the initials when it loads and falls back to them when it fails. It is always decorative: the name next to it is the accessible text.

Anatomy

  1. Circle (span.kit-av, aria-hidden): background and ink from the tone pair.
  2. Initials: first letter of the first and last word, upper-cased; Arabic initials joined by a zero-width non-joiner so they never fuse.
  3. Photo (img.kit-av-img, optional): alt="", lazy, object-fit: cover, absolutely over the initials.

Variants

sizeLookWhen
'sm'30px, 11px initialsDense rows, menus
'md' (default)38px, 13pxTable cells (PersonCell, CreatorCell)
'lg'62px, 19px, 4px card-coloured ringCreator cards, drawer heads

Tone pair by seed % 5: 0 --rasp-50/--rasp-d, 1 --lime-50/--olive, 2 --butter/--butter-ink, 3 --sky/--sky-ink, 4 --lilac/--lilac-ink. Inside an AvatarStack it draws at 34px with a 2px ring.

States

StateTriggerLook
Initialsno srcLetters on the tone
Photosrc loadsPhoto fills the circle
Broken photosrc fails (onError)Falls back to initials for that src; a new src is tried again
Single word name"Nour"One initial
Empty name""Coloured circle only

Types

Helper exported alongside: initials(name).

Usage

<Avatar name="Laila Saeed" seed={1042} />

In a table cell with the name beside it (what PersonCell does for you):

const creator = { id: 1042, name: 'Laila Saeed', handle: 'laila.saeed', avatarUrl: null };

<span style={{ display: 'flex', gap: 10, alignItems: 'center' }}>
  <Avatar name={creator.name} seed={creator.id} src={creator.avatarUrl} />
  <span><b>{creator.name}</b><br /><span className="kit-sub">@{creator.handle}</span></span>
</span>

A creator card head:

<Avatar name="سارة علي" seed={2} size="lg" src="https://cdn.example.com/creators/2.jpg" />

Where it appears

  • Brand › Creators › My creators table and Find creators cards (via CreatorCell / FindCreatorCard).
  • Brand › Home › Top creators this month; Brand › Motivation › leaderboards.
  • PR Portal › Creators table, Approvals queue, Audit log, Tiers moves, creator drawer head.
  • Sidebar user block. Screens: Creators, Home, PR · Creators, PR · Approvals.

Guidelines

Do

  • Pass the person's id as seed so the colour never changes between screens.
  • Always render the name as text next to it.
  • Use size="lg" only in card or drawer heads.

Don't

  • Don't use it for brands (use BrandAvatar) or products (use ProductThumb).
  • Don't pass a random or index seed in sortable lists: the colours would shuffle.

RTL and Arabic

  • Arabic initials are taken from the Arabic letters and separated by a zero-width non-joiner (U+200C).
  • Nothing to mirror.

Tokens

--rasp-50, --rasp-d, --lime-50, --olive, --butter, --butter-ink, --sky, --sky-ink, --lilac, --lilac-ink (tone pairs), --card (lg ring), --font-family-display.

Accessibility

  • aria-hidden and alt="": the adjacent name is the accessible text, so a screen reader never hears the name twice.
  • Initials meet contrast on each tone pair (ink on 50-tint).
  • Not focusable.

Found in the source

  • ARIA attributes set: aria-hidden.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Button · ButtonLink · CouponChip

Source

src/kit/primitives/Avatar.tsx (line 34) on GitHub.

On this page