Table of contents

Extends EventEmitter<TLEventMap>.

class Editor extends EventEmitter<TLEventMap> {}

Constructor

Constructs a new instance of the Editor class

Parameters
NameDescription

{ store, user, shapeUtils, bindingUtils, tools, getContainer, cameraOptions, initialState, autoFocus, inferDarkMode, options, }

TLEditorOptions

Properties


bindingUtils

A map of shape utility classes (TLShapeUtils) by shape type.

bindingUtils: {
  readonly [K in string]?: BindingUtil<TLUnknownBinding>
}

dispatch

Dispatch an event to the editor.

dispatch: (info: TLEventInfo) => this
Example
editor.dispatch(myPointerEvent)
Parameters
NameDescription

info

The event info.


disposables

A set of functions to call when the app is disposed.

readonly disposables: Set<() => void>

environment

A manager for the editor's environment.

readonly environment: EnvironmentManager

getContainer

The current HTML element containing the editor.

getContainer: () => HTMLElement
Example
const container = editor.getContainer()

history

A manager for the app's history.

readonly history: HistoryManager<TLRecord>

inputs

The app's current input state.

inputs: {
  buttons: Set<number>
  keys: Set<string>
  originScreenPoint: Vec
  originPagePoint: Vec
  currentScreenPoint: Vec
  currentPagePoint: Vec
  previousScreenPoint: Vec
  previousPagePoint: Vec
  pointerVelocity: Vec
  altKey: boolean
  ctrlKey: boolean
  isPen: boolean
  shiftKey: boolean
  isDragging: boolean
  isEditing: boolean
  isPanning: boolean
  isPinching: boolean
  isPointing: boolean
}

options

readonly options: TldrawOptions

root

The root state of the statechart.

readonly root: StateNode

scribbles

A manager for the editor's scribbles.

readonly scribbles: ScribbleManager

setCursor

Set the cursor.

setCursor: (cursor: Partial<TLCursor>) => this
Parameters
NameDescription

type

The cursor type.

rotation

The cursor rotation.


shapeUtils

A map of shape utility classes (TLShapeUtils) by shape type.

shapeUtils: {
  readonly [K in string]?: ShapeUtil<TLUnknownShape>
}

sideEffects

A manager for side effects and correct state enforcement. See StoreSideEffects for details.

readonly sideEffects: StoreSideEffects<TLRecord>

snaps

A manager for the app's snapping feature.

readonly snaps: SnapManager

store

The editor's store

readonly store: TLStore

styleProps

styleProps: {
  [key: string]: Map<StyleProp<any>, string>
}

textMeasure

A helper for measuring text.

readonly textMeasure: TextManager

timers

A manager for the any asynchronous events and making sure they're cleaned up upon disposal.

readonly timers: Timers

user

A manager for the user and their preferences.

readonly user: UserPreferencesManager

Methods

addOpenMenu()

Add an open menu.

addOpenMenu(id: string): this
Example
editor.addOpenMenu('menu-id')
Parameters
NameDescription

id

string
Returns
this

alignShapes()

Align shape positions.

alignShapes(
  shapes: TLShape[] | TLShapeId[],
  operation:
    | 'bottom'
    | 'center-horizontal'
    | 'center-vertical'
    | 'left'
    | 'right'
    | 'top'
): this
Example
editor.alignShapes([box1, box2], 'left')
editor.alignShapes(editor.getSelectedShapeIds(), 'left')
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to align.

operation

  | 'bottom'
  | 'center-horizontal'
  | 'center-vertical'
  | 'left'
  | 'right'
  | 'top'

The align operation to apply.

Returns
this

animateShape()

Animate a shape.

animateShape(
  partial: null | TLShapePartial | undefined,
  opts?: Partial<{
    animation: Partial<{
      duration: number
      easing: (t: number) => number
    }>
    force: boolean
    immediate: boolean
    reset: boolean
  }>
): this
Example
editor.animateShape({ id: 'box1', type: 'box', x: 100, y: 100 })
editor.animateShape(
  { id: 'box1', type: 'box', x: 100, y: 100 },
  { animation: { duration: 100, ease: (t) => t * t } }
)
Parameters
NameDescription

partial

null | TLShapePartial | undefined

The shape partial to update.

opts

Partial<{
  animation: Partial<{
    duration: number
    easing: (t: number) => number
  }>
  force: boolean
  immediate: boolean
  reset: boolean
}>
Returns
this

animateShapes()

Animate shapes.

animateShapes(
  partials: (null | TLShapePartial | undefined)[],
  opts?: Partial<{
    animation: Partial<{
      duration: number
      easing: (t: number) => number
    }>
    force: boolean
    immediate: boolean
    reset: boolean
  }>
): this
Example
editor.animateShapes([{ id: 'box1', type: 'box', x: 100, y: 100 }])
editor.animateShapes([{ id: 'box1', type: 'box', x: 100, y: 100 }], {
  animation: { duration: 100, ease: (t) => t * t },
})
Parameters
NameDescription

partials

(null | TLShapePartial | undefined)[]

The shape partials to update.

opts

Partial<{
  animation: Partial<{
    duration: number
    easing: (t: number) => number
  }>
  force: boolean
  immediate: boolean
  reset: boolean
}>
Returns
this

bail()

Clear all marks in the undo stack back to the next mark.

bail(): this
Example
editor.bail()

bailToMark()

Clear all marks in the undo stack back to the mark with the provided mark id.

bailToMark(id: string): this
Example
editor.bailToMark('dragging')
Parameters
NameDescription

id

string
Returns
this

batch()

Run a function in a batch.

batch(fn: () => void, opts?: TLHistoryBatchOptions): this
Parameters
NameDescription

fn

() => void

opts

TLHistoryBatchOptions
Returns
this

blur()

Switches off the editor's focused mode.

This makes the editor ignore keyboard events and some pointer events (move, wheel).

blur({ blurContainer }?: { blurContainer?: boolean | undefined }): this
Example
editor.blur()

By default this also dispatches a 'blur' event to the container element. To prevent this, pass blurContainer: false.

editor.blur({ blurContainer: false })
Parameters
NameDescription

{ blurContainer }

{
  blurContainer?: boolean | undefined
}
Returns
this

bringForward()

Bring shapes forward in the page's object list.

bringForward(shapes: TLShape[] | TLShapeId[]): this
Example
editor.bringForward(['id1', 'id2'])
editor.bringForward(box1, box2)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this

bringToFront()

Bring shapes to the front of the page's object list.

bringToFront(shapes: TLShape[] | TLShapeId[]): this
Example
editor.bringToFront(['id1', 'id2'])
editor.bringToFront([box1, box2])
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this

canBindShapes()

canBindShapes({
  fromShape,
  toShape,
  binding,
}: {
  binding:
    | {
        type: TLBinding['type']
      }
    | TLBinding
    | TLBinding['type']
  fromShape:
    | {
        type: TLShape['type']
      }
    | TLShape
    | TLShape['type']
  toShape:
    | {
        type: TLShape['type']
      }
    | TLShape
    | TLShape['type']
}): boolean
Parameters
NameDescription

{ fromShape, toShape, binding, }

{
  binding:
    | {
        type: TLBinding['type']
      }
    | TLBinding
    | TLBinding['type']
  fromShape:
    | {
        type: TLShape['type']
      }
    | TLShape
    | TLShape['type']
  toShape:
    | {
        type: TLShape['type']
      }
    | TLShape
    | TLShape['type']
}
Returns
boolean

cancel()

Dispatch a cancel event.

cancel(): this
Example
editor.cancel()

cancelDoubleClick()

Prevent a double click event from firing the next time the user clicks

cancelDoubleClick(): void

centerOnPoint()

Center the camera on a point (in the current page space).

centerOnPoint(point: VecLike, opts?: TLCameraMoveOptions): this
Example
editor.centerOnPoint({ x: 100, y: 100 })
editor.centerOnPoint({ x: 100, y: 100 }, { animation: { duration: 200 } })
Parameters
NameDescription

point

VecLike

The point in the current page space to center on.

opts

TLCameraMoveOptions
Returns
this

clearOpenMenus()

