# Line chart

A time series with gap filling and a built-in granularity switcher.

- Component: `<LineChart />`, imported from `em-kit`
- Required props: `xAxis`, `measures` and `results`
- HTML page, with live previews: https://emkit.embeddable.com/docs/components/line-chart
- Playground (needs a browser): https://emkit.embeddable.com/docs/components/line-chart/playground

`LineChart` takes `xAxis` + `measures`. Its siblings name their fields differently: `LineChartGrouped` and `AreaChart` take `xAxis` + `groupBy` + `measure`.

## Install

```bash
npm install em-kit
pnpm add em-kit   # or, with pnpm
yarn add em-kit   # or, with yarn
bun add em-kit   # or, with bun
```

`react` and `react-dom` 19.1.1 or later are the only peer dependencies; Chart.js installs with the package. Wrap your app, or the part with charts, in `<ChartsProvider>` once: without it every chart throws `EmKit components must be rendered inside <ChartsProvider>.` Every example on this page includes `<ChartsProvider>` so that it runs on its own: if your app already has one, delete it from the example. A chart fills its parent, so the parent needs a height. In the Next.js App Router, every file that renders `ChartsProvider` or a chart starts with `'use client'`, and the provider pins the locale, `theme={{ formatter: { locale: 'en-US' } }}`, so the server and the browser format numbers alike. [The quick start](/docs/quick-start.md#in-the-nextjs-app-router) has the Next.js files.

## Usage

```tsx
import { ChartsProvider, LineChart, dimension, measure, results } from 'em-kit';

const startDate = dimension({
  name: 'startDate',
  title: 'Start date',
  type: 'time',
  granularity: 'month',
});
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { abbreviateLargeNumber: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <LineChart
        title="Signups over time"
        xAxis={startDate}
        measures={[signups]}
        results={results(rows)}
        showValueLabels={false}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { startDate: '2026-03-01T00:00:00.000', signups: 2266 },
  { startDate: '2026-04-01T00:00:00.000', signups: 2474 },
  { startDate: '2026-05-01T00:00:00.000', signups: 2945 },
  { startDate: '2026-06-01T00:00:00.000', signups: 2634 },
];
```

- The time field’s `granularity` labels the axis and fills periods with no row. For a picker in the card, set `showGranularityDropdown` on the field and pass `setGranularity` (both optional), then refetch at the granularity it reports.
- Rows are long format, one per time bucket, with zone-less ISO time strings.

## States

The chart draws its own states from `results`: a skeleton while `isLoading` is true and it has no rows, a spinner in the header while it reloads rows it already has, an empty state when `data` is `[]`, and the message when `error` is set. Pass your query’s state straight through.

## Examples

### Filled

A shaded area under the line, for a sense of volume over time. `fillUnderLine` is a field option on the measure, so each measure in `measures` can choose its own.

```tsx
import { ChartsProvider, LineChart, dimension, measure, results } from 'em-kit';

const startDate = dimension({
  name: 'startDate',
  title: 'Start date',
  type: 'time',
  granularity: 'month',
});
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { abbreviateLargeNumber: true, fillUnderLine: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <LineChart
        title="Signups over time"
        xAxis={startDate}
        measures={[signups]}
        results={results(rows)}
        showValueLabels={false}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { startDate: '2026-03-01T00:00:00.000', signups: 2266 },
  { startDate: '2026-04-01T00:00:00.000', signups: 2474 },
  { startDate: '2026-05-01T00:00:00.000', signups: 2945 },
  { startDate: '2026-06-01T00:00:00.000', signups: 2634 },
];
```

### Dashed

A dashed line, for a forecast or a target, with compact numbers on the axis. `dashedLine` and `abbreviateLargeNumber` are field options on the measure, not chart props.

```tsx
import { ChartsProvider, LineChart, dimension, measure, results } from 'em-kit';

const startDate = dimension({
  name: 'startDate',
  title: 'Start date',
  type: 'time',
  granularity: 'month',
});
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { dashedLine: true, abbreviateLargeNumber: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <LineChart
        title="Signups over time"
        xAxis={startDate}
        measures={[signups]}
        results={results(rows)}
        showValueLabels={false}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { startDate: '2026-03-01T00:00:00.000', signups: 2266 },
  { startDate: '2026-04-01T00:00:00.000', signups: 2474 },
  { startDate: '2026-05-01T00:00:00.000', signups: 2945 },
  { startDate: '2026-06-01T00:00:00.000', signups: 2634 },
];
```

### Fitted value axis

The value axis starts just below the lowest point instead of at zero, to bring out small changes. The axis starts at zero by default; `yAxisRangeMin` moves it, and `yAxisLabel` captions it.

```tsx
import { ChartsProvider, LineChart, dimension, measure, results } from 'em-kit';

const startDate = dimension({
  name: 'startDate',
  title: 'Start date',
  type: 'time',
  granularity: 'month',
});
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { abbreviateLargeNumber: true },
});

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 360 }}>
      <LineChart
        title="Signups over time"
        xAxis={startDate}
        measures={[signups]}
        results={results(rows)}
        showValueLabels={false}
        yAxisRangeMin={2000}
        yAxisLabel="Signups"
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { startDate: '2026-03-01T00:00:00.000', signups: 2266 },
  { startDate: '2026-04-01T00:00:00.000', signups: 2474 },
  { startDate: '2026-05-01T00:00:00.000', signups: 2945 },
  { startDate: '2026-06-01T00:00:00.000', signups: 2634 },
];
```

### Granularity picker

A picker in the card switches between weeks, months and quarters. `showGranularityDropdown` shows it; `setGranularity` gets the choice, which you keep in state and query again at.

```tsx
import { useState } from 'react';
import { ChartsProvider, LineChart, dimension, measure, results } from 'em-kit';
import type { Granularity } from 'em-kit';

const startDate = dimension({
  name: 'startDate',
  title: 'Start date',
  type: 'time',
  inputs: {
    showGranularityDropdown: true,
    // The picker offers the granularities with 1 to 100 periods in this range.
    dateBounds: {
      from: new Date('2026-01-05'),
      to: new Date('2026-06-28'),
    },
  },
});
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { abbreviateLargeNumber: true },
});

export const Example = () => {
  const [granularity, setGranularity] = useState<Granularity>('month');
  return (
    <ChartsProvider>
      <div style={{ height: 360 }}>
        <LineChart
          title="Signups over time"
          xAxis={{ ...startDate, inputs: { ...startDate.inputs, granularity } }}
          measures={[signups]}
          results={results(rowsBy(granularity))}
          setGranularity={setGranularity}
          showValueLabels={false}
        />
      </div>
    </ChartsProvider>
  );
};

// Signups per day from Monday 5 January 2026, as your database holds them.
const daily = [
  90, 84, 76, 93, 87, 61, 52, 93, 93, 96, 70, 83, 57, 49, 96, 83, 85, 76, 86,
  53, 65, 75, 94, 94, 96, 84, 50, 55, 89, 88, 85, 76, 79, 63, 56, 102, 85, 98,
  98, 89, 54, 50, 81, 74, 73, 82, 80, 57, 58, 99, 90, 84, 100, 87, 60, 57, 70,
  87, 71, 74, 89, 53, 60, 72, 74, 93, 72, 83, 52, 58, 69, 68, 81, 93, 80, 59,
  54, 83, 69, 70, 89, 97, 46, 57, 92, 93, 85, 77, 104, 58, 69, 83, 98, 82, 88,
  93, 51, 70, 90, 87, 98, 95, 87, 50, 51, 100, 104, 101, 110, 80, 65, 53, 87,
  84, 94, 81, 102, 71, 62, 96, 108, 105, 110, 106, 70, 74, 116, 104, 97, 106,
  107, 67, 68, 121, 100, 96, 122, 106, 71, 79, 97, 112, 111, 102, 117, 75, 67,
  104, 93, 97, 108, 89, 64, 67, 88, 92, 102, 99, 92, 69, 60, 88, 93, 102, 109,
  98, 64, 59, 98, 98, 113, 93, 100, 61, 63,
];

// The first day of the week, month or quarter that a day falls in.
const periodOf = (day: Date, granularity: Granularity) => {
  const y = day.getUTCFullYear();
  const m = day.getUTCMonth();
  let start = Date.UTC(y, m, 1);
  if (granularity === 'quarter') start = Date.UTC(y, m - (m % 3), 1);
  if (granularity === 'week') {
    start = Date.UTC(y, m, day.getUTCDate() - ((day.getUTCDay() + 6) % 7));
  }
  return new Date(start).toISOString().slice(0, 23); // drop the "Z"
};

// Stand-in for your API: the days summed into the periods the reader picks,
// each keyed by its first day.
const rowsBy = (granularity: Granularity) => {
  const sums = new Map<string, number>();
  daily.forEach((value, i) => {
    const key = periodOf(new Date(Date.UTC(2026, 0, 5 + i)), granularity);
    sums.set(key, (sums.get(key) ?? 0) + value);
  });
  return [...sums].map(([key, signups]) => ({
    'startDate': key,
    signups,
  }));
};
```

## Props

Required props come first. A blank default means the prop is unset unless you pass it.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `xAxis` | `Dimension` | yes |  | The dimension along the x-axis. A time dimension gets gap filling and date labels. |
| `measures` | `Measure[]` | yes |  | The numeric fields to plot, one series each. Their `inputs` set the formatting. |
| `results` | `DataResponse` | yes |  | Your query’s state: `{ isLoading, data, error }`, where `data` is your rows. `results(rows)` builds it from an array. |
| `reverseXAxis` | `boolean` | no | `false` | Reverse the order of the x-axis. |
| `showLegend` | `boolean` | no | `true` | Show the legend. A chart with one series shows none; entries wrap onto more lines when they do not fit. |
| `showLogarithmicScale` | `boolean` | no | `false` | Use a logarithmic value axis, for values that span several orders of magnitude. |
| `showTooltips` | `boolean` | no | `true` | Show a formatted tooltip on hover. |
| `showValueLabels` | `boolean` | no | `true` | Print each value on the chart. |
| `xAxisLabel` | `string` | no |  | A title under the x-axis. |
| `yAxisLabel` | `string` | no |  | A title beside the y-axis. |
| `yAxisRangeMax` | `number` | no |  | Fix the highest value on the y-axis. When unset, it fits the data. |
| `yAxisRangeMin` | `number` | no |  | Fix the lowest value on the y-axis. When unset, a bar, line or area chart’s axis includes zero, and a scatter or bubble chart’s fits the data. |
| `xAxisMaxItems` | `number` | no |  | Show at most this many x values. The rest are added up into one “Other” value. |
| `granularity` | `Granularity` | no |  | Only sets the size of the date range a click reports (`dimensionTimeRange`). The axis labels and the gap filling come from the time field, `dimension({ granularity })`, and this prop follows the field when left out. One of `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"`, `"month"`, `"quarter"`, `"year"`. |
| `setGranularity` | `(granularity: Granularity) => void` | no |  | Called with the granularity the reader picks in the card. The picker only shows when the time field sets `showGranularityDropdown: true` in its `inputs`. Store the value, set it as the field’s `granularity` and pass rows at that granularity. |
| `onLineClicked` | `(arg: LineChartOptionsClickArg) => void` | no |  | Called with the clicked point’s dimension value and date range. |
| `componentName` | `string` | no |  | A name for this component, included in the interaction events it dispatches on the DOM, for your analytics. |
| `trackingId` | `string` | no |  | An id included in the same events, to tell two instances apart. |
| `title` | `string` | no |  | The card’s title. A `"key\|fallback"` string is looked up in your translations. |
| `description` | `string` | no |  | Smaller text under the title. Translates like `title`. |
| `tooltip` | `string` | no |  | Text for an info icon beside the title. |
| `hideMenu` | `boolean` | no | `false` | Hide the card’s header: the title, description and menu. |
| `menuOptions` | `("csv" \| "xlsx" \| "png" \| "maximize")[]` | no | `["csv", "xlsx", "png", "maximize"]` | Which entries the card menu offers. Pass `[]` for none. |

```ts
type LineChartOptionsClickArg = { dimensionValue: string | number | undefined; dimensionTimeRange: TimeRange; measureValue?: number | undefined; measureValues?: Record<string, unknown> | undefined; }
type Granularity = "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year"
type TimeRange = { from: Date | undefined; to: Date | undefined; relativeTimeString?: string; } | undefined
```

Each is exported from `em-kit` as a type, for example `import type { LineChartOptionsClickArg } from 'em-kit'`.

A click payload’s `TimeRange` is `undefined` unless the clicked field is a time dimension, and its `relativeTimeString` is always `undefined`, so read it as `range?.from`. When you pass one, `from` and `to` are enough.

## Field options

Options go in a field’s `inputs`, for example `measure({ name: 'revenue', inputs: { prefix: '$' } })`. Every field takes `prefix`, `suffix`, `decimalPlaces`, `currency`, `abbreviateLargeNumber`, `displayName` and `maxCharacters`. A time dimension in `xAxis` also takes `granularity`, `showGranularityDropdown`, `dateBounds` and `ignoreEmptyDate`. Its `granularity` is what labels the axis as dates and fills periods with no row; `dimension()` takes it in `inputs` or at the top level, `dimension({ granularity: 'month' })`. [Field options](/docs/describing-your-data.md#field-options) describes them. `LineChart` also reads:

| Option | Type | Set on | Default | Description |
|---|---|---|---|---|
| `fillUnderLine` | `boolean` | `measures` |  | Shade the area under the line. |
| `lineColor` | `string` | `measures` |  | A colour for this measure’s line, in place of the theme’s. |
| `connectGaps` | `boolean` | `measures` | `false` | Draw a missing value as zero, so the line carries on. When off, the line breaks at the gap. |
| `dashedLine` | `boolean` | `measures` | `false` | Draw the line dashed. |
