React Timeline Component Hooks & UI - @techsquidtv/canvas-timeline-react

Installation

pnpm add @techsquidtv/canvas-timeline-react

npm install @techsquidtv/canvas-timeline-react

yarn add @techsquidtv/canvas-timeline-react

bun add @techsquidtv/canvas-timeline-react

When to use it

You already have a `TimelineEngine` instance and want to bind its state reactively to React components and controls.

You want built-in hooks to track playback cursor position, selected clips, viewport state, undo/redo stacks, and clipboard actions.

You need pointer-captured, CSS-styleable interaction layers like selection boxes, drag-and-trim handles, playhead scrubbers, and customized scrollbars.

Common imports

import {
  Timeline,
  TimelineProvider,
  useTimeline,
} from '@techsquidtv/canvas-timeline-react';

import '@techsquidtv/canvas-timeline-react/styles.css';

import '@techsquidtv/canvas-timeline-react/base.css';

import {
  useClipEditPreview,
  useTimelineClips,
  useTimelineEditCommands,
  useTimelineEditImpacts,
  useTimelineEditMode,
  useTimelineEditPreview,
  useTimelineRangeSelection,
} from '@techsquidtv/canvas-timeline-react/hooks';

Usage notes

•Binds `TimelineEngine` state and controls to React contexts and hooks (`useTimeline`) for reactive UI updates and property synchronization.
•Provides headless edit-command hooks so product gestures can validate, preview, commit, and cancel typed edits through `TimelineEngine`.
•Styles low-frequency interaction chrome (e.g., scrollbars, drag handles, active overlays) using CSS, keeping DOM nodes minimal and high-frequency rendering off the main thread.
•Leverages `Timeline.ClipInteractionLayer` with pointer capture and hit testing to handle complex gestures (selection, drag, trim) without spawning per-clip DOM trees.
•Provides building blocks like `Timeline.PlayheadArea` and `Timeline.PlayheadGrabber` to facilitate dragging behavior and layout composition.
•Provides an accessible Base UI-backed range selector (`Timeline.RangeSelector`) for loop and selection bounds.
•Use the native HTML media adapter package for one `HTMLMediaElement`; embedded video audio is supported by the element, while separate visual/audio track sync needs a custom multi-element adapter.

API Surface

Explore the key components, hooks, and classes exported by this package. Click any symbol to view its full TSDoc parameter signatures.

Key Entry Points

FunctionTimelineProvider

Sets up a bridge between the central event-driven `TimelineEngine` model and standard React functional layouts. Subscribes to settled state, selection, playback, content, and clipboard changes, pushing lightweight state updates downwards into hooks.

VariableTimeline

Namespace of timeline UI components for composing an editor surface.

Timeline HooksuseTimeline

Reads the timeline engine and synchronized state from React context. Use this hook inside components wrapped by `TimelineProvider` when you need to call imperative engine commands and read the latest React-rendered state in the same component. Prefer narrower hooks such as `useTimelineState`, `useTimelinePlayback`, or `useTimelineClips` when a component only needs one slice of timeline behavior.

Timeline HooksuseTimelineState

Reads the current synchronized timeline state. This is a render-focused shortcut for components that need track, playhead, zoom, scroll, marker, or playback state without calling engine methods. The returned value updates when `TimelineProvider` receives engine state events.

Timeline HooksuseTimelinePlayback

Provides canonical transport, playhead command, and in/out range commands. Compose this with `useTimelinePlayheadTime` when a component also needs a live clock readout.

VariableTimecodeField

Compact timecode field parts. `TimecodeField.Root` owns editing state. `TimecodeField.Trigger` renders the compact displayed value, and `TimecodeField.Input` renders the temporary `TimecodeInput` used for typed edits.

Subpath Imports

Import specific files or modules directly to reduce bundle size or target specialized package layers.

Import Path	Description
@techsquidtv/canvas-timeline-react	Provider, context, hooks, and Timeline component namespace.
@techsquidtv/canvas-timeline-react/hooks	Hook-only entrypoint.
@techsquidtv/canvas-timeline-react/components	Component-only entrypoint.
@techsquidtv/canvas-timeline-react/base.css	Structural interaction geometry without default visuals.
@techsquidtv/canvas-timeline-react/theme.css	Shadcn-token-driven visual theme for interaction chrome and timeline tokens.
@techsquidtv/canvas-timeline-react/styles.css	Structural styles plus shadcn-compatible interaction chrome.

Canvas React Timeline Editor UI Bindings