Clear all open menus.

clearOpenMenus(): this
Example
editor.clearOpenMenus()

complete()

Dispatch a complete event.

complete(): this
Example
editor.complete()

createAssets()

Create one or more assets.

createAssets(assets: TLAsset[]): this
Example
editor.createAssets([...myAssets])
Parameters
NameDescription

assets

TLAsset[]

The assets to create.

Returns
this

createBinding()

Create a single binding from a partial. You can omit the ID and most props of a binding, but the type, toId, and fromId must all be provided.

createBinding<B extends TLBinding = TLBinding>(
  partial: TLBindingCreate<B>
): this
Parameters
NameDescription

partial

TLBindingCreate<B>
Returns
this

createBindings()

Create bindings from a list of partial bindings. You can omit the ID and most props of a binding, but the type, toId, and fromId must all be provided.

createBindings(partials: TLBindingCreate[]): this
Parameters
NameDescription

partials

TLBindingCreate[]
Returns
this

createPage()

Create a page.

createPage(page: Partial<TLPage>): this
Example
editor.createPage(myPage)
editor.createPage({ name: 'Page 2' })
Parameters
NameDescription

page

Partial<TLPage>

The page (or page partial) to create.

Returns
this

createShape()

Create a single shape.

createShape<T extends TLUnknownShape>(
  shape: OptionalKeys<TLShapePartial<T>, 'id'>
): this
Example
editor.createShape(myShape)
editor.createShape({ id: 'box1', type: 'text', props: { text: 'ok' } })
Parameters
NameDescription

shape

OptionalKeys<TLShapePartial<T>, 'id'>

The shape (or shape partial) to create.

Returns
this

createShapes()

Create shapes.

createShapes<T extends TLUnknownShape>(
  shapes: OptionalKeys<TLShapePartial<T>, 'id'>[]
): this
Example
editor.createShapes([myShape])
editor.createShapes([{ id: 'box1', type: 'text', props: { text: 'ok' } }])
Parameters
NameDescription

shapes

OptionalKeys<TLShapePartial<T>, 'id'>[]

The shapes (or shape partials) to create.

Returns
this

deleteAssets()

Delete one or more assets.

deleteAssets(assets: TLAsset[] | TLAssetId[]): this
Example
editor.deleteAssets(['asset1', 'asset2'])
Parameters
NameDescription

assets

TLAsset[] | TLAssetId[]
Returns
this

deleteBinding()

Delete a binding by its ID. If the binding doesn't exist, it's ignored.

deleteBinding(
  binding: TLBinding | TLBindingId,
  opts?: Parameters<this['deleteBindings']>[1]
): this
Parameters
NameDescription

binding

TLBinding | TLBindingId

opts

Parameters<this['deleteBindings']>[1]
Returns
this

deleteBindings()

Delete several bindings by their IDs. If a binding ID doesn't exist, it's ignored.

deleteBindings(
  bindings: (TLBinding | TLBindingId)[],
  {
    isolateShapes,
  }?: {
    isolateShapes?: boolean | undefined
  }
): this
Parameters
NameDescription

bindings

(TLBinding | TLBindingId)[]

{ isolateShapes }

{
  isolateShapes?: boolean | undefined
}
Returns
this

deleteOpenMenu()

Delete an open menu.

deleteOpenMenu(id: string): this
Example
editor.deleteOpenMenu('menu-id')
Parameters
NameDescription

id

string
Returns
this

deletePage()

Delete a page.

deletePage(page: TLPage | TLPageId): this
Example
editor.deletePage('page1')
Parameters
NameDescription

page

TLPage | TLPageId
Returns
this

deleteShape()

Delete a shape.

deleteShape(id: TLShapeId): this
Example
editor.deleteShape(shape.id)
Parameters
NameDescription

id

TLShapeId

The id of the shape to delete.

Returns
this

deleteShapes()

Delete shapes.

deleteShapes(ids: TLShapeId[]): this
Example
editor.deleteShapes(['box1', 'box2'])
Parameters
NameDescription

ids

TLShapeId[]

The ids of the shapes to delete.

Returns
this

deselect()

Remove a shape from the existing set of selected shapes.

deselect(...shapes: TLShape[] | TLShapeId[]): this
Example
editor.deselect(shape.id)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]
Returns
this

dispose()

Dispose the editor.

dispose(): void

distributeShapes()

Distribute shape positions.

distributeShapes(
  shapes: TLShape[] | TLShapeId[],
  operation: 'horizontal' | 'vertical'
): this
Example
editor.distributeShapes([box1, box2], 'horizontal')
editor.distributeShapes(editor.getSelectedShapeIds(), 'horizontal')
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to distribute.

operation

'horizontal' | 'vertical'

Whether to distribute shapes horizontally or vertically.

Returns
this

duplicatePage()

Duplicate a page.

duplicatePage(page: TLPage | TLPageId, createId?: TLPageId): this
Parameters
NameDescription

page

TLPage | TLPageId

createId

TLPageId

The id of the new page. Defaults to a new id.

Returns
this

duplicateShapes()

Duplicate shapes.

duplicateShapes(shapes: TLShape[] | TLShapeId[], offset?: VecLike): this
Example
editor.duplicateShapes(['box1', 'box2'], { x: 8, y: 8 })
editor.duplicateShapes(editor.getSelectedShapes(), { x: 8, y: 8 })
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to duplicate.

offset

VecLike

The offset (in pixels) to apply to the duplicated shapes.

Returns
this

findCommonAncestor()

Get the common ancestor of two or more shapes that matches a predicate.

findCommonAncestor(
  shapes: TLShape[] | TLShapeId[],
  predicate?: (shape: TLShape) => boolean
): TLShapeId | undefined
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to check.

predicate

(shape: TLShape) => boolean

The predicate to match.

Returns
TLShapeId | undefined

findShapeAncestor()

Find the first ancestor matching the given predicate

findShapeAncestor(
  shape: TLShape | TLShapeId,
  predicate: (parent: TLShape) => boolean
): TLShape | undefined
Example
const ancestor = editor.findShapeAncestor(myShape)
const ancestor = editor.findShapeAncestor(myShape.id)
const ancestor = editor.findShapeAncestor(
  myShape.id,
  (shape) => shape.type === 'frame'
)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to check the ancestors for.

predicate

(parent: TLShape) => boolean
Returns
TLShape | undefined

flipShapes()

Flip shape positions.

flipShapes(
  shapes: TLShape[] | TLShapeId[],
  operation: 'horizontal' | 'vertical'
): this
Example
editor.flipShapes([box1, box2], 'horizontal', 32)
editor.flipShapes(editor.getSelectedShapeIds(), 'horizontal', 32)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The ids of the shapes to flip.

operation

'horizontal' | 'vertical'

Whether to flip horizontally or vertically.

Returns
this

focus()

Puts the editor into focused mode.

This makes the editor eligible to receive keyboard events and some pointer events (move, wheel).

focus({ focusContainer }?: { focusContainer?: boolean | undefined }): this
Example
editor.focus()

By default this also dispatches a 'focus' event to the container element. To prevent this, pass focusContainer: false.

editor.focus({ focusContainer: false })
Parameters
NameDescription

{ focusContainer }

{
  focusContainer?: boolean | undefined
}
Returns
this

getAncestorPageId()

Get the id of the containing page for a given shape.

getAncestorPageId(shape?: TLShape | TLShapeId): TLPageId | undefined
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to get the page id for.

Returns
TLPageId | undefined

The id of the page that contains the shape, or undefined if the shape is undefined.


getAsset()

Get an asset by its id.

getAsset(asset: TLAsset | TLAssetId): TLAsset | undefined
Example
editor.getAsset('asset1')
Parameters
NameDescription

asset

TLAsset | TLAssetId

The asset (or asset id) to get.

Returns
TLAsset | undefined

getAssetForExternalContent()

Get an asset for an external asset content type.

getAssetForExternalContent(
  info: TLExternalAssetContent
): Promise<TLAsset | undefined>
Example
const asset = await editor.getAssetForExternalContent({
  type: 'file',
  file: myFile,
})
const asset = await editor.getAssetForExternalContent({
  type: 'url',
  url: myUrl,
})
Parameters
NameDescription

