Editor

The Editor class is the main way of controlling tldraw's editor. You can use it to manage the editor's internal state, make changes to the document, or respond to changes that have occurred.

By design, the Editor's surface area is very large. Almost everything is available through it. Need to create some shapes? Use Editor#createShapes. Need to delete them? Use Editor#deleteShapes. Need a sorted array of every shape on the current page? Use Editor#getCurrentPageShapesSorted.

Accessing the editor

You can access the editor in two ways:

The onMount callback

The Tldraw component's onMount callback provides the editor as the first argument.

function App() {
	return (
		<Tldraw
			onMount={(editor) => {
				// your editor code here
			}}
		/>
	)
}

The useEditor hook

The useEditor hook returns the editor instance. It must be called from within the JSX of the Tldraw component.

function InsideOfContext() {
	const editor = useEditor()
	// your editor code here
	return null
}

function App() {
	return (
		<Tldraw>
			<InsideOfContext />
		</Tldraw>
	)
}

If you're using the subcomponents as shown in this example, the editor instance is provided by the TldrawEditor component.

Reactive state

The editor's state is reactive. Methods like Editor#getSelectedShapeIds or Editor#getCurrentPageShapes return values that automatically update when the underlying data changes. You can use these values directly in React components with the track wrapper or useValue hook.

import { track, useEditor } from 'tldraw'

export const SelectedShapeIdsCount = track(() => {
	const editor = useEditor()
	return <div>{editor.getSelectedShapeIds().length}</div>
})

See the Signals article for more on tldraw's reactive state system.

Batching changes

Each change to the editor happens within a transaction. You can batch multiple changes into a single transaction using the Editor#run method. Batching improves performance and reduces overhead for persisting or distributing changes.

editor.run(() => {
	editor.createShapes(myShapes)
	editor.sendToBack(myShapes)
	editor.selectNone()
})

The run method also accepts options to control history and locked shape behavior:

// Make changes without affecting undo/redo history
editor.run(
	() => {
		editor.createShapes(myShapes)
	},
	{ history: 'ignore' }
)

// Make changes to locked shapes
editor.run(
	() => {
		editor.updateShapes(myLockedShapes)
	},
	{ ignoreShapeLock: true }
)

Capabilities

The editor provides methods and properties organized around these areas:

Data

• Signals — Reactive state primitives
• Store — The reactive database holding all records
• Shapes — Create, read, update, and delete shapes
• Bindings — Relationships between shapes
• Pages — Manage document pages
• Assets — Images, videos, and other media

Interaction

• Tools — The state machine that handles user input
• Selection — Manage which shapes are selected
• Input handling — Pointer and keyboard state
• Events — Subscribe to user interactions and state changes

View

• Camera — Control viewport position and zoom
• Coordinates — Convert between screen and page space

State management

• Instance state — Per-editor settings like current tool and focus
• Visibility — Control which shapes are shown
• History — Undo, redo, and history management
• Side effects — React to record lifecycle changes

Configuration

• User preferences — Cross-instance settings like dark mode
• Readonly mode — Disable editing
• Locked shapes — Prevent changes to specific shapes

Output

• Image export — Export to SVG, PNG, and other formats

See the Editor API reference for the complete list of methods and properties.