Skip to content
Kimenpre-v1documentation home
Color scheme

ki-stat

Use a stat for one measurement in a dashboard or report. Set direction to lower-is-better for rates such as render time or error count, or neutral when a change carries no judgment. The sign of delta determines the glyph.

Theme for this example
Color scheme for this example
<ki-stat label="Median render time" value="84" unit="ms" delta="-9" delta-label="vs last week" direction="lower-is-better"></ki-stat>

Number formatting

Use lang on the page or a surrounding region to choose the number locale. Assign format and deltaFormat as JavaScript properties with Intl.NumberFormatOptions. The delta inherits format unless it has its own options. A decimal reading uses unit as a suffix. Percent, currency and Intl unit styles supply their own symbols.

Accessibility

Supply a localized metric label and comparison period. Localize up-label and down-label when the page uses a language other than English. A screen reader can read the metric and comparison as one phrase. The stat itself adds no tab stop. Give any sparkline in the chart slot a separate text equivalent when it adds information.

API reference

When to use: Summarize one numeric metric in a dashboard or report. Set direction to lower-is-better for metrics such as latency and neutral for changes that carry no favorable or unfavorable meaning.

When not to use: Present a sequence of readings or inspect multiple data points. Use a chart or table with a text equivalent for that data.

Properties & attributes

AttributePropertyTypeDefaultDescription
deltadeltanumber | undefined–Optional finite change. Its sign determines the trend and its magnitude is displayed.
delta-labeldeltaLabelstring | undefined–Localized comparison period, such as "vs last week".
directiondirection"higher-is-better" | "lower-is-better" | "neutral"'higher-is-better'Which direction is favorable for this metric. Use neutral to avoid a judgment.
down-labeldownLabelstring'down'Localized spoken direction for a negative delta.
labellabelstring–Localized name of the metric, such as "Median render time".
unitunitstring | undefined–Literal suffix for decimal readings, such as "ms".
up-labelupLabelstring'up'Localized spoken direction for a positive delta.
valuevaluenumber–Current finite reading.

Slots

SlotDescription
chartAn optional sparkline after the summary. Give informative charts a textual equivalent, and hide charts that repeat the summary.

CSS parts

PartDescription
cardThe surface containing the metric and chart.
comparisonThe optional row with delta and reference period.
deltaThe trend glyph and formatted comparison magnitude.
labelThe visible metric label.
referenceThe visible comparison period.
trendThe decorative rising or falling trend glyph.
valueThe formatted current reading and its unit.

CSS custom properties

The public styling contract of ki-stat: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-stat-backdrop-filterComplete optional filter behind the metric surface.
--ki-stat-bgRaised surface of the metric card.
--ki-stat-bg-imageOptional image layered over the metric surface.
--ki-stat-borderSubtle metric card outline.
--ki-stat-border-widthWidth of the metric card outline.
--ki-stat-delta-danger-fgInk of an unfavorable comparison.
--ki-stat-delta-line-heightLine height of the comparison.
--ki-stat-delta-neutral-fgInk of an unchanged or ungraded comparison.
--ki-stat-delta-sizeText size of the comparison.
--ki-stat-delta-success-fgInk of a favorable comparison.
--ki-stat-emphasis-weightWeight of the main reading and comparison magnitude.
--ki-stat-gapSpace between the reading and comparison or chart.
--ki-stat-label-fgInk of the metric label and comparison period.
--ki-stat-label-line-heightLine height of the metric label.
--ki-stat-label-sizeText size of the metric label.
--ki-stat-paddingInsets around the metric and chart.
--ki-stat-radiusCorner radius of the metric card.
--ki-stat-trend-gapSpace between the trend glyph and comparison magnitude.
--ki-stat-trend-sizeSize of the rising or falling trend glyph.
--ki-stat-value-fgInk of the main reading.
--ki-stat-value-font-familyTypeface of the main reading.
--ki-stat-value-letter-spacingSpacing between digits in the main reading.
--ki-stat-value-line-heightLine height of the main reading.
--ki-stat-value-sizeSize of the main reading.
--ki-typography-family-bodysemantic font family for typography family body.

Workshop

Open ki-stat in Storybook