info

TLExternalAssetContent

Info about the external content.

Returns
Promise<TLAsset | undefined>

The asset.


getAssets()

Get all assets in the editor.

getAssets(): (
  | import('@tldraw/tlschema').TLBookmarkAsset
  | TLImageAsset
  | TLVideoAsset
)[]

getBaseZoom()

Get the camera's base level for calculating actual zoom levels based on the zoom steps.

getBaseZoom(): number
Example
editor.getBaseZoom()

getBinding()

Get a binding from the store by its ID if it exists.

getBinding(id: TLBindingId): TLBinding | undefined
Parameters
NameDescription

id

TLBindingId
Returns
TLBinding | undefined

getBindingsFromShape()

Get all bindings of a certain type from a particular shape. These are the bindings whose fromId matched the shape's ID.

getBindingsFromShape<Binding extends TLUnknownBinding = TLBinding>(
  shape: TLShape | TLShapeId,
  type: Binding['type']
): Binding[]
Parameters
NameDescription

shape

TLShape | TLShapeId

type

Binding['type']
Returns
Binding[]

getBindingsInvolvingShape()

Get all bindings involving a particular shape. This includes bindings where the shape is the fromId or toId. If a type is provided, only bindings of that type are returned.

getBindingsInvolvingShape<Binding extends TLUnknownBinding = TLBinding>(
  shape: TLShape | TLShapeId,
  type?: Binding['type']
): Binding[]
Parameters
NameDescription

shape

TLShape | TLShapeId

type

Binding['type']
Returns
Binding[]

getBindingsToShape()

Get all bindings of a certain type to a particular shape. These are the bindings whose toId matches the shape's ID.

getBindingsToShape<Binding extends TLUnknownBinding = TLBinding>(
  shape: TLShape | TLShapeId,
  type: Binding['type']
): Binding[]
Parameters
NameDescription

shape

TLShape | TLShapeId

type

Binding['type']
Returns
Binding[]

getBindingUtil()

Get a binding util from a binding itself.

getBindingUtil<S extends TLUnknownBinding>(
  binding:
    | {
        type: S['type']
      }
    | S
): BindingUtil<S>
Example
const util = editor.getBindingUtil(myArrowBinding)
const util = editor.getBindingUtil('arrow')
const util = editor.getBindingUtil<TLArrowBinding>(myArrowBinding)
const util = editor.getBindingUtil(TLArrowBinding)('arrow')
Parameters
NameDescription

binding

  | {
      type: S['type']
    }
  | S

A binding, binding partial, or binding type.

Returns
BindingUtil<S>

getCamera()

The current camera.

getCamera(): TLCamera

getCameraOptions()

Get the current camera options.

getCameraOptions(): TLCameraOptions
Example
editor.getCameraOptions()

getCameraState()

Whether the camera is moving or idle.

getCameraState(): 'idle' | 'moving'
Example
editor.getCameraState()

getCanRedo()

Whether the app can redo.

getCanRedo(): boolean

getCanUndo()

Whether the app can undo.

getCanUndo(): boolean

getCollaborators()

Returns a list of presence records for all peer collaborators. This will return the latest presence record for each connected user.

getCollaborators(): import('@tldraw/tlschema').TLInstancePresence[]

getCollaboratorsOnCurrentPage()

Returns a list of presence records for all peer collaborators on the current page. This will return the latest presence record for each connected user.

getCollaboratorsOnCurrentPage(): import('@tldraw/tlschema').TLInstancePresence[]

getContentFromCurrentPage()

Get content that can be exported for the given shape ids.

getContentFromCurrentPage(
  shapes: TLShape[] | TLShapeId[]
): TLContent | undefined
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to get content for.

Returns
TLContent | undefined

The exported content.


getCroppingShapeId()

The current cropping shape's id.

getCroppingShapeId(): null | TLShapeId

getCulledShapes()

Get culled shapes.

getCulledShapes(): Set<TLShapeId>

getCurrentPage()

The current page.

getCurrentPage(): TLPage
Example
editor.getCurrentPage()

getCurrentPageBounds()

The bounds of the current page (the common bounds of all of the shapes on the page).

getCurrentPageBounds(): Box | undefined

getCurrentPageId()

The current page id.

getCurrentPageId(): TLPageId
Example
editor.getCurrentPageId()

getCurrentPageRenderingShapesSorted()

An array containing all of the rendering shapes in the current page, sorted in z-index order (accounting for nested shapes): e.g. A, B, BA, BB, C.

getCurrentPageRenderingShapesSorted(): TLShape[]

getCurrentPageShapeIds()

An array of all of the shapes on the current page.

getCurrentPageShapeIds(): Set<TLShapeId>
Example
editor.getCurrentPageIds()

getCurrentPageShapes()

An array containing all of the shapes in the current page.

getCurrentPageShapes(): TLShape[]

getCurrentPageShapesSorted()

An array containing all of the shapes in the current page, sorted in z-index order (accounting for nested shapes): e.g. A, B, BA, BB, C.

getCurrentPageShapesSorted(): TLShape[]

getCurrentPageState()

The current page state.

getCurrentPageState(): TLInstancePageState

getCurrentTool()

The current selected tool.

getCurrentTool(): StateNode

getCurrentToolId()

The id of the current selected tool.

getCurrentToolId(): string

getDocumentSettings()

The global document settings that apply to all users.

getDocumentSettings(): TLDocument

getDroppingOverShape()

Get the shape that some shapes should be dropped on at a given point.

getDroppingOverShape(
  point: VecLike,
  droppingShapes?: TLShape[]
): TLUnknownShape | undefined
Parameters
NameDescription

point

VecLike

The point to find the parent for.

droppingShapes

TLShape[]

The shapes that are being dropped.

Returns
TLUnknownShape | undefined

The shape to drop on.


getEditingShape()

The current editing shape.

getEditingShape(): TLShape | undefined

getEditingShapeId()

The current editing shape's id.

getEditingShapeId(): null | TLShapeId

getErasingShapeIds()

The editor's current erasing ids.

getErasingShapeIds(): TLShapeId[]

getErasingShapes()

The editor's current erasing shapes.

getErasingShapes(): NonNullable<TLShape | undefined>[]

getFocusedGroup()

The current focused group.

getFocusedGroup(): TLShape | undefined

getFocusedGroupId()

The current focused group id.

getFocusedGroupId(): TLPageId | TLShapeId

getHighestIndexForParent()

Get the index above the highest child of a given parent.

getHighestIndexForParent(parent: TLPage | TLParentId | TLShape): IndexKey
Parameters
NameDescription

parent

TLPage | TLParentId | TLShape
Returns
IndexKey

The index.


getHintingShape()

The editor's current hinting shapes.

getHintingShape(): NonNullable<TLShape | undefined>[]

getHintingShapeIds()

The editor's current hinting shape ids.

getHintingShapeIds(): TLShapeId[]

getHoveredShape()

The current hovered shape.

getHoveredShape(): TLShape | undefined

getHoveredShapeId()

The current hovered shape id.

getHoveredShapeId(): null | TLShapeId

getInitialMetaForShape()

Get the initial meta value for a shape.

getInitialMetaForShape(_shape: TLShape): JsonObject
Example
editor.getInitialMetaForShape = (shape) => {
  if (shape.type === 'note') {
    return { createdBy: myCurrentUser.id }
  }
}
Parameters
NameDescription

_shape

TLShape
Returns
JsonObject

getInitialZoom()

Get the camera's initial or reset zoom level.

getInitialZoom(): number
Example
editor.getInitialZoom()

getInstanceState()

The current instance's state.

getInstanceState(): TLInstance

getIsFocused()

getIsFocused(): boolean

getIsMenuOpen()

Get whether any menus are open.

getIsMenuOpen(): boolean
Example
editor.getIsMenuOpen()

getOnlySelectedShape()

The app's only selected shape.

getOnlySelectedShape(): null | TLShape

getOnlySelectedShapeId()

The id of the app's only selected shape.

getOnlySelectedShapeId(): null | TLShapeId

getOpenMenus()

