# Tick tape

> Events as they happen, one hairline each: as tall as its latency, bright when it lands and cooling as it travels, with errors in red. Point at it to hold it still and read one.

Live traffic is usually a line chart of averages, which hides the one slow call and the burst of errors you came to look for. Tick tape draws every event. Each one you push lands at the right edge as an upright hairline as tall as its value, rising into place. It arrives at full light and cools as it travels left, so how recent something is reads as how bright it is. Errors are red and stay lit longer. Point at the tape and it holds still while time runs on, and the event under the pointer lights with a readout of what it was. Move away and the tape catches up on what arrived meanwhile at an even, quicker pace, never with a jump. The Live pill holds it until you press it again. Above the tape, events per second, p95 and the error share over the last half minute update once a second, as plain figures that do not keep the header moving. Push from your own stream through a ref; one canvas, one frame loop that sleeps off screen and while held.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/tick-tape.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/tick-tape
- Registry item (source): https://hairlineui.com/r/tick-tape.json

## Usage

```tsx
import { useRef } from "react";
import { TickTape, type TickTapeHandle } from "@/components/tick-tape";

const tape = useRef<TickTapeHandle>(null);
// wherever your events arrive:
tape.current?.push({ value: 182, status: "ok", label: "GET /v1/orders · 200" });

<TickTape ref={tape} title="API requests" />
```

## From a server-sent event stream

Open the stream in an effect and push each event as it arrives; close it when the component goes.

```tsx
"use client";
import { useEffect, useRef } from "react";
import { TickTape, type TickTapeHandle } from "@/components/tick-tape";

export function LiveRequests() {
  const tape = useRef<TickTapeHandle>(null);
  useEffect(() => {
    const source = new EventSource("/api/requests/stream");
    source.onmessage = (message) => {
      const r = JSON.parse(message.data); // { ms: 182, status: 200, route: "GET /v1/orders", at: 1762700000000 }
      tape.current?.push({ value: r.ms, status: r.status >= 500 ? "error" : "ok", label: `${r.route} · ${r.status}`, time: r.at });
    };
    return () => source.close();
  }, []);
  return <TickTape ref={tape} title="API requests" />;
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ref` | `Ref<TickTapeHandle>` | – | push(event \| events) adds to the tape; clear() empties it. |
| `title` | `string` | `"Requests"` | Above the figures. |
| `seconds` | `number` | `12` | How much time the tape shows. |
| `format / locales` | `Intl.NumberFormatOptions / string` | `milliseconds` | How values read in the readout and p95. |
| `color` | `string` | `var(--chart-1)` | Any CSS colour for ok events; errors use red. |

## States

- **arrive**: A pushed event lands at the right edge and rises to its height over 220ms.
- **age**: It travels left across the tape (12 seconds by default), its light cooling from full to about a fifth over a few seconds; errors cool from full to half over about six.
- **hold**: With the pointer on the tape it stops; the event nearest the pointer (within 8px) is drawn at full light and the rest dim, with a readout of its value and label.
- **catch up**: When the pointer leaves, the tape runs at 2.2 times real speed until it has caught up, at an even pace.
- **paused**: The Live pill holds the tape until pressed again; its dot stops pulsing and greys.
- **figures**: Events per second (last 5s), p95 and the error share (last 30s) update once a second as plain figures; the error share turns red when there are any.
- **reduced motion**: The tape steps once a second instead of gliding; events appear without rising and the Live dot does not pulse.

## What it handles

A live chart of averages smooths away the one slow request and the burst of errors, and a log list scrolls too fast to read.

- **Every event, not an average**: One hairline per event, as tall as its value, so outliers and bursts show for what they are.
- **Recency as light**: New events land bright and cool as they travel; errors are red and stay lit longer.
- **Hold it to read it**: Point at the tape to stop it and read the event under the pointer; it catches up smoothly when you leave.
- **The figures that matter**: Events per second, p95 and the error share over the last half minute, once a second.
- **Plugs into any stream**: Call push() from a WebSocket, SSE or polling loop through a ref; the tape keeps no connection of its own.
- **Light on the page**: One canvas and one frame loop that sleeps off screen, in hidden tabs and while held.

## Replaces

a live line chart, a request log, a latency histogram, a live/pause toggle, a chart library

## Where it fits

- **API and request monitoring**: Every request with its latency, and failures in red, on a service's overview.
- **Webhook deliveries**: Each delivery as it goes out, with the slow and failed ones easy to spot.
- **Job and queue runs**: Background jobs finishing, their durations and their failures.
- **Payments and checkouts**: Payments as they clear, with declines standing out.

## Notes

- The tape is an image with a description; the three figures above it are plain text that updates once a second and is not a live region, so screen readers aren't interrupted.
- Red only marks errors, and the readout of an error carries a dot and its label too.
- Drawn on one canvas through a rule of 2px hairlines; the loop sleeps off screen, in hidden tabs, while held and while paused.
- With reduced motion the tape steps once a second.

License: MIT (https://hairlineui.com/license#components)
