Line

A line shows how a measure changes across an ordered x. Each row is one position on that x. A second measure is a second line in the same chart.

When to use it

Use a line for a trend: time, or any categories that have an order. A bar is the chart for comparing totals that do not form a sequence. A pie or a donut is the chart for parts of one total. A sparkline is the small line with no axes, for a table cell or a KPI.

Line and area

There is no type: "area". A filled line is still type: "line", with mark.area set to true. Area is the page for that note.

mark.area fills under every series. A single y channel can set area: true and leave the others as lines. Revenue against target fills revenue and draws the target as a dashed line.

Several series that add up to one shape are a stacked area. That chart has its own type.

Data

Each row is one x and one or more numbers. encoding.x is the category or the time. encoding.y is a field name, or a list of channels when the chart has more than one series.

Quarterly units is one series, units, across four quarters. Revenue against target is two series, revenue and target, across twelve months. Revenue and cost is two series across six months.

A missing number leaves a gap in that series, unless mark.connectNulls is true. a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest line. version, type, and a11y.alt are required. The curve, the points, and the fill come from the line defaults, so mark can be omitted. The default curve is monotone. Points show on hover. The area is off.

spec.json
{
  "version": "1",
  "type": "line",
  "data": [
    {
      "month": "Jan",
      "revenue": 120
    },
    {
      "month": "Feb",
      "revenue": 150
    },
    {
      "month": "Mar",
      "revenue": 132
    }
  ],
  "encoding": {
    "x": "month",
    "y": "revenue"
  },
  "a11y": {
    "alt": "Revenue rose from January to February, then eased in March."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/lineBundle@chartkitdev/core/allLine gzip32,110 BFamilyCore
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing line specs. Quarterly units is one series. Revenue against target is two series, with a fill on revenue only. Deploys, step curve holds each value until the next day. Revenue and cost names the tooltip field. The area note and stacked area are the filled cousins.

Curve

mark.curve is how the line joins the points. monotone is the default. It stays inside the data, so a spike does not overshoot. linear draws straight segments. step holds the value and then jumps, which is the right curve for a count that changes and then sits still.

mark.curve
{
  "mark": { "curve": "linear" }
}
mark.curve step
{
  "mark": { "curve": "step" }
}

step-before and step-after place the jump on the other side of the point. Set those in the playground.

Points

mark.points is none, hover, or always. The default is hover: the dot appears under the pointer. always draws a dot on every point. none draws the line only. The field is mark.points, not mark.markers.

mark.points
{
  "mark": { "points": "always" }
}

Area fill

mark.area fills under every line. Omit it, or set false, and the chart is a line. Set true and the same spec is a filled line. That is the chart at /docs/charts/area.

mark.area
{
  "mark": { "area": true }
}

To fill one series and leave another as a line, set area: true on that y channel. The Area fill control writes mark.area for every series. A mixed spec, such as Revenue against target, leaves both buttons off until you choose one.

encoding.y area
{
  "encoding": {
    "y": [
      { "field": "revenue", "title": "Revenue", "area": true },
      { "field": "target", "title": "Target", "dash": "dashed" }
    ]
  }
}

Legend

A line with one series hides the legend. A line with several series shows it. Omit legend, or set true, and the legend sits on top. false hides it. legend.position is top, right, bottom, left, or inside.

legend.position
{
  "legend": { "position": "top" }
}

Tooltip

tooltip is on for a line when the key is omitted. Hovering a point shows the series and the value. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows in the card, and tooltip.position places it. Revenue and cost sets the fields. Change those in the playground. Turning the card off and on again puts that object back.

The rest of the spec

axes.x.title and axes.y.title name the axes. mark.sampling downsamples a long line. mark.strokeWidth, mark.pointShape, and mark.labelFormat refine the drawing. Theme presets live on the playground, with the full option list.