Skip to content
ilinxa/pro-ui

Category Cloud

alphav0.3.0

Flex-wrapped cloud of clickable category chips with optional counts — single-select, toggleable, controlled or uncontrolled.

Category: FormsUpdated: 2026-10-25Created: 2026-05-02Author: ilinxa

Context

Sidebar / inline filter affordance. Differs from `entity-picker` (popover-driven select with search) by being always-visible and count-augmented. Differs from `filter-panel` (multi-section schema-driven filter panel) by handling a single category dimension. Generic over category items via `string[]` shorthand or full `CategoryCloudItem[]` shape. Migration origin: kasder kas-social-front-v0 NewsMagazineGrid.tsx sidebar Categories block. Composed by `magazine-layout` in the news-domain family.

Installation

Initialize shadcn (once per project)Seeds lib/utils.ts and components.json. Skip if you've already used any shadcn component.
pnpm dlx shadcn@latest init
Install the component
pnpm dlx shadcn@latest add @ilinxa/category-cloud

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/category-cloud-fixtures

CLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:

"registries": {
  "@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}

Preview

Filter by department

Demo source

demo.tsxtsx
"use client"; import { useState } from "react";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { CategoryCloud } from "./category-cloud";import { DUMMY_CATEGORIES_AR, DUMMY_CATEGORIES_EN, DUMMY_CATEGORIES_TR } from "./dummy-data"; const DUMMY_CATEGORIES_TR_BIG = DUMMY_CATEGORIES_TR.map((c, i) => ({ ...c, count: 1200 * (i + 1) + 345 })); export default function CategoryCloudDemo() {  const [controlledValue, setControlledValue] = useState<string | null>(null);  // Stands in for "the category in the current URL" (a real app derives it from the router).  const [linkValue, setLinkValue] = useState<string | null>("sustainability");   return (    <Tabs defaultValue="basic" className="w-full">      <SwipeTabsList>        <TabsTrigger value="basic">Basic</TabsTrigger>        <TabsTrigger value="counts">With counts</TabsTrigger>        <TabsTrigger value="controlled">Controlled</TabsTrigger>        <TabsTrigger value="i18n">Localized</TabsTrigger>        <TabsTrigger value="links">Link mode</TabsTrigger>        <TabsTrigger value="rtl">RTL</TabsTrigger>      </SwipeTabsList>       <TabsContent value="basic" className="mt-6 max-w-md rounded-2xl border border-border/50 bg-card p-6">        <CategoryCloud          items={["All", "Tech", "Design", "Engineering", "Marketing", "Operations"]}          title="Filter by department"        />      </TabsContent>       <TabsContent value="counts" className="mt-6 max-w-md rounded-2xl border border-border/50 bg-card p-6">        <CategoryCloud items={DUMMY_CATEGORIES_EN} title="Categories" />      </TabsContent>       <TabsContent value="controlled" className="mt-6 max-w-md space-y-4 rounded-2xl border border-border/50 bg-card p-6">        <CategoryCloud          items={DUMMY_CATEGORIES_EN}          title="Categories"          value={controlledValue}          onChange={setControlledValue}        />        <p className="text-sm text-muted-foreground">          Active value: <code className="rounded bg-muted px-1.5 py-0.5 text-xs">{controlledValue ?? "null"}</code>        </p>      </TabsContent>       <TabsContent value="i18n" className="mt-6 max-w-md rounded-2xl border border-border/50 bg-card p-6">        <CategoryCloud          items={DUMMY_CATEGORIES_TR_BIG}          title="Kategoriler"          locale="tr"          labels={{ group: "Kategori filtresi", count: (_n, formatted) => ` (${formatted} yazı)` }}        />      </TabsContent>       <TabsContent value="links" className="mt-6 max-w-md space-y-3 rounded-2xl border border-border/50 bg-card p-6">        <CategoryCloud          items={DUMMY_CATEGORIES_EN}          title="Categories"          value={linkValue}          onChange={setLinkValue}          getHref={(item) => `#category-${item.value}`}        />        <p className="text-sm text-muted-foreground">          Chips are real links; the active one carries <code>aria-current=&quot;page&quot;</code>. Pass your router&apos;s          link as <code>linkComponent</code>. A Ctrl / Cmd-click opens the link elsewhere and leaves the active chip          alone. Current: <code>{linkValue ?? "none"}</code>        </p>      </TabsContent>       <TabsContent value="rtl" className="mt-6 max-w-md rounded-2xl border border-border/50 bg-card p-6">        <div dir="rtl" lang="ar">          <CategoryCloud            items={DUMMY_CATEGORIES_AR}            title="التصنيفات"            locale="ar"            labels={{ count: (_n, formatted) => ` (${formatted})` }}          />        </div>      </TabsContent>    </Tabs>  );} 

Usage

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}
/>;

Pass null to clear. For URL-driven filters use link mode below instead of pushing state from onChange.

Link mode (URL-driven filters)

<CategoryCloud
  items={categories}
  value={activeSlug}
  getHref={(item) => `/explore?category=${item.value}`}
  linkComponent={Link} // your router's link; defaults to "a"
/>;

Chips render as links with aria-current="page" on the one matching value (no aria-pressed). onChange still fires on click; the default navigation is not prevented. An item whose getHref returns undefined stays a button. toggleable has no meaning for links.

Localization

<CategoryCloud
  items={items}
  locale="tr" // 12345 -> "12.345"
  labels={{
    group: "Kategori filtresi",
    count: (_n, formatted) => ` (${formatted} yazi)`,
  }}
/>;

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 (or a link with aria-current in link mode).
  • Container is role="group"; aria-label is ariaLabel, else title, else labels.group.
  • Tab moves between chips; Enter / Space activates a button chip, Enter a link chip. 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.

Features

  • Always-visible flex-wrap of pill chips (vs entity-picker's popover-driven select)
  • Optional inline counts via `count` field on items; configurable format via `formatCount` callback
  • String-array shorthand: `items={["All", "Tech"]}` desugars to `{value, label}` form
  • Controlled-or-uncontrolled value (single-select; pass null to clear)
  • Toggleable — re-clicking active clears (configurable via `toggleable` prop)
  • Native `<button>` semantics with `aria-pressed`; Tab + Enter/Space work natively (link chips: Enter, as for any link)
  • Link mode: `getHref` renders chips as links (`linkComponent`, default `<a>`) with `aria-current="page"` on the active one — for URL-driven filters and SEO-crawlable facets
  • `labels` (group name, count text) + `defaultCategoryCloudLabels` for localization; `locale` formats counts with `Intl.NumberFormat` (invalid tag falls back to `en`)
  • Dev-only warnings for a controlled `value` matching no item and for duplicate item values
  • Optional editorial-header title with `pb-2 border-b` separator (matches the magazine sidebar header rhythm)
  • Heading semantic level configurable via `headingAs` (h2 | h3 | h4)
  • ARIA group named by `ariaLabel`, else `title`, else `labels.group`
  • React.memo wrapped

Tags

category-cloudformsfiltertagscategoriesmigration

Dependencies

shadcn primitives: badge