Preparing data

The data has to meet a few criteria to ensure that each chart type works correctly and renders the expected output.

1. The data has to be an array of objects with a consistent shape.
2. Each object is one data point.
3. The data has to be sorted.
4. Date values must be in ISO 8601 format (e.g. YYYY-MM-DD).
5. Missing values must be handled explicitly.

Consistent shape

A consistent shape means that each object in the array has the same keys and types. The keys in the data objects should match the groupByKey and dataKey in the chart options.

const data = [
  { date: "2022-01-01", value: 5.3, name: "Zürich" },
  { date: "2023-01-01", value: 5.7, name: "Zürich" },
  { date: "2022-01-01", value: 4.8, name: "Winterthur" },
  { date: "2023-01-01", value: 5.1, name: "Winterthur" },
];

const options = {
  groupByKey: "name",
  xAxis: { dataKey: "date" },
  yAxis: { dataKey: "value" },
};

Each object is one data point

Each object in the data array is one data point, representing a single observation. Each chart type renders it as a single mark.

[
  { date: "2022-01-01", Winterthur: 4.8, Zürich: 5.1 },
  { date: "2022-01-01", value: 4.8, name: "Winterthur" },
  { date: "2022-01-01", value: 5.1, name: "Zürich" },
];

Sorting

The library can’t and won’t make any assumptions about what order the data should have. Therefore, the data must be sorted in a way that makes sense for your use case. For example, for a time series chart, the data should be sorted by date in ascending order.

Date values

Date values must be in ISO 8601 format (e.g., YYYY-MM-DD) to ensure proper parsing and rendering on the time axis. Don’t pass JavaScript Date objects. The library will parse the date strings internally.

Missing values

A value can be missing in two ways, and each renders differently.

If you leave a data point out of the array entirely, the chart has nothing to draw at that position. A line connects the surrounding data points as if the gap were not there.

If you set a value to null or NaN, the chart treats it as a known gap. A line chart interrupts the line and bridges the gap with a dashed segment. A bar chart draws no bar. In both cases the tooltip shows the text from tooltip.undefinedLabel.

Prefer explicit null values when your data has real gaps. It keeps the missing value visible to the reader instead of hiding it.