Data Display

Statistic

Single key metric with a label, formatted value, and optional change indicator that pairs into a statistic-group dashboard tile.

import { Statistic } from '@lostgradient/cinder/statistic';
data-displaymetric
01

Overview

Single metric tile displaying a labelled numeric value with optional trend or unit.

Choosing this component

  • Surfacing a single KPI or headline number in a dashboard or summary card (revenue, users, uptime).
  • Pairing related figures — wrap multiple Statistic tiles in StatisticGroup for consistent grid layout.
  • Showing a trend or change value alongside the primary number via the change prop.

Choosing something else

  • Code-change line counts (+/- additions and removals) — use DiffStatistics, which is purpose-built for that display.
  • Long lists of data points — use a Table or DataList instead.

Related components

  • StatisticGroup — grid wrapper for multiple Statistic tiles with shared layout.
  • DiffStatistics — specialised display for added, modified, and removed line counts.

Usage

Statistic is a compose-only leaf of StatisticGroup. The idiomatic API is StatisticGroup.Statistic, reached through the parent namespace — see the statistic-group README for the composed snippet. The flat @lostgradient/cinder/statistic subpath remains exported for à-la-carte builds that import the leaf directly.

Theming

With no theme, Statistic paints its value from --cinder-text-default and its label, icon, and change description from --cinder-text-muted, keeping the background transparent. The muted token is what separates the label from the value, so it is a real token rather than an opacity on inherited text — the label is body text and has to clear the 4.5:1 contrast floor on its own.

Pass a partial theme when a statistic needs an explicit local foreground, muted color, or background — on a custom-coloured panel, for instance. Supplying a theme switches the omitted fields back to inheriting currentColor from the surrounding application, so a partial theme never mixes your explicit colours with the global tokens: theme={{ foreground: 'white', background: 'black' }} leaves the label inheriting white rather than dropping the app's dark muted token onto a black surface. To make an unthemed-looking Statistic follow an ancestor's color instead of the tokens, ask for it explicitly with theme={{ foreground: 'currentColor', muted: 'currentColor' }}.

Change direction remains visible through its arrow glyph, signed value, description, and screen-reader text rather than color alone.

02

When to use

Use when
  • Highlighting one important number such as revenue, signups, or error rate.
  • Composing a dashboard tile alongside other Statistic instances inside statistic-group.
Avoid when
  • Conveying status with a short label or icon — use badge instead.
  • Showing tabular numeric breakdowns — use table or data-list instead.
03

Props

Props for statistic
Name
Type
Default
Description
label required text Short label describing the metric, e.g. "Monthly Revenue".
value required text The statistic. Strings rendered verbatim; numbers formatted via formatNumber.
change { /** The change magnitude as a display string, e.g. "4.75%", "+$120", "12". */ value: string; /** Direction of change — drives icon + color. */ directi…
Show full type { /** The change magnitude as a display string, e.g. "4.75%", "+$120", "12". */ value: string; /** Direction of change — drives icon + color. */ direction: StatisticChangeDirection; /** Optional visible description, e.g. "from last month". Rendered aria-hidden. */ description?: string; /** * Optional fully-worded accessible label for the change indicator. * When omitted, a phrase is synthesized from `direction` + `value` (+ optional `description`). * When provided, used verbatim — the caller owns the full wording. */ label?: string; }
 Optional change indicator with direction and accessible wording.
icon snippet Optional leading icon snippet (decorative — wrapper is aria-hidden).
theme ChartTheme Partial visual theme override. Omitted fields inherit the surrounding application.
valueFormatOptions Intl.NumberFormatOptions Intl.NumberFormat options applied only when value is a number.
valueLocale text Locale forwarded to formatNumber. Defaults to the nearest LocaleProvider locale, then en-US.
id text