Guide

Format Engine

Every MetricUI component uses a built-in format engine. Pass a shorthand string or a full config object to any format prop.

Shorthand Strings

The simplest way to format values. Pass a string to any format prop:

Shorthand	Description	Example
`"number"`	Auto-compact with K/M/B/T suffixes	"1.2K", "3.5M"
`"compact"`	Same as "number" with compact: true	"1.2K", "3.5M"
`"currency"`	Currency with compact suffixes	"$1.2K", "$3.5M"
`"percent"`	Percentage with 1 decimal	"12.5%"
`"duration"`	Human-readable duration from seconds	"5m 30s"
`"custom"`	Base format — use prefix/suffix	"12.5 items"

FormatConfig Objects

For fine control, pass an object with the fields you need:

// Currency in EUR with 2 decimals, no compacting
format={{ style: "currency", currency: "EUR", compact: false, precision: 2 }}

// Percent where input is decimal (0.12 = 12%)
format={{ style: "percent", percentInput: "decimal" }}

// Duration from milliseconds, clock style
format={{ style: "duration", durationInput: "milliseconds", durationStyle: "clock" }}

// Compact to millions only
format={{ style: "number", compact: "millions" }}

// Custom prefix/suffix
format={{ style: "number", prefix: "~", suffix: " users", compact: false }}

The fmt() Helper

Build FormatConfig objects with less boilerplate:

import { fmt } from "metricui";

format={fmt("currency", { precision: 2 })}
format={fmt("compact")}
format={fmt("percent", { percentInput: "decimal" })}

Compact Modes

Value	Behavior
`true / "auto"`	Auto-pick K/M/B/T based on magnitude
`"thousands"`	Always divide by 1,000 and append K
`"millions"`	Always divide by 1,000,000 and append M
`"billions"`	Always divide by 1,000,000,000 and append B
`"trillions"`	Always divide by 1,000,000,000,000 and append T
`false`	No compacting, show full number

Duration Styles

Styles

Style	Example
`"compact"`	"5m 30s", "2h 15m"
`"long"`	"5 minutes 30 seconds"
`"clock"`	"5:30", "2:15:30"
`"narrow"`	"5.5m", "2.3h"

Precision (smallest unit shown)

Precision	Example
`"milliseconds"`	"5m 30s 250ms"
`"seconds"`	"5m 30s" (default)
`"minutes"`	"2h 30m"
`"hours"`	"3d 4h"
`"days"`	"2w 3d"

Conditional Formatting

Use the conditions prop on KpiCard to color values based on thresholds. Rules are evaluated top-to-bottom — first match wins.

conditions={[
  { when: "above", value: 100, color: "emerald" },
  { when: "between", min: 50, max: 100, color: "amber" },
  { when: "below", value: 50, color: "red" },
]}

Operators: above, below, between, equals, not_equals, at_or_above, at_or_below

Named colors: emerald, red, amber, blue, indigo, purple, pink, cyan. Or use any CSS color string.

Compound conditions

conditions={[
  {
    when: "and",
    rules: [
      { operator: "above", value: 50 },
      { operator: "below", value: 100 },
    ],
    color: "amber",
  },
]}

Locale Integration

The format engine respects MetricProvider's locale and currency settings. Individual format configs can override with their own locale/currency fields.

<MetricProvider locale="de-DE" currency="EUR">
  <KpiCard title="Umsatz" value={142300} format="currency" />
  {/* Renders: "142,3 Tsd. €" */}
</MetricProvider>