Widgets

The Widgets showcase (/widgets, sidebar Components → Widget, lazy-loaded) is a modern, interactive gallery of every widget in src/components/widgets/, arranged in labelled sections: Welcome heroes (three variants), a KPI tile gallery, Chart cards (donut, gauge, breakdown, area trend, stat list, weekly bars), Overview panels (report panel + mini calendar), Lists & activity, and Cloud & infrastructure (Google Cloud and Firebase console-style sets).

Every widget is fully data-driven via props — the page passes demo data, but the components carry no sample content of their own. Widgets are pure presentational cards: they render inside the shared Card (or their own token-styled shell), wrap themselves in a staggerItem motion variant so a surrounding Stagger grid cascades them in, and stay reduced-motion safe throughout.

Three cross-cutting rules apply everywhere:

Architecture & files

The route is registered lazily in src/routes.tsx:

const WidgetsPage = lazy(() => import('@/pages/ui/WidgetsPage').then((m) => ({default: m.WidgetsPage})))
// …
{path: '/widgets', element: <WidgetsPage />},

Usage

Import from the barrel and drop widgets into a Stagger grid (each widget carries its own staggerItem variant, so the grid cascades them in automatically):

import {KpiTile, DonutWidget, WidgetSection} from '@/components/widgets'
import {DollarSign} from 'lucide-react'
 
<WidgetSection title={t('chartsTitle')} subtitle={t('chartsSubtitle')} gridClassName="lg:grid-cols-3">
    <KpiTile variant="flat" tone="primary" icon={DollarSign} label={t('mRevenue')} value={48250} prefix="$" delta={12.4} spark={[12, 18, 14, 22, 19, 27, 24, 31]} />
    <DonutWidget
        title={t('donutTitle')}
        subtitle={t('donutSubtitle')}
        total={4820}
        totalLabel={t('donutTotal')}
        segments={[{label: t('segCity'), value: 2100}, {label: t('segAirport'), value: 1450}]}
    />
</WidgetSection>

WidgetSection provides the heading and the Stagger grid. All widget text arrives as props — pass t(…) results, never literals.

API / Props

All widgets share the pattern: an outer motion.div with variants={staggerItem} and h-full, a Card/token-styled shell, a WidgetHeader, and (where a footer exists) an mt-auto bottom-anchored stat row. Tones are the five semantic keys primary | success | warning | danger | info unless noted.

Primitives

WidgetHeader

WidgetMenu takes no props — it is the demo ⋯ Dropdown (Refresh / Export / View details / Fullscreen / Hide) whose items fire an info toast. Replace it with a real menu by passing your own action and menu={false} to WidgetHeader.

WidgetSection — title: string, subtitle: string, icon?: ReactNode (rendered in a primary-tinted chip), gridClassName?: string, children.

TrendPill — value: number (signed percentage; sign drives the arrow and the success/danger tint), suffix?: string, className?.

Sparkline

The line/area draw-in is an animated clip rect whose width grows from x=0 — strictly left→right, robust under preserveAspectRatio="none". Under reduced motion the full curve renders immediately.

MiniBarChart — data: number[], labels: string[], highlightIndex: number (the one bar drawn at full opacity; the rest at ~35% alpha), tone? (default 'primary'). A chart.js Bar with a staggered grow-in, disabled under reduced motion; colors from useChartTokens().

KPI tiles

KpiTile (KpiTileProps, exported)

Solid-fill variants (gradient, the flip back face) use the text-*-foreground token map — never text-white — so contrast holds on skins with dark foregrounds (e.g. Amber). flip is a CSS 3D hover-flip.

Chart cards

• DonutWidget — title, subtitle, total: number, totalLabel, prefix?, segments: DonutSegment[] ({label, value} — colored by cycling useChartTokens().series), footer?, tint?, icon?. chart.js Doughnut, cutout: '68%', centered AnimatedNumber total.
• GaugeWidget — title, subtitle, value (0–100), valueLabel, tone?: 'primary' | 'success' | 'warning' | 'info', segments? (arc tick count, default 15), bannerIcon, bannerText, stats, breakdown?. A chart.js half-doughnut of rounded ticks.
• AreaTrendWidget — title, subtitle, calloutLabel, periods: TrendPeriod[] (a period Dropdown switches the chart and headline), breakdownLabel?, breakdown?, footer?. The one Recharts widget; colors from useChartTokens().
• BarStatWidget — title, subtitle, value: string, delta: number, data: number[] (7 values), highlightIndex, tone?, breakdown?, stats?. Weekday labels via Intl — no i18n keys.
• BreakdownWidget — title, subtitle, rows: BreakdownRow[] (tone includes neutral), total?, unit?, delta?, activity?: number[], activityLabel?, footer?, tint?, icon?. DOM/token-only.
• StatListChartWidget — title, subtitle, rows: StatRow[], spark: number[], sparkTone?, sparkLabel?, footer?.

