Guides

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.

ForUse
Theme and translationsuseChartsTheme, i18nSetup, resolveI18nProps
Formatting every valuegetThemeFormatter(theme).data(field, value)
Time seriesuseFillGaps, getDimensionWithGranularity, getTimeRangeFromDimensionValue
Comparison periodsdefaultComparisonPeriodOptions, getComparisonPeriodDateRange
Series coloursgetChartColors, getDimensionMeasureColor
Theme tokensgetStyle, getStyleNumber
Card, states and menuChartCard, EditorCard
Chart.js primitivesBarChart, LineChart, PieChart, DonutChart, KpiChart
Data and option buildersgetBarChartProData, 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.

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

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

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 Pro options builder only formats values. Pass it as options to a primitive, which merges it onto its themed base.
  • Take data colours from getChartColors() and getDimensionMeasureColor(), so a value keeps its colour across charts. Read everything else from a theme token with getStyle() during render, so it follows theme changes.
  • Wrap the chart in ChartCard and pass it the filled results. It draws the skeleton, the empty and error states and the export menu.