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-merge

Then 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

PropTypeDefaultDescription
durationnumber24Total 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.
fpsnumber30Frames 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.
zoomnumber1Initial 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.
snapThresholdnumber10How 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.
showRulerbooleantrueShow 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.
showMarkersbooleantrueShow 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.
loopbooleantrueWrap 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.
playbackRatenumber1Playback 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.
trackHeightnumber72Height 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.
accentstring (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

Appears In