You're in the Library

Avatar

A person, a team or Claude, shown as a photo with an initials or illustrated fallback. AvatarGroup stacks several and collapses the rest into a +N counter.
Stable
Edit

Preview appears after the next Storybook update.

Avatar example
<Avatar />
Rendered with the real componentFrom the code
Light
Dark

When to use

Use it for

  • Owners, reviewers and authors next to tokens, components and changes.
  • fallback="illustrated" when most people have no photo: a drawn face from their login tells rows apart faster than two letters. Import Avatar from @bridge-ds/react/avatar-illustrated (the drawings are a separate entry, about 120 kB gzipped).
  • kind="agent" brand="claude" for work Claude did (a drafted text, a change it opened): the Bridge agent mark (the Field Guide robot: a rounded head with an antenna, dot eyes and a smile) on a rounded square tile, named "Claude AI", so people see at a glance it is not a person.
  • mark only to show a vendor logo you have the brand owner's approval to use: Bridge ships its own agent mark because company logos are trademarks that need their owner's approval.
  • AvatarGroup for the reviewers of a change; set max so the row never wraps.

Not for

  • As the only way to identify someone in a table: write the name too.
  • For product or brand logos: use an image with its own alt text. The agent preset only attributes an agent's actions.
  • To make up a face for someone who has a photo: the illustration is a fallback, the photo wins.

Do and don't

Every example is rendered with the real component, so it always matches what ships.

Kenji Sato
Do

Name next to the avatar in lists

Faces are hard to tell apart at 24px. Mark the avatar decorative when the name is right beside it.

Maya Okafor
Do

Seed with something stable

Seed the illustrated face with the login, not the display name: people rename themselves, their face should stay.

Don't

Ten avatars in a row

Past four or five faces nobody counts. Let the +N counter carry the rest.

Don't

Claude dressed as a person

Do not give Claude a drawn face or initials. Use the agent preset so nobody mistakes its work for a teammate's.

Accessibility

  • role img with the full name as its label; initials and drawings are hidden from screen readers so they do not spell letters or describe a face.
  • The Claude preset is named "Claude AI"; its mark (the Bridge robot or a custom mark) is decorative inside it.
  • The robot is one stroke in currentColor with no fill, so it keeps the tile's checked contrast in light and dark, and still reads at the xs size (16px mark).
  • decorative removes it from the accessibility tree when the name is already written next to it.
  • The image has an empty alt: the name is on the container. Broken images fall back to initials or the drawing (Base UI Avatar).
  • AvatarGroup is a named group; the +N counter is announced as "3 more: names".

Content guidelines

  • Pass the full display name; initials are computed from the first and last words.
  • Seed illustrated faces with the login so the same person always gets the same face.
  • Name groups by role: "Reviewers", "Owners".

From the code Generated from the component, not editable here.

Anatomy and tokens

Read from packages/react/src/components/Avatar/Avatar.module.css at build time. Every value is a token: open one to see its alias chain in both themes.

24 tokens10 semantic or component, change with theme and brand14 from the shared scales

Motion and interaction

Avatar does not animate: its states change at once.

From the code Generated from the component, not editable here.

Props

Parsed from the TypeScript types in packages/react/src/components/Avatar/Avatar.tsx, so this table cannot drift from the code. It also accepts every native <span> attribute.

