Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tldraw/tldraw/llms.txt
Use this file to discover all available pages before exploring further.
The Editor class is the heart of tldraw. It manages the infinite canvas, handles shape operations, processes user input, and maintains the application state through a reactive store.
Constructor
Create a new Editor instance with the required configuration.
const editor = new Editor({
store: myStore,
shapeUtils: [RectangleUtil, CircleUtil],
bindingUtils: [ArrowBindingUtil],
tools: [SelectTool, DrawTool],
getContainer: () => document.getElementById('canvas')!
})
Configuration object for the editorThe Store instance containing the editor’s data
shapeUtils
TLAnyShapeUtilConstructor[]
required
Array of shape utility classes for creating and managing shapes
bindingUtils
TLAnyBindingUtilConstructor[]
required
Array of binding utility classes for managing shape relationships
tools
TLStateNodeConstructor[]
required
Array of tool classes for handling user interactions
getContainer
() => HTMLElement
required
Function that returns the HTML container element for the editor
Custom user configuration
The editor’s initial active tool or state node id
Whether to automatically focus the editor when it mounts
Additional editor options including camera and text configuration
Core properties
store
The editor’s reactive store containing all records (shapes, pages, assets, etc.).
history
readonly history: HistoryManager<TLRecord>
user
readonly user: UserPreferencesManager
readonly inputs: InputsManager
snaps
readonly snaps: SnapManager
Shape operations
getShape
Get a shape by its id.
getShape<T extends TLShape = TLShape>(id: TLShapeId): T | undefined
The id of the shape to get
The shape with the given id, or undefined if not found
const shape = editor.getShape('shape:abc123')
if (shape) {
console.log('Shape type:', shape.type)
}
getShapes
Get multiple shapes by their ids.
getShapes(ids: TLShapeId[]): TLShape[]
createShape
Create a new shape.
createShape<T extends TLShape>(partial: TLCreateShapePartial<T>): this
editor.createShape({
type: 'geo',
x: 100,
y: 100,
props: {
w: 200,
h: 100,
geo: 'rectangle'
}
})
updateShape
Update an existing shape.
updateShape<T extends TLShape>(
partial: TLShapePartial<T> | null | undefined
): this
editor.updateShape({
id: 'shape:abc123',
x: 150,
y: 200
})
updateShapes
Update multiple shapes.
updateShapes<T extends TLShape>(partials: (TLShapePartial<T> | null | undefined)[]): this
deleteShape
Delete a shape by its id.
deleteShape(id: TLShapeId): this
deleteShapes
Delete multiple shapes.
deleteShapes(ids: TLShapeId[]): this
getShapeUtil
Get the shape utility for a given shape type.
getShapeUtil<S extends TLShape>(shape: S | TLShapePartial<S> | S['type']): ShapeUtil<S>
Selection
getSelectedShapes
Get all currently selected shapes.
getSelectedShapes(): TLShape[]
getSelectedShapeIds
Get the ids of all selected shapes.
getSelectedShapeIds(): TLShapeId[]
setSelectedShapes
Set the selected shapes.
setSelectedShapes(shapes: TLShapeId[] | TLShape[]): this
// Select by ids
editor.setSelectedShapes(['shape:abc', 'shape:def'])
// Select by shapes
const shapes = editor.getShapesOnPage()
editor.setSelectedShapes(shapes.slice(0, 2))
select
Select one or more shapes.
select(...shapes: TLShapeId[] | TLShape[]): this
selectAll
Select all shapes on the current page.
selectNone
Clear the selection.
getSelectionPageBounds
Get the bounding box of the current selection.
getSelectionPageBounds(): Box | null
History operations
undo
Undo to the last mark.
redo
Redo to the next mark.
canUndo
Check if undo is available.
canRedo
Check if redo is available.
markHistoryStoppingPoint
Create a new mark in the undo/redo history.
markHistoryStoppingPoint(name?: string): string
Optional name for the mark (useful for debugging)
Unique id for the mark that can be used with squashToMark or bailToMark
const mark = editor.markHistoryStoppingPoint('before rotation')
editor.rotateShapes(selectedShapes, Math.PI / 4)
// If needed, can bail back to the mark
// editor.bailToMark(mark)
run
Run a function in a transaction with optional history control.
run(fn: () => void, opts?: TLEditorRunOptions): this
The callback function to run
Options for the transactionhistory
'record' | 'record-preserveRedoStack' | 'ignore'
How to handle history for this transaction
Whether to allow changes to locked shapes
// Update without adding to history
editor.run(() => {
editor.updateShape({ id: myShape.id, x: 100 })
}, { history: 'ignore' })
// Force changes to locked shapes
editor.run(() => {
editor.deleteShape(lockedShape.id)
}, { ignoreShapeLock: true })
Camera operations
getCamera
Get the current camera state.
setCamera
Set the camera position and zoom.
setCamera(point: VecLike, options?: TLCameraMoveOptions): this
zoomIn
Zoom in the camera.
zoomIn(point?: VecLike, options?: TLCameraMoveOptions): this
zoomOut
Zoom out the camera.
zoomOut(point?: VecLike, options?: TLCameraMoveOptions): this
zoomToFit
Zoom to fit all shapes on the current page.
zoomToFit(options?: TLCameraMoveOptions): this
zoomToSelection
Zoom to fit the current selection.
zoomToSelection(options?: TLCameraMoveOptions): this
Page operations
getCurrentPage
Get the current page.
getCurrentPageId
Get the current page id.
getCurrentPageId(): TLPageId
setCurrentPage
Set the current page.
setCurrentPage(page: TLPageId | TLPage): this
getPages
Get all pages.
createPage
Create a new page.
createPage(options?: { name?: string, id?: TLPageId }): this
deletePage
Delete a page.
deletePage(page: TLPageId | TLPage): this
getCurrentTool(): StateNode
getCurrentToolId(): string
setCurrentTool(id: string, info?: {}): this
editor.setCurrentTool('select')
editor.setCurrentTool('draw', { date: Date.now() })
getPath
Get the current path of active states.
Path of active states separated by periods (e.g., “select.idle” or “draw.drawing”)
isIn
Check if the editor is in a specific state.
isIn(path: string): boolean
if (editor.isIn('select.brushing')) {
console.log('User is brush selecting')
}
Editing
getEditingShape
Get the shape currently being edited.
getEditingShape(): TLShape | undefined
getEditingShapeId
Get the id of the shape currently being edited.
getEditingShapeId(): TLShapeId | null
setEditingShape
Set the shape to edit.
setEditingShape(shape: TLShapeId | TLShape | null): this
Events
The Editor extends EventEmitter and emits various events:
// Listen to all changes
editor.on('change', (changes) => {
console.log('Store changed:', changes)
})
// Listen to editor updates
editor.on('update', () => {
console.log('Editor updated')
})
// Listen to tick events
editor.on('tick', (elapsed) => {
console.log('Tick:', elapsed, 'ms')
})
Lifecycle
dispose
Dispose of the editor and clean up resources.
Example:
// When unmounting
editor.dispose()