Driver • tldraw Docs

Table of contents

clipboard
editor
Properties
Methods

Driver wraps an Editor instance and provides an imperative API for driving it programmatically. Useful for scripting, automation, REPL usage, and testing.

All methods use only public Editor APIs and return this for fluent chaining.

class Driver {}

Constructor

Constructs a new instance of the Driver class

Parameters

Name	Description
`editor`	`Editor;`

Properties

clipboard

Local clipboard content. Used by copy, cut, and paste.

clipboard: null | TLContent;

editor

readonly

readonly editor: Editor;

Methods

click( )

Dispatches a pointer down followed by pointer up at the given screen coordinates.

click(
  x?: number,
  y?: number,
  options?: PointerEventInit,
  modifiers?: EventModifiers,
): this;

Parameters

Name	Description
`x`	`number;` Screen x coordinate. Defaults to current pointer.
`y`	`number;` Screen y coordinate. Defaults to current pointer.
`options`	`PointerEventInit;` Target shape/selection or partial event info.
`modifiers`	`EventModifiers;` Override shift, ctrl, or alt key state.

Returns

this;

copy( )

Copies the given shapes to the controller clipboard. Defaults to the current selection.

copy(ids?: TLShapeId[]): this;

Parameters

Name	Description
`ids`	`TLShapeId[];` Shape IDs to copy. Defaults to the current selection.

Returns

this;

createPageID( )

Creates a page ID from a string.

createPageID(id: string): import("@tldraw/editor").TLPageId;

Parameters

Name	Description
`id`	`string;` The string to convert to a page ID.

Returns

import("@tldraw/editor").TLPageId;

createShapeID( )

Creates a shape ID from a string.

createShapeID(id: string): TLShapeId;

Parameters

Name	Description
`id`	`string;` The string to convert to a shape ID.

Returns

TLShapeId;

cut( )

Cuts the given shapes (copy to clipboard, then delete). Defaults to the current selection.

cut(ids?: TLShapeId[]): this;

Parameters

Name	Description
`ids`	`TLShapeId[];` Shape IDs to cut. Defaults to the current selection.

Returns

this;

dispose( )

Remove all registered side-effect handlers. Call when this controller is no longer needed.

dispose(): void;

doubleClick( )

Dispatches a double-click sequence at the given screen coordinates.

doubleClick(
  x?: number,
  y?: number,
  options?: PointerEventInit,
  modifiers?: EventModifiers,
): this;

Parameters

Name	Description
`x`	`number;` Screen x coordinate. Defaults to current pointer.
`y`	`number;` Screen y coordinate. Defaults to current pointer.
`options`	`PointerEventInit;` Target shape/selection or partial event info.
`modifiers`	`EventModifiers;` Override shift, ctrl, or alt key state.

Returns

this;

forceTick( )

Emits tick events to advance the editor by the given number of frames (default 1).

forceTick(count?: number): this;

Parameters

Name	Description
`count`	`number;` Number of tick events to emit. Defaults to 1.

Returns

this;

getArrowsBoundTo( )

Returns all arrow shapes bound to the given shape.

getArrowsBoundTo(shapeId: TLShapeId): TLArrowShape[];

Parameters

Name	Description
`shapeId`	`TLShapeId;` The shape ID to find arrows bound to.

Returns

TLArrowShape[];

getLastCreatedShape( )

Get the last created shape.

getLastCreatedShape<T extends TLShape>(): T;

getLastCreatedShapes( )

Get the last created shapes.

getLastCreatedShapes(count?: number): TLShape[];

Parameters

Name	Description
`count`	`number;` The number of shapes to get.

Returns

TLShape[];

getPageCenter( )

Returns the center of a shape in page coordinates, or null if the shape has no page transform.

getPageCenter(shape: TLShape): null | Vec;

Parameters

Name	Description
`shape`	`TLShape;` The shape to get the center of.

Returns

null | Vec;

getPageRotation( )

Returns the rotation of a shape in page space, in radians.

getPageRotation(shape: TLShape): number;

Parameters

Name	Description
`shape`	`TLShape;` The shape to get the rotation of.

Returns

number;

getPageRotationById( )

Returns the rotation of a shape in page space by ID, in radians.

getPageRotationById(id: TLShapeId): number;

Parameters

Name	Description
`id`	`TLShapeId;` The shape ID.

Returns

number;

getSelectionPageCenter( )

Returns the center of the current selection in page coordinates, or null if nothing is selected.

getSelectionPageCenter(): null | Vec;

getViewportPageCenter( )

Returns the center of the viewport in page coordinates.

getViewportPageCenter(): Vec;

