Canvas Timeline
Function

useTimelineClipNavigation

Provides constant-DOM keyboard navigation and commands for canvas clips. The hook flattens canvas-rendered clips into a navigable model without mounting one DOM element per clip. Consumers can use the returned `focusTargetProps` on a single focused element, or wire the navigation and edit commands into their own shortcut system and selected-clip inspector.

Signature

Type Definition
useTimelineClipNavigation(options: TimelineClipNavigationOptions<TrackKind> = {}): object

Type parameters

NameConstraintDefaultDescription
TrackKindNonestringNo type parameter summary yet.

Parameters

NameTypeDescription
optionsTimelineClipNavigationOptions<TrackKind>Initial active clip and navigation behavior options.

Returns

object

Active clip metadata, flattened clip list, navigation commands, edit commands, and optional focus-target props.

Return members

NameSignatureDescription
activeClipactiveClip: TimelineNavigableClip<TrackKind> | nullMetadata for the active navigable clip, or `null` when no clips exist.
activeClipIdactiveClipId: stringClip id for the active navigable clip.
activeClipStatusTextactiveClipStatusText: stringActive clip summary suitable for an accessible label or live status.
clipCountclipCount: numberNumber of navigable clips.
clipsclips: TimelineNavigableClip<TrackKind>[]Flattened list of canvas clips with accessibility metadata.
focusTargetPropsfocusTargetProps: HTMLAttributes<HTMLElement>Default props for a single focusable clip-navigation target.
getFocusTargetProps(props: HTMLAttributes<T> = {}): HTMLAttributes<T>Builds props for a single focusable clip-navigation target.
isFocusTargetFocusedisFocusTargetFocused: booleanWhether the returned focus target currently contains focus.
moveActiveClipBy(deltaSeconds: number): TimelineCommandResult<void> | TimelineCommandResult<TimelineClipMoveResult>Moves the active clip by a relative number of seconds and returns the command result.
moveActiveClipToTrack(deltaTrackIndex: number): TimelineCommandResult<void> | TimelineCommandResult<TimelineClipMoveResult>Moves the active clip vertically by a relative track delta and returns the command result.
navigateBy(delta: number): TimelineNavigableClip<TrackKind> | nullMoves active navigation by a flattened clip delta.
navigateToFirst(): TimelineNavigableClip<TrackKind>Moves active navigation to the first clip in timeline order.
navigateToLast(): TimelineNavigableClip<TrackKind>Moves active navigation to the last clip in timeline order.
navigateToTrack(delta: number): TimelineNavigableClip<TrackKind> | nullMoves active navigation vertically between tracks.
selectActiveClip(): voidSelects the active clip in the timeline engine.
setActiveClip(clipId: string | null): voidSets the active clip id and optionally selects it in the engine.
trimActiveClipBy(edge: "start" | "end", deltaSeconds: number): TimelineCommandResult<void>Trims one edge of the active clip by a relative number of seconds and returns the command result.

Examples

tsx Example
const clipNavigation = useTimelineClipNavigation();


return (
  <div {...clipNavigation.focusTargetProps}>
    {clipNavigation.activeClip?.name}
  </div>
);