Build your own chart
The toolkit the built-in charts are made from, for the charts you add yourself.
The samples assume the ChartsProvider from step 2 of the quick start.
When no component fits, build one from the toolkit the built-in charts use, imported from em-kit/build. Your chart then formats values, picks colours, fills time gaps and draws the same states as the rest.
| For | Use |
|---|---|
| Theme and translations | useChartsTheme, i18nSetup, resolveI18nProps |
| Formatting every value | getThemeFormatter(theme).data(field, value) |
| Time series | useFillGaps, getDimensionWithGranularity, getTimeRangeFromDimensionValue |
| Comparison periods | defaultComparisonPeriodOptions, getComparisonPeriodDateRange |
| Series colours | getChartColors, getDimensionMeasureColor |
| Theme tokens | getStyle, getStyleNumber |
| Card, states and menu | ChartCard, EditorCard |
| Chart.js primitives | BarChart, LineChart, PieChart, DonutChart, KpiChart |
| Data and option builders | getBarChartProData, getBarChartProOptions, getLineChartProData, getLineChartProOptions, getPieChartProData, getPieChartProOptions |
Example: a line with a target
The built-in line chart plus a dashed target line. Everything except the target dataset comes from the toolkit, which is why it matches the other charts.
import type { DataResponse, Dimension, Measure } from 'em-kit';
import {
ChartCard,
LineChart,
getLineChartProData,
getLineChartProOptions,
getStyle,
getStyleNumber,
i18nSetup,
resolveI18nProps,
useChartsTheme,
useFillGaps,
} from 'em-kit/build';
type TargetLineChartProps = {
xAxis: Dimension;
measure: Measure;
results: DataResponse;
target: number;
title?: string;
description?: string;
};
// A line chart with a flat target line: the built-in line chart plus one
// extra dataset, assembled from the same toolkit the built-in charts use.
export const TargetLineChart = (props: TargetLineChartProps) => {
const { xAxis, measure, target } = props;
const theme = useChartsTheme();
i18nSetup(theme);
const { title, description } = resolveI18nProps(props);
// Missing months become empty buckets instead of a line jumping across them.
const results = useFillGaps({ results: props.results, dimension: xAxis });
// Labels, values, colours and dashing exactly as <LineChart> does them.
const data = getLineChartProData(
{ data: results.data, dimension: xAxis, measures: [measure], hasMinMaxYAxisRange: false },
theme,
);
// The new part. A chrome colour (not a series colour) from a theme token,
// so it follows the theme and dark mode.
const targetColor = getStyle('--em-sem-text--muted', '#71717a');
const dash = getStyleNumber('--em-linechart-line-dash', '0.25rem') ?? 4;
data.datasets.push({
label: 'Target',
data: (data.labels ?? []).map(() => target),
borderColor: targetColor,
backgroundColor: targetColor,
borderDash: [dash * 2, dash],
pointRadius: 0,
pointHoverRadius: 0,
});
// The value-formatting overlay. It formats each dataset with the measure at
// the same index, so the target is listed twice to share its formatting.
// <LineChart> merges this onto its own themed base options.
const options = getLineChartProOptions(
{ data, dimension: xAxis, measures: [measure, measure] },
theme,
);
return (
<ChartCard
data={results}
dimensionsAndMeasures={[xAxis, measure]}
errorMessage={results.error}
title={title}
description={description}
>
<LineChart data={data} options={options} showLegend showTooltips />
</ChartCard>
);
};Use it like any built-in chart:
import { dimension, measure, results } from 'em-kit';
import { TargetLineChart } from './TargetLineChart';
const month = dimension({ name: 'month', title: 'Month', type: 'time', granularity: 'month' });
const revenue = measure({ name: 'revenue', title: 'Revenue', inputs: { prefix: '$' } });
const rows = [
{ month: '2026-01-01T00:00:00.000', revenue: 48200 },
{ month: '2026-02-01T00:00:00.000', revenue: 51900 },
{ month: '2026-03-01T00:00:00.000', revenue: 55400 },
{ month: '2026-04-01T00:00:00.000', revenue: 61300 },
{ month: '2026-05-01T00:00:00.000', revenue: 58700 },
{ month: '2026-06-01T00:00:00.000', revenue: 66100 },
];
export function RevenueTarget() {
return (
<div style={{ height: 340 }}>
<TargetLineChart
title="Revenue against target"
description="Monthly, with a flat target line"
xAxis={month}
measure={revenue}
results={results(rows)}
target={55000}
/>
</div>
);
}Revenue against target
Monthly, with a flat target line
Rules that keep it consistent
- Format every value with
getThemeFormatter(theme).data(field, value), so the field’s options and the locale apply. - A
Prooptions builder only formats values. Pass it asoptionsto a primitive, which merges it onto its themed base. - Take data colours from
getChartColors()andgetDimensionMeasureColor(), so a value keeps its colour across charts. Read everything else from a theme token withgetStyle()during render, so it follows theme changes. - Wrap the chart in
ChartCardand pass it the filledresults. It draws the skeleton, the empty and error states and the export menu.