Canvas Timeline

React Registry

componentViewport Scrollbar@techsquidtv/canvas-timeline-react

Viewport Scrollbar

A timeline adapter that maps range scrollbar changes to pan and zoom state.

Viewport scrollbar preview

Timeline-aware range controls wired to scrollLeft and zoomScale.

Open full demo

Installation

pnpm
pnpm add @techsquidtv/canvas-timeline-react
  1. 1

    Install the package.

    The command above adds the React bindings and their package dependencies.

  2. 2

    Import from the React entrypoint.

    @techsquidtv/canvas-timeline-react
  3. 3

    Add the timeline styles.

    Use the full stylesheet with shadcn-compatible tokens, or base.css when your app owns the visual theme.

    Default visuals
    import '@techsquidtv/canvas-timeline-react/styles.css';
    Base geometry
    import '@techsquidtv/canvas-timeline-react/base.css';

Usage

TimelineViewportScrollbar.tsx
import { useMemo } from 'react';
import { TimelineEngine } from '@techsquidtv/canvas-timeline-core';
import { Timeline, TimelineProvider } from '@techsquidtv/canvas-timeline-react';
import { fromSeconds } from '@techsquidtv/canvas-timeline-utils';


export function TimelineViewportScrollbar() {
  const engine = useMemo(
    () =>
      new TimelineEngine({
        duration: fromSeconds(30),
        tracks: [],
        zoomScale: 80,
      }),
    []
  );


  return (
    <TimelineProvider engine={engine}>
      <Timeline.Root className="h-80" />


      <Timeline.ViewportScrollbar>
        <Timeline.ViewportScrollbarThumb>
          <Timeline.ViewportScrollbarHandle side="start" />
          <Timeline.ViewportScrollbarHandle side="end" />
        </Timeline.ViewportScrollbarThumb>
      </Timeline.ViewportScrollbar>
    </TimelineProvider>
  );
}

Examples

Generic Range

Use RangeScrollbar directly when your control is not bound to a TimelineEngine.

Notes

  • Render these components inside a TimelineProvider so they can read the shared TimelineEngine.
  • Import @techsquidtv/canvas-timeline-react/styles.css when your app defines shadcn-compatible semantic tokens, or base.css when supplying your own theme.
  • CSS styles interaction layers; renderer theme styles canvas-painted timeline visuals.
  • Use the theming guide when CSS tokens should drive canvas-painted colors.
  • The viewport scrollbar reads viewportWidth, scrollLeft, and zoomScale from the shared TimelineEngine.
  • Dragging the thumb pans with engine.setScrollLeft(); dragging either handle changes zoom with engine.setZoomScale() and then repositions scrollLeft.
  • Mount Timeline.Root in the same TimelineProvider so the engine knows the measured viewport width used for handle zoom math.
  • Use Timeline.VerticalScrollbar for track-stack scrolling; ViewportScrollbar is the horizontal time viewport and zoom control.

API Reference

Viewport Scrollbar

A timeline adapter that maps range scrollbar changes to pan and zoom state.

Exports

NameReferenceDescription
Timeline.ViewportScrollbarAPI referenceTimeline-aware root that adapts the generic range scrollbar.
Timeline.ViewportScrollbarThumbAPI referenceDraggable thumb representing the visible timeline window.
Timeline.ViewportScrollbarHandleAPI referenceResize handle for adjusting one side of the visible timeline window.
useTimelineViewportScrollbarAPI referenceHook that derives range scrollbar props from timeline viewport state.

Props and Inputs

NameTypeDescription
side'start' | 'end'Resize handle side for Timeline.ViewportScrollbarHandle.
minSpannumberSmallest visible timeline duration in seconds.