Dashboard

All-in-one dashboard wrapper. Replaces the 5-provider nesting pattern (MetricProvider + FilterProvider + CrossFilterProvider + LinkedHoverProvider + DrillDown.Root) with a single flat component.

import { Dashboard } from "metricui";

Use Dashboard as the outermost wrapper for any MetricUI dashboard. It replaces the 5-provider nesting pattern with a single flat component — every prop is optional, every hook works inside. For fine-grained control (e.g., two FilterProviders), compose the individual providers directly.

Before & After

Without Dashboard, you need to nest five providers manually. The wrapper collapses all of that into a single component.

Before (5 providers)

<MetricProvider theme="emerald" exportable>
  <FilterProvider defaultPreset="30d">
    <CrossFilterProvider>
      <LinkedHoverProvider>
        <DrillDown.Root>
          <DashboardHeader title="Sales" />
          <MetricGrid>
            <KpiCard title="Revenue" value={142800} format="currency" />
            <BarChart data={data} categories={["revenue"]} index="month" />
          </MetricGrid>
          <DrillDown.Overlay />
        </DrillDown.Root>
      </LinkedHoverProvider>
    </CrossFilterProvider>
  </FilterProvider>
</MetricProvider>

After (1 wrapper)

<Dashboard theme="emerald" filters={{ defaultPreset: "30d" }} exportable>
  <DashboardHeader title="Sales" />
  <MetricGrid>
    <KpiCard title="Revenue" value={142800} format="currency" />
    <BarChart data={data} categories={["revenue"]} index="month" />
  </MetricGrid>
</Dashboard>

Basic Example

The simplest Dashboard — just a theme and some content. Every prop is optional; omit filters and FilterProvider is skipped entirely.

Revenue

<Dashboard theme="emerald">
  <KpiCard title="Revenue" value={142800} format="currency" />
</Dashboard>

With Filters

Pass the filters prop to enable FilterProvider. The useMetricFilters() hook and filter components like PeriodSelector become available inside.

Active Users

Conversion Rate

<Dashboard
  theme="indigo"
  filters={{ defaultPreset: "30d", defaultComparison: "previous" }}
>
  <KpiCard title="Active Users" value={8420} format="number" />
  <KpiCard title="Conversion Rate" value={0.034} format="percent" />
</Dashboard>

Full Featured

Combine theme, filters, export, dense layout, and multiple component types. All MetricUI components inherit the Dashboard configuration automatically.

Revenue

Orders

AOV

Monthly Revenue

<Dashboard
  theme="rose"
  filters={{ defaultPreset: "30d" }}
  exportable
  dense
>
  <MetricGrid>
    <KpiCard title="Revenue" value={142800} format="currency" />
    <KpiCard title="Orders" value={1284} format="number" />
    <KpiCard title="AOV" value={111.21} format="currency" />
    <BarChart
      data={revenueData}
      categories={["revenue"]}
      index="month"
      title="Monthly Revenue"
      format={{ style: "currency" }}
    />
  </MetricGrid>
</Dashboard>

Individual Providers

Dashboard covers 90% of use cases, but sometimes you need fine-grained control. Use the individual providers when you need:

Two FilterProviders — e.g. a main dashboard filter and a separate modal with its own date range.
Custom renderContent — the Dashboard passes renderContent to the drill-down overlay panel, but if you need the overlay placed elsewhere in the tree, compose manually.
Partial provider stacks — e.g. MetricProvider + LinkedHoverProvider only, without cross-filter or drill-down.

// Example: two independent filter scopes
<MetricProvider theme="emerald">
  <FilterProvider defaultPreset="30d">
    <MainDashboard />
  </FilterProvider>

  <FilterProvider defaultPreset="7d">
    <ComparisonPanel />
  </FilterProvider>
</MetricProvider>

Props

Prop	Type	Default	Description
`theme`	`string \| ThemePreset`	—	Theme preset name or custom ThemePreset object. Built-in: indigo, emerald, rose, amber, cyan, violet, slate, orange.
`colorScheme`	`"light" \| "dark" \| "auto"`	`"auto"`	Color scheme. 'auto' detects system preference.
`variant`	`CardVariant`	`"default"`	Default card variant for all components.
`locale`	`string`	`"en-US"`	BCP 47 locale string.
`currency`	`string`	`"USD"`	ISO 4217 currency code.
`animate`	`boolean`	`true`	Global animation toggle.
`dense`	`boolean`	`false`	Compact layout toggle.
`exportable`	`boolean`	`false`	Global export toggle. Enables ExportButton on all components.
`tooltipHint`	`boolean`	`true`	Show action hints in chart tooltips.
`loading`	`boolean`	`false`	Global loading toggle. Shows skeletons on all components.
`texture`	`boolean`	`true`	Noise texture on card surfaces.
`filters`	`{ defaultPreset?: PeriodPreset; defaultComparison?: ComparisonMode; referenceDate?: Date }`	—	Filter configuration. Omit to skip FilterProvider entirely.
`maxDrillDepth`	`number`	`4`	Max nested drill-down levels.
`renderContent`	`(trigger: DrillDownTrigger) => ReactNode \| null`	—	Render function for reactive drill content. Runs in the parent render cycle for live data.
`emptyState`	`{ message?: string; icon?: ReactNode }`	—	Default empty state template.
`errorState`	`{ message?: string }`	—	Default error state template.

Notes

Dashboard replaces the 5-provider nesting pattern. Use it as the outermost wrapper for any MetricUI dashboard.
All props are optional. Omit `filters` to skip FilterProvider entirely.
Every hook (useMetricFilters, useCrossFilter, useDrillDownAction, useLinkedHover) works inside Dashboard.
For fine-grained control (two FilterProviders, custom provider ordering), use individual providers instead.
Dashboard renders: MetricProvider → FilterProvider (if filters prop) → CrossFilterProvider → LinkedHoverProvider → DrillDownProvider + DrillDownOverlay.
The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.