KPI explained

A figure with its meaning, formula, source, freshness and host-defined thresholds.

Web · ✓Mobile · n/aDesktop · ✓BetaBlocks

import { KpiExplained } from "@krizaka/ui/kpi-explained";

Ventes du mois

Dans les attentes

6 994,46 $

Ce montant est entré dans la caisse en mars, avant les remboursements.

Calcul: Ventes TTC − remboursements
Source: export-mars.csvVérifier

Lu: 31 mars 2026, 18 h 00

Web only — React, from @krizaka/ui/kpi-explained. Beta: its API may still change in a minor version.

Mobile · n/a. The native twin is a follow-up; compose the same data in a native screen for now. → Stat

Why it is here. Akinaza's shop dashboard: monthly sales, spend and margin explained with their source and cadence; Orazaka later.

When to use

A shop owner needs to understand a monthly figure, not just read a number.
A dashboard must show the origin and age of a key figure.

When not to use

A value needs only a label and a trend.Use instead: Stat
A reader needs to change or enter the value.Use instead: Field

Installation

Install

npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcss

Styles

@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";

Import

import { KpiExplained } from "@krizaka/ui/kpi-explained";

Examples

A salon's month

A shop owner's revenue figure, explained in French with its source and read cadence.

Ventes du mois

Dans les attentes

6 994,46 $

Ce montant est entré dans la caisse en mars, avant les remboursements.

Calcul: Ventes TTC − remboursements
Source: export-mars.csvVérifier

Lu: 31 mars 2026, 18 h 00

A founder's cockpit

A masked figure for a public capture, without exposing its raw value.

Dépenses mensuelles

À surveiller

• •••••• •

Le total des factures payées ce mois-ci.

Calcul: Factures payées, taxes incluses
Source: ledger/octobre.csv

Lu: 22 oct. 2026, 12 h 00

Props

A key figure that explains what it means, how it is calculated and where it came from.

Prop	Type	Default	Description
`format`required	`KpiFormat`	—	How to format the value with `@krizaka/intl`.
`formula`required	`string`	—	The calculation in words, e.g. “dépenses TTC ÷ ventes TTC”.
`formulaLabel`required	`ReactNode`	—	The localized label for the formula row.
`freshness`required	`{ lastRead: DateInput; expectedAt: DateInput; now: DateInput; lastReadLabel: ReactNode; staleLabel: ReactNode; }`	—	Reading time and the expected next reading time (the host derives it from its cadence).
`label`required	`ReactNode`	—	The figure's name.
`locale`required	`Locale`	—	The app's locale, e.g. `fr-CA`.
`maskedLabel`required	`string`	—	The accessible name shown instead of the value when masked.
`meaning`required	`string`	—	One plain-language sentence about what the figure means.
`source`required	`ReactNode`	—	The source link or file name, supplied by the host.
`sourceLabel`required	`ReactNode`	—	The localized label for the source row.
`stateLabels`required	`Record<KpiState, ReactNode>`	—	Host-provided words for the derived state.
`thresholds`required	`{ direction: "above" \| "below"; watchAt: number; actAt: number; }`	—	Host-provided thresholds in the same units as `value`.
`value`required	`number`	—	The raw number: money is integer minor units; percentages are ratios such as 0.125.
`masked`	`boolean`	`false`	Replace every non-space character in the value while preserving its formatted shape.
`sparkline`	`ReactNode`	—	An optional Sparkline from `@krizaka/charts`, with its own accessible summary.
`timeZone`	`string`	`UTC`	The IANA time zone for freshness dates; defaults to UTC for deterministic rendering.
`verify`	`ReactNode`	—	A host-provided action such as “Verify”, next to the source.

Accessibility

The state and stale words remain visible; colour is never the only signal.
When masked, the figure is replaced in the DOM and its accessible name is maskedLabel.

Keyboard

Keys	Action
`Tab`	Moves to the optional source and verify actions.

Best practices

Give the meaning and formula in the host's plain language; thresholds and state words come from the host too.
Pass the expected read time derived from the host's cadence and an injected now for stable rendering.
Pass the host's IANA time zone for freshness dates; the default is UTC.
Pass a Sparkline from @krizaka/charts in sparkline; it owns its accessible summary.

Generated from the code of @krizaka/ui 3.63.1: its meta.ts, its examples and its types.Edit this documentation on GitHub