Guides

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.

PlanChart.tsx
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>
  );
}
Result

Recurring revenue by plan

Field properties

PropertyWhat it is
nameThe key the chart reads from each row.
titleThe label on axes, legends, tooltips and table headers. Defaults to name.
typestring, number, time or boolean. Dimensions default to string and measures to number.
granularityTime dimensions only: second, minute, hour, day, week, month, quarter or year. See below.
inputsThe 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.

OptionForWhat it does
prefixAny fieldText before each value. prefix: '$' shows $48,200.
suffixAny fieldText after each value. suffix: '%' shows 12%.
decimalPlacesNumbersA fixed number of decimal places. 1 shows 12.5.
currencyNumbersAn ISO currency code such as EUR. The value is formatted as money in the reader’s locale.
abbreviateLargeNumberNumbersShortens large numbers: 1,200,000 becomes 1.2M.
displayNameAny fieldA label shown in place of title.
maxCharactersTextCuts longer text off at this length and adds ....
displayNullAsAny fieldText shown when a value is missing, such as n/a.
showGranularityDropdownTime dimensionsShows a granularity picker in the card. See Time series.
dateBoundsTime dimensions{ from, to }: the first and last date on the axis. The default is the range of your rows.
ignoreEmptyDateTime dimensionsLeaves out periods with no rows instead of showing them as gaps.
color, lineColorMeasuresA 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.

KeyTypeWhat it is
isLoadingbooleanWhether a request is in flight.
dataArray of objectsYour rows.
errorstringA message to show in place of the chart.
totalnumberThe total row count, for paginated tables.

Loading, empty and errors shows what each combination draws.