M

MetricUI

MetricUI Documentation

A React component library for building data dashboards — KPI cards, charts, tables, and more with built-in formatting, theming, and data states.

npm install metricui

How MetricUI Thinks

Seven principles that shape every component. Understanding these will tell you whether MetricUI is the right tool for your project.

AI-native from day one

MetricUI ships an MCP server, llms.txt, and structured documentation designed for AI coding tools. When Claude, Cursor, or Copilot builds a dashboard, it reaches for MetricUI and gets the props right on the first try. The API is deliberately simple and consistent — because the same things that make code easy for AI to generate make it easy for you to read.

Your data, our rendering

MetricUI never fetches, caches, or transforms your data. Pass values in, get a dashboard out. REST, GraphQL, Supabase, a CSV you parsed at 2am — we don’t care where it comes from. Filters are pure UI: they tell you what the user selected, you decide what to fetch.

One data shape, any chart

Pass flat rows with an index and categories. The same data renders as an AreaChart, BarChart, DonutChart, or HeatMap — swap the component, keep your data. No more reshaping arrays for every chart library’s proprietary format.

Format once, use everywhere

Say format="currency" and every component — cards, charts, tables, tooltips — knows how to display it. Currency, percent, duration, compact notation, locale-aware. One prop replaces pages of Intl.NumberFormat boilerplate.

Every component handles failure

Loading skeletons that match the layout. Empty states with messages. Error states with retry buttons. Stale data indicators. One prop each. No wrapper components, no conditional rendering trees, no forgotten edge cases.

Set it once, override when needed

MetricProvider sets global defaults — theme, locale, currency, density, animation. Every component inherits. Any prop overrides. Nest providers for sections. You configure once at the top; components just work.

Developer-first, not config-first

Components work with zero config and get smarter as you add props. Auto-infer columns from data. Auto-detect chart series. Auto-format numbers by magnitude. Smart defaults mean your first render looks good; explicit props mean your final render looks exactly right.

Built for Real Use

Details that add up when you're shipping a product, not a prototype.

forwardRef on every component

id, data-testid, classNames on every component

Error boundaries that don’t crash your dashboard

prefers-reduced-motion respected globally

Keyboard-accessible drill-downs, sorts, and toggles

Colorblind-safe default palette

Dense mode on everything — one prop or global

Dark mode via CSS variables — zero JS

8 theme presets, custom presets via ThemePreset type

TypeScript-first — every prop, every callback, every type exported

MCP server for AI coding tools — Claude, Cursor, Copilot

200+ tests, <1s runtime

Guides

Getting StartedInstall MetricUI and build your first dashboard in minutes.Read guide Data FormatOne flat data shape works across every chart. Swap chart types without reshaping data.Read guide Format EngineCurrency, percent, duration, compact — format any value with one prop.Read guide ThemingCSS variables, presets, dark mode, custom variants.Read guide FilteringPeriod selectors, comparison modes, dimension filters — pure UI, your data.Read guide Data StatesLoading, empty, error, and stale — every component handles them.Read guide AccessibilityKeyboard navigation, ARIA, reduced motion, color blind safe.Read guide MCP ServerGive AI tools full knowledge of every component, prop, and pattern. 13 tools, 9 resources, 3 prompts.Read guide

Components

PeriodSelectorA date-range picker with preset periods, custom ranges, and comparison toggle.View docs

SegmentToggleA pill-style toggle for switching between segments with single/multi-select, icons, badges, and FilterContext integration.View docs

DropdownFilterA single or multi-select dropdown for dimension filtering with search, grouped options, count badges, and FilterContext integration.View docs

FilterTagsContext-driven filter chips that automatically display active filters from FilterProvider.View docs

KpiCardA metric card showing a single KPI with optional comparison, sparkline, goal progress, and conditional formatting.View docs

StatGroupA row/grid of mini stat cells, perfect for summary bars at the top of dashboards.View docs

AreaChartA time-series area chart with gradient fills, stacking, dual Y-axis, comparison overlays, and reference lines.View docs

LineChartA line chart — AreaChart with area fill disabled. Shows clean unbroken lines by default.View docs

BarChartA bar chart supporting vertical/horizontal layouts, grouped/stacked/percent modes, presets, comparison bars, target bars, and sorting.View docs

BarLineChartA dual-axis combo chart with bars on the left Y-axis and lines on the right Y-axis.View docs

DonutChartA donut/pie chart with center content, percentage display, arc labels, and interactive legends.View docs

SparklineA tiny inline chart (line or bar) for embedding in cards, tables, and tight spaces.View docs

DataTableA data table with sorting, pagination, search, formatting, sticky headers, pinned columns, and a footer row.View docs

BadgeA small status indicator with variant colors, dot/icon prefix, and optional dismiss button.View docs

GaugeA minimal arc gauge showing where a value sits in a range with optional threshold zones and target marker.View docs

HeatMapTwo-dimensional matrix with color intensity. Day×hour usage, correlation, activity grids.View docs

StatusIndicatorRule-based status display with threshold coloring, pulse animation, and five size modes.View docs

CalloutStyled message block with info, warning, success, and error variants. Supports data-driven rules, embedded metrics, collapsible detail, action buttons, and auto-dismiss.View docs

SectionHeaderStandalone section title with subtitle, description popover, action slot, and inline badge. For separating dashboard sections.View docs

DividerThemed horizontal or vertical rule with optional centered label or icon.View docs

FunnelConversion funnel chart showing value drop-off between stages. View docs

BulletChartBullet chart for comparing actual values against targets with qualitative range bands. View docs

WaterfallWaterfall chart showing sequential positive and negative changes from a starting value. View docs

MetricGridSmart auto-layout grid for dashboards. Drop components in, it figures out the layout from component types.View docs

DashboardHeaderTop-level dashboard identity bar with title, live/stale status, auto-ticking 'Updated Xm ago', breadcrumbs, back navigation, and action slots.View docs

FilterProviderContext provider that wires PeriodSelector, DropdownFilter, SegmentToggle, and FilterTags together into a shared filter state.View docs

CrossFilterProviderContext provider for cross-filtering. Charts with crossFilter prop emit selections; dev reads state via useCrossFilter() and filters their own data.View docs

LinkedHoverProviderSyncs hover state across sibling charts — crosshairs and tooltips move together.View docs

DrillDown.RootProvider wrapper that manages the drill-down stack and renders the overlay panel. Wrap your dashboard (or a section) in DrillDown.Root to enable drill-down on child components.View docs

FilterBarA container component for dashboard filters with auto-generated FilterTags, badge slot, collapsible accordion, active filter count, and clear-all.View docs