Trace waterfallPro
Spans of an agent run on one time axis, with nesting, duration, token and cost columns, collapse by depth and keyboard tree navigation.
On this page
Installation
Usage
import { TraceWaterfall } from "@/components/ui/chatcn/pro/trace-waterfall"
<TraceWaterfall spans={trace.spans} meta={trace.id} onSelect={openSpan} />Pass every span of a trace with its offset from the trace start. Nesting comes from parentId; a span whose parent is missing becomes a root instead of disappearing. Parents without their own tokens or cost show the total of everything under them in a lighter gray.
Bars recede for agents and chains, lead for model calls and sit between for tools. Red is a failed span, blue a running one; the glyph and the screen reader text say the same thing without color. Hover a row and its window shades across every other row, so you see what ran in parallel and what waited.
For a live trace set live and startedAt: running spans grow against a now line, and the axis end snaps to whole ticks so it rescales in steps rather than every frame. The waterfall is a variant of the free trace component with a timing axis and columns.
Examples
Live trace
States
Props
| Prop | Type | Notes |
|---|---|---|
spans | TraceSpan[] | { id, parentId?, name, kind, status?, startMs, durationMs?, model?, tokens?, costUsd?, input?, output?, metadata?, events?, scores?, error?, request? } |
selectedId, defaultSelectedId | string | null | The selected span |
onSelect | (id) => void | Enter, Space or a click on a row |
live, startedAt | boolean, number | Grow running spans against a live clock |
defaultDepth | number | "all" | Levels shown at first. Default all |
columns | { tokens?, cost? } | Hide either column. Both show from 672 px wide |
maxHeight | number | string | Rows area height. Default 440 |
loading | boolean | Skeleton rows and a shimmer label |
meta, labels, locale | Text beside the title, every string, number format |
Keyboard
| Key | Action |
|---|---|
Up, Down | Move between spans |
Right | Open a span, then move to its first child |
Left | Close a span, then move to its parent |
Home, End | First and last span |
Enter, Space | Select the span |
Accessibility
- A
treegridwith levels, positions and expanded state on every row; one row takes focus at a time. - Each row reads its kind and status in words, and its bar as a start and end time.
- Numbers keep left to right order inside right to left layouts.
Motion
Only the disclosure chevron turns, for 150 ms; rows appear and disappear without animation because they follow keys. The crosshair follows the pointer by writing one CSS variable, with no re-render. Reduced motion removes the turn.