Recipe: building a console/dashboard page

You're building something like Vercel's project dashboard, a Datadog-style usage console, or an admin panel — a sidebar or topbar, a project/workspace switcher, a grid of cards with row actions, KPI tiles, and usage sparklines or time-series charts. Every part below already ships in cascivo. This page maps the need to the exact component, in one place, so you don't reach for custom SVG or a separate headless library.

Prerequisite reading: GETTING-STARTED.md for the two install paths (copy-paste vs. @cascivo/react). Everything below works with either.

The Channel column says how you get each entry: a package name means you can import { X } from '<package>', and copy-paste means it has no npm export — run npx cascivo add <registry id> to own the source, or compose it from exported primitives. The column is generated from registry.json and checked by scripts/checks/recipe-channels.test.ts, so it cannot drift.

Component map

Whole-page starting points

Don't build from the component list above if one of these already matches — start from the block/template and adapt it, which is faster and more consistent than composing from scratch:

Before scaffolding by hand, check list_templates (MCP) or /docs/marketplace for a whole-page dashboard template — see the cascivo-design-page skill's step 0.

Reference implementations

Five full example apps compose exactly this component set into real consoles — read one end-to-end rather than starting from a blank file:

• apps/examples/deploy — Vercel-style deploy dashboard: project grid, switcher, sparklines.
• apps/examples/pulse — Datadog-style monitoring console: LineChart, Sparkline.
• apps/examples/trade — Trade Republic-style: Sparkline, Stat.
• apps/examples/pay — Stripe-style: AreaChart, BarChart.
• apps/examples/track — Linear-style issue tracker console.

Bundle size, and the 500 KB warning on your first build

A six-route console drawing on a few dozen of the catalog's components plus three chart types measures roughly 540 KB JS / 177 KB gzip and 166 KB CSS / 21 KB gzip in production. Vite prints its default chunk-size-limit warning at 500 KB, so a stock cascivo dashboard trips that warning on the first build. That is alarming and worth explaining: it is one eagerly-loaded chunk containing every route, not a signal that something is wrong.

The fix is ordinary route-level code splitting, which every router supports — including the index route. That last clause is the whole trick, and omitting it is what has cost two adopters a build cycle each:

// React Router — lazy route modules. Note `/` is lazy too, not just the "big" routes.
{ index: true, lazy: () => import('./routes/overview') },
{ path: 'analytics', lazy: () => import('./routes/analytics') },

// TanStack Router — the same idea
createFileRoute('/analytics')({ component: lazyRouteComponent(() => import('./analytics')) })

Charts are the single biggest win: @cascivo/charts is a real charting engine, and a console typically renders charts on one or two routes out of six. Splitting those routes keeps the engine out of the initial chunk entirely.

⚠ Split the index route too, or the chart engine lands in your entry chunk anyway

"Split the chart routes" reads as not including the landing page, and an adopter took it that way (2026-08-08 report B). They split /analytics exactly as above, left / eager, and measured:

dist/assets/index-*.js     524.70 kB   ← still over the limit
dist/assets/analytics-*.js   2.88 kB   ← the "big" chart route

The analytics chunk was 2.9 kB because @cascivo/charts was already in the entry chunk: the Overview page uses Sparkline in its KPI tiles and project cards — which is what "Composing a KPI tile with a sparkline" below recommends. One Sparkline on an eagerly-loaded route pulls the engine into the entry chunk, and route-splitting the chart pages then buys almost nothing.

Making / lazy like every other route fixes it, at no cost. A later adopter did exactly that on the same shape of app and measured (2026-08-21 report):

dist/assets/index-*.js     413.07 kB / 133.25 kB gzip   ← no warning
dist/assets/dist-*.js       44.87 kB /  14.84 kB gzip   ← the chart engine, shared

Sparklines on the landing page and an entry chunk under the limit. The engine moves to a shared chunk that every chart route reuses; the landing page fetches it in parallel with its own chunk rather than serialised behind the entry.

One sparkline and no engine at all. If a page wants a trend line but draws no real charts — a marketing page, a KPI strip — import from the engine-free subpath instead:

import { Sparkline } from '@cascivo/charts/sparkline'   // ~3.5 kB gzip, no chart engine

Same chart, same props, same markup; the one difference is that it has no hover tooltip, because the tooltip is what requires the engine. Use the main entry when the page draws other charts anyway — the engine is then already paid for and the subpath saves nothing.

Two footnotes:

• Do not pre-emptively raise build.chunkSizeWarningLimit. The 2026-08-21 adopter set it to 700 on the strength of an earlier version of this box, measured, and deleted it again — it was never needed. Raise it only after you have measured and decided the number is fine.
• Expect a HydrateFallback warning once your routes are lazy — it is React Router's, not cascivo's, and USING-WITH-A-ROUTER.md has the two-line fix.
• Verify rather than assume. grep the built bundles for a chart-engine symbol to confirm which chunk it landed in. Chunking is a property of your import graph, not of cascivo.

The CSS number behaves differently and needs no action — per-component tree-shaking already dropped ~40% of the aggregate sheet (166 KB of 273 KB) — except under SSR, where the aggregate import is required; see USING-WITH-VITE-SSR.md.

