useTimelineState (react) 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(): object

Returns

object

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

Return members

Name	Signature	Description
`clipDropFeedback`	`clipDropFeedback: object`	Transient cross-track clip drop feedback for the active body drag interaction.
`clipGroups`	`clipGroups: typeOperator`	Clip groups edited as linked units.
`contentRevision`	`contentRevision: number`	Monotonic counter incremented when track or clip edits can change active layer lookup at a fixed playhead.
`duration?`	`duration?: { r: number; v: number }`	Explicit duration of the timeline. If set, this overrides the dynamic duration calculated from clips.
`inPoint?`	`inPoint?: { r: number; v: number }`	Optional current selection region In-Point boundary.
`markers?`	`markers?: typeOperator`	List of markers positioned on the timeline.
`outPoint?`	`outPoint?: { r: number; v: number }`	Optional current selection region Out-Point boundary.
`playbackRate?`	`playbackRate?: number`	Playback speed multiplier (1.0 = normal speed).
`playheadTime`	`playheadTime: { r: number; v: number }`	The current playhead position.
`playing?`	`playing?: boolean`	Current playback state of the timeline.
`scrollLeft`	`scrollLeft: number`	Horizontal scroll offset in pixels.
`scrollTop`	`scrollTop: number`	Vertical scroll offset in pixels.
`snapEnabled`	`snapEnabled: boolean`	Whether magnetic snapping is globally enabled.
`snapFeedback`	`snapFeedback: { lines: typeOperator; target: object \| null }`	Transient snap guide feedback for the active interaction.
`snapThresholdPixels`	`snapThresholdPixels: number`	Magnetic snap radius in screen pixels.
`tracks`	`tracks: typeOperator`	Active set of tracks.
`viewportHeight?`	`viewportHeight?: number`	Height of the visible timeline area in pixels (for frustum culling/virtualization).
`viewportWidth?`	`viewportWidth?: number`	Width of the visible timeline area in pixels (for frustum culling/virtualization).
`zoomScale`	`zoomScale: number`	Zoom scale representing pixels per second.

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>
  );
}

- TimelineStateSnapshot - TimelineProvider - useTimelinePlayheadTime - useTimelineViewport