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.
{
"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().
{
"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.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}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} />;
});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;
}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": 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.