Tag Browser

tag-browserControls

Pick keywords by category, preset-browser style.

$ pnpm dlx shadcn@latest add @pluginui/core-tag-browser
Loading interactive preview…

Install

Copies the source into your project. Anything it depends on comes with it. Run this in your React project with shadcn initialized; no registry configuration is needed.

Pulls in

use-element-size
Install using the registry URL
$ pnpm dlx shadcn@latest add https://pluginui.com/r/core-tag-browser.json

Usage

Connect the documented props to your application or host.

example.tsx
import { TagBrowser } from "@/components/ui/tag-browser"

<TagBrowser
  variant="panel"
  search
  disableZeroCount={browseMode}
  categories={[
    { id: "instrument", label: "Instrument", selection: "single", tags: instruments },
    { id: "character", label: "Character", selection: { max: 3 }, tags: characters },
  ]}
  value={selection}
  onChange={(next) => setSelection(next)}
/>
About Tag Browser

A controlled category/keyword chip browser. Each category is single-select (a pick replaces) or allows up to n chips (the next pick is refused and announced). Chips can show match counts; in browse mode a chip that matches nothing is disabled but stays focusable. Per-category and global clear, and an optional search. Columns from 560 px, stacked and wrapping below, so a 360 px face never scrolls sideways. Quiet, Panel and Glass skins share the headless useTagBrowser hook; the rules are a pure, tested model.

Props

PropTypeDefaultDescription
categoriesTagCategory[]—Each { id, label, selection?, tags }. selection is "single" or { max }; omitted means unlimited. Tags are { id, label, count?, disabled?, keywords? }.
value / onChangeRecord<string, string[]> / (next, change) => void—Controlled selection: category id → chip ids in pick order. change says toggle, clear-category or clear-all.
disableZeroCountbooleanfalseBrowse mode: chips whose count is 0 cannot be picked. Selected chips stay clearable.
search / query / onQueryChangeboolean / string / callback—Show the filter field; optionally control its text.
layout / columnsMinWidth"auto" | "columns" | "stacked" / number"auto" / 560Columns from the component's own width, stacked below it.
variant"quiet" | "panel" | "glass""quiet"The PresetSelector skins.

Interaction

  • Keyboard One tab stop. Columns: Up/Down within a category, Left/Right across. Stacked: Left/Right along the chips, Up/Down between categories. Home/End, Ctrl+Home/End. Space or Enter toggles.
  • Limits A single-select category replaces its chip; a full category refuses another pick and says why in a polite live region.
  • Search Type to filter chips; ArrowDown enters the chips, ArrowUp from the first row returns, Escape clears.
All controlsStart building