# Realtime stream

> A live line that glides as values arrive, with a threshold, average and peak.

Component · Pro · https://lodeui.com/components/realtime-stream

## When to use

- Watching a metric as it happens: latency, requests, sensor readings, active users.
- Status pages and dashboards where the last minute matters most.

## When not to use

- History over hours or days: use a line or area chart.
- Values that change less than once a minute: a stat card is clearer.

## Installation

```bash
npx shadcn@latest add @lode/realtime-stream
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion, lucide-react

## Usage

```tsx title="example.tsx"
import { RealtimeStream } from "@/components/ui/realtime-stream";

export function Latency() {
  // Return the latest reading; called every interval.
  const next = () => readLatency();
  return <RealtimeStream next={next} unit="ms" threshold={220} label="p95 latency" />;
}
```

## API reference

### RealtimeStream

Polls next() on an interval and scrolls the line left as points arrive.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| next | `() => number` | – | Returns the next value. Read from a ref or store fed by your socket. |
| initial | `number[]` | – | Values to show before the first tick, oldest first. |
| interval | `number` | `1000` | Milliseconds between samples. |
| window | `number` | `40` | Points kept on screen. |
| threshold | `number` | – | A limit line; points above it are marked. |
| label | `string` | `"Live"` | Beside the live dot. |
| unit | `string` | – | After values, like ms or rps. |
| format | `(n) => string` | – | Formats every value. |
| color | `string` | `var(--chart-1)` | Line and fill colour. |
| height | `number` | `200` | Plot height in px. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Move to pause |
| Enter / Space | Pause or resume the stream |

## Accessibility

- The chart has a text summary of the latest value, average and peak.
- Values are not announced on every tick, so screen readers aren't flooded.

## Motion

- The line slides one step across each interval, so it glides instead of jumping.
- With reduced motion the line updates in place and the live dot doesn't pulse.

## Responsive behavior

- Width follows the container; the stats wrap under the value on narrow screens.

## Performance

- Sampling stops when the chart is off screen or the tab is hidden.
- One SVG path; the slide runs on the compositor.

## Notes for AI

- Keep next() cheap and synchronous: read the latest value pushed by a WebSocket into a ref.
- Pass a stable next (useState or useCallback) so the timer isn't reset on every render.

## Related

- [Line chart](https://lodeui.com/components/line-chart) — Multi-series lines with legend toggles, crosshair and shared tooltip.
- [Sparkline](https://lodeui.com/components/sparkline) — A tiny trend line that draws itself in.
- [Area chart](https://lodeui.com/components/area-chart) — A smooth trend line with a comparison period and an inspectable crosshair.