Skip to main content

<Canvas>v4.0.527

Renders a Remotion composition using <Player>, registers its timeline tracks, and optionally overlays selection outlines that can be dragged to move elements.

Unlike a plain <Player>, the Canvas enables the interactivity of the mounted elements: each track exposes its controls and the controller can preview prop values without changing the source.

warning

Experimental API: This package is not stable. Its public API may change without a major version bump.

Preview.tsx
import {Canvas, useCanvasController} from '@remotion/sdk';
import {Video} from './Video';

export const Preview = () => {
  const controller = useCanvasController();
  return (
    <Canvas
      controller={controller}
      showOutlines
      component={Video}
      compositionWidth={1920}
      compositionHeight={1080}
      durationInFrames={150}
      fps={30}
    />
  );
};

Props​

CanvasProps includes the <Player> props and the props below. <Canvas> forwards its ref to the Player.

controller​

A CanvasController shared with your timeline and selection UI. Keep it stable while the Canvas is mounted.

showOutlines?​

Whether to draw hover and selection outlines over the composition. Default: false. When enabled, pointer events select outlines instead of reaching interactive controls inside the composition. Set it to false for an interaction mode that lets users operate those controls.

Clicking empty canvas space or pressing Escape while the overlay is focused clears selection. Shift-click selects a range; Command-click on macOS or Ctrl-click elsewhere toggles an item.

onSequencePropsChange?v4.0.530​

Enables moving elements on the canvas. Dragging a selected outline moves every selected element; the arrow keys nudge the selection by one pixel, ten with Shift, while the overlay is focused. Shift locks a drag to the dominant axis. The moved elements snap to the edges and the center of the composition, unless Command or Ctrl is held.

While the gesture is in progress, the new style.translate values are previewed through controller.overrides. When the gesture ends with a changed value, the callback receives one CanvasSequencePropChange per moved source node with nodePathInfo, the schema key, the value and the element's schema. A change with type: 'static' also carries the schema defaultValue; write it with updateNodeProps(). A change with type: 'keyframe' carries the frame at which to add a keyframe with updateNodeKeyframes(); it is reported for props that getSequencePropStatuses describes as keyframed. Clear the overrides once the update is applied; until then, the canvas keeps showing the new position.

Persisting a move
export const onSequencePropsChange = async (changes: readonly CanvasSequencePropChange[]) => {
  for (const change of changes) {
    await persist(change);
    controller.overrides.clear(change.nodePathInfo);
  }
};

Elements can be moved when they expose a style.translate field in their controls and their source node is registered with setSequenceNodePaths(). Without the callback, outlines can be selected but not moved.

getSequencePropStatuses?v4.0.530​

A CanvasSequencePropStatusResolver called with a SequenceNodePathInfo and the schema keys about to be edited, before a move starts. Return how those props are written in the source, as the props of getNodeProps() report them, or null if the source is unknown.

A prop with status: 'computed' cannot be moved: the outline is selected but does not follow the pointer, like in the Remotion Studio. A status: 'keyframed' prop that uses interpolate() is moved by adding a keyframe at the current frame, and the gesture is previewed with the existing keyframes in place. A status: 'static' prop starts from its codeValue.

By default, the source is unknown: every prop starts from the runtime value of the mounted element and is reported as a static change.

Reading the source
export const getSequencePropStatuses: CanvasSequencePropStatusResolver = (nodePathInfo, keys) => {
  const {absolutePath, nodePath} = nodePathInfo.sequenceSubscriptionKey;
  return getNodeProps({
    project,
    node: {filePath: absolutePath, nodePath},
    keys: [...keys],
  }).props;
};

resolveSequenceNodePathInfo?​

A CanvasSequenceNodePathResolver called with a TimelineTrackData and its index. It returns a SequenceNodePathInfo identity or null to make the track unselectable. The default is getCanvasSequenceNodePathInfo(), which uses the identities registered with setSequenceNodePaths().

Use the same resolver when constructing selection items for the layer list. Keep its function identity stable where possible, for example with useCallback().

Compatibility​

BrowsersEnvironments
Chrome
Firefox
Safari

See also​