Describing your data
Dimensions, measures, field options and the one response shape every chart takes.
The samples assume the ChartsProvider from step 2 of the quick start.
Charts do not guess what your columns mean. You describe each one once, as a dimension (something you group by) or a measure (a number), and reuse the description in every chart.
A dimension and a measure
This chart groups by one dimension, the plan, and plots one measure, the recurring revenue.
import { BarChart, dimension, measure, results } from 'em-kit';
// A dimension is something you group by.
const plan = dimension({ name: 'plan', title: 'Plan' });
// A measure is a number. Display options go on `inputs`.
const mrr = measure({
name: 'mrr',
title: 'Monthly recurring revenue',
inputs: { currency: 'EUR', abbreviateLargeNumber: true },
});
// Each row has one key per field name.
const rows = [
{ plan: 'Starter', mrr: 84200 },
{ plan: 'Growth', mrr: 213500 },
{ plan: 'Enterprise', mrr: 391000 },
];
export function PlanChart() {
return (
<div style={{ height: 320 }}>
<BarChart
title="Recurring revenue by plan"
dimension={plan}
measures={[mrr]}
results={results(rows)}
/>
</div>
);
}Recurring revenue by plan
Field properties
| Property | What it is |
|---|---|
name | The key the chart reads from each row. |
title | The label on axes, legends, tooltips and table headers. Defaults to name. |
type | string, number, time or boolean. Dimensions default to string and measures to number. |
granularity | Time dimensions only: second, minute, hour, day, week, month, quarter or year. See below. |
inputs | The field options below. |
Set granularity on the dimension itself, at the top level of dimension(). It formats the axis (month shows Jan 2026) and fills missing periods. See Time series.
A chart’s own granularity prop formats and fills nothing. It says which granularity the rows you pass are at now, so a click handler can turn a clicked period into a time range. Left out, it follows the dimension’s.
Field options
Field options go in a field’s inputs and apply wherever the field is shown: axes, value labels, tooltips, legends and table cells.
| Option | For | What it does |
|---|---|---|
prefix | Any field | Text before each value. prefix: '$' shows $48,200. |
suffix | Any field | Text after each value. suffix: '%' shows 12%. |
decimalPlaces | Numbers | A fixed number of decimal places. 1 shows 12.5. |
currency | Numbers | An ISO currency code such as EUR. The value is formatted as money in the reader’s locale. |
abbreviateLargeNumber | Numbers | Shortens large numbers: 1,200,000 becomes 1.2M. |
displayName | Any field | A label shown in place of title. |
maxCharacters | Text | Cuts longer text off at this length and adds .... |
displayNullAs | Any field | Text shown when a value is missing, such as n/a. |
showGranularityDropdown | Time dimensions | Shows a granularity picker in the card. See Time series. |
dateBounds | Time dimensions | { from, to }: the first and last date on the axis. The default is the range of your rows. |
ignoreEmptyDate | Time dimensions | Leaves out periods with no rows instead of showing them as gaps. |
color, lineColor | Measures | A colour for this measure’s bars or line. Bar and line charts only. |
There is no date format option: dates follow the granularity and the provider’s locale. Options that only one chart reads, such as a dashed line or a pivot total, are listed on that component’s page.
The response shape
Every component takes its rows through one prop, results. results(rows) builds it from an array, and counts as loading until rows has a value.
| Key | Type | What it is |
|---|---|---|
isLoading | boolean | Whether a request is in flight. |
data | Array of objects | Your rows. |
error | string | A message to show in place of the chart. |
total | number | The total row count, for paginated tables. |
Loading, empty and errors shows what each combination draws.