Tag
StableA compact label for a value. Static to describe, toggleable as a filter chip, or removable to show selected values.
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.
Put filter chips in a named group
role group with aria-label ("Filter by theme") tells screen reader users what the chips control.
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.
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.
- Container
.tag - Size sm
.sm - Signal tone
.signal - Static label
.label, .toggle - Toggle button, focus
.toggle:focus-visible, .remove:focus-visible - toggleable, hover
@media (hover: hover) .toggleable:not([data-disabled]):hover - toggleable
.toggleable:has(.toggle[data-pressed]) - removable
.removable .label, .removable .toggle - Remove button
.remove - Remove button, hover + disabled
@media (hover: hover) .remove:not(:disabled):hover - Container
.tag[data-disabled]
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.
| Prop | Type | Default | Description |
|---|---|---|---|
children required | ReactNode | none | The 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`. |
icon | LucideIcon | none | Leading Lucide icon. |
selected | boolean | none | Makes the tag a toggle (filter chip). Controlled pressed state, announced with aria-pressed. |
defaultSelected | boolean | none | Uncontrolled initial selected state for a toggle tag. |
onSelectedChange | (selected: boolean) => void | none | Called when a toggle tag is pressed. Passing it makes the tag interactive. |
onRemove | () => void | none | Adds a remove button. Called when it is pressed. |
removeLabel | string | none | Accessible name of the remove button, without the verb. Defaults to the tag text when it is a string. |
disabled | boolean | false | No 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.
<Tag>color.action</Tag>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
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