# Stream chart

> A live time series for telemetry: newest sample at the right edge, limits, and anything past a limit in red.

Category: Charts · Atomic level: organism
Page: https://ui.dtheo.dev/docs/charts/stream-chart

## Install

```bash
npx dtheo@latest add stream-chart
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/stream-chart.json
```

Dependencies: d3-scale. Registry dependencies: none.

## Exports

`StreamChart`, `createStream`

## Use it for

- Live bench and test-rig telemetry at up to a few kHz
- Watching a signal against a limit while a test runs

## Reach for something else

- Reviewing a finished capture: use Line chart, which reads with the keyboard
- Values that change a few times a minute: use Metric with a Sparkline

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stream` | `Stream` | – | A ring buffer from `createStream(channels, capacity)`. Push samples into it as fast as they arrive; the chart draws once per frame. |
| `series` | `StreamSeries[]` | – | Which channels to draw, with label, tone, width, unit and digits. |
| `window` | `number` | `10000` | History on screen, in milliseconds. |
| `yDomain` | `[number, number]` | – | A fixed y range, so the trace does not jump. |
| `limits` | `StreamLimit[]` | – | Dashed lines; give a channel and the part of its trace past the limit turns critical. |
| `paused` | `boolean` | `false` | Freeze the view while samples keep buffering. |

## Accessibility

- The latest values are text above the plot, with the word "over limit" when one is, never color alone.
- Crossing a limit is announced politely, at most once every ten seconds.
- With reduced motion on, the chart updates four times a second instead of scrolling smoothly.
- Drawing stops while the chart is off screen or the tab is hidden.

## Examples

### stream-chart

```tsx
import * as React from 'react';
import { PauseIcon, PlayIcon } from 'lucide-react';
import { StreamChart } from '@/components/charts/stream-chart';
import { createStream } from '@/components/charts/stream';
import { Button } from '@/components/ui/button';
// Synthetic demo data: npx dtheo add lab-data, or pass your own.
import { createBench } from '@/lib/lab-data';

// A 1 kHz bench feed, simulated in the page. In an app this would be a WebSocket pushing into the same stream.
export default function StreamChartExample() {
  // Start with six seconds of history, so the chart opens full rather than filling in.
  const [{ stream, bench }] = React.useState(() => {
    const s = createStream(['command', 'torque'], 12_000);
    const b = createBench();
    for (let k = 0; k < 6000; k++) {
      const v = b(1);
      s.push(v.t, [v.command, v.torque]);
    }
    return { stream: s, bench: b };
  });
  const [paused, setPaused] = React.useState(false);

  React.useEffect(() => {
    const id = setInterval(() => {
      for (let k = 0; k < 20; k++) {
        const s = bench(1);
        stream.push(s.t, [s.command, s.torque]);
      }
    }, 20);
    return () => clearInterval(id);
  }, [stream, bench]);

  return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex items-center justify-between gap-3">
        <div className="flex flex-col">
          <span className="text-headline">Live torque</span>
          <span className="text-caption text-muted-foreground">RA-14 hip pitch · Bench 3 · 1 kHz</span>
        </div>
        <Button size="sm" onClick={() => setPaused((p) => !p)}>
          {paused ? <PlayIcon aria-hidden="true" /> : <PauseIcon aria-hidden="true" />}
          {paused ? 'Resume' : 'Pause'}
        </Button>
      </div>
      <StreamChart
        stream={stream}
        paused={paused}
        window={6000}
        yDomain={[-4, 16]}
        yTicks={[0, 4, 8, 12, 16]}
        series={[
          { channel: 'command', label: 'Command', tone: 'faint', width: 1, unit: 'N·m' },
          { channel: 'torque', label: 'Measured', unit: 'N·m', digits: 2 },
        ]}
        limits={[{ value: 13.2, label: 'Overshoot limit 13.2 N·m', channel: 'torque' }]}
        height={200}
        ariaLabel="Live torque on Bench 3: a 12 N·m step every 1.5 seconds; each step overshoots past the 13.2 N·m limit."
      />
    </div>
  );
}
```

## Used in

- Loop tuning (page): https://ui.dtheo.dev/examples/tuning
