You're in the Library

Tag

A compact label for a value. Static to describe, toggleable as a filter chip, or removable to show selected values.
Stable
Edit

Preview appears after the next Storybook update.

Tag example
<Tag>color.action</Tag>
Rendered with the real componentFrom the code
Light
Dark

When to use

Use it for

  • Filter chips above a table or a list: toggle tags in a labelled group.
  • Selected values in a multi-select Combobox or a filter bar: removable tags.
  • Static metadata: token groups, platforms, component categories.

Not for

  • Status (Published, Failed): use Badge.
  • Actions: use Button. A tag describes a value; it does not do something.
  • Choosing one option out of several: use RadioGroup or Tabs.

Do and don't

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

Do

Put filter chips in a named group

role group with aria-label ("Filter by theme") tells screen reader users what the chips control.

Tokens that changed since the last release
Don't

Sentences in tags

Tags truncate. Keep them to a value of one to three words.

Accessibility

  • Toggle tags are Base UI Toggle buttons with aria-pressed; selected also shows a check icon, so selection is not color alone.
  • The remove button is a separate button named "Remove <label>" (removeLabel when the text is not a plain string).
  • Both buttons have the focus ring and are reachable with Tab; Enter and Space activate them.
  • Static tags are plain text with no role.

Content guidelines

  • Values as they appear elsewhere in the product: token paths in lowercase, names in sentence case.
  • After removing a tag, move focus to the next tag or back to the input.

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

Anatomy and tokens

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

28 tokens18 semantic or component, change with theme and brand10 from the shared scales

Motion and interaction

Tag has motion in code that this page cannot list yet: try it in the preview.

With reduced motion turned on, its changes happen at once.

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

Props

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

PropTypeDefaultDescription
childrenrequiredReactNodenoneThe tag text: a filter value, a token group, a component name.
tone'neutral' | 'signal''neutral'`signal` marks a tag that matches the current search or filter. Default `neutral`.
iconLucideIconnoneLeading Lucide icon.
selectedbooleannoneMakes the tag a toggle (filter chip). Controlled pressed state, announced with aria-pressed.
defaultSelectedbooleannoneUncontrolled initial selected state for a toggle tag.
onSelectedChange(selected: boolean) => voidnoneCalled when a toggle tag is pressed. Passing it makes the tag interactive.
onRemove() => voidnoneAdds a remove button. Called when it is pressed.
removeLabelstringnoneAccessible name of the remove button, without the verb. Defaults to the tag text when it is a string.
disabledbooleanfalseNo description in the code yet.
size'sm' | 'md''md'No description in the code yet.

Playground

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

Code for these props
<Tag>color.action</Tag>

tone

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 Tag 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.

Static

Removable

Toggle

FilterChips

AllStates

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

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

    v1.0.0, Nov 11, 2026

  • Fix

    Studio consistency: one count, one verb, one meaning per tag colour

    v1.0.0, Nov 11, 2026

  • Fix

    A drafted summary that names a token (tag.bg) keeps its sentences: a dot inside a token path is not a sentence end

    v1.0.0, Nov 11, 2026

  • Fix

    Adds the generated component-specs.json (run npm run specs) for Button, IconButton, Badge, Tag, Input and Card, read by the DS Bridge Figma plugin to pull them as component sets

    v1.0.0, Nov 11, 2026

  • Fix

    Exploration page, "What this changes in the library": each piece is one header line (kind tile, name, one tag, origin), a new component shows the piece as built with one "Add Timeline to the library" tick, and a change to a component part reads like the component's own options ("Padding: Comfortable", 20 px, +4 px) with the new values to tick, the ones already in the library under them, Rename, and a button that names the outcome

    v1.0.0, Nov 11, 2026

  • Fix

    Library review List: a piece's tag sits next to its name, and the name and its kind sit closer

    v1.0.0, Nov 11, 2026

  • Fix

    Studio polish: the lead's zone asks the library question first (1 of 2); Library review says its count in words, drops the shortcut hints and the shared-decision line, and shows the list and the piece as two cards with each piece in its own card and a list that scrolls on its own; the home's Oldest tag and the folder tiles' Captured tag keep their size and edge

    v1.0.0, Nov 11, 2026

  • Fix

    One Bridge account per Gmail mailbox: emails are keyed by their canonical spelling (lower case; for gmail.com and googlemail.com without dots or a "+tag"), so either spelling signs in to the same account

    v1.0.0, Nov 11, 2026

  • Fix

    An archived exploration keeps its page: the preview and activity, an Archived tag, one line and Unarchive, with no GitHub links

    v1.0.0, Nov 11, 2026

  • Fix

    Being built: no "Exploration" tag on rows (every change starts as an exploration); the row's line already says where it comes from

    v1.0.0, Nov 11, 2026

  • Fix

    After Done exploring, an exploration keeps the page it had while it ran: the status tag (Waiting for code, Being built, Shipped), who said done and when, the preview, what happens next in three steps, what the library gets from it, and the activity

    v1.0.0, Nov 11, 2026

  • Fix

    Team Libraries are noindex on the server: every /library/<owner>/<repo>/ address answers X-Robots-Tag: noindex, except the teams in the committed allow-list hosted/public-libraries.json

    v1.0.0, Nov 11, 2026

  • Fix

    Studio Components: the "Used in" column shows one tag per product instead of a sentence

    v1.0.0, Nov 11, 2026

All release notes

Updated Nov 11, 2026
View source

Generated from 4 files