Trend · Intermediate

Timeline

When things started and ended, and what overlapped: one bar per item on a time axis.

Use when: Items with a start and an end, such as a project schedule, deployment and job runs, an agent run log or an incident timeline
Avoid when: Each item has one value and no start or end (use bar), or the dependencies between tasks are the story

Try it

Reduce motion

Timeline

One agent run from plan to merge, in minutes

Timeline data
Plan	0 min to 3 min, 3 min
Search code	3 min to 8 min, 5 min
Edit files	8 min to 15 min, 7 min
Run tests	15 min to 18 min, 3 min
Run tests	22 min to 24 min, 2 min
Fix failing test	18 min to 22 min, 4 min
Open PR	24 min to 25 min, 1 min
Wait for CI	25 min to 43 min, 18 min
Merged	43 min

Hover over the chart, or Tab in and use the arrow keys to move between items. The numbers are sample data.

Variants

Named looks for this chart. Each one is the example above with a few options or fields changed. The CLI (ztd-charts example timeline --variant <id>) and the MCP server know the same names.

Status strip

One agent run from plan to merge, in minutes

Clock times

One agent run from plan to merge, in minutes

Longest first

One agent run from plan to merge, in minutes

Now line

One agent run from plan to merge, in minutes

Drag to zoom

One agent run from plan to merge, in minutes

Code

Timeline.tsx

import { ChartCard, Timeline } from "ztd-charts";

const data = [
  {"step":"Plan","start":0,"end":3,"run":"Agent run","state":"Working","startAt":"2026-11-10T09:00","endAt":"2026-11-10T09:03"},
  {"step":"Search code","start":3,"end":8,"run":"Agent run","state":"Working","startAt":"2026-11-10T09:03","endAt":"2026-11-10T09:08"},
  {"step":"Edit files","start":8,"end":15,"run":"Agent run","state":"Working","startAt":"2026-11-10T09:08","endAt":"2026-11-10T09:15"},
  {"step":"Run tests","start":15,"end":18,"run":"Agent run","state":"Working","startAt":"2026-11-10T09:15","endAt":"2026-11-10T09:18"},
  {"step":"Fix failing test","start":18,"end":22,"run":"Agent run","state":"Fixing","startAt":"2026-11-10T09:18","endAt":"2026-11-10T09:22"},
  {"step":"Run tests","start":22,"end":24,"run":"Agent run","state":"Working","startAt":"2026-11-10T09:22","endAt":"2026-11-10T09:24"},
  // … 3 more rows
];

export function Example() {
  return (
    <ChartCard number="41" title="Timeline" subtitle="One agent run from plan to merge, in minutes" takeaway="18 of 43 minutes went to waiting for CI" level="intermediate" replay>
      <Timeline
        data={data}
        label="step"
        start="start"
        end="end"
        unit=" min"
      />
    </ChartCard>
  );
}

Props

<Timeline> takes these props. Rows marked Common work the same on every chart.

34 props

