useTimelineEvent API

Usage notes

The hook keeps the event subscription stable while updating the callback ref every render, avoiding stale closures without resubscribing for handler-only changes. Use it for low-level integration work such as analytics, custom status panels, or imperative bridges. Prefer focused hooks such as useTimelinePlayheadTime or useTimelineClipDropFeedback when a public hook already exists for the state you need. Events with `void` payloads can still use zero-argument handlers.

Signature

useTimelineEvent(eventName: EventName, handler: TimelineEventHandler<EventName>, options: TimelineEventOptions = {}): void

Type parameters

Name	Constraint	Default	Description
`EventName`	`typeOperator`	None	Timeline engine event name from `EngineEventMap`.

Parameters

Name	Type	Description
eventName	EventName	TimelineEngine event name to subscribe to.
handler	TimelineEventHandler<EventName>	Callback invoked with the typed event payload.
options	TimelineEventOptions	Optional subscription controls.

Returns

void

Nothing; the subscription is managed for the component lifetime.

Examples

import { useState } from 'react';
import { useTimelineEvent } from '#react/hooks';

export function PlaybackRateReadout() {
  const [rate, setRate] = useState(1);

  useTimelineEvent('playback:rate', setRate);

  return <span>{rate}x</span>;
}

Events and lifecycle