Power-User Systems
Timeline Scrubber
Drag the head, snap it to markers, zoom into the track and let the viewport follow playback. One derived number — pixels per second — places the ticks, the pips, the head, the drag target and the follow scroll, so nothing on screen can disagree about where a time actually is.
Install
bun add lucide-react clsx tailwind-mergeThen copy 10 files into your project:
- components/registry/timeline-scrubber/timeline-scrubber.tsx
- components/registry/timeline-scrubber/types.ts
- components/registry/timeline-scrubber/util.ts
- components/registry/timeline-scrubber/use-timeline.ts
- components/registry/timeline-scrubber/ruler.tsx
- components/registry/timeline-scrubber/markers.tsx
- components/registry/timeline-scrubber/playhead.tsx
- components/registry/timeline-scrubber/transport.tsx
- lib/utils.ts
- hooks/use-animation-loop.ts
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| duration | number | 24 | Total length of the timeline. Everything on screen is a fraction of it, so shortening it zooms the whole track in rather than trimming the right-hand end off. |
| fps | number | 30 | Frames per second. Sets the last field of the timecode and the size of an arrow-key step — one frame, because a finer step would move the head without moving the readout, which reads as the control being broken. |
| zoom | number | 1 | Initial horizontal zoom; Ctrl/Cmd + wheel overrides it live and holds the time under the cursor fixed while it does. 1 fits the whole duration in the viewport, which is the only zoom at which the scrollbar is guaranteed absent. |
| snapThreshold | number | 10 | How close the pointer has to be to a marker to snap onto it. Specified in pixels and converted through the current zoom, because what makes a snap feel right is the distance on screen — a tolerance in seconds is generous zoomed out, unusable zoomed in, and needs re-tuning at every zoom. Hold Alt while dragging to bypass it. |
| showRuler | boolean | true | Show the tick ruler above the lane. Its divisions come off a fixed 1-2-5 ladder rather than being computed, so zooming walks through the same handful of intervals instead of inventing a new one at every step. |
| showMarkers | boolean | true | Show the marker pips. Off also disables snapping — there is nothing to snap to, and leaving invisible snap targets on the track is how a scrubber earns a reputation for fighting you. |
| loop | boolean | true | Wrap to the start on reaching the end. The overshoot carries across the wrap rather than being discarded, so a looping timeline does not run gradually slow at high playback rates. |
| playbackRate | number | 1 | Playback speed. The clock advances by real elapsed time from the runtime host, not by a fixed increment per frame, so a dropped frame costs a frame of smoothness and never a frame of time. |
| follow | "off" | "page" | "center" | "page" | What the viewport does when the head runs past its edge while playing. Page jumps a whole viewport and leaves the ruler still most of the time, which is what makes it readable; center pins the head and moves the world instead, which never loses it but never lets the ruler rest. |
| trackHeight | number | 72 | Height of the lane under the ruler. The playhead spans ruler and lane together, so this changes how much of the track the head has to cross rather than how tall the component's chrome is. |
| accent | string (hex) | "#a855f7" | Playhead, the active transport button, and any marker that does not carry its own colour. |
What It Demonstrates
- Drag
- Moving an element by grabbing it, often with momentum when released.
- Tabular numbers
- Fixed-width digits so numbers don't shift around as they change. Essential for tickers, timers, and counters.
- Interruptible animation
- An animation that can be smoothly redirected mid-flight instead of finishing first.
- Frame rate (FPS)
- Frames drawn per second. 60fps is the baseline for smooth motion; 120fps on newer displays.
- Spatial consistency
- Animating so an element keeps its identity and position across states, so users never lose track of where things went.
Related Components
Rewind
An undo history you can scrub, and that refuses to throw the future away. Drag the head and the interface reverts live under your finger rather than on release. Act from a past point and the abandoned future stays drawn on the rail as a branch you can walk back onto, instead of being silently destroyed the way every real undo stack destroys it. Controlled in the same shape as Ledger: it owns the rail, the gesture and the branch graph, and your reducer owns the states.
Physics Engine
A from-scratch 2D rigid-body physics lab. Fixed-timestep impulse solver, drag-to-throw bodies, force and velocity overlays, and a live energy readout on a blueprint grid.
Black Hole
A real-time Schwarzschild black hole raytraced per-pixel in a WebGL2 shader. Null geodesics bend a lensed accretion disk over the event horizon, with Doppler beaming, gravitational redshift, a photon ring, and a lensed starfield, all under a cinematic orbit.
Rotunda
Real HTML panels on a drag-spun 3D cylinder. A hand-rolled perspective projection written onto DOM elements rather than a canvas, so the text stays selectable, the links stay clickable, and a screen reader still reads every panel while the ring turns.
Weave
A sheet of cloth on a position-based solver. Particles and distance constraints relaxed to convergence every fixed step, with no forces, no rotations and no contacts. Drag it, load it, and pull until the constraints fail and the tear runs. Every quad is shaded by its own extension against the tear threshold, so the load path through the sheet is visible long before anything breaks.
Telemetry
A metric board that behaves as one instrument instead of eight sparklines. Hovering any tile broadcasts a single timestamp and every other tile resolves its own value at that same instant, so a latency spike and a queue backing up are visibly the same event rather than two coincidences. Threshold breaches are recorded on the sample rather than on a pixel, so the scar travels with its data and is still there forty seconds after the value recovered.