Lists & feeds

Composite widgets

• WelcomeWidget — greeting, name, message, ctaLabel, onCta?, avatar?, variant?: 'gradient' | 'panel' | 'lines' (default gradient), dateLabel?, stats?. All three variants share one vertical layout (chip · avatar+greeting · message · stats · CTA) for consistent spacing and equal height. lines layers a HeroCanvas variant="lines" under a surface gradient scrim.
• ReportPanelWidget — title, subtitle, revenueLabel, revenue: number, revenuePrefix?, revenueDelta, compareLabel, stats: ReportStat[], highlights?, teamsLabel, teams: TeamBar[] (ranked Progress bars), goalLabel? + goalPercent? + goalCaption?.
• MiniCalendarWidget — title, subtitle, events: CalEvent[] ({date, title, time, tone} — dates dot the calendar, the first 3 list as "upcoming"), upcomingLabel?. Reuses the calendar app's MiniCalendar with the active i18n.language.

Google Cloud & Firebase sets

Accents in these sets use the GcpHue = 'primary' | 'info' type — see the skin rule.

Configuration & customization

The equal-height flex-fill chain

Grid cells stretch, but card content top-aligns — so a short card in a row of tall ones would show a dead gap at the bottom. Every widget therefore builds a flex-fill chain and bottom-anchors its footer:

<motion.div variants={staggerItem} className="h-full">   {/* the grid cell fills */}
    <Card className="flex h-full flex-col">              {/* the card fills the cell */}
        <CardBody className="flex flex-1 flex-col">      {/* the body absorbs the height */}
            <WidgetHeader … />
            {/* …content; an inner chart area can take flex-1 too… */}
            <div className="mt-auto grid … border-t border-border pt-4">{/* footer pins to the bottom */}</div>
        </CardBody>
    </Card>
</motion.div>

Follow this chain in any new widget: h-full wrapper → Card flex h-full flex-col → CardBody flex flex-1 flex-col → mt-auto on the footer/stat row. Where a card still reads short, add real content rather than leaving whitespace — that's why most widgets accept optional footer/breakdown/activity props.

Chart colors & useChartTokens()

The chart.js widgets (DonutWidget, GaugeWidget, MiniBarChart/BarStatWidget) render to a <canvas>, which cannot resolve CSS variables — so they call useChartTokens(), which reads the raw --primary/--info/--foreground/… values off <html> and re-reads via a MutationObserver on class/data-skin/data-oled. Every canvas chart therefore re-colors live on theme/skin switch. The Recharts AreaTrendWidget uses the same hook. The SVG Sparkline doesn't need it — it draws with currentColor. Canvas animations are all gated by useReducedMotion(). See Charts for the full useChartTokens story.

The skin rule

Color skins override only --primary and --info — not --success/--warning/--danger, which stay semantic. So:

• Brand/decorative accents that should re-skin use only primary and info — the GcpHue type, the alternating breakdown dots, the Firebase gradient. GcpStatusCard maps ok/warn to primary/info; only a hard down keeps danger red.
• True status meaning (TrendPill up/down, health down, warning banners) keeps success/warning/danger.
• The multi-hue categorical palette (useChartTokens().series, used by DonutWidget) prefers a skin-provided --c1..--c6 palette (the Prism skin defines one); otherwise it anchors on the exact primary and hue-rotates around it so it stays distinct on every skin and in dark mode.

Troubleshooting

FAQ

Are these the same as StatCard or Panel? No. StatCard is a single dashboard stat primitive and Panel is the general collapsible portlet. The widgets library is a catalog of purpose-built dashboard cards with their own borderless WidgetHeader.

Which chart library do they use? chart.js (react-chartjs-2) for the donut, gauge, and weekly bars, plus Recharts for AreaTrendWidget and a dependency-free SVG Sparkline.

Do widgets fetch data? No — they are pure presentational components. Pass values from your API layer or state.

Can I use a widget outside the showcase? Yes — everything is exported from @/components/widgets. The home dashboards compose similar patterns.

Related