A set of strings representing any open menus. When menus are open, certain interactions will behave differently; for example, when a draw tool is selected and a menu is open, a pointer-down will not create a dot (because the user is probably trying to close the menu) however a pointer-down event followed by a drag will begin drawing a line (because the user is BOTH trying to close the menu AND start drawing a line).

getOpenMenus(): string[]

getOutermostSelectableShape()

Get the shape that should be selected when you click on a given shape, assuming there is nothing already selected. It will not return anything higher than or including the current focus layer.

getOutermostSelectableShape(
  shape: TLShape | TLShapeId,
  filter?: (shape: TLShape) => boolean
): TLShape
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to get the outermost selectable shape for.

filter

(shape: TLShape) => boolean

A function to filter the selectable shapes.

Returns
TLShape

The outermost selectable shape.


getPage()

Get a page.

getPage(page: TLPage | TLPageId): TLPage | undefined
Example
editor.getPage(myPage.id)
editor.getPage(myPage)
Parameters
NameDescription

page

TLPage | TLPageId

The page (or page id) to get.

Returns
TLPage | undefined

getPages()

Info about the project's current pages.

getPages(): TLPage[]
Example
editor.getPages()

getPageShapeIds()

Get the ids of shapes on a page.

getPageShapeIds(page: TLPage | TLPageId): Set<TLShapeId>
Example
const idsOnPage1 = editor.getPageShapeIds('page1')
const idsOnPage2 = editor.getPageShapeIds(myPage2)
Parameters
NameDescription

page

TLPage | TLPageId

The page (or page id) to get.

Returns
Set<TLShapeId>

getPageStates()

Page states.

getPageStates(): TLInstancePageState[]

getPath()

The editor's current path of active states.

getPath(): string
Example
editor.getPath() // "select.idle"

getPointInParentSpace()

Convert a delta in the current page space to a point in the local space of a shape's parent.

getPointInParentSpace(shape: TLShape | TLShapeId, point: VecLike): Vec
Example
editor.getPointInParentSpace(myShape.id, { x: 100, y: 100 })
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to get the point in the local space of.

point

VecLike

The page point to get in the local space of the shape.

Returns
Vec

getPointInShapeSpace()

Convert a point in the current page space to a point in the local space of a shape. For example, if a shape's page point were { x: 100, y: 100 }, a page point at { x: 110, y: 110 } would be at { x: 10, y: 10 } in the shape's local space.

getPointInShapeSpace(shape: TLShape | TLShapeId, point: VecLike): Vec
Example
editor.getPointInShapeSpace(myShape, { x: 100, y: 100 })
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to get the point in the local space of.

point

VecLike

The page point to get in the local space of the shape.

Returns
Vec

getRenderingShapes()

Get the shapes that should be displayed in the current viewport.

getRenderingShapes(): {
  backgroundIndex: number
  id: TLShapeId
  index: number
  opacity: number
  shape: TLShape
  util: ShapeUtil<TLUnknownShape>
}[]
Example
editor.getRenderingShapes()

getSelectedShapeAtPoint()

Get the top-most selected shape at the given point, ignoring groups.

getSelectedShapeAtPoint(point: VecLike): TLShape | undefined
Parameters
NameDescription

point

VecLike

The point to check.

Returns
TLShape | undefined

The top-most selected shape at the given point, or undefined if there is no shape at the point.


getSelectedShapeIds()

The current selected ids.

getSelectedShapeIds(): TLShapeId[]

getSelectedShapes()

An array containing all of the currently selected shapes.

getSelectedShapes(): TLShape[]

getSelectionPageBounds()

The current page bounds of all the selected shapes. If the selection is rotated, then these bounds are the axis-aligned box that the rotated bounds would fit inside of.

getSelectionPageBounds(): Box | null

getSelectionRotatedPageBounds()

The bounds of the selection bounding box in the current page space.

getSelectionRotatedPageBounds(): Box | undefined

getSelectionRotatedScreenBounds()

The bounds of the selection bounding box in the current page space.

getSelectionRotatedScreenBounds(): Box | undefined

getSelectionRotation()

The rotation of the selection bounding box in the current page space.

getSelectionRotation(): number

getShape()

Get a shape by its id.

getShape<T extends TLShape = TLShape>(
  shape: TLParentId | TLShape
): T | undefined
Example
editor.getShape('box1')
Parameters
NameDescription

shape

TLParentId | TLShape
Returns
T | undefined

getShapeAncestors()

Get the ancestors of a shape.

getShapeAncestors(shape: TLShape | TLShapeId, acc?: TLShape[]): TLShape[]
Example
const ancestors = editor.getShapeAncestors(myShape)
const ancestors = editor.getShapeAncestors(myShapeId)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape (or shape id) to get the ancestors for.

acc

TLShape[]
Returns
TLShape[]

getShapeAndDescendantIds()

Get the shape ids of all descendants of the given shapes (including the shapes themselves). IDs are returned in z-index order.

getShapeAndDescendantIds(ids: TLShapeId[]): Set<TLShapeId>
Parameters
NameDescription

ids

TLShapeId[]

The ids of the shapes to get descendants of.

Returns
Set<TLShapeId>

The descendant ids.


getShapeAtPoint()

Get the shape at the current point.

getShapeAtPoint(
  point: VecLike,
  opts?: {
    filter?: ((shape: TLShape) => boolean) | undefined
    hitFrameInside?: boolean | undefined
    hitInside?: boolean | undefined
    hitLabels?: boolean | undefined
    hitLocked?: boolean | undefined
    margin?: number | undefined
    renderingOnly?: boolean | undefined
  }
): TLShape | undefined
Parameters
NameDescription

point

VecLike

The point to check.

opts

{
  filter?: ((shape: TLShape) => boolean) | undefined
  hitFrameInside?: boolean | undefined
  hitInside?: boolean | undefined
  hitLabels?: boolean | undefined
  hitLocked?: boolean | undefined
  margin?: number | undefined
  renderingOnly?: boolean | undefined
}

Options for the check: hitInside to check if the point is inside the shape, margin to check if the point is within a margin of the shape, hitFrameInside to check if the point is inside the frame, and filter to filter the shapes to check.

Returns
TLShape | undefined

The shape at the given point, or undefined if there is no shape at the point.


getShapeClipPath()

Get the clip path for a shape.

getShapeClipPath(shape: TLShape | TLShapeId): string | undefined
Example
const clipPath = editor.getShapeClipPath(shape)
const clipPath = editor.getShapeClipPath(shape.id)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape (or shape id) to get the clip path for.

Returns
string | undefined

The clip path or undefined.


getShapeGeometry()

Get the geometry of a shape.

getShapeGeometry<T extends Geometry2d>(shape: TLShape | TLShapeId): T
Example
editor.getShapeGeometry(myShape)
editor.getShapeGeometry(myShapeId)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape (or shape id) to get the geometry for.

Returns
T

getShapeHandles()

Get the handles (if any) for a shape.

getShapeHandles<T extends TLShape>(shape: T | T['id']): TLHandle[] | undefined
Example
editor.getShapeHandles(myShape)
editor.getShapeHandles(myShapeId)
Parameters
NameDescription

shape

T | T['id']

The shape (or shape id) to get the handles for.

Returns
TLHandle[] | undefined

getShapeLocalTransform()

Get the local transform for a shape as a matrix model. This transform reflects both its translation (x, y) from from either its parent's top left corner, if the shape's parent is another shape, or else from the 0,0 of the page, if the shape's parent is the page; and the shape's rotation.

getShapeLocalTransform(shape: TLShape | TLShapeId): Mat
Example
editor.getShapeLocalTransform(myShape)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to get the local transform for.

Returns
Mat

getShapeMask()

Get the mask (in the current page space) for a shape.

getShapeMask(shape: TLShape | TLShapeId): undefined | VecLike[]
Example
const pageMask = editor.getShapeMask(shape.id)
Parameters
NameDescription

shape

TLShape | TLShapeId
Returns
undefined | VecLike[]

The mask for the shape.


getShapeMaskedPageBounds()

