MetricUI

The missing UI layer for React dashboards.
KPI cards, charts, tables, and layout — with built-in formatting, theming, data states, and zero config.

Demo · Docs · Spotify Dashboard · MCP Server

Why MetricUI?

You're building a dashboard. You need KPI cards, charts, tables. You reach for Recharts + shadcn + custom CSS and spend days wiring up formatting, dark mode, loading states, and responsive layouts.

MetricUI does all of that in one import.

import { KpiCard, AreaChart, DonutChart, DataTable, MetricGrid, MetricProvider } from "metricui";
import "metricui/styles.css";

export default function Dashboard() {
  return (
    <MetricProvider theme="emerald" dense>
      <MetricGrid>
        <KpiCard title="Revenue" value={127450} format="currency" comparison={{ value: 113500 }} />
        <KpiCard title="Users" value={8420} format="number" comparison={{ value: 7680 }} />
        <KpiCard title="Conversion" value={4.8} format="percent" comparison={{ value: 4.2 }} />

        <AreaChart data={revenueData} index="month" categories={["revenue"]} title="Revenue Over Time" format="currency" />
        <DonutChart data={planBreakdown} index="plan" categories={["users"]} title="By Plan" />

        <DataTable data={customers} title="Top Customers" columns={columns} />
      </MetricGrid>
    </MetricProvider>
  );
}

Zero layout code. MetricGrid auto-detects component types — KPIs go 3-across, charts split 2:1, tables go full width. Responsive out of the box.

Install

npm install metricui

That's it. All chart dependencies are included.

Features

🎯 Smart Format Engine

One prop formats any value. Currency, percentages, durations, compact notation — with locale support.

<KpiCard value={127450} format="currency" />        // → $127.5K
<KpiCard value={4.2} format="percent" />             // → 4.2%
<KpiCard value={3725} format="duration" />           // → 1h 2m 5s
<KpiCard value={2400000} format="number" />          // → 2.4M

🎨 Theme Presets

One prop. Entire dashboard changes color.

<MetricProvider theme="emerald">   // Green accent + green-first chart palette
<MetricProvider theme="rose">      // Pink accent + pink-first chart palette
<MetricProvider theme="amber">     // Warm amber everything

8 built-in presets. Custom presets via ThemePreset type.

📐 MetricGrid — Zero Layout Code

Drop components in. It figures out the layout.

<MetricGrid>
  <MetricGrid.Section title="Overview" />
  <KpiCard ... />
  <KpiCard ... />
  <KpiCard ... />
  <AreaChart ... />          {/* Auto 2/3 width */}
  <DonutChart ... />         {/* Auto 1/3 width */}
  <DataTable ... />          {/* Auto full width */}
</MetricGrid>

3 KPIs? Equal thirds. 5 KPIs? Equal fifths. No gaps, no orphans.

⚙️ MetricProvider — Global Config

Set it once. Every component inherits.

<MetricProvider
  theme="emerald"
  variant="elevated"
  dense
  animate={false}
  locale="de-DE"
  currency="EUR"
  nullDisplay="N/A"
>
  {/* Every component reads these defaults. Props override. */}
</MetricProvider>

Nested providers merge — override just what you need for a section.

📊 Data States — Loading, Empty, Error, Stale

Every component handles data states out of the box. No conditional rendering, no wrapper components.

<KpiCard title="Revenue" value={data?.revenue} format="currency" loading={isLoading} />
<AreaChart data={chartData} title="Trends" error={{ message: "API timeout", onRetry: refetch }} />
<DataTable data={[]} columns={cols} empty={{ message: "No results match your filters" }} />

One prop per state. Skeletons match the component layout. Errors show retry buttons. Empty states are customizable.

🛡️ Error Boundaries

One chart crashes? The rest keep running.

• Dev mode: Component name, error message, actionable hint, stack trace, copy button
• Prod mode: Clean "couldn't load" + retry button
• AI debugging: data-component and data-error attributes on the DOM

🌙 Dark Mode

CSS variables. Zero config. Matches system preference or toggle manually.

♿ Accessibility

• prefers-reduced-motion kills all animations
• Global focus-visible ring on every interactive element
• ARIA attributes on charts (role="meter", aria-valuenow)
• Keyboard-accessible drill-downs and popovers

Components

Advanced Charts

MCP Server

MetricUI ships an MCP server that gives AI coding tools (Claude Code, Cursor, etc.) structured knowledge of the entire API. When an AI builds a dashboard, it reaches for MetricUI and gets the props right on the first try.

# Install globally
npm install -g @metricui/mcp-server

# Add to Claude Code
claude mcp add --transport stdio metricui -- npx -y @metricui/mcp-server

12 tools, 9 resources, 3 prompts. Full API surface.

llms.txt

Machine-readable documentation for AI models at /llms.txt. Every component, every prop, every type, every pattern.

Built With

• Nivo — chart rendering (line, bar, pie, heatmap)
• Tailwind CSS — styling (ships pre-built, Tailwind not required in your project)
• Lucide — icons
• React 18/19

License

MIT

Built for developers who care about design.