TldrawOptions

Options for configuring tldraw. For defaults, see defaultTldrawOptions.

interface TldrawOptions {}

Example

const options: Partial<TldrawOptions> = {
  maxPages: 3,
  maxShapesPerPage: 1000,
};

function MyTldrawComponent() {
  return <Tldraw options={options} />;
}

Properties

readonly actionShortcutsLocation: "menu" | "swap" | "toolbar";

readonly adjacentShapeMargin: number;

readonly animationMediumMs: number;

Branding name of the app, currently only used for adding aria-label for the application.

readonly branding?: string;

Options for the editor's camera. These are the initial camera options. Use Editor.setCameraOptions to update camera options at runtime.

readonly camera: Partial<TLCameraOptions>;

readonly cameraMovingTimeoutMs: number;

readonly cameraSlideFriction: number;

readonly coarseDragDistanceSquared: number;

readonly coarseHandleRadius: number;

readonly coarsePointerWidth: number;

readonly collaboratorCheckIntervalMs: number;

readonly collaboratorIdleTimeoutMs: number;

readonly collaboratorInactiveTimeoutMs: number;

readonly createTextOnCanvasDoubleClick: boolean;

Whether to use debounced zoom level for certain rendering optimizations. When true, editor.getEfficientZoomLevel() returns a cached zoom value while the camera is moving, reducing re-renders. When false, it always returns the current zoom level.

readonly debouncedZoom: boolean;

The number of shapes that must be on the page for the debounced zoom level to be used. Defaults to 500 shapes.

readonly debouncedZoomThreshold: number;

Options for syncing the editor's camera state with the URL. Set to true to enable with default options, or pass an options object to customize behavior.

readonly deepLinks: TLDeepLinkOptions | true | undefined;

Example

// Enable with defaults
<Tldraw options={{ deepLinks: true }} />

// Enable with custom options
<Tldraw options={{ deepLinks: { param: 'd', debounceMs: 500 } }} />

readonly defaultSvgPadding: number;

readonly doubleClickDurationMs: number;

readonly dragDistanceSquared: number;

readonly edgeScrollDelay: number;

readonly edgeScrollDistance: number;

readonly edgeScrollEaseDuration: number;

readonly edgeScrollSpeed: number;

By default, the toolbar items are accessible via number shortcuts according to their order. To disable this, set this option to false.

readonly enableToolbarKeyboardShortcuts: boolean;

The react provider to use when exporting an image. This is useful if your shapes depend on external context providers. By default, this is React.Fragment.

readonly exportProvider: ComponentType<{
  children: React.ReactNode;
}>;

readonly flattenImageBoundsExpand: number;

readonly flattenImageBoundsPadding: number;

readonly followChaseViewportSnap: number;

readonly gridSteps: readonly {
  readonly mid: number;
  readonly min: number;
  readonly step: number;
}[];

readonly handleRadius: number;

readonly hitTestMargin: number;

readonly laserDelayMs: number;

How long (in milliseconds) to fade all laser scribbles after the session ends. The total points across all scribbles will be removed proportionally over this duration. Defaults to 500ms (0.5 seconds).

readonly laserFadeoutMs: number;

readonly longPressDurationMs: number;

readonly maxExportDelayMs: number;

readonly maxFilesAtOnce: number;

The maximum number of fonts that will be loaded while blocking the main rendering of the canvas. If there are more than this number of fonts needed, we'll just show the canvas right away and let the fonts load in in the background.

readonly maxFontsToLoadBeforeRender: number;

readonly maxPages: number;

readonly maxShapesPerPage: number;

readonly multiClickDurationMs: number;

If you have a CSP policy that blocks inline styles, you can use this prop to provide a nonce to use in the editor's styles.

readonly nonce: string | undefined;

Whether the quick-zoom brush preserves its screen-pixel size when the user zooms the overview. When true, zooming in shrinks the target viewport (higher return zoom); zooming out expands it. When false, the brush keeps the original viewport's page dimensions regardless of overview zoom changes.

readonly quickZoomPreservesScreenBounds: boolean;

The distance (in screen pixels) at which shapes snap to guides and other shapes.

readonly snapThreshold: number;

Whether to allow spacebar panning. When true, the spacebar will pan the camera when held down. When false, the spacebar will not pan the camera.

readonly spacebarPanning: boolean;

How long should previews created by Editor.createTemporaryAssetPreview last before they expire? Defaults to 3 minutes.

readonly temporaryAssetPreviewLifetimeMs: number;

Options for the editor's text rendering. These include TipTap configuration and font handling. These are the initial text options and cannot be changed at runtime.

readonly text: TLTextOptions;

readonly textShadowLod: number;

readonly tooltipDelayMs: number;

readonly uiCoarseDragDistanceSquared: number;

readonly uiDragDistanceSquared: number;

The default padding (in pixels) used when zooming to fit content in the viewport. This affects methods like zoomToFit(), zoomToSelection(), and zoomToBounds(). The actual padding used is the minimum of this value and 28% of the viewport width. Defaults to 128 pixels.

readonly zoomToFitPadding: number;

Methods

Called when content is dropped on the canvas. Provides the page position where the drop occurred and the underlying drag event object. Return true to prevent default drop handling (files, URLs, etc.)

Parameters

{
  event: React.DragEvent<Element>;
  point: VecLike;
};

Returns

boolean;

Called before content is written to the clipboard during a copy or cut operation. Receives the serialized content (shapes, bindings, assets) and can filter or transform it before it reaches the clipboard.

Return a modified TLContent object to change what is copied or cut. Return false to cancel the clipboard write (for cut, the selected shapes are not removed). Return void (or undefined) to pass through unchanged. You may return a Promise of those values if the hook is async.

Example

// Filter out "locked" shapes from copy
onBeforeCopyToClipboard({ content, operation }) {
    return {
        ...content,
        shapes: content.shapes.filter(s => !s.meta.locked),
        rootShapeIds: content.rootShapeIds.filter(id =>
            content.shapes.find(s => s.id === id && !s.meta.locked)
        ),
    }
}

Parameters

{
  content: TLContent;
  editor: Editor;
} & TLClipboardWriteInfo;

Returns

Awaitable<false | TLContent | void>;

Called before pasted content is processed and shapes are created. Receives the parsed external content from the clipboard and can filter, transform, or cancel it.

Return false to cancel the paste. Return a modified content object to transform it. Return void (or undefined) to pass through unchanged. You may return a Promise of those values if the hook is async.

This only fires for clipboard paste operations (keyboard shortcuts and menu actions), not for file drops or programmatic putExternalContent calls.

Example

// Block pasting of image files
onBeforePasteFromClipboard({ content }) {
    if (content.type === 'files') {
        const nonImages = content.files.filter(f => !f.type.startsWith('image/'))
        if (nonImages.length === 0) return false
        return { ...content, files: nonImages }
    }
}

Parameters

{
  content: TLExternalContent<unknown>;
  editor: Editor;
  point?: VecLike;
  source: "clipboard-read" | "native-event";
};

Returns

Awaitable<false | TLExternalContent<unknown> | void>;

Called first for keyboard and menu paste, before tldraw handles or parses clipboard data (and before TldrawOptions.onBeforePasteFromClipboard).

Return false to cancel tldraw's default paste handling for this gesture (same convention as TldrawOptions.onBeforePasteFromClipboard). Use this when you handle paste yourself from raw clipboard data, or to block the gesture entirely. Return void (or undefined) to continue.

Parameters

TLClipboardPasteRawInfo;

Returns

false | void;