# Span waterfall

> One run's steps, and where the time went. Sample data: one 9.1 s run, plan 0.8 s, six fetches 6.1 s, write 1.7 s, 4.4 s after the fix.

- Type 107 · Schedule and status
- Component: `<SpanWaterfall>`, the same name as the Figma component
- Install: `npx shadcn add @chartory/span-waterfall` (Code and Complete plans)
- Type page: https://usechartory.com/charts/span-waterfall

## Installation

1. **Set up the registry once.** Your token in .env and @chartory in components.json. Skip this when another chart is already installed. [Installation guide](https://usechartory.com/docs/installation)

2. **Add the chart.** One command adds the Span waterfall component to your project.

```bash
npx shadcn add @chartory/span-waterfall
```

3. **Use it.** Pass your rows. The props are the Figma properties.

usage.tsx:

```tsx
import { SpanWaterfall }
  from "@/components/chartory/span-waterfall"

<SpanWaterfall
  data={runSpans}
  size="m"
  legend
/>
```

## Props

### `<SpanWaterfall>`

Every prop but data is a Figma property with the same name and values.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| data | SpanWaterfallData | Required | The chart's data. The tables below list every field. |
| size | "xs" \| "s" \| "m" \| "l" | "m" | The size class. Each one is laid out again from the data. |
| legend | boolean | true | Shows the legend row under the plot. |

### SpanWaterfallData

The data prop: one object for the whole chart.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| max | number | Required | The top of the value scale. |
| ticks | [number, string][] | Required | The axis ticks: [value, label] pairs. |
| rows | SpanWaterfallRow[] | Required | One entry per row. |
| now | SpanWaterfallNow | Required | Now: where it is and its label. |
| fix | SpanWaterfallFix | Required | The value after the fix, and its label. |

### SpanWaterfallRow

One object per entry in rows.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| label | string | Required | The name shown on the chart. |
| group? | string | — | The group the row belongs to; rows in one group can merge. |
| s | number | Required | Where the span starts. |
| d | number | Required | The span's duration. |
| tok | string | Required | The colour token, e.g. "data/primary". |
| ghost? | [number, number] | — | The span before the fix: [start, duration]. |

### SpanWaterfallNow

The now object.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| v | number | Required | The value. |
| text | string | Required | The label as shown. |

### SpanWaterfallFix

The fix object.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| v | number | Required | The value. |
| text | string | Required | The label as shown. |

## Span waterfall: a React and Figma chart in four sizes

### What does a span waterfall show?

A span waterfall draws each step of one run as a bar starting where it began, so the slow step stands out. A second marker can show the run time after a fix. Use it for agent runs, traces and request timings.

Chartory ships it as a Figma component and a React component with the same name. The code installs from the shadcn registry with one command and lands in your project as a file you own.

### What is the Span waterfall component?

It is one **<SpanWaterfall>** component. Its props are the Figma properties with the same names and values, and the props table above lists them. The data is steps with a start and a length.

Sizes **XS**, **S**, **M** and **L** re-lay the chart out from the data instead of scaling it, so labels stay readable at every size.

### When should I use it?

- **Are the steps in one flat list?** Yes means the span waterfall fits.
- **Is it one run?** Yes means the span waterfall fits.
- **Is it time, not money?** Yes means the span waterfall fits.

### When does another type fit better?

- **Steps nested in steps.** Use Flame graph instead.
- **Many runs.** Use Latency field instead.
- **A cash walk.** Use Waterfall instead.

## Span waterfall questions

### Does the Span waterfall chart work with shadcn/ui?

Yes. It installs through the shadcn registry with the shadcn CLI, and the file lands in your project.

### How do I install it?

Add your token and the @chartory registry once, then run npx shadcn add @chartory/span-waterfall. The Installation guide has the steps.

### Can my coding agent install it?

Yes. Connect the Chartory MCP server and ask for the span waterfall chart; the agent runs the same command and you review the diff.

### What data does it expect?

Steps with a start and a length. The sample data comes with the component, and the props table lists every field.

### Which sizes does it ship in?

XS, S, M and L, in Figma and in code. Each size is laid out again from the data, so text and lines keep their size.

### Is it in the Figma file too?

Yes. chart/107-span-waterfall has the same properties as the component.

### Does it follow light and dark mode?

Yes. Every paint is a token, so the chart follows light and dark mode and the collection you pick.

### Which plan has the code?

Code and Complete. Figma has the Figma file only.