ki-stat
@kimen/elements/ki-stat- Source
- Agent reference
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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
delta | delta | number | undefined | – | Optional finite change. Its sign determines the trend and its magnitude is displayed. |
delta-label | deltaLabel | string | undefined | – | Localized comparison period, such as "vs last week". |
direction | direction | "higher-is-better" | "lower-is-better" | "neutral" | 'higher-is-better' | Which direction is favorable for this metric. Use neutral to avoid a judgment. |
down-label | downLabel | string | 'down' | Localized spoken direction for a negative delta. |
label | label | string | – | Localized name of the metric, such as "Median render time". |
unit | unit | string | undefined | – | Literal suffix for decimal readings, such as "ms". |
up-label | upLabel | string | 'up' | Localized spoken direction for a positive delta. |
value | value | number | – | Current finite reading. |
Slots
| Slot | Description |
|---|---|
chart | An optional sparkline after the summary. Give informative charts a textual equivalent, and hide charts that repeat the summary. |
CSS parts
| Part | Description |
|---|---|
card | The surface containing the metric and chart. |
comparison | The optional row with delta and reference period. |
delta | The trend glyph and formatted comparison magnitude. |
label | The visible metric label. |
reference | The visible comparison period. |
trend | The decorative rising or falling trend glyph. |
value | The 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.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-stat-backdrop-filter | Complete optional filter behind the metric surface. |
--ki-stat-bg | Raised surface of the metric card. |
--ki-stat-bg-image | Optional image layered over the metric surface. |
--ki-stat-border | Subtle metric card outline. |
--ki-stat-border-width | Width of the metric card outline. |
--ki-stat-delta-danger-fg | Ink of an unfavorable comparison. |
--ki-stat-delta-line-height | Line height of the comparison. |
--ki-stat-delta-neutral-fg | Ink of an unchanged or ungraded comparison. |
--ki-stat-delta-size | Text size of the comparison. |
--ki-stat-delta-success-fg | Ink of a favorable comparison. |
--ki-stat-emphasis-weight | Weight of the main reading and comparison magnitude. |
--ki-stat-gap | Space between the reading and comparison or chart. |
--ki-stat-label-fg | Ink of the metric label and comparison period. |
--ki-stat-label-line-height | Line height of the metric label. |
--ki-stat-label-size | Text size of the metric label. |
--ki-stat-padding | Insets around the metric and chart. |
--ki-stat-radius | Corner radius of the metric card. |
--ki-stat-trend-gap | Space between the trend glyph and comparison magnitude. |
--ki-stat-trend-size | Size of the rising or falling trend glyph. |
--ki-stat-value-fg | Ink of the main reading. |
--ki-stat-value-font-family | Typeface of the main reading. |
--ki-stat-value-letter-spacing | Spacing between digits in the main reading. |
--ki-stat-value-line-height | Line height of the main reading. |
--ki-stat-value-size | Size of the main reading. |
--ki-typography-family-body | semantic font family for typography family body. |