Get the bounds of a shape in the current page space, incorporating any masks. For example, if the shape were the child of a frame and was half way out of the frame, the bounds would be the half of the shape that was in the frame.

getShapeMaskedPageBounds(shape: TLShape | TLShapeId): Box | undefined
Example
editor.getShapeMaskedPageBounds(myShape)
editor.getShapeMaskedPageBounds(myShapeId)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to get the masked bounds for.

Returns
Box | undefined

getShapePageBounds()

Get the bounds of a shape in the current page space.

getShapePageBounds(shape: TLShape | TLShapeId): Box | undefined
Example
editor.getShapePageBounds(myShape)
editor.getShapePageBounds(myShapeId)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape (or shape id) to get the bounds for.

Returns
Box | undefined

getShapePageTransform()

Get the transform of a shape in the current page space.

getShapePageTransform(shape: TLShape | TLShapeId): Mat
Example
editor.getShapePageTransform(myShape)
editor.getShapePageTransform(myShapeId)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape (or shape id) to get the page transform for.

Returns
Mat

getShapeParent()

Get the parent shape for a given shape. Returns undefined if the shape is the direct child of the page.

getShapeParent(shape?: TLShape | TLShapeId): TLShape | undefined
Example
editor.getShapeParent(myShape)
Parameters
NameDescription

shape

TLShape | TLShapeId
Returns
TLShape | undefined

getShapeParentTransform()

Get the local transform of a shape's parent as a matrix model.

getShapeParentTransform(shape: TLShape | TLShapeId): Mat
Example
editor.getShapeParentTransform(myShape)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape (or shape id) to get the parent transform for.

Returns
Mat

getShapesAtPoint()

Get the shapes, if any, at a given page point.

getShapesAtPoint(
  point: VecLike,
  opts?: {
    hitInside?: boolean | undefined
    margin?: number | undefined
  }
): TLShape[]
Example
editor.getShapesAtPoint({ x: 100, y: 100 })
editor.getShapesAtPoint({ x: 100, y: 100 }, { hitInside: true, exact: true })
Parameters
NameDescription

point

VecLike

The page point to test.

opts

{
  hitInside?: boolean | undefined
  margin?: number | undefined
}
Returns
TLShape[]

getShapeStyleIfExists()

getShapeStyleIfExists<T>(shape: TLShape, style: StyleProp<T>): T | undefined
Parameters
NameDescription

shape

TLShape

style

StyleProp<T>
Returns
T | undefined

getShapeUtil()

Get a shape util from a shape itself.

getShapeUtil<S extends TLUnknownShape>(
  shape: S | TLShapePartial<S>
): ShapeUtil<S>
Example
const util = editor.getShapeUtil(myArrowShape)
const util = editor.getShapeUtil('arrow')
const util = editor.getShapeUtil<TLArrowShape>(myArrowShape)
const util = editor.getShapeUtil(TLArrowShape)('arrow')
Parameters
NameDescription

shape

S | TLShapePartial<S>

A shape, shape partial, or shape type.

Returns
ShapeUtil<S>

getSharedOpacity()

Get the currently selected shared opacity. If any shapes are selected, this returns the shared opacity of the selected shapes. Otherwise, this returns the chosen opacity for the next shape.

getSharedOpacity(): SharedStyle<number>

getSharedStyles()

A map of all the current styles either in the current selection, or that are relevant to the current tool.

getSharedStyles(): ReadonlySharedStyleMap
Example
const color = editor.getSharedStyles().get(DefaultColorStyle)
if (color && color.type === 'shared') {
  print('All selected shapes have the same color:', color.value)
}

getSnapshot()

getSnapshot(): TLEditorSnapshot

getSortedChildIdsForParent()

Get an array of all the children of a shape.

getSortedChildIdsForParent(parent: TLPage | TLParentId | TLShape): TLShapeId[]
Example
editor.getSortedChildIdsForParent('frame1')
Parameters
NameDescription

parent

TLPage | TLParentId | TLShape
Returns
TLShapeId[]

getStateDescendant()

Get a descendant by its path.

getStateDescendant<T extends StateNode>(path: string): T | undefined
Example
state.getStateDescendant('select')
state.getStateDescendant('select.brushing')
Parameters
NameDescription

path

string

The descendant's path of state ids, separated by periods.

Returns
T | undefined

getStyleForNextShape()

Get the style for the next shape.

getStyleForNextShape<T>(style: StyleProp<T>): T
Example
const color = editor.getStyleForNextShape(DefaultColorStyle)
Parameters
NameDescription

style

StyleProp<T>

The style to get.

Returns
T

getSvg()

getSvg(
  shapes: TLShape[] | TLShapeId[],
  opts?: TLSvgOptions
): Promise<SVGSVGElement | undefined>
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

opts

TLSvgOptions
Returns
Promise<SVGSVGElement | undefined>

getSvgElement()

Get an exported SVG element of the given shapes.

getSvgElement(
  shapes: TLShape[] | TLShapeId[],
  opts?: TLSvgOptions
): Promise<
  | {
      height: number
      svg: SVGSVGElement
      width: number
    }
  | undefined
>
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

opts

TLSvgOptions

Options for the export.

Returns
Promise<
  | {
      height: number
      svg: SVGSVGElement
      width: number
    }
  | undefined
>

The SVG element.


getSvgString()

Get an exported SVG string of the given shapes.

getSvgString(
  shapes: TLShape[] | TLShapeId[],
  opts?: TLSvgOptions
): Promise<
  | {
      height: number
      svg: string
      width: number
    }
  | undefined
>
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

opts

TLSvgOptions

Options for the export.

Returns
Promise<
  | {
      height: number
      svg: string
      width: number
    }
  | undefined
>

The SVG element.


getViewportPageBounds()

The current viewport in the current page space.

getViewportPageBounds(): Box

getViewportScreenBounds()

The bounds of the editor's viewport in screen space.

getViewportScreenBounds(): Box

getViewportScreenCenter()

The center of the editor's viewport in screen space.

getViewportScreenCenter(): Vec

getZoomLevel()

The current camera zoom level.

getZoomLevel(): number

groupShapes()

Create a group containing the provided shapes.

groupShapes(
  shapes: TLShape[],
  options?: Partial<{
    groupId: TLShapeId
    select: boolean
  }>
): this
Example
editor.groupShapes([myShape, myOtherShape])
editor.groupShapes([myShape, myOtherShape], {
  groupId: myGroupId,
  select: false,
})
Parameters
NameDescription

shapes

TLShape[]

The shapes (or shape ids) to group. Defaults to the selected shapes.

options

Partial<{
  groupId: TLShapeId
  select: boolean
}>

An options object.

Returns
this

hasAncestor()

Returns true if the the given shape has the given ancestor.

hasAncestor(
  shape: TLShape | TLShapeId | undefined,
  ancestorId: TLShapeId
): boolean
Parameters
NameDescription

shape

TLShape | TLShapeId | undefined

The shape.

ancestorId

TLShapeId

The id of the ancestor.

Returns
boolean

interrupt()

Dispatch an interrupt event.

interrupt(): this
Example
editor.interrupt()

isAncestorSelected()

Determine whether or not any of a shape's ancestors are selected.

isAncestorSelected(shape: TLShape | TLShapeId): boolean
Parameters
NameDescription

shape

TLShape | TLShapeId
Returns
boolean

isIn()

Get whether a certain tool (or other state node) is currently active.

isIn(path: string): boolean
Example
editor.isIn('select')
editor.isIn('select.brushing')
Parameters
NameDescription

path

string

The path of active states, separated by periods.

Returns
boolean

isInAny()

Get whether the state node is in any of the given active paths.

isInAny(...paths: string[]): boolean
Example
state.isInAny('select', 'erase')
state.isInAny('select.brushing', 'erase.idle')
Parameters
NameDescription

paths

string[]
Returns
boolean

isPointInShape()

Test whether a point (in the current page space) will will a shape. This method takes into account masks, such as when a shape is the child of a frame and is partially clipped by the frame.

isPointInShape(
  shape: TLShape | TLShapeId,
  point: VecLike,
  opts?: {
    hitInside?: boolean | undefined
    margin?: number | undefined
  }
): boolean
Example
editor.isPointInShape({ x: 100, y: 100 }, myShape)
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to test against.

