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 = {}): object

Parameters

NameTypeDescription
optionsTimelineClipNavigationOptionsInitial active clip and navigation behavior options.

Returns

object

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

Return members

NameSignatureDescription
activeClipactiveClip: TimelineNavigableClip | 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[]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): object | { cause: undefined; message: undefined; ok: true; reason: undefined } & { value: undefined } | { cause: undefined; message: undefined; ok: true; reason: undefined } & { value: TimelineEditCommitResult }Moves the active clip by a relative number of seconds and returns the command result.
moveActiveClipToTrack(deltaTrackIndex: number): object | { cause: undefined; message: undefined; ok: true; reason: undefined } & { value: undefined } | { cause: undefined; message: undefined; ok: true; reason: undefined } & { value: TimelineEditCommitResult }Moves the active clip vertically by a relative track delta and returns the command result.
navigateBy(delta: number): TimelineNavigableClip | nullMoves active navigation by a flattened clip delta.
navigateToFirst(): TimelineNavigableClipMoves active navigation to the first clip in timeline order.
navigateToLast(): TimelineNavigableClipMoves active navigation to the last clip in timeline order.
navigateToTrack(delta: number): TimelineNavigableClip | 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): object | { cause: undefined; message: undefined; ok: true; reason: undefined } & { value: undefined } | { cause: undefined; message: undefined; ok: true; reason: undefined } & { value: TimelineEditCommitResult }Trims one edge of the active clip by a relative number of seconds and returns the command result.

Examples

tsx Example
import { useTimelineClipNavigation } from '@techsquidtv/canvas-timeline-react';


export function CanvasClipNavigator() {
  const clipNavigation = useTimelineClipNavigation({ selectOnNavigate: true });


  return (
    <div {...clipNavigation.focusTargetProps}>
      <p>{clipNavigation.activeClipStatus}</p>
      <button type="button" onClick={() => clipNavigation.navigatePrevious()}>
        Previous clip
      </button>
      <button type="button" onClick={() => clipNavigation.navigateNext()}>
        Next clip
      </button>
    </div>
  );
}

Related links