Canvas Timeline
Function

useTimelineKeyframeDrag

Headless keyframe drag behavior shared by canvas and custom timeline UIs.

Usage notes

Use this hook when building custom DOM or canvas hit targets for keyframe points. The hook owns drag lifecycle, preview updates, value mapping, and settle behavior. It intentionally does not render handles; pair it with useTimelineKeyframeGeometry for keyframe geometry.

Signature

Type Definition
useTimelineKeyframeDrag(options: UseTimelineKeyframeDragOptions = {}): UseTimelineKeyframeDragResult

Parameters

NameTypeDescription
optionsUseTimelineKeyframeDragOptionsDrag geometry aligned with the renderer and hit-test layer.

Returns

UseTimelineKeyframeDragResult

Keyframe drag state and pointer command helpers.

Examples

tsx Example
import type { RefObject } from 'react';
import { useTimelineKeyframeDrag } from '@techsquidtv/canvas-timeline-react';


// Share the containing timeline viewport's ref, including its ruler area.
export function KeyframeHandle({
  clipId,
  keyframeId,
  viewportRef,
}: {
  clipId: string;
  keyframeId: string;
  viewportRef: RefObject<HTMLElement | null>;
}) {
  const drag = useTimelineKeyframeDrag();


  return (
    <button
      type="button"
      aria-pressed={drag.dragging}
      onPointerDown={(event) => {
        const rect = viewportRef.current?.getBoundingClientRect();
        if (!rect) return;
        drag.startKeyframeDrag({
          clipId,
          keyframeId,
          clientX: event.clientX,
          viewportY: event.clientY - rect.top,
        });
      }}
    >
      Move keyframe
    </button>
  );
}

Related links