# Data format

> labels and series, pairs, point objects, gaps and time axes.

Source: https://82chart.com/en/docs/data-format/

Every chart takes one `data: { labels?, series }`. A series' `data` comes in one of three shapes.

| Shape | Example | Used for |
| --- | --- | --- |
| Numbers | `[120, 98, null, 143]` | `labels[i]` is the x. Most lines, bars and areas |
| [x, y] pairs | `[['2026-10-01', 120], ['2026-10-02', 98]]` | Time axes, series with different x values |
| Point objects | `[{ x: 3, y: 12, r: 8 }]` | Scatter plots, bubbles (`r`) |

## Series options

| Property | What it does |
| --- | --- |
| `name` | Name in the legend, tooltip and table |
| `data` | One of the shapes above |
| `type` | `'line' \| 'area' \| 'bar' \| 'scatter'`; mixing them makes a [combo](https://82chart.com/en/docs/combo/) |
| `color` | This series' color instead of the palette |
| `stack` | Series with the same name pile up (`stacked: true` puts every bar or area series in one stack) |
| `smooth` / `dashed` | Curve or dash just this series |
| `hidden` | Hidden at first (the legend shows it again) |
| `axis` | `'right'` puts it on a right y axis ([combo](https://82chart.com/en/docs/combo/), opt-in) |

## Gaps

`null` means "no value": the line breaks instead of dropping to zero. Change that with `nulls`: `'gap'` (default), `'connect'` (a dashed bridge) or `'zero'`.

```js
createChart('#chart', {
  type: 'line',
  title: 'Daily visitors',
  nulls: 'connect',
  data: {
    labels: ['Oct 14', 'Oct 15', 'Oct 16', 'Oct 17', 'Oct 18', 'Oct 19', 'Oct 20'],
    series: [{ name: 'Visitors', data: [1820, 2140, null, 2410, 2290, 1650, 1980] }],
  },
});
```

## Time axes

When labels or x values are dates (`Date`, `'2026-10'`, `'2026-10-21'`, `'2026-10-21T09:00'`) 82chart labels them to fit the spacing: `Oct`, `Oct 21`, `09:00`. Given as [x, y] pairs they make a real time axis, so missing days leave a gap of their width. Date-only strings are read as local midnight, not UTC.

```js
createChart('#chart', {
  type: 'area',
  title: 'Orders',
  data: {
    series: [{ name: 'Orders', data: [['2026-10-01', 412], ['2026-10-02', 455], ['2026-10-05', 520], ['2026-10-06', 498], ['2026-10-07', 610], ['2026-10-08', 588]] }],
  },
});
```

Pick the axis kind yourself with `xAxis: { type: 'category' | 'linear' | 'time' }`; `'category'` spaces date labels evenly.

With `type: 'time'`, numeric x values are epoch milliseconds (`Date.now()`, `getTime()`), so timestamps from a database or API can be passed as they are. Numeric x without a `type` stays a numeric axis.

```js
createChart('#chart', {
  type: 'line',
  xAxis: { type: 'time' },
  data: { series: [{ name: 'Sessions', data: [[1792800000000, 120], [1792886400000, 180], [1792972800000, 150]] }] },
});
```

## From a server or a web component

The data is plain JSON. If your server returns `{"labels": [...], "series": [...]}`, it is one `chart.update(json)`; for `<chart-82 data='...'>` it goes in the attribute as a string.