# 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](/docs/quick-start.md#2-add-the-provider).

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.

```tsx title="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:

```tsx title="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: the revenue line with a dashed line at $55,000 and “Target” in the legend.

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