A featured statistic with its label, change and the context that gives it meaning.
Annotated timeline
A vertical sequence of dated events along a rail, each with a short explanation and, optionally, a small chart or figure.
- Use when
- Telling how something unfolded when the events matter more than a continuous measure: a policy history, an incident, a product's milestones. Four to eight events; give a figure only to the ones where a number changed.
- Avoid when
- Events that should be read against a time scale, with gaps and overlaps to scale (use timeline chart); a continuous series with a few annotated moments (use line chart with
annotations); ordered steps that are not dated (use section withstep).
Preview
The ECB raised its deposit rate from −0.5% to 4% between July 2022 and September 2023
Euro area deposit facility rate and annual inflation, 2021 to 2024
July 2021Inflation reaches 2.2%
The ECB's target is 2%. The bank kept its deposit rate at −0.5%.
July 2022The deposit rate rises from −0.5% to 0%
This was the ECB's first rate rise in eleven years. Inflation was 8.9%.
Annual inflation, July 20228.9%The target is 2%October 2022Inflation reaches 10.6%
This was the highest monthly figure of 2022. The ECB raised rates by 0.75 points at each of two consecutive meetings.
September 2023The deposit rate reaches 4%
This was the tenth rise in a row. Inflation was 4.3%.
June 2024The deposit rate is cut to 3.75%
The cut was 0.25 points. Inflation was 2.5%.
Source: European Central Bank; Eurostat · Figures are approximate, for illustration
import { AnnotatedTimeline, registerAll } from "insightcharts";
// The slot props below are JSON specs. This makes their `type` names resolvable.
registerAll();
export function Example() {
return (
<AnnotatedTimeline
title="The ECB raised its deposit rate from −0.5% to 4% between July 2022 and September 2023"
subtitle="Euro area deposit facility rate and annual inflation, 2021 to 2024"
events={[
{
date: "July 2021",
title: "Inflation reaches 2.2%",
text: "The ECB's target is 2%. The bank kept its deposit rate at −0.5%.",
},
{
date: "July 2022",
title: "The deposit rate rises from −0.5% to 0%",
emphasis: true,
text: "This was the ECB's first rate rise in eleven years. Inflation was 8.9%.",
figure: {
type: "big-number",
value: "8.9%",
label: "Annual inflation, July 2022",
context: "The target is 2%",
},
},
{
date: "October 2022",
title: "Inflation reaches 10.6%",
text: "This was the highest monthly figure of 2022. The ECB raised rates by 0.75 points at each of two consecutive meetings.",
figure: {
type: "sparkline",
data: [
{ month: "2022-01", rate: 5.1 },
{ month: "2022-02", rate: 5.9 },
{ month: "2022-03", rate: 7.4 },
{ month: "2022-04", rate: 7.4 },
{ month: "2022-05", rate: 8.1 },
{ month: "2022-06", rate: 8.6 },
{ month: "2022-07", rate: 8.9 },
{ month: "2022-08", rate: 9.1 },
{ month: "2022-09", rate: 9.9 },
{ month: "2022-10", rate: 10.6 },
{ month: "2022-11", rate: 10.1 },
{ month: "2022-12", rate: 9.2 },
],
x: "month",
y: "rate",
format: "{value}%",
extremes: true,
showValue: true,
style: { maxWidth: 260 },
},
},
{
date: "September 2023",
title: "The deposit rate reaches 4%",
text: "This was the tenth rise in a row. Inflation was 4.3%.",
},
{
date: "June 2024",
title: "The deposit rate is cut to 3.75%",
emphasis: true,
text: "The cut was 0.25 points. Inflation was 2.5%.",
},
]}
source="European Central Bank; Eurostat"
note="Figures are approximate, for illustration"
/>
);
}{
"type": "annotated-timeline",
"title": "The ECB raised its deposit rate from −0.5% to 4% between July 2022 and September 2023",
"subtitle": "Euro area deposit facility rate and annual inflation, 2021 to 2024",
"events": [
{
"date": "July 2021",
"title": "Inflation reaches 2.2%",
"text": "The ECB's target is 2%. The bank kept its deposit rate at −0.5%."
},
{
"date": "July 2022",
"title": "The deposit rate rises from −0.5% to 0%",
"emphasis": true,
"text": "This was the ECB's first rate rise in eleven years. Inflation was 8.9%.",
"figure": {
"type": "big-number",
"value": "8.9%",
"label": "Annual inflation, July 2022",
"context": "The target is 2%"
}
},
{
"date": "October 2022",
"title": "Inflation reaches 10.6%",
"text": "This was the highest monthly figure of 2022. The ECB raised rates by 0.75 points at each of two consecutive meetings.",
"figure": {
"type": "sparkline",
"data": [
{ "month": "2022-01", "rate": 5.1 },
{ "month": "2022-02", "rate": 5.9 },
{ "month": "2022-03", "rate": 7.4 },
{ "month": "2022-04", "rate": 7.4 },
{ "month": "2022-05", "rate": 8.1 },
{ "month": "2022-06", "rate": 8.6 },
{ "month": "2022-07", "rate": 8.9 },
{ "month": "2022-08", "rate": 9.1 },
{ "month": "2022-09", "rate": 9.9 },
{ "month": "2022-10", "rate": 10.6 },
{ "month": "2022-11", "rate": 10.1 },
{ "month": "2022-12", "rate": 9.2 }
],
"x": "month",
"y": "rate",
"format": "{value}%",
"extremes": true,
"showValue": true,
"style": { "maxWidth": 260 }
}
},
{
"date": "September 2023",
"title": "The deposit rate reaches 4%",
"text": "This was the tenth rise in a row. Inflation was 4.3%."
},
{
"date": "June 2024",
"title": "The deposit rate is cut to 3.75%",
"emphasis": true,
"text": "The cut was 0.25 points. Inflation was 2.5%."
}
],
"source": "European Central Bank; Eurostat",
"note": "Figures are approximate, for illustration"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Composition
Built from
The pieces annotated timeline renders or expects in its slots.
Atoms
4A readable block of narration at a 45-75 character measure, for the text between charts.
A word-sized line or bar series without axes, with the latest point marked.
A numbered chapter or step heading ("01 — Electricity sources in 2015") for sequencing the sections of a story.
Used in
1 template uses annotated timeline.
Templates
1A story told in date order. It has a headline, one overview exhibit of the whole period (a timeline chart or an annotated line), dated chapters along a rail, a closing paragraph and a source note. Each chapter has a short text and an optional small exhibit.
Installation
$ pnpm dlx shadcn@latest add @insightcharts/annotated-timelineThe CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:
import { AnnotatedTimeline } from "insightcharts";Examples
Figures at the side
2015The Paris Agreement is signed
Solar supplied 2.9% of EU electricity. Coal supplied 24.6%.
Solar share of EU electricity2.9%2019Solar module prices are half their 2015 level
New utility-scale solar costs less than new gas plants in southern Europe.
2022The EU adds 41 GW of solar capacity
Gas prices rose sharply in 2022. Solar installations were 47% higher than in 2021.
Solar capacity added in the EU41 GW+47% vs 20212024Solar supplies 11.1% of EU electricity
Coal supplied 9.8%.
Solar share of EU electricity11.1%Coal supplied 9.8%
Source: Ember; SolarPower Europe · Figures are approximate, for illustration
import { AnnotatedTimeline, registerAll } from "insightcharts";
// The slot props below are JSON specs. This makes their `type` names resolvable.
registerAll();
export function Example() {
return (
<AnnotatedTimeline
figurePosition="side"
events={[
{
date: "2015",
title: "The Paris Agreement is signed",
text: "Solar supplied 2.9% of EU electricity. Coal supplied 24.6%.",
figure: { type: "big-number", value: "2.9%", label: "Solar share of EU electricity" },
},
{
date: "2019",
title: "Solar module prices are half their 2015 level",
text: "New utility-scale solar costs less than new gas plants in southern Europe.",
},
{
date: "2022",
title: "The EU adds 41 GW of solar capacity",
emphasis: true,
text: "Gas prices rose sharply in 2022. Solar installations were 47% higher than in 2021.",
figure: {
type: "big-number",
value: "41 GW",
label: "Solar capacity added in the EU",
delta: 0.47,
deltaLabel: "vs 2021",
},
},
{
date: "2024",
title: "Solar supplies 11.1% of EU electricity",
text: "Coal supplied 9.8%.",
figure: {
type: "big-number",
value: "11.1%",
label: "Solar share of EU electricity",
context: "Coal supplied 9.8%",
},
},
]}
source="Ember; SolarPower Europe"
note="Figures are approximate, for illustration"
/>
);
}{
"type": "annotated-timeline",
"figurePosition": "side",
"events": [
{
"date": "2015",
"title": "The Paris Agreement is signed",
"text": "Solar supplied 2.9% of EU electricity. Coal supplied 24.6%.",
"figure": {
"type": "big-number",
"value": "2.9%",
"label": "Solar share of EU electricity"
}
},
{
"date": "2019",
"title": "Solar module prices are half their 2015 level",
"text": "New utility-scale solar costs less than new gas plants in southern Europe."
},
{
"date": "2022",
"title": "The EU adds 41 GW of solar capacity",
"emphasis": true,
"text": "Gas prices rose sharply in 2022. Solar installations were 47% higher than in 2021.",
"figure": {
"type": "big-number",
"value": "41 GW",
"label": "Solar capacity added in the EU",
"delta": 0.47,
"deltaLabel": "vs 2021"
}
},
{
"date": "2024",
"title": "Solar supplies 11.1% of EU electricity",
"text": "Coal supplied 9.8%.",
"figure": {
"type": "big-number",
"value": "11.1%",
"label": "Solar share of EU electricity",
"context": "Coal supplied 9.8%"
}
}
],
"source": "Ember; SolarPower Europe",
"note": "Figures are approximate, for illustration"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| eventsrequired | { date, title, text?, figure?, emphasis? }[] | The events in reading order. date is shown as written; figure is a chart spec or element; emphasis fills the marker to mark the most important events. | |
| figurePosition | "below" | "side" | "below" | Where an event's figure sits; side falls back to below under 640px. |
| level | 2 | 3 | 4 | 5 | 6 | 3 | Heading level of the event titles. |
| title | string | The main fact with its number, or a plain label. | |
| subtitle | string | Scope and period. | |
| source | string | Shown under the timeline as "Source: ...". | |
| note | string | Method note or caveat. | |
| theme | ThemeInput | Theme override, passed on to every event. | |
| mode | "auto" | "system" | "light" | "dark" | "auto" | Colour mode. |