Guide

Theming

MetricUI uses CSS custom properties for theming, making it compatible with any CSS framework or design system.

CSS Variables

Set these on your root element (or any parent container):

:root {
  --background: #ffffff;
  --foreground: #0f172a;
  --card-bg: #ffffff;
  --card-border: #e2e8f0;
  --card-glow: #f8fafc;
  --muted: #64748b;
  --accent: #6366f1;
  --font-mono: "JetBrains Mono", "Fira Code", monospace;
}

.dark {
  --background: #0f172a;
  --foreground: #f1f5f9;
  --card-bg: #1e293b;
  --card-border: #334155;
  --card-glow: #1e293b;
  --muted: #94a3b8;
  --accent: #818cf8;
}

Variable	Purpose
`--background`	Page background color
`--foreground`	Primary text color
`--card-bg`	Card/container background
`--card-border`	Card border and divider color
`--card-glow`	Hover/ghost variant background tint
`--muted`	Secondary/muted text color
`--accent`	Primary accent color
`--font-mono`	Monospace font family for values

Theme Presets

MetricUI includes 8 built-in theme presets. Pass a preset name to MetricProvider:

<MetricProvider theme="emerald">

Available presets: indigo (default), emerald, rose, amber, cyan, violet, slate, orange. Each preset sets the accent color and an 8-color chart palette.

Card Variants

Four built-in variants control card appearance via CSS custom properties:

Variant	Description
`default`	Clean bordered card with card background
`outlined`	Transparent background, 2px border, inset shadow
`ghost`	Accent-tinted background, no border
`elevated`	Card background with multi-layer shadow, no visible border

Custom Variants

Create custom variants by defining CSS variables under a [data-variant="..."] selector:

/* CSS */
[data-variant="glass"] {
  --mu-card-bg: rgba(255,255,255,0.08);
  --mu-card-border: rgba(255,255,255,0.15);
  --mu-card-border-w: 1px;
  --mu-card-shadow: 0 8px 32px rgba(0,0,0,0.1);
  --mu-card-radius: 1rem;
  backdrop-filter: blur(12px);
}

// Use it on any component
<KpiCard variant="glass" title="Revenue" value={42000} format="currency" />
<MetricProvider variant="glass">{children}</MetricProvider>

Dark Mode

MetricUI detects dark mode via the dark class on the document. All components automatically adapt using the CSS variables. Simply toggle the .dark class on your <html> or <body> element.

Dense Mode

Enable compact layouts globally or per-component. Dense mode reduces padding, font sizes, and chart heights.

// Global
<MetricProvider dense>

// Per-component
<KpiCard dense title="Revenue" value={42000} />

Chart Colors

Override the default 8-color series palette via MetricProvider:

<MetricProvider colors={["#3B82F6", "#EF4444", "#10B981", "#F59E0B"]}>
  {children}
</MetricProvider>

The default palette is colorblind-safe: indigo, cyan, amber, pink, emerald, orange, violet, teal.

Motion / Animation

Animation timing uses spring physics via MotionConfig:

import { DEFAULT_MOTION_CONFIG } from "metricui";

// Slower, bouncier animations
<MetricProvider motionConfig={{ mass: 1.5, tension: 120, friction: 20, clamp: false }}>

// Faster, snappier animations
<MetricProvider motionConfig={{ mass: 0.8, tension: 250, friction: 30, clamp: true }}>

// Disable all animation
<MetricProvider animate={false}>

MetricUI respects prefers-reduced-motion automatically.