Category Cloud

When to use

Reach for CategoryCloud when you have a fixed set of categories / tags / segments and want users to filter by clicking one. Always-visible flex-wrap of pill chips with optional counts. Single-select; re-clicking the active chip clears it (toggleable).

Minimal example

import { CategoryCloud } from "@/components/category-cloud";

<CategoryCloud items={["All", "Tech", "Design", "Engineering"]} />;

String-array shorthand is desugared internally to [{ value, label }]. No counts in this form.

With counts

<CategoryCloud
  items={[
    { value: "tech", label: "Technology", count: 12 },
    { value: "design", label: "Design", count: 8 },
  ]}
  title="Categories"
/>;

Controlled

const [active, setActive] = useState<string | null>(null);

<CategoryCloud
  items={categories}
  value={active}
  onChange={setActive}
/>;

For URL-state sync, drive value from your router and update via onChange. Pass null to clear.

Custom count format

<CategoryCloud
  items={items}
  formatCount={(c) => c > 999 ? ` (${(c/1000).toFixed(1)}k)` : ` (${c})`}
/>;

Disable toggle (always-active)

By default, re-clicking the active chip clears the selection. Pass toggleable={false} to disable this — useful when nullisn't a valid filter state in your app.

Accessibility

• Each chip is a real <button> with aria-pressed.
• Container is role="group"; aria-label defaults to title if provided.
• Tab moves between chips; Enter / Space activates. Focus-visible ring per chip.
• Heading level configurable via headingAs={"h2" | "h3" | "h4"}. Default h3.

Stable references

The card is React.memo-wrapped. Hoist the items array outside the parent render or memoize it to prevent unnecessary re-renders.