point

VecLike

The page point to test (in the current page space).

opts

{
  hitInside?: boolean | undefined
  margin?: number | undefined
}
Returns
boolean

isShapeInPage()

Get whether the given shape is the descendant of the given page.

isShapeInPage(shape: TLShape | TLShapeId, pageId?: TLPageId): boolean
Example
editor.isShapeInPage(myShape)
editor.isShapeInPage(myShape, 'page1')
Parameters
NameDescription

shape

TLShape | TLShapeId

The shape to check.

pageId

TLPageId

The id of the page to check against. Defaults to the current page.

Returns
boolean

isShapeOfType()

Get whether a shape matches the type of a TLShapeUtil.

isShapeOfType<T extends TLUnknownShape>(
  shape: TLUnknownShape,
  type: T['type']
): shape is T
Example
const isArrowShape = isShapeOfType<TLArrowShape>(someShape, 'arrow')
Parameters
NameDescription

shape

TLUnknownShape

the shape to test

type

T['type']
Returns
shape is T

isShapeOrAncestorLocked()

Check whether a shape or its parent is locked.

isShapeOrAncestorLocked(shape?: TLShape): boolean
Parameters
NameDescription

shape

TLShape

The shape (or shape id) to check.

Returns
boolean

loadSnapshot()

Loads a snapshot into the editor.

loadSnapshot(snapshot: Partial<TLEditorSnapshot> | TLStoreSnapshot): this
Parameters
NameDescription

snapshot

Partial<TLEditorSnapshot> | TLStoreSnapshot

the snapshot to load

Returns
this

mark()

Create a new "mark", or stopping point, in the undo redo history. Creating a mark will clear any redos.

mark(markId?: string): this
Example
editor.mark()
editor.mark('flip shapes')
Parameters
NameDescription

markId

string

The mark's id, usually the reason for adding the mark.

Returns
this

moveShapesToPage()

Move shapes to page.

moveShapesToPage(shapes: TLShape[] | TLShapeId[], pageId: TLPageId): this
Example
editor.moveShapesToPage(['box1', 'box2'], 'page1')
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) of the shapes to move.

pageId

TLPageId

The id of the page where the shapes will be moved.

Returns
this

nudgeShapes()

Move shapes by a delta.

nudgeShapes(shapes: TLShape[] | TLShapeId[], offset: VecLike): this
Example
editor.nudgeShapes(['box1', 'box2'], { x: 8, y: 8 })
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

offset

VecLike
Returns
this

packShapes()

Pack shapes into a grid centered on their current position. Based on potpack (https://github.com/mapbox/potpack).

packShapes(shapes: TLShape[] | TLShapeId[], gap: number): this
Example
editor.packShapes([box1, box2], 32)
editor.packShapes(editor.getSelectedShapeIds(), 32)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to pack.

gap

number

The padding to apply to the packed shapes. Defaults to 16.

Returns
this

pageToScreen()

Convert a point in the current page space to a point in current screen space.

pageToScreen(point: VecLike): Vec
Example
editor.pageToScreen({ x: 100, y: 100 })
Parameters
NameDescription

point

VecLike

The point in page space.

Returns
Vec

pageToViewport()

Convert a point in the current page space to a point in current viewport space.

pageToViewport(point: VecLike): Vec
Example
editor.pageToViewport({ x: 100, y: 100 })
Parameters
NameDescription

point

VecLike

The point in page space.

Returns
Vec

popFocusedGroupId()

Exit the current focused group, moving up to the next parent group if there is one.

popFocusedGroupId(): this

putContentOntoCurrentPage()

Place content into the editor.

putContentOntoCurrentPage(
  content: TLContent,
  options?: {
    point?: VecLike
    preserveIds?: boolean
    preservePosition?: boolean
    select?: boolean
  }
): this
Parameters
NameDescription

content

TLContent

The content.

options

{
  point?: VecLike
  preserveIds?: boolean
  preservePosition?: boolean
  select?: boolean
}

Options for placing the content.

Returns
this

putExternalContent()

Handle external content, such as files, urls, embeds, or plain text which has been put into the app, for example by pasting external text or dropping external images onto canvas.

putExternalContent(info: TLExternalContent): Promise<void>
Parameters
NameDescription

info

TLExternalContent

Info about the external content.

Returns
Promise<void>

redo()

Redo to the next mark.

redo(): this
Example
editor.redo()

registerExternalAssetHandler()

Register an external content handler. This handler will be called when the editor receives external content of the provided type. For example, the 'image' type handler will be called when a user drops an image onto the canvas.

registerExternalAssetHandler<T extends TLExternalAssetContent['type']>(
  type: T,
  handler:
    | ((
        info: TLExternalAssetContent & {
          type: T
        }
      ) => Promise<TLAsset>)
    | null
): this
Example
editor.registerExternalAssetHandler('text', myHandler)
Parameters
NameDescription

type

T

The type of external content.

handler

  | ((
      info: TLExternalAssetContent & {
        type: T
      }
    ) => Promise<TLAsset>)
  | null

The handler to use for this content type.

Returns
this

registerExternalContentHandler()

Register an external content handler. This handler will be called when the editor receives external content of the provided type. For example, the 'image' type handler will be called when a user drops an image onto the canvas.

registerExternalContentHandler<T extends TLExternalContent['type']>(
  type: T,
  handler:
    | ((
        info: T extends TLExternalContent['type']
          ? TLExternalContent & {
              type: T
            }
          : TLExternalContent
      ) => void)
    | null
): this
Example
editor.registerExternalContentHandler('text', myHandler)
Parameters
NameDescription

type

T

The type of external content.

handler

  | ((
      info: T extends TLExternalContent['type']
        ? TLExternalContent & {
            type: T
          }
        : TLExternalContent
    ) => void)
  | null

The handler to use for this content type.

Returns
this

renamePage()

Rename a page.

renamePage(page: TLPage | TLPageId, name: string): this
Example
editor.renamePage('page1', 'My Page')
Parameters
NameDescription

page

TLPage | TLPageId

name

string

The new name.

Returns
this

reparentShapes()

Reparent shapes to a new parent. This operation preserves the shape's current page positions / rotations.

reparentShapes(
  shapes: TLShape[] | TLShapeId[],
  parentId: TLParentId,
  insertIndex?: IndexKey
): this
Example
editor.reparentShapes([box1, box2], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1', 4)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) of the shapes to reparent.

parentId

TLParentId

The id of the new parent shape.

insertIndex

IndexKey

The index to insert the children.

Returns
this

resetZoom()

Set the zoom back to 100%.

resetZoom(point?: Vec, opts?: TLCameraMoveOptions): this
Example
editor.resetZoom()
editor.resetZoom(editor.getViewportScreenCenter(), {
  animation: { duration: 200 },
})
editor.resetZoom(editor.getViewportScreenCenter(), {
  animation: { duration: 200 },
})
Parameters
NameDescription

point

Vec

The screen point to zoom out on. Defaults to the viewport screen center.

opts

TLCameraMoveOptions

The camera move options.

Returns
this

resizeShape()

Resize a shape.

resizeShape(
  shape: TLShape | TLShapeId,
  scale: VecLike,
  options?: TLResizeShapeOptions
): this
Parameters
NameDescription

shape

TLShape | TLShapeId

scale

VecLike

The scale factor to apply to the shape.

options

TLResizeShapeOptions

Additional options.

Returns
this

rotateShapesBy()

Rotate shapes by a delta in radians. Note: Currently, this assumes that the shapes are your currently selected shapes.

rotateShapesBy(shapes: TLShape[] | TLShapeId[], delta: number): this
Example
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI)
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI / 2)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) of the shapes to move.

delta

number

The delta in radians to apply to the selection rotation.

Returns
this

screenToPage()

Convert a point in screen space to a point in the current page space.

screenToPage(point: VecLike): Vec
Example
editor.screenToPage({ x: 100, y: 100 })
Parameters
NameDescription

point

VecLike

The point in screen space.

Returns
Vec

select()

Select one or more shapes.

