BridgeHandbookDraft
For agents
Menu
ExperimentalatomData display

Avatar

A person's photo or initials, a member or Super Connector badge, and stacks of faces.

import { … } from "@brdgapp/ui/components/avatar"

Usage

Avatar is a person's photo in a circle, or their initials on light blue when there's no photo, with an optional corner badge for a Bridge member, a Super Connector, or an account that needs attention. AvatarGroup stacks a few faces and counts the rest. Pass names and photo URLs; the component works out the initials, shows them while a photo loads, and keeps them if it fails. The usual mistake is drawing the circle, the badge or the stack by hand: the Bridge apps do it in over 100 places.

When to use

  • Next to a person's name in rows, lists, feeds, cards and drawers.
  • With a badge, wherever it matters who is a Bridge member or a Super Connector, or that someone's account can't receive intros.
  • AvatarGroup for several people in a small space: who can introduce you, who was in a meeting, a deal's contacts.
  • On its own, as the button that opens your account menu (set standalone).

When not to use

  • For a company or network. Those use the organization's logo in a rounded square, not a circle.
  • As a loading placeholder. Use Skeleton's circle, at the avatar's size. Use Skeleton instead.
  • For a long list of people. AvatarGroup shows a few faces; a list of names belongs in a list or a drawer.

The look comes from props

A component's appearance comes only from its own options (variant, size, color). className on a package component is for layout (mt-4, shrink-0, w-full), never for font size, color, padding, radius or hover. If the look needs a className, the component or the chosen option is wrong: fix that instead.

Anatomy

Bridge member

  1. Circle. One of six sizes. Light blue (--info-bg) shows through until a photo covers it.

  2. Photo or initials. The photo, cropped to fill. With no photo, while it loads, or if it fails: one or two bold letters in blue (--info), from the first and last word of the name.

  3. Badge. Optional, bottom right, ringed in the page color: a blue tick, a purple award or an amber “!”. Not shown at 16px.

Examples

Next to a name

The usual place. Screen readers hear the name once, then the badge.

  • Super Connector

    Marcus Bell

    General Partner, Lanternfield Capital · Super Connector

  • Bridge member

    Leah Okonkwo

    Partner, Saltmarsh Partners · Bridge member

  • Bridge member

    Priya Natarajan

    Co-founder & CEO, Quillbase · Bridge member

  • Kwame Asante

    CEO, Halcyra Bio · Not on Bridge

  • Account needs attention

    Hannah Weiss

    Angel investor · Emails to her are failing

Badges

A Bridge member, a Super Connector (the award replaces the tick), and an account whose emails are failing.

Bridge member
memberBridge member
Super Connector
super-connectorSuper Connector
Account needs attention
warningNeeds attention

A stack of people

Three faces, then a count. When the names are written beside it, the stack stays silent for screen readers.

+4

7 people can introduce you

to Quillbase

Marcus Bell, Leah Okonkwo

Sizes

Pick the size for the place, never by eye. No badge at 16px.

Bridge member
xs16px · Chips
Bridge member
sm24px · Stacks
Bridge member
md32px · Lists
Bridge member
lg40px · Rows
Bridge member
xl48px · Cards
Bridge member
2xl64px · Profiles

Photo or initials

With no photo, or a photo that fails to load, the initials show. Nothing is ever blank or broken.

Photo
No photo
Photo failed
No name

States

StateWhat happens
PhotoThe photo fills the circle.
LoadingInitials show until the photo arrives, so nothing is ever blank.
No photoInitials on light blue.
Photo failedInitials stay. A broken image never shows.

Behavior

  • Initials come from the first and last word: “Priya Natarajan” is PN, “Mei Lin Zhou” is MZ, a single word gives one letter, and no name gives “?”.
  • Sizes: xs 16px in chips, sm 24px in stacks, md 32px in lists (the default), lg 40px in rows, xl 48px on cards, 2xl 64px in profile headers.
  • Badges: member is a blue tick for a Bridge member. super-connector is a purple award and replaces the tick, since every Super Connector is a member. warning is an amber “!” when the account is deactivated or its emails are failing.
  • AvatarGroup shows the first 3 faces (max) at 24px, each tucked a little under the one before, then a grey “+N” circle for the rest.
  • className is for layout only (mt-0.5). Never a size, color or shape.

Do and don't

Do

Pass the person's name, photo URL and badge, and let Avatar handle the rest.

Don't

Write your own initials(), a styled <span>, or an absolutely placed tick.

Do

Use one badge: the award for a Super Connector, the tick for any other member.

Don't

Show both the tick and the award on the same person.

Do

Pick the size for the place: sm in a stack, md in a list, xl on a card.

Don't

Set size-10 or h-11 w-11 by eye.

Content

  • No text of its own. The name next to it says who it is; the badge says what they are.

Accessibility

  • Next to a name, the picture is hidden from screen readers so the name isn't read twice. A badge is still read: “Bridge member”, “Super Connector”, “Account needs attention”.
  • On its own, set standalone: it's read as the name and badge, like “Leah Okonkwo, Bridge member”.
  • AvatarGroup is read as the names: “Leah Okonkwo, Priya Natarajan, Mei Lin Zhou and 4 others”. Set decorative when the names are written beside it.
  • The initials are --info on --info-bg: 7.6:1 in light, above 5:1 on every dark surface. Each badge's white mark passes 3:1 in both themes.

API reference

Avatar

A person's photo or initials, with an optional badge.

PropTypeDefaultDescription
namestring | null—The person's name. Gives the initials, and the spoken name when standalone.
srcstring | null—Photo URL. Empty shows the initials.
size"xs" | "sm" | "md" | "lg" | "xl" | "2xl""md"16, 24, 32, 40, 48 or 64px.
badge"member" | "super-connector" | "warning" | null—The corner mark. Not shown at xs.
standalonebooleanfalseSet when no name shows next to it, so screen readers hear who it is.
classNamestring—Layout only: mt-0.5.

AvatarGroup

A few faces, overlapping, then “+N”.

PropTypeDefaultDescription
people{ name, src? }[]—Everyone in the group, in order. The first ones show.
maxnumber3How many faces show before “+N”.
sizesame as Avatar"sm"Stacks are usually 24px.
decorativebooleanfalseSet when the names are written next to the stack.
classNamestring—Layout only.

initialsOf

The same initials as text, for places that need the letters without the circle.

PropTypeDefaultDescription
namestring | null—“Priya Natarajan” gives “PN”.

Lineage

What it's built from and where it's used, read from the code. When you change it, check these too.

Built from
Nothing else in the package
Used by components
None
Used in patterns
None
Used in templates
FeedTable page