useTimelineState API

Usage notes

Use `useTimelineState` for low-frequency product chrome that needs a broad view of timeline content, viewport, playback, markers, or edit feedback without calling engine methods. The returned snapshot updates when TimelineProvider receives engine state events. Prefer narrower hooks when a component only needs one live value. For example, use useTimelinePlayheadTime for playback readouts and useTimelineViewport for viewport controls. See React editor hooks for the hook selection guide.

State available

Area	Fields	Use for
Content	tracks, clipGroups, contentRevision	Track lists, clip counts, inspectors, and content-change badges.
Playback and time	playheadTime, playing, playbackRate, duration	Toolbar state and coarse playback status. Use useTimelinePlayheadTime() for live readouts.
Viewport	zoomScale, scrollLeft, scrollTop, viewportWidth, viewportHeight	Viewport-aware chrome. Use viewport hooks for focused scroll and zoom controls.
Selection and ranges	inPoint, outPoint	Range labels, loop region state, and edit selection chrome.
Markers	markers	Marker lists and annotation panels.
Interaction feedback	snapEnabled, snapThresholdPixels, snapFeedback, clipDropFeedback	Snapping toggles, drag/drop hints, and lightweight editor status.

Signature

useTimelineState(): TimelineState

Returns

TimelineState

The latest `TimelineState` snapshot published by `TimelineProvider`.

Examples

import { useTimelineState } from '@techsquidtv/canvas-timeline-react';

export function TimelineStatus() {
  const state = useTimelineState();

  return (
    <dl>
      <dt>Tracks</dt>
      <dd>{state.tracks.length}</dd>
      <dt>Playback</dt>
      <dd>{state.playing ? 'Playing' : 'Paused'}</dd>
      <dt>Zoom</dt>
      <dd>{state.zoomScale}px/s</dd>
    </dl>
  );
}

- TimelineState - TimelineProvider - useTimelinePlayheadTime - useTimelineViewport