select(...shapes: TLShape[] | TLShapeId[]): this
Example
editor.select('id1')
editor.select('id1', 'id2')
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]
Returns
this

selectAll()

Select all direct children of the current page.

selectAll(): this
Example
editor.selectAll()

selectNone()

Clear the selection.

selectNone(): this
Example
editor.selectNone()

sendBackward()

Send shapes backward in the page's object list.

sendBackward(shapes: TLShape[] | TLShapeId[]): this
Example
editor.sendBackward(['id1', 'id2'])
editor.sendBackward([box1, box2])
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this

sendToBack()

Send shapes to the back of the page's object list.

sendToBack(shapes: TLShape[] | TLShapeId[]): this
Example
editor.sendToBack(['id1', 'id2'])
editor.sendToBack(box1, box2)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this

setCamera()

Set the current camera.

setCamera(point: VecLike, opts?: TLCameraMoveOptions): this
Example
editor.setCamera({ x: 0, y: 0 })
editor.setCamera({ x: 0, y: 0, z: 1.5 })
editor.setCamera(
  { x: 0, y: 0, z: 1.5 },
  { animation: { duration: 1000, easing: (t) => t * t } }
)
Parameters
NameDescription

point

VecLike

The new camera position.

opts

TLCameraMoveOptions

The camera move options.

Returns
this

setCameraOptions()

Set the camera options. Changing the options won't immediately change the camera itself, so you may want to call setCamera after changing the options.

setCameraOptions(options: Partial<TLCameraOptions>): this
Example
editor.setCameraOptions(myCameraOptions)
editor.setCamera(editor.getCamera())
Parameters
NameDescription

options

Partial<TLCameraOptions>

The camera options to set.

Returns
this

setCroppingShape()

Set the current cropping shape.

setCroppingShape(shape: null | TLShape | TLShapeId): this
Example
editor.setCroppingShape(myShape)
editor.setCroppingShape(myShape.id)
Parameters
NameDescription

shape

null | TLShape | TLShapeId

The shape (or shape id) to set as cropping.

Returns
this

setCurrentPage()

Set the current page.

setCurrentPage(page: TLPage | TLPageId): this
Example
editor.setCurrentPage('page1')
editor.setCurrentPage(myPage1)
Parameters
NameDescription

page

TLPage | TLPageId

The page (or page id) to set as the current page.

Returns
this

setCurrentTool()

Set the selected tool.

setCurrentTool(id: string, info?: {}): this
Example
editor.setCurrentTool('hand')
editor.setCurrentTool('hand', { date: Date.now() })
Parameters
NameDescription

id

string

The id of the tool to select.

info

{}

Arbitrary data to pass along into the transition.

Returns
this

setEditingShape()

Set the current editing shape.

setEditingShape(shape: null | TLShape | TLShapeId): this
Example
editor.setEditingShape(myShape)
editor.setEditingShape(myShape.id)
Parameters
NameDescription

shape

null | TLShape | TLShapeId

The shape (or shape id) to set as editing.

Returns
this

setErasingShapes()

Set the editor's current erasing shapes.

setErasingShapes(shapes: TLShape[] | TLShapeId[]): this
Example
editor.setErasingShapes([myShape])
editor.setErasingShapes([myShape.id])
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to set as hinting.

Returns
this

setFocusedGroup()

Set the current focused group shape.

setFocusedGroup(shape: null | TLGroupShape | TLShapeId): this
Parameters
NameDescription

shape

null | TLGroupShape | TLShapeId

The group shape id (or group shape's id) to set as the focused group shape.

Returns
this

setHintingShapes()

Set the editor's current hinting shapes.

setHintingShapes(shapes: TLShape[] | TLShapeId[]): this
Example
editor.setHintingShapes([myShape])
editor.setHintingShapes([myShape.id])
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to set as hinting.

Returns
this

setHoveredShape()

Set the editor's current hovered shape.

setHoveredShape(shape: null | TLShape | TLShapeId): this
Example
editor.setHoveredShape(myShape)
editor.setHoveredShape(myShape.id)
Parameters
NameDescription

shape

null | TLShape | TLShapeId
Returns
this

setOpacityForNextShapes()

Set the opacity for the next shapes. This will effect subsequently created shapes.

setOpacityForNextShapes(
  opacity: number,
  historyOptions?: TLHistoryBatchOptions
): this
Example
editor.setOpacityForNextShapes(0.5)
Parameters
NameDescription

opacity

number

The opacity to set. Must be a number between 0 and 1 inclusive.

historyOptions

TLHistoryBatchOptions

The history options for the change.

Returns
this

setOpacityForSelectedShapes()

Set the current opacity. This will effect any selected shapes.

setOpacityForSelectedShapes(opacity: number): this
Example
editor.setOpacityForSelectedShapes(0.5)
Parameters
NameDescription

opacity

number

The opacity to set. Must be a number between 0 and 1 inclusive.

Returns
this

setSelectedShapes()

Select one or more shapes.

setSelectedShapes(shapes: TLShape[] | TLShapeId[]): this
Example
editor.setSelectedShapes(['id1'])
editor.setSelectedShapes(['id1', 'id2'])
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]
Returns
this

setStyleForNextShapes()

Set the value of a StyleProp for the next shapes. This change will be applied to subsequently created shapes.

setStyleForNextShapes<T>(
  style: StyleProp<T>,
  value: T,
  historyOptions?: TLHistoryBatchOptions
): this
Example
editor.setStyleForNextShapes(DefaultColorStyle, 'red')
editor.setStyleForNextShapes(DefaultColorStyle, 'red', { ephemeral: true })
Parameters
NameDescription

style

StyleProp<T>

The style to set.

value

T

The value to set.

historyOptions

TLHistoryBatchOptions

The history options for the change.

Returns
this

setStyleForSelectedShapes()

Set the value of a StyleProp. This change will be applied to the currently selected shapes.

setStyleForSelectedShapes<S extends StyleProp<any>>(
  style: S,
  value: StylePropValue<S>
): this
Example
editor.setStyleForSelectedShapes(DefaultColorStyle, 'red')
Parameters
NameDescription

style

S

The style to set.

value

StylePropValue<S>

The value to set.

Returns
this

slideCamera()

Slide the camera in a certain direction.

slideCamera(opts?: {
  direction: VecLike
  friction?: number | undefined
  speed: number
  speedThreshold?: number | undefined
}): this
Example
editor.slideCamera({ speed: 1, direction: { x: 1, y: 0 }, friction: 0.1 })
Parameters
NameDescription

opts

{
  direction: VecLike
  friction?: number | undefined
  speed: number
  speedThreshold?: number | undefined
}

Options for the slide

Returns
this

stackShapes()

Stack shape.

stackShapes(
  shapes: TLShape[] | TLShapeId[],
  operation: 'horizontal' | 'vertical',
  gap: number
): this
Example
editor.stackShapes([box1, box2], 'horizontal', 32)
editor.stackShapes(editor.getSelectedShapeIds(), 'horizontal', 32)
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to stack.

operation

'horizontal' | 'vertical'

Whether to stack horizontally or vertically.

gap

number

The gap to leave between shapes.

Returns
this

startFollowingUser()

Start viewport-following a user.

startFollowingUser(userId: string): this
Example
editor.startFollowingUser(myUserId)
Parameters
NameDescription

userId

string

The id of the user to follow.

Returns
this

stopCameraAnimation()

Stop the current camera animation, if any.

stopCameraAnimation(): this
Example
editor.stopCameraAnimation()

stopFollowingUser()

Stop viewport-following a user.

stopFollowingUser(): this
Example
editor.stopFollowingUser()

stretchShapes()

Stretch shape sizes and positions to fill their common bounding box.

stretchShapes(
  shapes: TLShape[] | TLShapeId[],
  operation: 'horizontal' | 'vertical'
): this
Example
editor.stretchShapes([box1, box2], 'horizontal')
editor.stretchShapes(editor.getSelectedShapeIds(), 'horizontal')
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to stretch.

operation

'horizontal' | 'vertical'

Whether to stretch shapes horizontally or vertically.

Returns
this

toggleLock()

