Skip to content

Design system

Documentation

DesignComponents / Tag

Components / Tag

Beta

Tag

Use Tag for selectable filters and removable chips; keep Badge for non-interactive status labels.

On this page

Examples

Selectable filter

A pressed state communicates whether a filter is active and can be changed by keyboard or pointer.

Selectable Billing filter

Removable filter

Removal is a separate named action beside the toggle, never a nested button.

Removable Trial plan filter

Disabled filter

A disabled value stays visible but cannot be toggled or removed.

Disabled selected filter

Try the filter

Change the selected state and shared control density.

Tag property playground

When to use

Use Tag for a filter or classification that people can toggle, and optionally remove from the active set. Use Badge for a static lifecycle state, role, or result label.

Usage

import { Tag } from "@phuctech/ui/components/tag";

<Tag label="Billing" selected={selected} onSelectedChange={setSelected} onRemove={removeBillingFilter} />

Behavior

  • selected + onSelectedChange is controlled; defaultSelected initializes local state when selected is omitted.
  • onRemove adds a separate, named IconButton after the toggle. It reports a request; feature state removes the tag.
  • Disabled applies to both toggle and remove actions.
  • Removing a filter is a local selection change. If an action would delete a resource, confirm it through the shared Dialog pattern in the feature.

API

Component API
PropTypeDefaultDescriptionConstraints
labelstringrequiredVisible label and default accessible name for the toggle.Keep it concise and identify the filter value.
selected / defaultSelectedbooleanfalseControlled or initial pressed state.Choose one ownership model for the instance.
onSelectedChange(selected: boolean) => void—Receives the requested pressed state.Update controlled feature state here.
onRemove() => void—When provided, renders a separate remove action.The feature owns removal; resource deletion still requires confirmation.
removeLabelstringRemove {label}Accessible name for the remove action.Provide a more specific name when the default is ambiguous.
size"sm" | "md""md"Shared control density.Use one density consistently within a filter group.
disabled / button props / refnative button propsfalse / — / —Forwards trigger attributes and ref; disabled also disables removal.The main control is a toggle button with aria-pressed.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-action-primary / --color-bg-subtleSelected filterSemantic action rolesKeeps selected and unselected state distinct in both themes.
--size-control-xs / smTag densityShared control scaleAligns the pill toggle and remove control with nearby UI.
--focus-ring-*Keyboard focusShared focus ringShows focus independently on the toggle and remove action.

Accessibility

The toggle has a visible label and exposes its pressed state. The remove action is a second button with a name that includes the tag label by default. Both actions are keyboard reachable; Escape is not required because the tag does not open a popup.

Do and don’t

Do

Keep selection and removal as separate controls and state transitions.

Don’t

Use an interactive Tag for passive status text or make the entire chip disappear without a labeled action.

  • Badge is a non-interactive status or classification label.
  • Checkbox is better when a filter list is long or arranged as a form.
  • Button handles general actions and navigation.