Components · Lines

Line chart

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

Open in playground

Preview

Signups over time

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.

Install with npm install em-kit. Needs <ChartsProvider> once and a parent with a height: Quick start.

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.

tsxDiffers from Usage
Show full code (34 lines)
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 },
];
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { abbreviateLargeNumber: true, fillUnderLine: true },
});

<LineChart
  title="Signups over time"
  xAxis={startDate}
  measures={[signups]}
  results={results(rows)}
  showValueLabels={false}
/>

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.

tsxDiffers from Usage
Show full code (34 lines)
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 },
];
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { dashedLine: true, abbreviateLargeNumber: true },
});

<LineChart
  title="Signups over time"
  xAxis={startDate}
  measures={[signups]}
  results={results(rows)}
  showValueLabels={false}
/>

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.

tsxDiffers from Usage
Show full code (36 lines)
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 },
];
const startDate = dimension({
  name: 'startDate',
  title: 'Start date',
  type: 'time',
  granularity: 'month',
});
const signups = measure({
  name: 'signups',
  title: 'Signups',
  inputs: { abbreviateLargeNumber: true },
});

<LineChart
  title="Signups over time"
  xAxis={startDate}
  measures={[signups]}
  results={results(rows)}
  showValueLabels={false}
  yAxisRangeMin={2000}
  yAxisLabel="Signups"
/>

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.

tsxDiffers from Usage
Show full code (80 lines)
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,
  }));
};
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 [granularity, setGranularity] = useState<Granularity>('month');

// rowsBy(granularity: Granularity): in the full code.
<LineChart
  title="Signups over time"
  xAxis={{ ...startDate, inputs: { ...startDate.inputs, granularity } }}
  measures={[signups]}
  results={results(rowsBy(granularity))}
  setGranularity={setGranularity}
  showValueLabels={false}
/>

Props

Keyboard and screen readers: Accessibility.

PropTypeDefaultDescription
xAxisrequiredDimensionThe dimension along the x-axis. A time dimension gets gap filling and date labels.
measuresrequiredMeasure[]The numeric fields to plot, one series each. Their inputs set the formatting.
resultsrequiredDataResponseYour query’s state: { isLoading, data, error }, where data is your rows. results(rows) builds it from an array.
reverseXAxisbooleanfalseReverse the order of the x-axis.
showLegendbooleantrueShow the legend. A chart with one series shows none; entries wrap onto more lines when they do not fit.
showLogarithmicScalebooleanfalseUse a logarithmic value axis, for values that span several orders of magnitude.
showTooltipsbooleantrueShow a formatted tooltip on hover.
showValueLabelsbooleantruePrint each value on the chart.
xAxisLabelstringA title under the x-axis.
yAxisLabelstringA title beside the y-axis.
yAxisRangeMaxnumberFix the highest value on the y-axis. When unset, it fits the data.
yAxisRangeMinnumberFix 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.
xAxisMaxItemsnumberShow at most this many x values. The rest are added up into one “Other” value.
granularityGranularityOnly 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) => voidCalled 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) => voidCalled with the clicked point’s dimension value and date range.LineChartOptionsClickArg = { dimensionValue: string | number | undefined; dimensionTimeRange: TimeRange; measureValue?: number | undefined; measureValues?: Record<string, unknown> | undefined; }
componentNamestringA name for this component, included in the interaction events it dispatches on the DOM, for your analytics.
trackingIdstringAn id included in the same events, to tell two instances apart.
titlestringThe card’s title. A "key|fallback" string is looked up in your translations.
descriptionstringSmaller text under the title. Translates like title.
tooltipstringText for an info icon beside the title.
hideMenubooleanfalseHide the card’s header: the title, description and menu.
menuOptions("csv" | "xlsx" | "png" | "maximize")[]["csv", "xlsx", "png", "maximize"]Which entries the card menu offers. Pass [] for none.

A blank default means the prop is unset unless you pass it.

TypeDefinition
Granularity"second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year"
TimeRange{ from: Date | undefined; to: Date | undefined; relativeTimeString?: string; } | undefinedWhat a click’s TimeRange holds: Events.

Field options

Set in a field’s inputs, beside the common options:

OptionTypeSet onDescription
fillUnderLinebooleanmeasuresShade the area under the line.
lineColorstringmeasuresA colour for this measure’s line, in place of the theme’s.
connectGapsbooleanmeasuresDraw a missing value as zero, so the line carries on. When off, the line breaks at the gap. Default: false.
dashedLinebooleanmeasuresDraw the line dashed. Default: false.