PropTypeDefaultDescription
namestringnoneFull name. Used for the initials fallback and as the accessible name. Optional for an agent preset.
srcstringnoneImage URL. While it loads or if it fails, the fallback shows instead.
size'xs' | 'sm' | 'md' | 'lg''md'xs 20, sm 24, md 32, lg 40. Default `md`.
decorativebooleanfalseHide from assistive tech when the name is already written next to the avatar.
fallback'initials' | 'illustrated''initials'`initials` (default) or `illustrated`: a drawn face that is always the same for the same seed. The drawing comes from `illustration`; the Avatar exported by `@bridge-ds/react/avatar-illustrated` fills it from the seed for you.
seedstringnoneWhat the illustrated face is drawn from, for example a login. Default: the name.
illustrationstringnoneImage (URL or data URI) of the illustrated face. Without it, `fallback="illustrated"` shows initials.
kind'person' | 'agent'none`person` (default), or `agent`: an AI acting in the product, so people can tell its work from a person's.
brand'claude'noneWith `kind="agent"`: `claude` names the agent "Claude AI" and shows the Bridge agent mark, the Field Guide robot, on its tile.
markReactNodenoneWith `kind="agent"`: replaces the Bridge agent mark (the Field Guide robot), for example with a vendor logo (an SVG that fills its box). Only for a logo you have the brand owner's approval to use. Decorative: the name stays the accessible name.

Comes with initials, avatarName, each accepting native <div> attributes.

Playground

Change the props and see the real Avatar update. Controls are generated from the TypeScript props; nothing here changes the system.

Code for these props
<Avatar name="Florian Gouloubi" kind="person" />

size

fallback

kind

Workbench

For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Avatar in Storybook).

Embed Storybook stories here (7)

Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.

Initials

Image

BrokenImage

Illustrated

Agent

Group

AllStates

From the code Generated from the component, not editable here.

Changelog

  • New

    Avatar agent: Bridge now draws its own agent mark (a prompt chevron and cursor line, Deep Harbor on a Harbor rounded square tile) instead of shipping the Claude logo, which is an Anthropic trademark

    v1.0.0, Nov 11, 2026

  • New

    The agent mark of Avatar kind="agent" (and avatarHtml({ kind: 'agent' })) is now the Field Guide robot from the landing page: a rounded head with an antenna, two dot eyes, a smile, side ears and two legs, drawn as one round-cap stroke in currentColor with no fill, so it keeps the tile contrast in light and dark and reads at the xs size (16px mark)

    v1.0.0, Nov 11, 2026

  • New

    Avatar: illustrated faces and Claude's identity

    v1.0.0, Nov 11, 2026

  • New

    Data display: Card restyled as a flat plate with an interactive option and padding sizes; Badge gains appearance (subtle, now the default, or solid), a dot, icons and sizes (existing solid badges must pass appearance="solid" to keep their look); new Avatar and AvatarGroup, Table (sortable headers with aria-sort, selectable rows, sticky header, focusable scroll region, useTableSort), Accordion, Tag (removable, toggleable), Divider and Kbd

    v1.0.0, Nov 11, 2026

  • Fix

    Skeleton docs: the preview shows an avatar, two text lines and a block (it rendered at zero width)

    v1.0.0, Nov 11, 2026

  • Fix

    The count of changed elements no longer reads like "This change": the bar says "13 changed", then "2 / 13 changed" while stepping, and screen readers hear "Changed element 2 of 13: Avatar" (also with changes tried together)

    v1.0.0, Nov 11, 2026

  • Fix

    One face per email member everywhere: the account menu, the header, Members, the invite dialog, exploration cards and rows, the review page and an exploration's activity all draw the face of the member's name (~name), never their email, a row index, the Bridge app's avatar or a GitHub account that happens to share their name

    v1.0.0, Nov 11, 2026

  • Fix

    Homepage closing: the profile card the walkers carry is now a DS Card with a DS Avatar and a full-width "Connect on LinkedIn" button

    v1.0.0, Nov 11, 2026

  • Fix

    Homepage, design system lead section: Dana's avatar stroke is Deep Harbor

    v1.0.0, Nov 11, 2026

  • Fix

    Homepage, design system lead section: Dana's avatar has a white stroke instead of a drop shadow

    v1.0.0, Nov 11, 2026

  • Fix

    Component pages: the On this page rail sits on the right from the top of the page (from 1320px) instead of inside the reading column, and the Skeleton preview shows an avatar, two lines and a block

    v1.0.0, Nov 11, 2026

All release notes

Updated Nov 11, 2026
View source

Generated from 4 files