KPI with comparison
A headline figure with its change against a comparison period, coloured by direction.
Preview
Revenue, last 30 days
Usage
import { ChartsProvider, KpiNumberComparison, measure, results } from 'em-kit';
const revenue = measure({
name: 'revenue',
title: 'Revenue',
inputs: { currency: 'USD', decimalPlaces: 0 },
});
export const Example = () => (
<ChartsProvider>
<div style={{ width: 360, height: 200 }}>
<KpiNumberComparison
title="Revenue, last 30 days"
measure={revenue}
results={results(currentRows)}
resultsComparison={results(previousRows)}
comparisonPeriod="Previous period"
primaryDateRange={currentRange}
comparisonDateRange={previousRange}
/>
</div>
</ChartsProvider>
);
const currentRange = {
from: new Date('2026-06-01'),
to: new Date('2026-06-30'),
};
const previousRange = {
from: new Date('2026-05-02'),
to: new Date('2026-05-31'),
};
const currentRows = [{ revenue: 160625 }];
const previousRows = [{ revenue: 143757 }];Install with npm install em-kit. Needs <ChartsProvider> once and a parent with a height: Quick start.
Examples
Change as a percentage
The change as a percentage of the earlier figure, instead of an amount in the measure’s own format. displayChangeAsPercentage switches to a percentage, to one decimal place.
Show full code (36 lines)
import { ChartsProvider, KpiNumberComparison, measure, results } from 'em-kit';
const revenue = measure({
name: 'revenue',
title: 'Revenue',
inputs: { currency: 'USD', decimalPlaces: 0 },
});
export const Example = () => (
<ChartsProvider>
<div style={{ width: 360, height: 200 }}>
<KpiNumberComparison
title="Revenue, last 30 days"
measure={revenue}
results={results(currentRows)}
resultsComparison={results(previousRows)}
comparisonPeriod="Previous period"
primaryDateRange={currentRange}
comparisonDateRange={previousRange}
displayChangeAsPercentage
/>
</div>
</ChartsProvider>
);
const currentRange = {
from: new Date('2026-06-01'),
to: new Date('2026-06-30'),
};
const previousRange = {
from: new Date('2026-05-02'),
to: new Date('2026-05-31'),
};
const currentRows = [{ revenue: 160625 }];
const previousRows = [{ revenue: 143757 }];<KpiNumberComparison
title="Revenue, last 30 days"
measure={revenue}
results={results(currentRows)}
resultsComparison={results(previousRows)}
comparisonPeriod="Previous period"
primaryDateRange={currentRange}
comparisonDateRange={previousRange}
displayChangeAsPercentage
/>Lower is better
For costs, churn or response times: a rise shows red and a fall shows green. reversePositiveNegativeColors swaps the colours. reverseTrendDirection={false} keeps the arrow pointing the way the number moved; without it the arrow flips with the colours.
Show full code (37 lines)
import { ChartsProvider, KpiNumberComparison, measure, results } from 'em-kit';
const churnRate = measure({
name: 'churn_rate',
title: 'Churn rate',
inputs: { suffix: '%', decimalPlaces: 1 },
});
export const Example = () => (
<ChartsProvider>
<div style={{ width: 360, height: 200 }}>
<KpiNumberComparison
title="Churn rate, last 30 days"
measure={churnRate}
results={results(currentRows)}
resultsComparison={results(previousRows)}
comparisonPeriod="Previous period"
primaryDateRange={currentRange}
comparisonDateRange={previousRange}
reversePositiveNegativeColors
reverseTrendDirection={false}
/>
</div>
</ChartsProvider>
);
const currentRange = {
from: new Date('2026-06-01'),
to: new Date('2026-06-30'),
};
const previousRange = {
from: new Date('2026-05-02'),
to: new Date('2026-05-31'),
};
const currentRows = [{ churn_rate: 2.5 }];
const previousRows = [{ churn_rate: 2.7 }];const churnRate = measure({
name: 'churn_rate',
title: 'Churn rate',
inputs: { suffix: '%', decimalPlaces: 1 },
});
<KpiNumberComparison
title="Churn rate, last 30 days"
measure={churnRate}
results={results(currentRows)}
resultsComparison={results(previousRows)}
comparisonPeriod="Previous period"
primaryDateRange={currentRange}
comparisonDateRange={previousRange}
reversePositiveNegativeColors
reverseTrendDirection={false}
/>
const currentRows = [{ churn_rate: 2.5 }];
const previousRows = [{ churn_rate: 2.7 }];Two decimals
A percentage change to two decimal places, for metrics that move by fractions of a percent. percentageDecimalPlaces only applies with displayChangeAsPercentage.
Show full code (37 lines)
import { ChartsProvider, KpiNumberComparison, measure, results } from 'em-kit';
const revenue = measure({
name: 'revenue',
title: 'Revenue',
inputs: { currency: 'USD', decimalPlaces: 0 },
});
export const Example = () => (
<ChartsProvider>
<div style={{ width: 360, height: 200 }}>
<KpiNumberComparison
title="Revenue, last 30 days"
measure={revenue}
results={results(currentRows)}
resultsComparison={results(previousRows)}
comparisonPeriod="Previous period"
primaryDateRange={currentRange}
comparisonDateRange={previousRange}
displayChangeAsPercentage
percentageDecimalPlaces={2}
/>
</div>
</ChartsProvider>
);
const currentRange = {
from: new Date('2026-06-01'),
to: new Date('2026-06-30'),
};
const previousRange = {
from: new Date('2026-05-02'),
to: new Date('2026-05-31'),
};
const currentRows = [{ revenue: 160625 }];
const previousRows = [{ revenue: 143757 }];<KpiNumberComparison
title="Revenue, last 30 days"
measure={revenue}
results={results(currentRows)}
resultsComparison={results(previousRows)}
comparisonPeriod="Previous period"
primaryDateRange={currentRange}
comparisonDateRange={previousRange}
displayChangeAsPercentage
percentageDecimalPlaces={2}
/>Props
Keyboard and screen readers: Accessibility.
| Prop | Type | Default | Description |
|---|---|---|---|
measurerequired | Measure | The number to show and compare. Its inputs (prefix, suffix, decimalPlaces) set the formatting. | |
primaryDateRangerequired | TimeRange | The dates results covers: { from: Date, to: Date }, with an optional relativeTimeString naming a preset. Only read to work out the comparison dates for setComparisonDateRange. | |
resultsrequired | DataResponse | Your query’s state: { isLoading, data, error }, where data is your rows. results(rows) builds it from an array. | |
resultsComparisonrequired | DataResponse | Rows for the comparison period, with the same keys as results. | |
comparisonDateRangerequired | TimeRange | The dates resultsComparison covers: { from: Date, to: Date }, with an optional relativeTimeString naming a preset. Without it the change is not shown. | |
changeFontSize | number | Font size of the change line in pixels. | |
comparisonPeriod | string | Names the comparison under the number (“vs previous period”, translated). One of "Previous period", "Previous week", "Previous month", "Previous quarter", "Previous year", "Same period last week", "Same period last month", "Same period last quarter", "Same period last year"; any other string leaves the name empty. | |
displayChangeAsPercentage | boolean | false | Show the change as a percentage instead of a difference. |
fontSize | number | Font size of the headline number in pixels. By default it grows and shrinks to fit the card. | |
reversePositiveNegativeColors | boolean | false | Colour an increase as bad and a decrease as good, for costs or churn. |
reverseTrendDirection | boolean | Point the trend arrow the other way. When unset, the arrow follows reversePositiveNegativeColors. | |
percentageDecimalPlaces | number | 1 | Decimal places on the percentage change. |
displayNullAs | string | Text shown where a value is null, for example "–". | |
setComparisonDateRange | ( | If set, the card works out the comparison dates from primaryDateRange and comparisonPeriod and calls this with them, so you can query them. When it cannot work them out, it calls this with no range. | |
title | string | The card’s title. A "key|fallback" string is looked up in your translations. | |
description | string | Smaller text under the title. Translates like title. | |
tooltip | string | Text for an info icon beside the title. | |
hideMenu | boolean | false | Hide the card’s header: the title, description and menu. |
menuOptions | ( | ["csv", | Which entries the card menu offers. Pass [] for none. |
A blank default means the prop is unset unless you pass it.
| Type | Definition |
|---|---|
TimeRange | { from: Date |What a click’s TimeRange holds: Events. |
Field options
KpiNumberComparison reads only the common options in a field’s inputs.