Tags

Badge-based tag pills and controlled command selectors for filtering, categorizing, and lightweight metadata workflows.

Selector

Search, create from the menu, create from separators, paste, and toggle selected options.

Known options

Badge variants

DefaultSecondaryDestructiveOutlineGhostLink

Sizes

SmallBaseLarge

Install

npm install @patternmode/tags

import { Tag, TagSelector, type TagItem } from "@patternmode/tags";
import "@patternmode/tags/styles.css";

function Example() {
  const [tags, setTags] = useState<TagItem[]>([
    { id: "accessible", label: "Accessible" },
  ]);
  const options = [
    { id: "accessible", label: "Accessible" },
    { id: "command-menu", label: "Command menu" },
    { id: "reusable", label: "Reusable" },
  ];

  return (
    <>
      <Tag variant="outline" onRemove={() => null}>
        Accessible
      </Tag>
      <TagSelector
        aria-label="Component tags"
        value={tags}
        onChange={setTags}
        options={options}
        onCreateItem={(label) => ({
          id: label.toLowerCase().replace(/[^a-z0-9]+/g, "-"),
          label,
        })}
      />
    </>
  );
}

Core API

`Badge`

Shadcn-compatible badge base with variant and asChild support.

variant: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link""default"Matches the normal shadcn Badge variant names.
asChild: booleanfalseRenders the badge styles onto a child via Radix Slot.

`Tag`

Badge extension for selected filters, labels, metadata, and removable tokens.

variant: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link""secondary"Inherited from the Badge base.
size: "sm" | "base" | "lg""base"Controls compact, default, or large sizing.
onRemove: () => voidAdds an accessible remove button inside the tag.
selected: booleanfalseAdds a selected treatment without changing semantics.

`TagSelector`

Controlled object-based tag selector with Popover content, ScrollFrame selected tags, creation, keyboard navigation, paste parsing, and Stacksheet-style parts.

value: readonly TagItem[]The selected items. Selection order follows this array order.
onChange: (items: TagItem[]) => voidCalled with the next selected item objects.
options: readonly TagItem[]The consumer-owned option catalog. Selected options stay visible and toggle off by id.
onCreateItem: (label: string) => Promise<TagItem> | TagItemEnables creation through the create option, Enter/comma, and paste. The consumer returns the new object.
renderTag: (props: TagRenderProps) => ReactNodeRenders selected items with any component. Patternmode provides Tag as the convenient default.
renderOption: (props: TagOptionRenderProps) => ReactNodeRenders command options while preserving provided props.
emptyMessage: ReactNode"No tags found."Empty command-list state when no option can be shown.

`TagSelector parts`

Composable selector parts for Stacksheet-style layouts: Root, Trigger, Content, Search, List, Option, and Empty.

TagSelector.Root: TagSelectorRootPropsOwns state wiring, filtering, creation, serialization, and Popover context.
TagSelector.Trigger: TagSelectorTriggerPropsRenders selected tags in a horizontal ScrollFrame by default.
TagSelector.Content: TagSelectorContentPropsPopover-backed command surface.
TagSelector.Search | List | Option | Empty: component partsSearch input, option list, explicit option renderer, and empty state.