Tag / Chip
Compact labels for entities, filters, selected values, and removable metadata.
Tag is the universal compact label component for an entity or value. It can remain static, behave as a selectable filter, link to another view, or expose a dedicated remove action. Use Tag for readable statuses, categories, filters, identities, and removable values. Badge is intentionally narrower and is reserved for numeric, short-count, and dot indicators.
Basic usage
<Tag tone="primary">React</Tag>
<Tag tone="success" icon={<CheckIcon size={14} />}>Published</Tag>
<Tag avatar={<Avatar src="/maya.jpg" alt="Maya Chen" />}>Maya Chen</Tag>Selectable filters
Use selectable when a tag behaves like a compact toggle or filter. The selected state can be controlled or managed internally:
const [selected, setSelected] = useState(false);
<Tag
selectable
selected={selected}
onSelectedChange={setSelected}
tone="primary"
>
Needs review
</Tag>Selectable tags expose aria-pressed and support Enter and Space. Use a group-level label when several tags form a filter group.
Removable values
<Tag
removable
onRemove={() => removeFilter('TypeScript')}
removeLabel="Remove TypeScript filter"
>
TypeScript
</Tag>The remove control is a separate keyboard-accessible button and does not activate the parent tag. This makes the component suitable for selected filters, recipients, categories, and multi-value inputs.
Variants, icons, links, and states
tone supports neutral, primary, secondary, success, warning, and danger. variant supports solid, soft, outline, and light; size supports xs, sm, default, and lg; and shape supports rounded, pill, and square.
Use href for a link-like tag, icon for a leading icon, avatar for an identity, loading while a tag action is in progress, disabled when it cannot be changed, and truncate for long values.
API Reference
| Property | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Tag label or content. |
tone | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral' | Semantic color. |
variant | 'solid' | 'soft' | 'outline' | 'light' | 'soft' | Visual treatment. |
size | 'xs' | 'sm' | 'default' | 'lg' | 'default' | Density preset. |
shape | 'rounded' | 'pill' | 'square' | 'pill' | Corner treatment. |
icon | ReactNode | — | Leading icon. |
avatar | ReactNode | — | Identity content; takes precedence over icon. |
selectable | boolean | false | Makes the tag a toggle. |
selected | boolean | — | Controlled selected state. |
defaultSelected | boolean | false | Initial uncontrolled selected state. |
onSelectedChange | (selected: boolean) => void | — | Called when a selectable tag changes. |
removable | boolean | false | Shows the remove button. |
onRemove | (event) => void | — | Called by the remove button. |
removeLabel | string | 'Remove tag' | Accessible remove-button label. |
href | string | — | Renders the tag as a link. |
onClick | (event) => void | — | Handles activation. |
closeIcon | ReactNode | X | Custom remove-button icon. |
loading | boolean | false | Shows loading and disables interaction. |
disabled | boolean | false | Disables interaction. |
truncate | boolean | false | Truncates long content. |
title | string | — | Native tooltip/title attribute. |
id | string | — | Root element id. |
className | string | — | Additional root class. |
style | CSSProperties | — | Additional root styles. |