Toggle the lock state of one or more shapes. If there is a mix of locked and unlocked shapes, all shapes will be locked.

toggleLock(shapes: TLShape[] | TLShapeId[]): this
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to toggle.

Returns
this

undo()

Undo to the last mark.

undo(): this
Example
editor.undo()

ungroupShapes()

Ungroup some shapes.

ungroupShapes(
  ids: TLShapeId[],
  options?: Partial<{
    select: boolean
  }>
): this
Example
editor.ungroupShapes([myGroup, myOtherGroup])
editor.ungroupShapes([myGroup], { select: false })
Parameters
NameDescription

ids

TLShapeId[]

options

Partial<{
  select: boolean
}>

An options object.

Returns
this

updateAssets()

Update one or more assets.

updateAssets(assets: TLAssetPartial[]): this
Example
editor.updateAssets([{ id: 'asset1', name: 'New name' }])
Parameters
NameDescription

assets

TLAssetPartial[]

The assets to update.

Returns
this

updateBinding()

Update a binding from a partial binding. Each partial must include an ID, which will be used to match the binding to it's existing record. If there is no existing record, that binding is skipped. The changes from the partial are merged into the existing record.

updateBinding<B extends TLBinding = TLBinding>(
  partial: TLBindingUpdate<B>
): this
Parameters
NameDescription

partial

TLBindingUpdate<B>
Returns
this

updateBindings()

Update bindings from a list of partial bindings. Each partial must include an ID, which will be used to match the binding to it's existing record. If there is no existing record, that binding is skipped. The changes from the partial are merged into the existing record.

updateBindings(partials: (null | TLBindingUpdate | undefined)[]): this
Parameters
NameDescription

partials

(null | TLBindingUpdate | undefined)[]
Returns
this

updateCurrentPageState()

Update this instance's page state.

updateCurrentPageState(
  partial: Partial<
    Omit<
      TLInstancePageState,
      'editingShapeId' | 'focusedGroupId' | 'pageId' | 'selectedShapeIds'
    >
  >,
  historyOptions?: TLHistoryBatchOptions
): this
Example
editor.updateCurrentPageState({ id: 'page1', editingShapeId: 'shape:123' })
editor.updateCurrentPageState(
  { id: 'page1', editingShapeId: 'shape:123' },
  { ephemeral: true }
)
Parameters
NameDescription

partial

Partial<
  Omit<
    TLInstancePageState,
    | 'editingShapeId'
    | 'focusedGroupId'
    | 'pageId'
    | 'selectedShapeIds'
  >
>

The partial of the page state object containing the changes.

historyOptions

TLHistoryBatchOptions

The history options for the change.

Returns
this

updateDocumentSettings()

Update the global document settings that apply to all users.

updateDocumentSettings(settings: Partial<TLDocument>): this
Parameters
NameDescription

settings

Partial<TLDocument>
Returns
this

updateInstanceState()

Update the instance's state.

updateInstanceState(
  partial: Partial<Omit<TLInstance, 'currentPageId'>>,
  historyOptions?: TLHistoryBatchOptions
): this
Parameters
NameDescription

partial

Partial<Omit<TLInstance, 'currentPageId'>>

A partial object to update the instance state with.

historyOptions

TLHistoryBatchOptions
Returns
this

updatePage()

Update a page.

updatePage(partial: RequiredKeys<Partial<TLPage>, 'id'>): this
Example
editor.updatePage({ id: 'page2', name: 'Page 2' })
Parameters
NameDescription

partial

RequiredKeys<Partial<TLPage>, 'id'>

The partial of the shape to update.

Returns
this

updateShape()

Update a shape using a partial of the shape.

updateShape<T extends TLUnknownShape>(
  partial: null | TLShapePartial<T> | undefined
): this
Example
editor.updateShape({ id: 'box1', type: 'geo', props: { w: 100, h: 100 } })
Parameters
NameDescription

partial

null | TLShapePartial<T> | undefined

The shape partial to update.

Returns
this

updateShapes()

Update shapes using partials of each shape.

updateShapes<T extends TLUnknownShape>(
  partials: (null | TLShapePartial<T> | undefined)[]
): this
Example
editor.updateShapes([{ id: 'box1', type: 'geo', props: { w: 100, h: 100 } }])
Parameters
NameDescription

partials

(null | TLShapePartial<T> | undefined)[]

The shape partials to update.

Returns
this

updateViewportScreenBounds()

Update the viewport. The viewport will measure the size and screen position of its container element. This should be done whenever the container's position on the screen changes.

updateViewportScreenBounds(screenBounds: Box, center?: boolean): this
Example
editor.updateViewportScreenBounds(new Box(0, 0, 1280, 1024))
editor.updateViewportScreenBounds(new Box(0, 0, 1280, 1024), true)
Parameters
NameDescription

screenBounds

Box

center

boolean

Whether to preserve the viewport page center as the viewport changes.

Returns
this

visitDescendants()

Run a visitor function for all descendants of a shape.

visitDescendants(
  parent: TLPage | TLParentId | TLShape,
  visitor: (id: TLShapeId) => false | void
): this
Example
editor.visitDescendants('frame1', myCallback)
Parameters
NameDescription

parent

TLPage | TLParentId | TLShape

visitor

(id: TLShapeId) => false | void

The visitor function.

Returns
this

zoomIn()

Zoom the camera in.

zoomIn(point?: Vec, opts?: TLCameraMoveOptions): this
Example
editor.zoomIn()
editor.zoomIn(editor.getViewportScreenCenter(), {
  animation: { duration: 200 },
})
editor.zoomIn(editor.inputs.currentScreenPoint, {
  animation: { duration: 200 },
})
Parameters
NameDescription

point

Vec

The screen point to zoom in on. Defaults to the screen center

opts

TLCameraMoveOptions

The camera move options.

Returns
this

zoomOut()

Zoom the camera out.

zoomOut(point?: Vec, opts?: TLCameraMoveOptions): this
Example
editor.zoomOut()
editor.zoomOut(editor.getViewportScreenCenter(), {
  animation: { duration: 120 },
})
editor.zoomOut(editor.inputs.currentScreenPoint, {
  animation: { duration: 120 },
})
Parameters
NameDescription

point

Vec

The point to zoom out on. Defaults to the viewport screen center.

opts

TLCameraMoveOptions

The camera move options.

Returns
this

zoomToBounds()

Zoom the camera to fit a bounding box (in the current page space).

zoomToBounds(
  bounds: BoxLike,
  opts?: {
    inset?: number
    targetZoom?: number
  } & TLCameraMoveOptions
): this
Example
editor.zoomToBounds(myBounds)
editor.zoomToBounds(myBounds, { animation: { duration: 200 } })
editor.zoomToBounds(myBounds, {
  animation: { duration: 200 },
  inset: 0,
  targetZoom: 1,
})
Parameters
NameDescription

bounds

BoxLike

The bounding box.

opts

{
  inset?: number
  targetZoom?: number
} & TLCameraMoveOptions

The camera move options, target zoom, or custom inset amount.

Returns
this

zoomToFit()

Zoom the camera to fit the current page's content in the viewport.

zoomToFit(opts?: TLCameraMoveOptions): this
Example
editor.zoomToFit()
editor.zoomToFit({ animation: { duration: 200 } })
Parameters
NameDescription

opts

TLCameraMoveOptions

The camera move options.

Returns
this

zoomToSelection()

Zoom the camera to fit the current selection in the viewport.

zoomToSelection(opts?: TLCameraMoveOptions): this
Example
editor.zoomToSelection()
editor.zoomToSelection({ animation: { duration: 200 } })
Parameters
NameDescription

opts

TLCameraMoveOptions
Returns
this

zoomToUser()

Animate the camera to a user's cursor position. This also briefly show the user's cursor if it's not currently visible.

zoomToUser(userId: string, opts?: TLCameraMoveOptions): this
Example
editor.zoomToUser(myUserId)
editor.zoomToUser(myUserId, { animation: { duration: 200 } })
Parameters
NameDescription

userId

string

The id of the user to animate to.

opts

TLCameraMoveOptions

The camera move options.

Returns
this

Edge2dEllipse2d