Trend · Intermediate

Timeline

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

Open in playground
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

41

Timeline

One agent run from plan to merge, in minutes
  • Fixing
  • Waiting
  • Merged
  • Working
TimelineTimeline. 9 items on 8 rows, from 0 min to 43 min. Longest: Wait for CI, 18 min. Status strip: Working 0 min to 18 min, Fixing 18 min to 22 min, Working 22 min to 25 min, Waiting 25 min to 43 min, Merged 43 min.3 min5 min7 min2 min4 min1 min18 min
Timeline data
Plan0 min to 3 min, 3 min, Working
Search code3 min to 8 min, 5 min, Working
Edit files8 min to 15 min, 7 min, Working
Run tests15 min to 18 min, 3 min, Working
Run tests22 min to 24 min, 2 min, Working
Fix failing test18 min to 22 min, 4 min, Fixing
Open PR24 min to 25 min, 1 min, Working
Wait for CI25 min to 43 min, 18 min, Waiting
Merged43 min, Merged
18 of 43 minutes went to waiting for CIIntermediate

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 colors on bars

One agent run from plan to merge, in minutes
  • Fixing
  • Waiting
  • Merged
  • Working
Sample data

Clock times

One agent run from plan to merge, in minutes
  • Fixing
  • Waiting
  • Merged
  • Working
Sample data

Longest first

One agent run from plan to merge, in minutes
  • Fixing
  • Waiting
  • Merged
  • Working
Sample data

Now line

One agent run from plan to merge, in minutes
  • Fixing
  • Waiting
  • Merged
  • Working
Sample data

Drag to zoom

One agent run from plan to merge, in minutes
  • Fixing
  • Waiting
  • Merged
  • Working
Sample data

Code

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

const data = [
  {"step":"Plan","start":0,"end":3,"state":"Working","startAt":"2026-11-10T09:00","endAt":"2026-11-10T09:03"},
  {"step":"Search code","start":3,"end":8,"state":"Working","startAt":"2026-11-10T09:03","endAt":"2026-11-10T09:08"},
  {"step":"Edit files","start":8,"end":15,"state":"Working","startAt":"2026-11-10T09:08","endAt":"2026-11-10T09:15"},
  {"step":"Run tests","start":15,"end":18,"state":"Working","startAt":"2026-11-10T09:15","endAt":"2026-11-10T09:18"},
  {"step":"Fix failing test","start":18,"end":22,"state":"Fixing","startAt":"2026-11-10T09:18","endAt":"2026-11-10T09:22"},
  {"step":"Run tests","start":22,"end":24,"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"
        status="state"
        unit=" min"
        statusStrip={true}
      />
    </ChartCard>
  );
}

Props

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

35 props

Prop
dataRequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]
labelRequiredRow name. Items with the same name share a rowstring | (d, i) => string
startRequiredStart: a number (minutes, seconds, any unit) or a date or date-timestring | (d, i) => any
endRequiredEnd, same kind as start. Equal to start draws a point event; empty means still openstring | (d, i) => any
groupGroup field (one color per group, and the legend)string | (d, i) => string
statusState 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
xTypeTime 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"
dayFirstReads 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
sortRow order: "none" keeps the data order, "start" puts the earliest start first, "duration" the longest total first"none" | "start" | "duration"Default "none"
referenceLinesVertical 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[]
nowTime 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
statusStripAdds a bottom row that joins consecutive items of the same status into one labelled segment. Bars then show durations, the longest in the accent. Needs encoding.statusbooleanDefault false
brushDrag across the time axis to zoom in: "zoom" or true (keyboard: Shift+arrows, Enter). Escape or "Show all" zooms outanyDefault false
hiddenSeries to hide. Colors stay as if every series were shown. With card.legend "toggle", viewers can show them againstring[]
heightCommonHeight in px. Without it, each chart picks a default that fits its widthnumber
widthCommonFixed width in px. Without it, the chart fits its parentnumber
highlightCommonItem to highlight. An index, a name, an array, or "max" | "min" | "first" | "last" | "none"number | string | (number|string)[] | "max" …
formatCommonValue 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" | …
unitCommonUnit appended to values. For example "%" or "ms"string
localeCommonLocale 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"
animateCommonEntry and update animationbooleanDefault true
durationCommonAnimation length (ms)number
easingCommonMotion curve"spring" | "easeOut" | "easeInOut" | "linear"Default "spring"
staggerCommonDelay between items as they enter (ms)number
reducedMotionCommon"auto" follows the OS setting. true always turns motion offanyDefault "auto"
animateOnViewCommonPlay when the chart scrolls into viewbooleanDefault true
showLabelsCommonLabels drawn on the chart (values and names)booleanDefault true
tooltipCommonShow 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
syncIdCommonCharts with the same syncId show the hovered x together (line, area, bar, candlestick, skyline). <ChartGrid sync> sets one for every chart inside itstring
ariaLabelCommonName for screen readersstring
descriptionCommonDescription for screen readers. Built from the data when omittedstring
onHoverCommonRuns when hover or keyboard focus moves to another item(e: ChartEvent | null) => void
onClickCommonRuns on click, Enter or Space(e: ChartEvent) => void
replayKeyCommonReplays the entry animation when it changesstring | number
themeCommonChanges theme tokens for this chart onlyPartial<ChartTheme>