keyDown( )

Dispatches a key down event for the given key.

keyDown(
  key: string,
  options?: Partial<Omit<TLKeyboardEventInfo, "key">>,
): this;

Parameters

Name	Description
`key`	`string;` The key to press (e.g. 'a', 'Enter', 'Shift').
`options`	`Partial<Omit<TLKeyboardEventInfo, "key">>;` Partial keyboard event overrides.

Returns

this;

keyPress( )

Dispatches a key down followed by key up for the given key.

keyPress(
  key: string,
  options?: Partial<Omit<TLKeyboardEventInfo, "key">>,
): this;

Parameters

Name	Description
`key`	`string;` The key to press (e.g. 'a', 'Enter', 'Shift').
`options`	`Partial<Omit<TLKeyboardEventInfo, "key">>;` Partial keyboard event overrides.

Returns

this;

keyRepeat( )

Dispatches a key repeat event for the given key.

keyRepeat(
  key: string,
  options?: Partial<Omit<TLKeyboardEventInfo, "key">>,
): this;

Parameters

Name	Description
`key`	`string;` The key that is repeating (e.g. 'a', 'ArrowDown').
`options`	`Partial<Omit<TLKeyboardEventInfo, "key">>;` Partial keyboard event overrides.

Returns

this;

keyUp( )

Dispatches a key up event for the given key.

keyUp(key: string, options?: Partial<Omit<TLKeyboardEventInfo, "key">>): this;

Parameters

Name	Description
`key`	`string;` The key to release (e.g. 'a', 'Enter', 'Shift').
`options`	`Partial<Omit<TLKeyboardEventInfo, "key">>;` Partial keyboard event overrides.

Returns

this;

pan( )

Pans the camera by the given offset (in page coordinates). Does nothing if camera is locked.

pan(offset: VecLike): this;

Parameters

Name	Description
`offset`	`VecLike;` The pan delta (x, y) in page coordinates.

Returns

this;

paste( )

Pastes content from the controller clipboard. If shift is held, uses current pointer. Otherwise uses the given point.

paste(point?: VecLike): this;

Parameters

Name	Description
`point`	`VecLike;` Page coordinates for paste location. If omitted and shift is not held, placement may vary.

Returns

this;

pinchEnd( )

Dispatches a pinch end event.

pinchEnd(
  x: number | undefined,
  y: number | undefined,
  z: number,
  dx: number,
  dy: number,
  dz: number,
  options?: Partial<Omit<TLPinchEventInfo, "delta" | "offset" | "point">>,
): this;

Parameters

Name	Description
`x`	`number \| undefined;` Screen x coordinate. Defaults to current pointer.
`y`	`number \| undefined;` Screen y coordinate. Defaults to current pointer.
`z`	`number;` Pinch scale/factor.
`dx`	`number;` Delta x for pinch.
`dy`	`number;` Delta y for pinch.
`dz`	`number;` Delta z for pinch.
`options`	`Partial< Omit<TLPinchEventInfo, "delta" \| "offset" \| "point"> >;` Partial pinch event overrides.

Returns

this;

pinchStart( )

Dispatches a pinch start event.

pinchStart(
  x: number | undefined,
  y: number | undefined,
  z: number,
  dx: number,
  dy: number,
  dz: number,
  options?: Partial<Omit<TLPinchEventInfo, "delta" | "offset" | "point">>,
): this;

Parameters

Name	Description
`x`	`number \| undefined;` Screen x coordinate. Defaults to current pointer.
`y`	`number \| undefined;` Screen y coordinate. Defaults to current pointer.
`z`	`number;` Pinch scale/factor.
`dx`	`number;` Delta x for pinch.
`dy`	`number;` Delta y for pinch.
`dz`	`number;` Delta z for pinch.
`options`	`Partial< Omit<TLPinchEventInfo, "delta" \| "offset" \| "point"> >;` Partial pinch event overrides.

Returns

this;

pinchTo( )

Dispatches a pinch move event (pinch_to).

pinchTo(
  x: number | undefined,
  y: number | undefined,
  z: number,
  dx: number,
  dy: number,
  dz: number,
  options?: Partial<Omit<TLPinchEventInfo, "delta" | "offset" | "point">>,
): this;

Parameters

Name	Description
`x`	`number \| undefined;` Screen x coordinate. Defaults to current pointer.
`y`	`number \| undefined;` Screen y coordinate. Defaults to current pointer.
`z`	`number;` Pinch scale/factor.
`dx`	`number;` Delta x for pinch.
`dy`	`number;` Delta y for pinch.
`dz`	`number;` Delta z for pinch.
`options`	`Partial< Omit<TLPinchEventInfo, "delta" \| "offset" \| "point"> >;` Partial pinch event overrides.

