Category Cloud
alphav0.3.0Flex-wrapped cloud of clickable category chips with optional counts — single-select, toggleable, controlled or uncontrolled.
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
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/category-cloudAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/category-cloud-fixturesCLI 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
"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="page"</code>. Pass your router'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>witharia-pressed(or a link witharia-currentin link mode). - Container is
role="group";aria-labelisariaLabel, elsetitle, elselabels.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"}. Defaulth3.
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