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.

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 Required Bindable Description
label text req Short label describing the metric, e.g. "Monthly Revenue".
value string | number req 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. */ 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).
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 unknown req