Preview
Design guidance
Use tags for values that users can select or remove. Use Badge for read-only metadata. TagItem.Selectable works on its own; its leading plus changes to a check when selected. It uses the existing Checkbox behavior, including keyboard activation, native form values and controlled or uncontrolled state.
TagItem owns each tag's appearance, icon containers, selection indicators, removal and custom entry. TagGroup adds collection selection and limits through these same parts. TagInput keeps text entry, parsing and validation, while Combobox keeps chip navigation. The lower-level TagItem view and its parts remain available for those compositions.
The default filled style has a subtle surface and border. Outline uses Input background and border roles. Give remove actions accessible names. Selection and removal stay separate controls; removing an option does not also select it.
Removal appears on hover or keyboard focus by default, without reserving space at rest. Touch devices show the action directly. Set removeVisibility="always" on TagItem or TagItem.Selectable to keep it visible, as input-family chips do.
Installation
Basic usage
Structures
Examples
Outline
Select an input-like outline tag. TagGroup uses this style by default.
Base size
Both styles support the 32px base size. Each tag can be selected. The default small size is 28px; input hosts provide compact geometry for small tags.
Icon positions
Select tags with leading or trailing state icons. Both positions use the same fixed container: 24px in small tags and 28px in base tags. The 14px glyph stays centered inside it.
Without icons
Keep selection and keyboard behavior while showing the selected border alone.
Selected check
Show a check only while selected. The tag remains selectable when the icon is absent.
Controlled selection
Keep selection in the caller while using the same tag behavior and appearance.
Always-visible removal
Set removeVisibility="always" to keep the named remove button visible. The caller owns the values and removes a tag when the button is pressed.
Selection and removal
Select a tag or remove it with its separate button. These tags hug their content at rest and grow when hover or keyboard focus reveals removal. Touch devices show the remove action directly.
Custom entry
Add a value with Enter or the Arrow Up button. Each value can then be selected or removed. The caller owns insertion and uniqueness; TagItem.Input owns the entry control and submission interaction.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "filled" | "outline" = "filled" | Shared view and Selectable appearance. Filled uses a subtle surface and border; outline uses Input background and border roles. | |
size | "sm" | "base" = "sm" | Small is 28px standalone; base is 32px. Input hosts provide compact geometry for small tags. | |
TagItem.Selectable | TagItem props; native span attributes / ref | An independent checkbox tag, or a checkbox/radio item when composed in TagGroup. Its ref targets the selection control. A grouped item requires value; the group owns its checked state. | |
checked / defaultChecked / onCheckedChange | boolean / boolean / (checked, details) => void | Standalone controlled or initial uncontrolled selection. Form reset restores the initial uncontrolled value; a cancelled change leaves selection unchanged. Uses the existing Checkbox contract. Grouped selection uses TagGroup value/defaultValue/onValueChange instead. | |
value / name / form / required | string / string / string / boolean | Standalone native checkbox form contract. Grouped items receive these policies from TagGroup. | |
disabled / readOnly | boolean = false (Selectable) | Blocks selection and removal. Disabled values are omitted from form submission; readOnly values remain submitted. | |
indicator / indicatorPlacement | "plus" | "check" | "none" / "leading" | "trailing" | Selectable defaults to leading plus. Plus changes to check when selected. Check appears only when selected; none keeps the selected border without an icon. | |
onRemove / removeLabel / removeVisibility | () => void / string / "always" | "hover" | Optional Selectable removal as a sibling native button. removeVisibility also applies to the lower-level TagItem view and defaults to hover. Hover mode occupies no extra width at rest and remains available on keyboard focus or touch. Set always to keep removal visible. The caller removes the value. | |
TagItem.Input | Input props; onSubmit?: () => void; submitLabel?: string; ref | Dashed content-sized InputGroup entry. Enter or Arrow Up submits a non-empty draft; IME, readOnly and disabled are respected. The caller owns draft state and insertion. | |
TagItem | native span attributes / children / ref | The shared lower-level tag view for selectable controls and removable values. Plain text receives TagItem.Label alignment automatically. | |
TagItem.Label | native span attributes / children / ref | Aligns compound label content with icons and actions. | |
TagItem.Icon | native span attributes / children / ref | A decorative 24px/28px container at either edge, with a centered 14px glyph. Hidden from assistive technology by default. | |
TagItem.Remove | IconButton props; aria-label required; children?: ReactNode | A canonical ghost button with X by default. Supply onClick to remove a value. Pass disabled to block the action; children can replace the icon. | |
TagItem.Action | Button props / ref | Existing convenience part for a standard 32px outline Button. Standalone actions can compose Button directly. |