BridgeComfortable

Previews use

Applies to every design system preview on the site. The Bridge app chrome stays the same.

Brand

Density

Avatar

Stable
Edit in Studio

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

Updated Oct 16, 2026

Rendered with the real component
Light
Dark

When to use

Use it for

  • Owners, reviewers and authors next to tokens, components and pull requests.
  • 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.

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.

Don't

Ten avatars in a row

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

Accessibility

  • role img with the full name as its label; initials are hidden from screen readers so they do not spell letters.
  • 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 (Base UI Avatar).
  • AvatarGroup is a named group; the +N counter is announced as "3 more: names".

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.

16 tokens 5 semantic or component, change with theme and brand 11 from the shared scales

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.

Prop Type Default Description
name required string none Full name. Used for the initials fallback and as the accessible name.
src string none Image URL. While it loads or if it fails, the initials show instead.
size 'xs' | 'sm' | 'md' | 'lg' 'md' xs 20, sm 24, md 32, lg 40. Default `md`.
decorative boolean false Hide from assistive tech when the name is already written next to the avatar.

Comes with initials, 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. 

<Avatar name="Florian Gouloubi" />
size

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 (5)

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

Group

AllStates

Changelog

  • 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. Adds avatar, tag, kbd, divider and accordion component tokens.

    Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026

All release notes