Step timeline
A vertical log of an agent run with start times, durations and nested sub-steps.
Loading preview…
Install
- 1
Run this command in your Tailwind CSS project. It adds
components/ai/step-timeline-default.tsxand installs its dependencies.$ npx shadcn@latest add https://gradientdeck.com/ai-components/r/step-timeline-default.json
Usage & API
Example
import { StepTimeline } from "@/components/ai/step-timeline-default"
<StepTimeline
steps={[]}
/>Props StepTimeline
| Prop | Type & description | Required |
|---|---|---|
steps | TimelineStep[] | Required |
defaultOpen | string[] | Optional |
Dependencies
- React
- Tailwind CSS
- motion
- lucide-react
Implementation notes
Each row leads with a mark: a check for done, a cross for failed, a spinner for running, and an empty circle for queued. Failed titles use the error color. Queued titles are dim. A parent row shows a chevron and toggles its children. defaultOpen lists the ids that start open, and more than one parent can be open together. Children repeat the same four statuses at a smaller size. A running child shows no duration. A finished child shows duration when you passed it. The start time sits in a column that appears only when the container is wide enough. There is no click on a step that has no children.
Example
import { RunSummary } from "@/components/ai/step-timeline-run-summary"
<RunSummary
steps={[]}
/>Props RunSummary
| Prop | Type & description | Required |
|---|---|---|
steps | RunStep[] | Required |
Dependencies
- React
- Tailwind CSS
- lucide-react
Implementation notes
The header is a clock mark, the words Run trace, and the number of steps. Each row is a button with the duration string on the left, a colored dot, the title, and either Running or Step N. The dot is green, red or blue for done, failed and running. Opening a row reveals detail and closes any other open row. There is no default-open prop, no children and no wall-clock time. duration is printed as given, including while status is running, so pass a placeholder string if a running step should not show a finished time.
Choosing a layout
Use the timeline when a run has a shape worth logging after, or while, it happens: a reproduction, a fix, then a set of checks that are themselves steps. Children are how Run checks contains lint, type check and tests without those becoming siblings of the whole run. at is worth passing when the reader cares when a step started, not only how long it took. Leave at off and the row still shows title, status and duration. defaultOpen is how a failed parent can land already expanded.
Use the summary when you have a handful of named stages and a sentence of detail each, and you do not need nested rows or a clock. A todo list is flatter still: text and a checkbox, no duration, no start time. A plan is the proposal before the run, with approve and edit. Research progress is a phased job with a single bar and the latest page, not a log of arbitrary steps. Put the timeline in the reply when the log is part of the answer, or in a run panel when the same data should stay visible beside the transcript.
How are timeline durations formatted?
A number under 60 becomes seconds with one decimal, such as 8.9s. A number of 60 or more becomes whole minutes plus rounded seconds. The summary layout does not use that formatter. Its duration is a string, so 0:11 stays 0:11. Omit duration on a timeline step and a finished row shows a blank where the time would be. A running timeline step always prints running instead.
Which rows can be expanded?
On the timeline, only a step with a non-empty children array. defaultOpen accepts several ids. On the summary, every step expands, and only one stays open. detail is required on a summary step, so a row you can open always has a paragraph to show.