Getting Started
Install MetricUI and build your first dashboard in under a minute.
Quick Start
Install the package, then run init. It detects your framework, configures your AI tools, and scaffolds a working dashboard:
npm install metricui
npx metricui initThat's it. Run your dev server and open /dashboard to see it live.
What Init Does
The init command asks two yes/no questions and sets up:
- ✓AI tool config — Cursor rules, Claude Code hints, and MCP server — so your AI coding tools know to use MetricUI
- ✓Starter dashboard — A real page in your app with KPIs, charts, and a table — using your framework's conventions
It's idempotent — running it again skips files that already exist. If you prefer to set things up manually, keep reading.
Manual Setup
If you skipped init or want to understand what it does under the hood:
npm install metricuiMetricUI requires React 18+. All chart dependencies are bundled — no extra installs needed.
CSS Setup
Import the MetricUI stylesheet in your app entry point. This sets up the required CSS variables, card variants, dark mode, and animation styles.
import "metricui/styles.css";MetricUI uses CSS custom properties for theming. The stylesheet provides sensible defaults, but you can override them — see the Theming guide.
MetricProvider
Wrap your app (or any subtree) with MetricProvider to set global defaults. Every MetricUI component reads from this context.
import { MetricProvider } from "metricui";
import "metricui/styles.css";
export default function App({ children }) {
return (
<MetricProvider
locale="en-US"
currency="USD"
animate
theme="indigo"
>
{children}
</MetricProvider>
);
}MetricProvider supports nesting — child providers merge with their parent. Only the fields you specify are overridden.
Your First Card
import { KpiCard } from "metricui";
import { DollarSign } from "lucide-react";
function RevenueCard() {
return (
<KpiCard
title="Revenue"
value={142300}
format="currency"
comparison={{ value: 128500 }}
comparisonLabel="vs last month"
icon={<DollarSign />}
/>
);
}Your First Chart
import { AreaChart } from "metricui";
const data = [
{
id: "revenue",
data: [
{ x: "Jan", y: 4200 },
{ x: "Feb", y: 5100 },
{ x: "Mar", y: 4800 },
{ x: "Apr", y: 6200 },
{ x: "May", y: 7100 },
{ x: "Jun", y: 8400 },
],
},
];
function RevenueChart() {
return (
<AreaChart
data={data}
title="Monthly Revenue"
format="currency"
height={300}
/>
);
}