Components · KPIs

KPI with comparison

A headline figure with its change against a comparison period, coloured by direction.

Open in playground

Preview

Revenue, last 30 days

$160,625
+$16,868vs Previous period
+$16,868vs Previous period

Usage

tsx
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.

tsxDiffers from Usage
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.

tsxDiffers from Usage
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.

tsxDiffers from Usage
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.

PropTypeDefaultDescription
measurerequiredMeasureThe number to show and compare. Its inputs (prefix, suffix, decimalPlaces) set the formatting.
primaryDateRangerequiredTimeRangeThe dates results covers: { from: Date, to: Date }, with an optional relativeTimeString naming a preset. Only read to work out the comparison dates for setComparisonDateRange.
resultsrequiredDataResponseYour query’s state: { isLoading, data, error }, where data is your rows. results(rows) builds it from an array.
resultsComparisonrequiredDataResponseRows for the comparison period, with the same keys as results.
comparisonDateRangerequiredTimeRangeThe dates resultsComparison covers: { from: Date, to: Date }, with an optional relativeTimeString naming a preset. Without it the change is not shown.
changeFontSizenumberFont size of the change line in pixels.
comparisonPeriodstringNames 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.
displayChangeAsPercentagebooleanfalseShow the change as a percentage instead of a difference.
fontSizenumberFont size of the headline number in pixels. By default it grows and shrinks to fit the card.
reversePositiveNegativeColorsbooleanfalseColour an increase as bad and a decrease as good, for costs or churn.
reverseTrendDirectionbooleanPoint the trend arrow the other way. When unset, the arrow follows reversePositiveNegativeColors.
percentageDecimalPlacesnumber1Decimal places on the percentage change.
displayNullAsstringText shown where a value is null, for example "–".
setComparisonDateRange(dateRange: TimeRange) => voidIf 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.
titlestringThe card’s title. A "key|fallback" string is looked up in your translations.
descriptionstringSmaller text under the title. Translates like title.
tooltipstringText for an info icon beside the title.
hideMenubooleanfalseHide the card’s header: the title, description and menu.
menuOptions("csv" | "xlsx" | "png" | "maximize")[]["csv", "xlsx", "png", "maximize"]Which entries the card menu offers. Pass [] for none.

A blank default means the prop is unset unless you pass it.

TypeDefinition
TimeRange{ from: Date | undefined; to: Date | undefined; relativeTimeString?: string; } | undefinedWhat a click’s TimeRange holds: Events.

Field options

KpiNumberComparison reads only the common options in a field’s inputs.