Timeline

A timeline places named marks on one date axis. An event is a point. A period is a span. Overlapping periods stack in lanes. The labels move to a free side of the axis.

When to use it

Use a timeline when the question is what happened, and which eras overlap. Northstar, 2014 to 2026 is that chart: founding, two rounds, and a platform era. Northline, year by year is the same idea for a launch pad.

A gantt is the task chart. Each row has a bar, a section, a status, and often a dependency. A timeline row is not a task. It has no progress and no elbow. A line is a measure over ordered x. It is not a list of named events.

Timeline and gantt

Both use calendar days. The mark is what changes.

type: "timeline" draws a circle for an event and a rounded bar for a period. kind is event, period, or era. A start and an end that are different days are a period when kind is omitted. kind: "event" stays a point even when start and end differ.

type: "gantt" draws a task bar from start to end, with sections and dependencies. Do not use a timeline to show that one task waits on another.

Data

Each row is one mark. label is the name. An event uses date, or start. A period uses start and end, both YYYY-MM-DD. Lumen and Co leaves kind off. Night builds is a period because the end is after the start. The other rows are events because they only have a date.

encoding.x is the label. encoding.open and encoding.close are the period ends. encoding.color can name the kind field. The defaults are label, start, end, and kind, and a date column is read when it is present. A small spec can omit encoding.

Overlapping periods take the next lane. Northstar, 2014 to 2026 stacks Series A, Remote years, and Platform when they overlap. Events share one axis. Their labels alternate above and below so neighbors do not collide.

A period with no start or no end, or an event with no date, is CK1405 from validatePhase4. There is no legend on this chart. legend is not read.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

one period
{
  "label": "Platform",
  "start": "2024-01-15",
  "end": "2026-06-01",
  "kind": "period"
}

A spec that renders

This is the smallest timeline. version, type, and a11y.alt are required. Start is an event in 2014. Span is a period from 2024 to 2026.

The chart loads from @chartkitdev/core/charts/timeline, or from @chartkitdev/core/extra. It is not in the line bundle. validate() warns CK1011 and points at validatePhase4().

spec.json
{
  "version": "1",
  "type": "timeline",
  "data": [
    {
      "label": "Start",
      "date": "2014-06-01"
    },
    {
      "label": "Span",
      "start": "2024-01-01",
      "end": "2026-01-01",
      "kind": "period"
    }
  ],
  "a11y": {
    "alt": "It starts in 2014."
  }
}

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/timelineBundle@chartkitdev/core/extraFamilyPlanning
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;

The 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 timeline specs. Northstar, 2014 to 2026 is the core example, six events and three periods. The title is the full spec title. Lumen and Co is the showcase chart from a Mermaid timeline. Northline, year by year is the launch-manifest chart. The spec has no title, so the switcher uses the showcase heading.

Tooltip

tooltip is on for a timeline when the key is omitted. Hovering an event shows the label and the day. Hovering a period shows the label and the two days. The same sentence is the SVG title. tooltip: false tells the hover card not to open. tooltip: true turns it on.

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

tooltip.fields is not read. The card is the mark label, not a field table. Turning the card off and on again puts a custom tooltip object back in the spec. The card still uses the mark label.

The rest of the spec

There is no legend to place. Period colors follow the lane, and events use the accent. legend does not add a key or hide the labels. Theme presets live on the playground.