Prop	Type	Default	Description
`data`RequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]	object[]	-	An array of objects. Pass CSV, REST or database rows as they are
`label`RequiredRow name. Items with the same name share a rowstring \| (d, i) => string	string \| (d, i) => string	-	Row name. Items with the same name share a row
`start`RequiredStart: a number (minutes, seconds, any unit) or a date or date-timestring \| (d, i) => any	string \| (d, i) => any	-	Start: a number (minutes, seconds, any unit) or a date or date-time
`end`RequiredEnd, same kind as start. Equal to start draws a point event; empty means still openstring \| (d, i) => any	string \| (d, i) => any	-	End, same kind as start. Equal to start draws a point event; empty means still open
`group`Group field (one color per group, and the legend)string \| (d, i) => string	string \| (d, i) => string	-	Group field (one color per group, and the legend)
`status`State of the item, written inside the bar and in the tooltip. Without group it also colors the bars and makes the legend, so a row of consecutive states reads as a status stripstring \| (d, i) => string	string \| (d, i) => string	-	State of the item, written inside the bar and in the tooltip. Without group it also colors the bars and makes the legend, so a row of consecutive states reads as a status strip
`xType`Time axis type. Automatic when omitted: dates and date-times (ISO, "2025.03.01", Korean dates, quarters, English month names) make a date axis, otherwise numbers in options.unit. With "date", numbers are timestamps (10 digits are Unix seconds) or years"number" \| "date"	"number" \| "date"	-	Time axis type. Automatic when omitted: dates and date-times (ISO, "2025.03.01", Korean dates, quarters, English month names) make a date axis, otherwise numbers in options.unit. With "date", numbers are timestamps (10 digits are Unix seconds) or years
`dayFirst`Reads dates such as "05/03/2024", where either part could be the month, day first (5 March). Without it, a clear date in the column decides (25/03/2024), otherwise month first. true also reads "05.03.24" as day.month.yearboolean	boolean	-	Reads dates such as "05/03/2024", where either part could be the month, day first (5 March). Without it, a clear date in the column decides (25/03/2024), otherwise month first. true also reads "05.03.24" as day.month.year
`sort`Row order: "none" keeps the data order, "start" puts the earliest start first, "duration" the longest total first"none" \| "start" \| "duration"Default `"none"`	"none" \| "start" \| "duration"	"none"	Row order: "none" keeps the data order, "start" puts the earliest start first, "duration" the longest total first
`referenceLines`Vertical lines on the time axis [{ x, label }]. x is a number or a date, like the data. Lines outside the axis range are not drawnany[]	any[]	-	Vertical lines on the time axis [{ x, label }]. x is a number or a date, like the data. Lines outside the axis range are not drawn
`now`Time of a "Now" line, in the same form as the data. Items without an end run up to it. The chart never reads the clock, so server and browser draw the sameany	any	-	Time of a "Now" line, in the same form as the data. Items without an end run up to it. The chart never reads the clock, so server and browser draw the same
`brush`Drag across the time axis to zoom in: "zoom" or true (keyboard: Shift+arrows, Enter). Escape or "Show all" zooms outanyDefault `false`	any	false	Drag across the time axis to zoom in: "zoom" or true (keyboard: Shift+arrows, Enter). Escape or "Show all" zooms out
`hidden`Series to hide. Colors stay as if every series were shown. With card.legend "toggle", viewers can show them againstring[]	string[]	-	Series to hide. Colors stay as if every series were shown. With card.legend "toggle", viewers can show them again
`height`CommonHeight in px. Without it, each chart picks a default that fits its widthnumber	number	-	Height in px. Without it, each chart picks a default that fits its width
`width`CommonFixed width in px. Without it, the chart fits its parentnumber	number	-	Fixed width in px. Without it, the chart fits its parent
`highlight`CommonItem to highlight. An index, a name, an array, or "max" \| "min" \| "first" \| "last" \| "none"number \| string \| (number\|string)[] \| "max" …	number \| string \| (number\|string)[] \| "max" …	-	Item to highlight. An index, a name, an array, or "max" \| "min" \| "first" \| "last" \| "none"
`format`CommonValue format. "number" \| "integer" \| "percent" (values are already percents: 42 → "42%") \| "ratio" (0.42 → "42%") \| "compact" \| "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) \| "decimal" or Intl.NumberFormat options"number" \| "percent" \| "compact" \| …	"number" \| "percent" \| "compact" \| …	-	Value format. "number" \| "integer" \| "percent" (values are already percents: 42 → "42%") \| "ratio" (0.42 → "42%") \| "compact" \| "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) \| "decimal" or Intl.NumberFormat options
`unit`CommonUnit appended to values. For example "%" or "ms"string	string	-	Unit appended to values. For example "%" or "ms"
`locale`CommonLocale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider localestringDefault `"en-US"`	string	"en-US"	Locale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider locale
`animate`CommonEntry and update animationbooleanDefault `true`	boolean	true	Entry and update animation
`duration`CommonAnimation length (ms)number	number	-	Animation length (ms)
`easing`CommonMotion curve"spring" \| "easeOut" \| "easeInOut" \| "linear"Default `"spring"`	"spring" \| "easeOut" \| "easeInOut" \| "linear"	"spring"	Motion curve
`stagger`CommonDelay between items as they enter (ms)number	number	-	Delay between items as they enter (ms)
`reducedMotion`Common"auto" follows the OS setting. true always turns motion offanyDefault `"auto"`	any	"auto"	"auto" follows the OS setting. true always turns motion off
`animateOnView`CommonPlay when the chart scrolls into viewbooleanDefault `true`	boolean	true	Play when the chart scrolls into view
`showLabels`CommonLabels drawn on the chart (values and names)booleanDefault `true`	boolean	true	Labels drawn on the chart (values and names)
`tooltip`CommonShow tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left outtooltipDefault `true`	tooltip	true	Show tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left out
`syncId`CommonCharts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside itstring	string	-	Charts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside it
`ariaLabel`CommonName for screen readersstring	string	-	Name for screen readers
`description`CommonDescription for screen readers. Built from the data when omittedstring	string	-	Description for screen readers. Built from the data when omitted
`onHover`CommonRuns when hover or keyboard focus moves to another item(e: ChartEvent \| null) => void	(e: ChartEvent \| null) => void	-	Runs when hover or keyboard focus moves to another item
`onClick`CommonRuns on click, Enter or Space(e: ChartEvent) => void	(e: ChartEvent) => void	-	Runs on click, Enter or Space
`replayKey`CommonReplays the entry animation when it changesstring \| number	string \| number	-	Replays the entry animation when it changes
`theme`CommonChanges theme tokens for this chart onlyPartial<ChartTheme>	Partial<ChartTheme>	-	Changes theme tokens for this chart only

Try it

Variants

Code

Props

Also in Trend