upstream-tldraw/packages/driver

@tldraw/driver

Imperative API for driving the tldraw editor programmatically. Useful for scripting, automation, REPL usage, and testing.

Installation

npm install @tldraw/driver

Quick start

import { Driver } from '@tldraw/driver'

const driver = new Driver(editor)

// Simulate user interactions
driver.click(100, 200).pointerDown(300, 400).pointerMove(500, 600).pointerUp()

// Keyboard input
driver.keyPress('a')
driver.keyDown('Shift')
driver.keyUp('Shift')

// Clipboard
driver.copy()
driver.paste({ x: 100, y: 100 })

// Selection manipulation
driver.translateSelection(50, 0)
driver.rotateSelection(Math.PI / 4)
driver.resizeSelection({ scaleX: 2 }, 'bottom_right')

// Camera
driver.pan({ x: 100, y: 0 })
driver.wheel(0, -100)

// Cleanup
driver.dispose()

API

Constructor

new Driver(editor: Editor)

Wraps an existing Editor instance. All methods use only public Editor APIs.

Input events

All input methods return this for fluent chaining. Coordinates are in screen space.

Method	Description
pointerDown(x?, y?, options?, modifiers?)	Dispatch a pointer down event
pointerMove(x?, y?, options?, modifiers?)	Dispatch a pointer move event
pointerUp(x?, y?, options?, modifiers?)	Dispatch a pointer up event
click(x?, y?, options?, modifiers?)	Pointer down + up
rightClick(x?, y?, options?, modifiers?)	Right-click (button 2) down + up
doubleClick(x?, y?, options?, modifiers?)	Double-click sequence
keyDown(key, options?)	Dispatch a key down event
keyUp(key, options?)	Dispatch a key up event
keyPress(key, options?)	Key down + up
keyRepeat(key, options?)	Dispatch a key repeat event
wheel(dx, dy, options?)	Dispatch a wheel/scroll event
pinchStart(x?, y?, z, dx, dy, dz, options?)	Begin a pinch gesture
pinchTo(x?, y?, z, dx, dy, dz, options?)	Continue a pinch gesture
pinchEnd(x?, y?, z, dx, dy, dz, options?)	End a pinch gesture
forceTick(count?)	Emit tick events to advance the editor

Clipboard

Method	Description
copy(ids?)	Copy shapes to the driver's clipboard
cut(ids?)	Cut shapes (copy + delete)
paste(point?)	Paste from the driver's clipboard
clipboard	The current clipboard content (TLContent | null)

Selection manipulation

These methods work in page coordinates and handle the screen-space conversion internally.

Method	Description
translateSelection(dx, dy, options?)	Move the selection by a page-space delta
rotateSelection(angle, options?)	Rotate the selection by an angle in radians
resizeSelection(scale?, handle, options?)	Resize the selection via a handle

Queries

Method	Description
getViewportPageCenter()	Center of the viewport in page coordinates
getSelectionPageCenter()	Center of the selection in page coordinates
getPageCenter(shape)	Center of a shape in page coordinates
getPageRotation(shape)	Rotation of a shape in page space (radians)
getPageRotationById(id)	Rotation of a shape by ID (radians)
getArrowsBoundTo(shapeId)	All arrows bound to a shape
getLastCreatedShape()	The most recently created shape
getLastCreatedShapes(count?)	The last N created shapes

Camera

Method	Description
pan(offset)	Pan the camera by a page-space offset

Lifecycle

Method	Description
dispose()	Remove side-effect handlers. Call when done.

Documentation

Documentation for the most recent release can be found on tldraw.dev/docs, including reference docs. Our release notes can be found here.

For more agent-friendly docs, see our LLMs.txt.

License

See LICENSE.md.