Skip to content
Browse documentation

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.

Used forAPI and request monitoringWebhook deliveriesJob and queue runsPayments and checkouts

Install with the shadcn CLI

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

Registered the namespace? Then it’s shadcn add @hairline/tick-tape. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • 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.

What it handles for you

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.

Instead of wiring upa live line charta request loga latency histograma live/pause togglea chart library
  1. Every event, not an average

    One hairline per event, as tall as its value, so outliers and bursts show for what they are.

  2. Recency as light

    New events land bright and cool as they travel; errors are red and stay lit longer.

  3. 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.

  4. The figures that matter

    Events per second, p95 and the error share over the last half minute, once a second.

  5. Plugs into any stream

    Call push() from a WebSocket, SSE or polling loop through a ref; the tape keeps no connection of its own.

  6. Light on the page

    One canvas and one frame loop that sleeps off screen, in hidden tabs and while held.

Overview

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.

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.

Usage

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.

example.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

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

Accessibility and motion

  • 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.

Requirements

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

Source

components/tick-tape.tsx
"use client";import * as React from "react";/* ───────────────────────────────────────────────────────── * TICK TAPE: events as they happen, one hairline each * *   arrive    every event you push lands at the right edge as an *             upright hairline, as tall as its value (a request's *             latency, a job's duration), rising into place *   age       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 *   read      point at the tape and it holds still; the event under *             the pointer lights with a readout of what it was. *             Let go and the tape catches up on what arrived *             meanwhile at an even, quicker pace, never a jump *   pause     the Live pill holds it until you press it again *   figures   events per second, p95 and the error share over the *             last half minute, as plain figures updated once a second * * Push from your own stream through a ref: tape.current.push({...}). * One canvas, one frame loop that sleeps off screen and while held. * ───────────────────────────────────────────────────────── */export interface TickTapeEvent {  value: number;  status?: "ok" | "error";  /** In the readout, e.g. "GET /v1/orders · 200". */  label?: string;  /** When it happened (ms since epoch). Defaults to now. */  time?: number;}export interface TickTapeHandle {  push: (event: TickTapeEvent | TickTapeEvent[]) => void;  clear: () => void;}export interface TickTapeProps extends React.HTMLAttributes<HTMLDivElement> {  ref?: React.Ref<TickTapeHandle>;  title?: string;  /** How many seconds the tape shows. */  seconds?: number;  /** How the value reads, e.g. milliseconds. */  format?: Intl.NumberFormatOptions;  locales?: string | string[];  /** Any CSS colour for ok events. Defaults to your first chart colour. */  color?: string;}type Tick = { t: number; v: number; err: boolean; label?: string };const FOCUS = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40";const LINE = 2;const PITCH = 4;const MS: Intl.NumberFormatOptions = { style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 };const KEEP = 30_000; // the figures look back this farconst CATCH_UP = 2.2; // while catching up, time runs this much fasterconst reducedQuery = "(prefers-reduced-motion: reduce)";const subscribeReduced = (onChange: () => void) => {  const query = window.matchMedia(reducedQuery);  query.addEventListener("change", onChange);  return () => query.removeEventListener("change", onChange);};const useReducedMotion = () =>  React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);// Formatting waits for hydration: the server and the hydrating render share one fixed locale, then the visitor's takes over.const subscribeNothing = () => () => {};const useHydrated = () => React.useSyncExternalStore(subscribeNothing, () => true, () => false);function niceMax(value: number) {  if (value <= 0) return 1;  const step = 10 ** Math.floor(Math.log10(value));  for (const m of [1, 1.2, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10]) if (m * step >= value) return m * step;  return 10 * step;}export function TickTape({  ref,  title = "Requests",  seconds = 12,  format = MS,  locales,  color = "var(--chart-1, var(--primary))",  className = "",  ...props}: TickTapeProps) {  const reduced = useReducedMotion();  const hydrated = useHydrated();  const locale = locales ?? (hydrated ? undefined : "en-US");  const [paused, setPaused] = React.useState(false);  const [stats, setStats] = React.useState({ rate: 0, p95: 0, errors: 0 });  const [picked, setPicked] = React.useState<Tick | null>(null);  const rootRef = React.useRef<HTMLDivElement>(null);  const plotRef = React.useRef<HTMLDivElement>(null);  const canvasRef = React.useRef<HTMLCanvasElement>(null);  const probeRef = React.useRef<HTMLSpanElement>(null);  const inkRef = React.useRef<HTMLSpanElement>(null);  const errRef = React.useRef<HTMLSpanElement>(null);  const tagRef = React.useRef<HTMLDivElement>(null);  const engine = React.useRef({    ticks: [] as Tick[],    width: 0,    height: 0,    dpr: 1,    accent: "currentColor",    ink: "currentColor",    error: "red",    lag: 0, // how far the tape shows behind real time, in ms    frozen: null as number | null, // the tape's time while held or paused    held: false, // the pointer is on it    paused: false, // the Live pill    pointerX: null as number | null,    picked: null as Tick | null,    scale: 0,    last: 0,    frame: 0,    onScreen: false,    reduced: false,    secondsMs: seconds * 1000,    lastStep: 0,    loop: null as ((now: number) => void) | null,  });  const paint = React.useCallback((now: number) => {    const e = engine.current;    const canvas = canvasRef.current;    const ctx = canvas?.getContext("2d");    if (!canvas || !ctx || !e.width || !e.height) return;    const dt = e.last ? Math.min(now - e.last, 100) : 0;    e.last = now;    // Held or paused, the tape's clock stops while real time runs on; let go and it catches up at an even pace.    let view: number;    if (e.held || e.paused) {      if (e.frozen === null) e.frozen = Date.now() - e.lag;      view = e.frozen;    } else {      if (e.frozen !== null) {        e.lag = Date.now() - e.frozen;        e.frozen = null;      }      if (e.lag > 0) e.lag = Math.max(0, e.lag - dt * (CATCH_UP - 1));      view = Date.now() - e.lag;    }    const span = e.secondsMs;    const W = e.width;    const H = e.height;    // The scale eases toward a round number over what's on the tape.    let top = 0;    for (const k of e.ticks) if (k.t > view - span && k.t <= view && k.v > top) top = k.v;    const target = niceMax(top * 1.1 || 1);    e.scale = e.scale ? e.scale + (target - e.scale) * Math.min(1, dt / 220) : target;    ctx.setTransform(e.dpr, 0, 0, e.dpr, 0, 0);    ctx.clearRect(0, 0, W, H);    const rule = new Path2D();    for (let k = 0; ; k++) {      const y = Math.round((H - LINE - k * PITCH) * e.dpr) / e.dpr;      if (y < -LINE) break;      rule.rect(0, y, W, LINE);    }    ctx.save();    ctx.clip(rule);    ctx.fillStyle = e.ink;    ctx.globalAlpha = 0.04;    ctx.fillRect(0, 0, W, H);    // Find the event under the pointer while the tape is held.    let near: Tick | null = null;    let nearX = 0;    if (e.held && e.pointerX !== null) {      let best = 8;      for (const k of e.ticks) {        const x = W - ((view - k.t) / span) * W;        const d = Math.abs(x - e.pointerX);        if (k.t <= view && d < best) {          best = d;          near = k;          nearX = x;        }      }    }    for (const k of e.ticks) {      if (k.t > view || k.t < view - span - 1000) continue;      const age = view - k.t;      const x = W - (age / span) * W;      // Arrival: it rises into place over its first 220ms.      const rise = e.reduced ? 1 : Math.min(1, age / 220);      const h = Math.max(LINE, (Math.min(k.v, e.scale) / e.scale) * H * (1 - (1 - rise) ** 3));      // Recency is light: full on arrival, cooling over a few seconds; errors keep theirs longer.      const glow = k.err ? 0.5 + 0.5 * Math.exp(-age / 6000) : 0.22 + 0.78 * Math.exp(-age / 1800);      ctx.globalAlpha = near ? (k === near ? 1 : glow * 0.45) : glow;      ctx.fillStyle = k.err ? e.error : e.accent;      ctx.fillRect(Math.round((x - 1) * e.dpr) / e.dpr, H - h, 2, h);    }    ctx.restore();    ctx.globalAlpha = 1;    if (near !== e.picked) {      e.picked = near;      setPicked(near);    }    const tag = tagRef.current;    if (tag) {      tag.style.opacity = near ? "1" : "0";      if (near) {        const half = tag.offsetWidth / 2;        tag.style.transform = `translate3d(${Math.min(Math.max(nearX - half, 0), W - half * 2)}px,0,0)`;      }    }    // Keep the buffer to what the figures and the tape need.    const oldest = Date.now() - Math.max(KEEP, span) - e.lag - 2000;    let drop = 0;    while (drop < e.ticks.length && e.ticks[drop].t < oldest) drop++;    if (drop) e.ticks.splice(0, drop);  }, []);  // The frame loop lives on the engine, so it can schedule itself.  React.useLayoutEffect(() => {    const e = engine.current;    const loop = (now: number) => {      e.frame = 0;      // With reduced motion the tape steps once a second instead of gliding.      if (!e.reduced || now - e.lastStep >= 1000 || e.held) {        e.lastStep = now;        paint(now);      }      // Sleep off screen, and while held or paused: the tape only redraws when the pointer moves.      if (e.onScreen && !e.held && !e.paused) e.frame = requestAnimationFrame(loop);    };    e.loop = loop;  }, [paint]);  const wake = React.useCallback(() => {    const e = engine.current;    if (!e.frame && e.onScreen && e.loop) {      e.last = 0;      e.frame = requestAnimationFrame(e.loop);    }  }, []);  React.useImperativeHandle(    ref,    () => ({      push(input) {        const e = engine.current;        const list = Array.isArray(input) ? input : [input];        const now = Date.now();        for (const ev of list) e.ticks.push({ t: ev.time ?? now, v: Math.max(0, ev.value), err: ev.status === "error", label: ev.label });        if (list.some((ev) => ev.time !== undefined)) e.ticks.sort((a, b) => a.t - b.t);        wake();      },      clear() {        engine.current.ticks = [];        wake();      },    }),    [wake],  );  React.useEffect(() => {    const e = engine.current;    e.reduced = reduced;    e.secondsMs = seconds * 1000;    e.paused = paused;    wake();  }, [reduced, seconds, paused, wake]);  // Size the canvas; sleep when off screen or in a hidden tab.  React.useEffect(() => {    const plot = plotRef.current;    const canvas = canvasRef.current;    const root = rootRef.current;    if (!plot || !canvas || !root) return;    const e = engine.current;    const measure = () => {      const w = plot.clientWidth;      const h = canvas.clientHeight;      const dpr = Math.min(window.devicePixelRatio || 1, 3);      if (w === e.width && h === e.height && dpr === e.dpr) return;      e.width = w;      e.height = h;      e.dpr = dpr;      canvas.width = Math.round(w * dpr);      canvas.height = Math.round(h * dpr);      paint(performance.now());    };    measure();    const resize = new ResizeObserver(measure);    resize.observe(plot);    let seen = false;    const sync = () => {      e.onScreen = seen && !document.hidden;      if (e.onScreen) wake();      else if (e.frame) {        cancelAnimationFrame(e.frame);        e.frame = 0;      }    };    const io = new IntersectionObserver(([entry]) => {      seen = entry.isIntersecting;      sync();    });    io.observe(root);    document.addEventListener("visibilitychange", sync);    return () => {      resize.disconnect();      io.disconnect();      document.removeEventListener("visibilitychange", sync);      if (e.frame) cancelAnimationFrame(e.frame);      e.frame = 0;    };  }, [paint, wake]);  React.useEffect(() => {    const read = () => {      const e = engine.current;      if (probeRef.current) e.accent = getComputedStyle(probeRef.current).color;      if (inkRef.current) e.ink = getComputedStyle(inkRef.current).color;      if (errRef.current) e.error = getComputedStyle(errRef.current).color;      paint(performance.now());    };    read();    const observer = new MutationObserver(read);    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "style", "data-theme"] });    const media = window.matchMedia("(prefers-color-scheme: dark)");    media.addEventListener("change", read);    return () => {      observer.disconnect();      media.removeEventListener("change", read);    };  }, [color, paint]);  // The figures, once a second, from what arrived in the last half minute.  React.useEffect(() => {    const timer = window.setInterval(() => {      const e = engine.current;      if (!e.onScreen) return;      const now = Date.now();      const recent = e.ticks.filter((k) => k.t > now - KEEP && k.t <= now);      const last5 = recent.filter((k) => k.t > now - 5000).length / 5;      const sorted = recent.map((k) => k.v).sort((a, b) => a - b);      const p95 = sorted.length ? sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))] : 0;      const errors = recent.length ? recent.filter((k) => k.err).length / recent.length : 0;      setStats((s) => (s.rate === last5 && s.p95 === p95 && s.errors === errors ? s : { rate: last5, p95, errors }));    }, 1000);    return () => window.clearInterval(timer);  }, []);  const hold = (x: number | null) => {    const e = engine.current;    e.held = x !== null;    e.pointerX = x;    wake();  };  const fmt = (v: number) => new Intl.NumberFormat(locale, format).format(v);  const live = !paused;  return (    <div ref={rootRef} className={`w-full rounded-[22px] bg-background shadow-[0_0_0_1px_var(--border)] ${className}`} {...props}>      <span ref={probeRef} aria-hidden="true" className="hidden" style={{ color }} />      <span ref={inkRef} aria-hidden="true" className="hidden text-foreground" />      <span ref={errRef} aria-hidden="true" className="hidden text-red-500 dark:text-red-400" />      {/* Its natural width where the parent sizes to its content (a centred flex column), without forcing it on narrow screens. */}      <div aria-hidden="true" data-natural-width className="grid h-0" style={{ gridTemplateColumns: "minmax(0, 600px)" }} />      <div className="@container w-full">        <div className="p-4 @md:p-5 [--plot:120px] @md:[--plot:150px]">          <div className="flex items-center justify-between gap-3">            <p className="text-[12px] text-muted-foreground @md:text-[13px]">{title}</p>            <button              type="button"              aria-pressed={paused}              onClick={() => setPaused((p) => !p)}              className={`-my-1 inline-flex h-7 shrink-0 cursor-pointer items-center gap-1.5 rounded-full px-2.5 text-[12px] font-medium shadow-[inset_0_0_0_1px_var(--border)] transition-colors duration-200 @md:text-[12.5px] ${FOCUS} ${                live ? "text-foreground" : "text-muted-foreground hover:text-foreground"              }`}            >              <span aria-hidden="true" className="relative flex size-2">                {live && !reduced && <span className="absolute inset-0 animate-ping rounded-full bg-emerald-500/50" />}                <span className={`relative size-2 rounded-full transition-colors duration-200 ${live ? "bg-emerald-500" : "bg-foreground/30"}`} />              </span>              {live ? "Live" : "Paused"}            </button>          </div>          {/* Three figures over the last half minute, as a compact strip. */}          <div className="mt-1.5 grid grid-cols-3 gap-3">            {[              { label: "per second", node: new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(stats.rate) },              { label: "p95", node: fmt(stats.p95) },              {                label: "errors",                node: new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 }).format(stats.errors),                warn: stats.errors > 0,              },            ].map((f) => (              <div key={f.label} className="min-w-0">                <p                  className={`text-[19px] font-medium leading-tight tracking-[-0.03em] tabular-nums @md:text-[22px] ${                    f.warn ? "text-red-600 dark:text-red-400" : "text-foreground"                  }`}                >                  {f.node}                </p>                <p className="truncate text-[11px] text-muted-foreground @md:text-[12px]">{f.label}</p>              </div>            ))}          </div>          <div            ref={plotRef}            role="img"            aria-label={`${title}: the last ${seconds} seconds of events, newest on the right. Point at the tape to hold it and read an event.`}            onPointerMove={(ev) => {              const r = ev.currentTarget.getBoundingClientRect();              hold(ev.clientX - r.left);            }}            onPointerLeave={() => hold(null)}            onPointerCancel={() => hold(null)}            className="relative mt-4 cursor-crosshair touch-pan-y select-none @md:mt-5"          >            <canvas ref={canvasRef} aria-hidden="true" className="block w-full" style={{ height: "var(--plot)" }} />            <div aria-hidden="true" className="absolute inset-x-0 bottom-0 border-t border-border" />            <div              ref={tagRef}              aria-hidden="true"              className="pointer-events-none absolute left-0 top-0 flex h-[24px] items-center gap-1.5 whitespace-nowrap rounded-full bg-background px-2.5 text-[11.5px] shadow-[0_0_0_1px_var(--border)]"              style={{ opacity: 0 }}            >              {picked?.err && <span className="size-1.5 rounded-full bg-red-500" />}              <span className="font-medium tabular-nums text-foreground">{picked ? fmt(picked.v) : " "}</span>              {picked?.label && <span className="text-muted-foreground">{picked.label}</span>}            </div>          </div>          <div aria-hidden="true" className="mt-1.5 flex justify-between text-[10.5px] leading-4 text-muted-foreground">            <span>{seconds}s ago</span>            <span>now</span>          </div>        </div>      </div>    </div>  );}

Registry item: /r/tick-tape.json