Guide

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 init

That'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 metricui

MetricUI 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.

app/layout.tsx

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.

app/layout.tsx

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}
    />
  );
}

Shared Base Types

Every MetricUI component inherits from two shared type interfaces. Understanding these helps you use consistent props across the entire library.

BaseComponentProps (all components)

// Inherited by every MetricUI component
interface BaseComponentProps {
  aiContext?: string;       // Business context for AI Insights analysis
  id?: string;              // HTML id attribute
  "data-testid"?: string;   // Test id for automated testing
  className?: string;       // Additional CSS classes
}

DataComponentProps (data-displaying components)

// Inherited by KpiCard, charts, DataTable, and other data components
interface DataComponentProps extends BaseComponentProps {
  variant?: CardVariant;                    // Visual variant override
  dense?: boolean;                          // Compact layout toggle
  loading?: boolean;                        // Show loading skeleton
  empty?: { message?: string; icon?: ReactNode }; // Empty state config
  error?: { message?: string };             // Error state config
  stale?: { message?: string };             // Stale data indicator
  exportable?: boolean;                     // Enable export button
  state?: {                                 // Grouped state prop
    loading?: boolean;
    error?: { message?: string };
    empty?: { message?: string };
  };
}

You never need to import these types directly — they are built into every component's props. Set them on individual components or globally via MetricProvider.

Next Steps

Format Engine

Learn how to format currency, percent, duration, and more.

Theming

Customize colors, variants, dark mode, and presets.

Interactions

Linked hover and value flash.

Data States

Handle loading, empty, error, and stale states.

KPI Card

Deep dive into the most feature-rich component.