Composing a KPI tile with a sparkline

The canonical dashboard tile — a number, a trend, and a tiny chart — is either:

// Layout-only Stat, with a sparkline in its trailing `visual` slot
import { Stat } from '@cascivo/react'
import { Sparkline } from '@cascivo/charts'

<Stat
  label="Requests / min"
  value="1.2k"
  delta="+4.3%"
  trend="up"
  visual={<Sparkline data={requestsPerMinute} label="Requests per minute trend" />}
/>

// Or the charts package's own KPI tile, sparkline built in
import { Kpi } from '@cascivo/charts'

<Kpi
  label="Requests / min"
  value={1200}
  delta={4.3}
  deltaFormat="percent"   // renders +4.3% — `delta` is a number, Kpi owns the formatting
  sparkline={requestsPerMinute}
/>

Use Stat when the tile is pure layout and you want full control of the trailing visual; use Kpi when you want the chart-library tile with the sparkline baked in. The two disagree deliberately about who formats: Stat takes delta as a pre-formatted string (you own it), Kpi takes a number and owns the sign, arrow, colour and unit — pass deltaFormat="percent" for +4.3%, or a function for anything else.

Sizing charts — omit width

Every chart in @cascivo/charts is responsive by default. Omit width and it fills its container, tracking resizes through a ResizeObserver. There is no config, no wrapper and no container query to write:

<Card>
  <CardHeader>Requests</CardHeader>
  <CardContent>
    <AreaChart title="Requests" series={series} x={(d) => d.t} y={(d) => d.v} height={240} />
  </CardContent>
</Card>

• width — a fixed SVG width in px, for an export or a thumbnail. It is clamped to the container (max-inline-size: 100%), so it can never overflow its card, but it also stops the chart from growing. In a responsive dashboard grid there is no correct number: don't pass one.
• height — sets the aspect (default 300; 48 in plain mode). Unlike width it does not track the container, so this is the knob you do set.
• useChartSize is not the answer to "make my chart responsive" — charts already call it internally. Reach for it only to size a different element to match a chart, or to build a custom chart on the same measurement primitive.

Two axis-chrome details worth knowing, both automatic:

• Margins are sized to the actual tick labels, so a 60,000 left label or a right-hand second axis is never clipped.
• A crowded category axis is auto-strided (Jun 1 … Jun 30 renders every Nth label). xLabelEvery overrides that computation — omit it unless you specifically want a different stride; passing Math.ceil(n / 8) "to help" makes it worse. The stride is direction-aware: orientation="horizontal" stacks its categories down the y-axis, so they are measured by line height, not by name length. If you still see labels dropped on an axis that visibly has room, that is a bug worth reporting — but categoryLabelEvery={1} forces every label in the meantime.

Importing from more than one cascivo package

A dashboard file often imports from @cascivo/react, @cascivo/charts and @cascivo/icons at once. No name clash remains — the last one is fixed rather than documented:

import { Text } from '@cascivo/react' // typography
import { ChartText } from '@cascivo/charts' // SVG <text> primitive

@cascivo/charts no longer exports Text — the deprecated alias of ChartText was removed at 1.0, as this page said it would be. It was the name whose wrong resolution was silent: the SVG primitive rendered where a paragraph was meant and nothing errored. If you are upgrading from 0.x, import { Text } from '@cascivo/charts' is now a compile error; rename it to ChartText (and TextProps to ChartTextProps).

Calendar used to clash the same way. The charts heatmap is now CalendarHeatmap, so Calendar unambiguously means @cascivo/react's date picker and no alias is needed:

import { Calendar } from '@cascivo/react' // date picker
import { CalendarHeatmap } from '@cascivo/charts' // activity heatmap

@cascivo/icons shares names with both by nature — an icon set of ~440 nouns contains Search, Filter, Grid, User, BarChart, PieChart. The convention is the same one every icon library uses: import { Search as SearchIcon } from '@cascivo/icons'. scripts/checks/export-collisions.test.ts fails CI on a new react↔charts collision, and caps the icons overlap below so it cannot grow unnoticed.

These 20 names exist in both @cascivo/icons and a component package (@cascivo/react or @cascivo/charts). Both are valid JSX in the same position, so a wrong import resolves silently instead of failing to compile — alias the icon:

Guessing a familiar name is fine. @cascivo/icons exports the common aliases from other sets as real names, so Rocket (→ Spaceship), LayoutDashboard (→ Dashboard), MagnifyingGlass, Gear, Bolt and ~35 more resolve without a lookup. The exceptions are names already claimed elsewhere — Kbd is a component, LineChart is a chart, Box, Delete and Trash2 are icons in their own right — which stay searchable in the icon gallery but are deliberately not exported as aliases.

Don't hand-roll the behavior layer

Dropdown, Menu, ContextMenu, Combobox, CommandMenu, MultiSelect, and Tabs ship with keyboard navigation, focus management, and outside-click dismissal already implemented (native <dialog>/Popover APIs plus @cascivo/core primitives). If you find yourself writing a document .addEventListener('mousedown', ...) outside-click handler or your own arrow-key switch statement for a menu, stop — the component you're wrapping already does it.

As Markdown: /docs/recipe-dashboard.md

← All guides