CatalystTagv1.1.4Ready for Production
A compact label component for categorization, status indication, and content organization with support for icons and remove buttons.
Prefer AI-assisted development?
Catalyst Tag is a compound component built on Radix UI primitives that provides a compact, visually distinct label
for categorizing content or displaying status — with built-in design tokens, CVA variants, and accessibility defaults
so you get a production-ready tag with zero configuration. Standalone tags include a TagButton for removal.
Non-interactive tags are only used inside composed components such as Combobox Multi, where the
parent handles removal via keyboard.
Installation
npm install @pmi/catalyst-tagimport { TagRoot, TagSlot, TagButton } from '@pmi/catalyst-tag';Variants
Danger
Use the danger variant to indicate warnings, errors, or destructive actions.
Disabled
Disabled tags have reduced opacity. Pass disabled explicitly to TagButton to prevent removal — TagRoot does not propagate disabled to its children.
Common Patterns
Sizes
Tags are available in three sizes: sm, md, and lg.
AsChild
Use the asChild prop to merge tag props onto a child element such as a Button. Note: do not add TagButton when using asChild with a Button — nesting interactive elements is invalid HTML.
API Reference
Tag is a compound component. The sections below summarize the API surface for each part of the component.
TagRoot
The container component that manages tag state and appearance.
Prop
Type
TagSlot
A flexible slot for icons or custom leading content.
Accepts asChild, className, and children. Use asChild to merge slot props onto a custom element.
TagButton
An optional button for close or remove functionality.
Prop
Type
Accessibility
Tag is designed to meet WCAG 2.2 AA standards.
Keyboard Interactions
| Key | Action |
|---|---|
Tab | Moves focus to TagButton |
Enter | Activates TagButton (fires onClick) |
Space | Activates TagButton (fires onClick) |
Tab (disabled TagRoot) | Skipped — tabIndex={-1} is applied automatically to disabled tags |
ARIA attributes
TagRootrenders as adivby default. When used in a list of removable tags, wrap the collection in auland useasChildwith anlielement for proper list semantics.TagButtonrenders as a nativebutton, providing built-in keyboard operability (Tab to focus, Enter or Space to activate) and screen reader announcement.- Set
tabIndex={-1}onTagRootwhen it contains aTagButtonto ensure only the button receives focus and avoid redundant tab stops. - Disabled tags set
tabIndex={-1}automatically, removing them from the tab order. - Provide an
aria-labelonTagButtonwhen its visible content is an icon only (e.g.aria-label="Remove tag").
See the Radix Slot accessibility docs for inherited baseline behavior when using asChild.
Choosing the Right Component
Use Tag when you need a compact, styled label for categorization or status. Reach for a different primitive when:
| If you need... | Use instead |
|---|---|
| Numeric count or status dot indicators | Badge |
| A full-width or high-emphasis action element | Button |