Returns

this;

pointerDown( )

Dispatches a pointer down event at the given screen coordinates.

pointerDown(
  x?: number,
  y?: number,
  options?: PointerEventInit,
  modifiers?: EventModifiers,
): this;

Parameters

Name	Description
`x`	`number;` Screen x coordinate. Defaults to current pointer.
`y`	`number;` Screen y coordinate. Defaults to current pointer.
`options`	`PointerEventInit;` Target shape/selection or partial event info.
`modifiers`	`EventModifiers;` Override shift, ctrl, or alt key state.

Returns

this;

pointerMove( )

Dispatches a pointer move event at the given screen coordinates.

pointerMove(
  x?: number,
  y?: number,
  options?: PointerEventInit,
  modifiers?: EventModifiers,
): this;

Parameters

Name	Description
`x`	`number;` Screen x coordinate. Defaults to current pointer.
`y`	`number;` Screen y coordinate. Defaults to current pointer.
`options`	`PointerEventInit;` Target shape/selection or partial event info.
`modifiers`	`EventModifiers;` Override shift, ctrl, or alt key state.

Returns

this;

pointerUp( )

Dispatches a pointer up event at the given screen coordinates.

pointerUp(
  x?: number,
  y?: number,
  options?: PointerEventInit,
  modifiers?: EventModifiers,
): this;

Parameters

Name	Description
`x`	`number;` Screen x coordinate. Defaults to current pointer.
`y`	`number;` Screen y coordinate. Defaults to current pointer.
`options`	`PointerEventInit;` Target shape/selection or partial event info.
`modifiers`	`EventModifiers;` Override shift, ctrl, or alt key state.

Returns

this;

resizeSelection( )

Simulates resizing the current selection via the given handle, with optional scale factors.

resizeSelection(
  scale:
    | {
        scaleX?: number | undefined;
        scaleY?: number | undefined;
      }
    | undefined,
  handle: SelectionHandle,
  options?: Partial<TLPointerEventInfo>,
): this;

Parameters

Name	Description
`scale`	`\| { scaleX?: number \| undefined; scaleY?: number \| undefined; } \| undefined;` Scale factors for x and y. Defaults to `\{ scaleX: 1, scaleY: 1 \}`.
`handle`	`SelectionHandle;` The selection handle to drag (e.g. 'top', 'bottom_right').
`options`	`Partial<TLPointerEventInfo>;` Partial pointer event overrides (e.g. altKey to scale from center).

Returns

this;

rightClick( )

Dispatches a right-click (button 2) down and up at the given screen coordinates.

rightClick(
  x?: number,
  y?: number,
  options?: PointerEventInit,
  modifiers?: EventModifiers,
): this;

Parameters

Name	Description
`x`	`number;` Screen x coordinate. Defaults to current pointer.
`y`	`number;` Screen y coordinate. Defaults to current pointer.
`options`	`PointerEventInit;` Target shape/selection or partial event info.
`modifiers`	`EventModifiers;` Override shift, ctrl, or alt key state.

Returns

this;

rotateSelection( )

Simulates rotating the current selection by the given angle in radians via the rotation handle.

rotateSelection(
  angleRadians: number,
  options?: {
    handle?: RotateCorner;
    shiftKey?: boolean;
  },
): this;

Parameters

Name	Description
`angleRadians`	`number;` Rotation angle in radians.
`options`	`{ handle?: RotateCorner; shiftKey?: boolean; };` Optional handle and shiftKey. handle defaults to 'top_left_rotate'.

Returns

this;

translateSelection( )

Simulates translating the current selection by the given delta in page coordinates.

translateSelection(
  dx: number,
  dy: number,
  options?: Partial<TLPointerEventInfo>,
): this;

Parameters

Name	Description
`dx`	`number;` Horizontal delta in page coordinates.
`dy`	`number;` Vertical delta in page coordinates.
`options`	`Partial<TLPointerEventInfo>;` Partial pointer event overrides (e.g. altKey for center-based scaling).

Returns

this;

wheel( )

Dispatches a wheel event with the given delta values.

wheel(
  dx: number,
  dy: number,
  options?: Partial<Omit<TLWheelEventInfo, "delta">>,
): this;

Parameters

Name	Description
`dx`	`number;` Horizontal scroll delta.
`dy`	`number;` Vertical scroll delta.
`options`	`Partial<Omit<TLWheelEventInfo, "delta">>;` Partial wheel event overrides.

Returns

this;