MetricGrid

When to Use

Use MetricGrid as the auto-layout container for dashboards. Drop MetricUI components in and it figures out the layout — KPI cards go in equal-width rows, charts split side-by-side, tables go full width. No Tailwind grid classes, no manual column math, no responsive breakpoints to manage. Override individual items with MetricGrid.Item when the auto-layout is not what you want.

Basic Example

A typical dashboard with KPI cards, charts, and a table. MetricGrid detects each component type and assigns the right width automatically.

<MetricGrid>
  <KpiCard title="Revenue" value={78400} format="currency" comparison={{ value: 65200 }} />
  <KpiCard title="Users" value={3200} format="number" comparison={{ value: 2800 }} />
  <KpiCard title="Conversion" value={4.2} format="percent" comparison={{ value: 3.8 }} />

  <AreaChart
    data={revenueData}
    index="date"
    categories={["revenue", "cost"]}
    title="Revenue vs Cost"
    format="currency"
  />
  <BarChart
    data={channelData}
    index="channel"
    categories={["visits"]}
    title="Traffic by Channel"
  />

  <DataTable data={tableData} columns={columns} title="Top Pages" />
</MetricGrid>

MetricGrid.Section

MetricGrid.Section renders a full-width labeled divider between groups of components. It delegates to SectionHeader internally, so it supports all the same props: subtitle, description, action, badge, and border.

<MetricGrid>
  <MetricGrid.Section title="Overview" subtitle="Key metrics at a glance" />
  <KpiCard title="Revenue" value={78400} format="currency" />
  <KpiCard title="Users" value={3200} />
  <KpiCard title="Conversion" value={4.2} format="percent" />

  <MetricGrid.Section title="Trends" border />
  <AreaChart data={revenueData} index="date" categories={["revenue"]} title="Revenue Over Time" />

  <MetricGrid.Section title="Details" border />
  <DataTable data={tableData} columns={columns} title="Top Pages" />
</MetricGrid>

MetricGrid.Item

Wrap any child in MetricGrid.Item to override the auto-detected width. The span prop accepts "sm", "md", "lg", "full", or a number from 1 to 12.

<MetricGrid>
  <KpiCard title="Revenue" value={78400} format="currency" />
  <KpiCard title="Users" value={3200} />

  {/* Force this chart to full width instead of auto-pairing */}
  <MetricGrid.Item span="full">
    <AreaChart data={data} title="Revenue Over Time" />
  </MetricGrid.Item>

  <DataTable data={tableData} title="Details" />
</MetricGrid>

Auto-Detection

MetricGrid inspects each child's component type to decide how to lay it out. It checks for a static __gridHint property first, then falls back to matching the component's displayName. Unknown component types default to full width, so custom components are never broken.

To make your own custom component auto-detected, set the static __gridHint property:

import type { GridHint } from "metricui";

function MyCustomChart(props) {
  return <div>...</div>;
}
MyCustomChart.__gridHint = "chart" as GridHint;

// Now MetricGrid will treat it like any other chart

Props

MetricGrid.Section Props

MetricGrid.Item Props

Notes

• Auto-layout rules: consecutive KPIs → equal-width row, two charts → 2:1 split, single chart → full width, table → full width.
• Items in the same row always fill the space evenly. 3 KPIs = thirds, not 3 + gap.
• Unknown component types default to full width — no lock-in.
• MetricGrid.Section renders a full-width labeled divider with the same muted uppercase style.
• MetricGrid.Item accepts span='sm'|'md'|'lg'|'full' or a column count number.
• Responsive: 4 cols at lg, 2 at sm, 1 below 640px.
• Reveal-on-scroll: each grid cell animates in with a staggered 60ms fade+slide. Respects animate={false} and prefers-reduced-motion.

Related Components