Editor

Extends EventEmitter<TLEventMap>.

class Editor extends EventEmitter<TLEventMap> {}

Constructs a new instance of the Editor class

TLEditorOptions

Properties

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

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

Dispatch an event to the editor.

dispatch: (info: TLEventInfo) => this

editor.dispatch(myPointerEvent)

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

readonly disposables: Set<() => void>

A manager for moving the camera when the mouse is at the edge of the screen.

edgeScrollManager: EdgeScrollManager

A manager for the editor's environment.

readonly environment: EnvironmentManager

The current HTML element containing the editor.

getContainer: () => HTMLElement

const container = editor.getContainer()

A manager for the app's history.

protected readonly history: HistoryManager<TLRecord>

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
}

Whether the editor is disposed.

isDisposed: boolean

readonly options: TldrawOptions

The root state of the statechart.

readonly root: StateNode

A manager for the editor's scribbles.

readonly scribbles: ScribbleManager

Set the cursor.

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

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

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

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

readonly sideEffects: StoreSideEffects<TLRecord>

A manager for the app's snapping feature.

readonly snaps: SnapManager

The editor's store

readonly store: TLStore

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

A helper for measuring text.

readonly textMeasure: TextManager

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

readonly timers: Timers

A manager for the user and their preferences.

readonly user: UserPreferencesManager

Methods

Add an open menu.

addOpenMenu(id: string): this

editor.addOpenMenu('menu-id')

string

this

Align shape positions.

alignShapes(
  shapes: TLShape[] | TLShapeId[],
  operation:
    | 'bottom'
    | 'center-horizontal'
    | 'center-vertical'
    | 'left'
    | 'right'
    | 'top'
): this

editor.alignShapes([box1, box2], 'left')
editor.alignShapes(editor.getSelectedShapeIds(), 'left')

TLShape[] | TLShapeId[]

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

this

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

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 } }
)

null | TLShapePartial | undefined

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

this

Animate shapes.

animateShapes(
  partials: (null | TLShapePartial | undefined)[],
  opts?: Partial<{
    animation: Partial<{
      duration: number
      easing: (t: number) => number
    }>
    force: boolean
    immediate: boolean
    reset: boolean
  }>
): this

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 },
})

(null | TLShapePartial | undefined)[]

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

this

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

bail(): this

editor.bail()

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

bailToMark(id: string): this

editor.bailToMark('dragging')

string

this

batch(fn: () => void, opts?: TLEditorRunOptions): this

() => void

TLEditorRunOptions

this

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

editor.blur()

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

editor.blur({ blurContainer: false })

{
  blurContainer?: boolean | undefined
}

this

Bring shapes forward in the page's object list.

bringForward(shapes: TLShape[] | TLShapeId[]): this

editor.bringForward(['id1', 'id2'])
editor.bringForward(box1, box2)

TLShape[] | TLShapeId[]

this

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

bringToFront(shapes: TLShape[] | TLShapeId[]): this

editor.bringToFront(['id1', 'id2'])
editor.bringToFront([box1, box2])

TLShape[] | TLShapeId[]

this

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

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

boolean

Dispatch a cancel event.

cancel(): this

editor.cancel()

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

cancelDoubleClick(): void

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

centerOnPoint(point: VecLike, opts?: TLCameraMoveOptions): this

editor.centerOnPoint({ x: 100, y: 100 })
editor.centerOnPoint({ x: 100, y: 100 }, { animation: { duration: 200 } })

VecLike

TLCameraMoveOptions

this

clearHistory(): this

Clear all open menus.

clearOpenMenus(): this

editor.clearOpenMenus()

Dispatch a complete event.

complete(): this

editor.complete()

Create one or more assets.

createAssets(assets: TLAsset[]): this

editor.createAssets([...myAssets])

TLAsset[]

this

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

TLBindingCreate<B>

this

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

TLBindingCreate[]

this

Create a page.

createPage(page: Partial<TLPage>): this

editor.createPage(myPage)
editor.createPage({ name: 'Page 2' })

Partial<TLPage>

this

Create a single shape.

createShape<T extends TLUnknownShape>(
  shape: OptionalKeys<TLShapePartial<T>, 'id'>
): this

editor.createShape(myShape)
editor.createShape({ id: 'box1', type: 'text', props: { text: 'ok' } })

OptionalKeys<TLShapePartial<T>, 'id'>

this

Create shapes.

createShapes<T extends TLUnknownShape>(
  shapes: OptionalKeys<TLShapePartial<T>, 'id'>[]
): this

editor.createShapes([myShape])
editor.createShapes([{ id: 'box1', type: 'text', props: { text: 'ok' } }])

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

this

Delete one or more assets.

deleteAssets(assets: TLAsset[] | TLAssetId[]): this

editor.deleteAssets(['asset1', 'asset2'])

TLAsset[] | TLAssetId[]

this

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

TLBinding | TLBindingId

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

this

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

(TLBinding | TLBindingId)[]

{
  isolateShapes?: boolean | undefined
}

this

Delete an open menu.

deleteOpenMenu(id: string): this

editor.deleteOpenMenu('menu-id')

string

this

Delete a page.

deletePage(page: TLPage | TLPageId): this

editor.deletePage('page1')

TLPage | TLPageId

this

Delete a shape.

deleteShape(id: TLShapeId): this

editor.deleteShape(shape.id)

TLShapeId

this

Delete shapes.

deleteShapes(ids: TLShapeId[]): this

editor.deleteShapes(['box1', 'box2'])

TLShapeId[]

this

Remove a shape from the existing set of selected shapes.

deselect(...shapes: TLShape[] | TLShapeId[]): this

editor.deselect(shape.id)

TLShape[] | TLShapeId[]

this

Dispose the editor.

dispose(): void

Distribute shape positions.

distributeShapes(
  shapes: TLShape[] | TLShapeId[],
  operation: 'horizontal' | 'vertical'
): this

editor.distributeShapes([box1, box2], 'horizontal')
editor.distributeShapes(editor.getSelectedShapeIds(), 'horizontal')

TLShape[] | TLShapeId[]

'horizontal' | 'vertical'

this

Duplicate a page.

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

TLPage | TLPageId

TLPageId

this

Duplicate shapes.

duplicateShapes(shapes: TLShape[] | TLShapeId[], offset?: VecLike): this

editor.duplicateShapes(['box1', 'box2'], { x: 8, y: 8 })
editor.duplicateShapes(editor.getSelectedShapes(), { x: 8, y: 8 })

TLShape[] | TLShapeId[]

VecLike

this

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

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

TLShape[] | TLShapeId[]

(shape: TLShape) => boolean

TLShapeId | undefined

Find the first ancestor matching the given predicate

findShapeAncestor(
  shape: TLShape | TLShapeId,
  predicate: (parent: TLShape) => boolean
): TLShape | undefined

const ancestor = editor.findShapeAncestor(myShape)
const ancestor = editor.findShapeAncestor(myShape.id)
const ancestor = editor.findShapeAncestor(
  myShape.id,
  (shape) => shape.type === 'frame'
)

TLShape | TLShapeId

(parent: TLShape) => boolean

TLShape | undefined

Flip shape positions.

flipShapes(
  shapes: TLShape[] | TLShapeId[],
  operation: 'horizontal' | 'vertical'
): this

editor.flipShapes([box1, box2], 'horizontal', 32)
editor.flipShapes(editor.getSelectedShapeIds(), 'horizontal', 32)

TLShape[] | TLShapeId[]

'horizontal' | 'vertical'

this

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

editor.focus()

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

editor.focus({ focusContainer: false })

{
  focusContainer?: boolean | undefined
}

this

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

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

TLShape | TLShapeId

TLPageId | undefined

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

Get an asset by its id.

getAsset(asset: TLAsset | TLAssetId): TLAsset | undefined

editor.getAsset('asset1')

TLAsset | TLAssetId

TLAsset | undefined

Get an asset for an external asset content type.

getAssetForExternalContent(
  info: TLExternalAssetContent
): Promise<TLAsset | undefined>

const asset = await editor.getAssetForExternalContent({
  type: 'file',
  file: myFile,
})
const asset = await editor.getAssetForExternalContent({
  type: 'url',
  url: myUrl,
})

TLExternalAssetContent

Promise<TLAsset | undefined>

The asset.

Get all assets in the editor.

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

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

getBaseZoom(): number

editor.getBaseZoom()

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

getBinding(id: TLBindingId): TLBinding | undefined

TLBindingId

TLBinding | undefined

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[]

TLShape | TLShapeId

Binding['type']

Binding[]

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[]

TLShape | TLShapeId

Binding['type']

Binding[]

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[]

TLShape | TLShapeId

Binding['type']

Binding[]

Get a binding util from a binding itself.

getBindingUtil<S extends TLUnknownBinding>(
  binding:
    | {
        type: S['type']
      }
    | S
): BindingUtil<S>

const util = editor.getBindingUtil(myArrowBinding)
const util = editor.getBindingUtil('arrow')
const util = editor.getBindingUtil<TLArrowBinding>(myArrowBinding)
const util = editor.getBindingUtil(TLArrowBinding)('arrow')

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

BindingUtil<S>

The current camera.

getCamera(): TLCamera

Get the current camera options.

getCameraOptions(): TLCameraOptions

editor.getCameraOptions()

Whether the camera is moving or idle.

getCameraState(): 'idle' | 'moving'

editor.getCameraState()

Whether the app can redo.

getCanRedo(): boolean

Whether the app can undo.

getCanUndo(): boolean

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[]

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[]

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

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

TLShape[] | TLShapeId[]

TLContent | undefined

The exported content.

The current cropping shape's id.

getCroppingShapeId(): null | TLShapeId

Get culled shapes.

getCulledShapes(): Set<TLShapeId>

The current page.

getCurrentPage(): TLPage

editor.getCurrentPage()

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

getCurrentPageBounds(): Box | undefined

The current page id.

getCurrentPageId(): TLPageId

editor.getCurrentPageId()

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[]

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

getCurrentPageShapeIds(): Set<TLShapeId>

editor.getCurrentPageIds()

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

getCurrentPageShapes(): TLShape[]

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[]

The current page state.

getCurrentPageState(): TLInstancePageState

The current selected tool.

getCurrentTool(): StateNode

The id of the current selected tool.

getCurrentToolId(): string

The global document settings that apply to all users.

getDocumentSettings(): TLDocument

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

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

VecLike

TLShape[]

TLUnknownShape | undefined

The shape to drop on.

The current editing shape.

getEditingShape(): TLShape | undefined

The current editing shape's id.

getEditingShapeId(): null | TLShapeId

The editor's current erasing ids.

getErasingShapeIds(): TLShapeId[]

The editor's current erasing shapes.

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

The current focused group.

getFocusedGroup(): TLShape | undefined

The current focused group id.

getFocusedGroupId(): TLPageId | TLShapeId

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

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

TLPage | TLParentId | TLShape

IndexKey

The index.

The editor's current hinting shapes.

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

The editor's current hinting shape ids.

getHintingShapeIds(): TLShapeId[]

The current hovered shape.

getHoveredShape(): TLShape | undefined

The current hovered shape id.

getHoveredShapeId(): null | TLShapeId

Get the initial meta value for a shape.

getInitialMetaForShape(_shape: TLShape): JsonObject

editor.getInitialMetaForShape = (shape) => {
  if (shape.type === 'note') {
    return { createdBy: myCurrentUser.id }
  }
}

TLShape

JsonObject

Get the camera's initial or reset zoom level.

getInitialZoom(): number

editor.getInitialZoom()

The current instance's state.

getInstanceState(): TLInstance

getIsFocused(): boolean

Get whether any menus are open.

getIsMenuOpen(): boolean

editor.getIsMenuOpen()

The app's only selected shape.

getOnlySelectedShape(): null | TLShape

The id of the app's only selected shape.

getOnlySelectedShapeId(): null | TLShapeId

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[]

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

TLShape | TLShapeId

(shape: TLShape) => boolean

TLShape

The outermost selectable shape.

Get a page.

getPage(page: TLPage | TLPageId): TLPage | undefined

editor.getPage(myPage.id)
editor.getPage(myPage)

TLPage | TLPageId

TLPage | undefined

Info about the project's current pages.

getPages(): TLPage[]

editor.getPages()

Get the ids of shapes on a page.

getPageShapeIds(page: TLPage | TLPageId): Set<TLShapeId>

const idsOnPage1 = editor.getPageShapeIds('page1')
const idsOnPage2 = editor.getPageShapeIds(myPage2)

TLPage | TLPageId

Set<TLShapeId>

Page states.

getPageStates(): TLInstancePageState[]

The editor's current path of active states.

getPath(): string

editor.getPath() // "select.idle"

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

editor.getPointInParentSpace(myShape.id, { x: 100, y: 100 })

TLShape | TLShapeId

VecLike

Vec

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

editor.getPointInShapeSpace(myShape, { x: 100, y: 100 })

TLShape | TLShapeId

VecLike

Vec

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>
}[]

editor.getRenderingShapes()

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

getSelectedShapeAtPoint(point: VecLike): TLShape | undefined

VecLike

TLShape | undefined

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

The current selected ids.

getSelectedShapeIds(): TLShapeId[]

An array containing all of the currently selected shapes.

getSelectedShapes(): TLShape[]

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

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

getSelectionRotatedPageBounds(): Box | undefined

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

getSelectionRotatedScreenBounds(): Box | undefined

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

getSelectionRotation(): number

Get a shape by its id.

getShape<T extends TLShape = TLShape>(
  shape: TLParentId | TLShape
): T | undefined

editor.getShape('box1')

TLParentId | TLShape

T | undefined

Get the ancestors of a shape.

getShapeAncestors(shape: TLShape | TLShapeId, acc?: TLShape[]): TLShape[]

const ancestors = editor.getShapeAncestors(myShape)
const ancestors = editor.getShapeAncestors(myShapeId)

TLShape | TLShapeId

TLShape[]

TLShape[]

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>

TLShapeId[]

Set<TLShapeId>

The descendant ids.

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

VecLike

{
  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

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

Get the clip path for a shape.

getShapeClipPath(shape: TLShape | TLShapeId): string | undefined

const clipPath = editor.getShapeClipPath(shape)
const clipPath = editor.getShapeClipPath(shape.id)

TLShape | TLShapeId

string | undefined

The clip path or undefined.

Get the geometry of a shape.

getShapeGeometry<T extends Geometry2d>(shape: TLShape | TLShapeId): T

editor.getShapeGeometry(myShape)
editor.getShapeGeometry(myShapeId)

TLShape | TLShapeId

T

Get the handles (if any) for a shape.

getShapeHandles<T extends TLShape>(shape: T | T['id']): TLHandle[] | undefined

editor.getShapeHandles(myShape)
editor.getShapeHandles(myShapeId)

T | T['id']

TLHandle[] | undefined

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

editor.getShapeLocalTransform(myShape)

TLShape | TLShapeId

Mat

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

getShapeMask(shape: TLShape | TLShapeId): undefined | VecLike[]

const pageMask = editor.getShapeMask(shape.id)

TLShape | TLShapeId

undefined | VecLike[]

The mask for the shape.

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

editor.getShapeMaskedPageBounds(myShape)
editor.getShapeMaskedPageBounds(myShapeId)

TLShape | TLShapeId

Box | undefined

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

getShapePageBounds(shape: TLShape | TLShapeId): Box | undefined

editor.getShapePageBounds(myShape)
editor.getShapePageBounds(myShapeId)

TLShape | TLShapeId

Box | undefined

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

getShapePageTransform(shape: TLShape | TLShapeId): Mat

editor.getShapePageTransform(myShape)
editor.getShapePageTransform(myShapeId)

TLShape | TLShapeId

Mat

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

editor.getShapeParent(myShape)

TLShape | TLShapeId

TLShape | undefined

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

getShapeParentTransform(shape: TLShape | TLShapeId): Mat

editor.getShapeParentTransform(myShape)

TLShape | TLShapeId

Mat

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

getShapesAtPoint(
  point: VecLike,
  opts?: {
    hitInside?: boolean | undefined
    margin?: number | undefined
  }
): TLShape[]

editor.getShapesAtPoint({ x: 100, y: 100 })
editor.getShapesAtPoint({ x: 100, y: 100 }, { hitInside: true, exact: true })

VecLike

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

TLShape[]

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

TLShape

StyleProp<T>

T | undefined

Get a shape util from a shape itself.

getShapeUtil<S extends TLUnknownShape>(
  shape: S | TLShapePartial<S>
): ShapeUtil<S>

const util = editor.getShapeUtil(myArrowShape)
const util = editor.getShapeUtil('arrow')
const util = editor.getShapeUtil<TLArrowShape>(myArrowShape)
const util = editor.getShapeUtil(TLArrowShape)('arrow')

S | TLShapePartial<S>

ShapeUtil<S>

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>

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

getSharedStyles(): ReadonlySharedStyleMap

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

getSnapshot(): TLEditorSnapshot

Get an array of all the children of a shape.

getSortedChildIdsForParent(parent: TLPage | TLParentId | TLShape): TLShapeId[]

editor.getSortedChildIdsForParent('frame1')

TLPage | TLParentId | TLShape

TLShapeId[]

Get a descendant by its path.

getStateDescendant<T extends StateNode>(path: string): T | undefined

state.getStateDescendant('select')
state.getStateDescendant('select.brushing')

string

T | undefined

Get the style for the next shape.

getStyleForNextShape<T>(style: StyleProp<T>): T

const color = editor.getStyleForNextShape(DefaultColorStyle)

StyleProp<T>

T

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

TLShape[] | TLShapeId[]

TLSvgOptions

Promise<SVGSVGElement | undefined>

Get an exported SVG element of the given shapes.

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

TLShape[] | TLShapeId[]

TLSvgOptions

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

The SVG element.

Get an exported SVG string of the given shapes.

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

TLShape[] | TLShapeId[]

TLSvgOptions

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

The SVG element.

The current viewport in the current page space.

getViewportPageBounds(): Box

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

getViewportScreenBounds(): Box

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

getViewportScreenCenter(): Vec

The current camera zoom level.

getZoomLevel(): number

Create a group containing the provided shapes.

groupShapes(
  shapes: TLShape[],
  options?: Partial<{
    groupId: TLShapeId
    select: boolean
  }>
): this

editor.groupShapes([myShape, myOtherShape])
editor.groupShapes([myShape, myOtherShape], {
  groupId: myGroupId,
  select: false,
})

TLShape[]

Partial<{
  groupId: TLShapeId
  select: boolean
}>

this

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

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

TLShape | TLShapeId | undefined

TLShapeId

boolean

hasExternalAssetHandler(type: TLExternalAssetContent['type']): boolean

TLExternalAssetContent['type']

boolean

Dispatch an interrupt event.

interrupt(): this

editor.interrupt()

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

isAncestorSelected(shape: TLShape | TLShapeId): boolean

TLShape | TLShapeId

boolean

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

isIn(path: string): boolean

editor.isIn('select')
editor.isIn('select.brushing')

string

boolean

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

isInAny(...paths: string[]): boolean

state.isInAny('select', 'erase')
state.isInAny('select.brushing', 'erase.idle')

string[]

boolean

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

editor.isPointInShape({ x: 100, y: 100 }, myShape)

TLShape | TLShapeId

VecLike

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

boolean

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

isShapeInPage(shape: TLShape | TLShapeId, pageId?: TLPageId): boolean

editor.isShapeInPage(myShape)
editor.isShapeInPage(myShape, 'page1')

TLShape | TLShapeId

TLPageId

boolean

Get whether a shape matches the type of a TLShapeUtil.

isShapeOfType<T extends TLUnknownShape>(
  shape: TLUnknownShape,
  type: T['type']
): shape is T

const isArrowShape = isShapeOfType<TLArrowShape>(someShape, 'arrow')

TLUnknownShape

T['type']

shape is T

Check whether a shape or its parent is locked.

isShapeOrAncestorLocked(shape?: TLShape): boolean

TLShape

boolean

Loads a snapshot into the editor.

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

Partial<TLEditorSnapshot> | TLStoreSnapshot

this

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

mark(markId?: string): this

editor.mark()
editor.mark('flip shapes')

string

this

Move shapes to page.

moveShapesToPage(shapes: TLShape[] | TLShapeId[], pageId: TLPageId): this

editor.moveShapesToPage(['box1', 'box2'], 'page1')

TLShape[] | TLShapeId[]

TLPageId

this

Move shapes by a delta.

nudgeShapes(shapes: TLShape[] | TLShapeId[], offset: VecLike): this

editor.nudgeShapes(['box1', 'box2'], { x: 8, y: 8 })

TLShape[] | TLShapeId[]

VecLike

this

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

editor.packShapes([box1, box2], 32)
editor.packShapes(editor.getSelectedShapeIds(), 32)

TLShape[] | TLShapeId[]

number

this

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

pageToScreen(point: VecLike): Vec

editor.pageToScreen({ x: 100, y: 100 })

VecLike

Vec

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

pageToViewport(point: VecLike): Vec

editor.pageToViewport({ x: 100, y: 100 })

VecLike

Vec

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

popFocusedGroupId(): this

Place content into the editor.

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

TLContent

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

this

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>

TLExternalContent

Promise<void>

Redo to the next mark.

redo(): this

editor.redo()

Register an external asset handler. This handler will be called when the editor needs to create an asset for some external content, like an image/video file or a bookmark URL. For example, the 'file' type handler will be called when a user drops an image onto the canvas.

The handler should extract any relevant metadata for the asset, upload it to blob storage using Editor.uploadAsset if needed, and return the asset with the metadata & uploaded URL.

registerExternalAssetHandler<T extends TLExternalAssetContent['type']>(
  type: T,
  handler:
    | ((
        info: TLExternalAssetContent & {
          type: T
        }
      ) => Promise<TLAsset>)
    | null
): this

editor.registerExternalAssetHandler('file', myHandler)

T

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

this

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

editor.registerExternalContentHandler('text', myHandler)

T

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

this

Rename a page.

renamePage(page: TLPage | TLPageId, name: string): this

editor.renamePage('page1', 'My Page')

TLPage | TLPageId

string

this

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

editor.reparentShapes([box1, box2], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1', 4)

TLShape[] | TLShapeId[]

TLParentId

IndexKey

this

Set the zoom back to 100%.

resetZoom(point?: Vec, opts?: TLCameraMoveOptions): this

editor.resetZoom()
editor.resetZoom(editor.getViewportScreenCenter(), {
  animation: { duration: 200 },
})
editor.resetZoom(editor.getViewportScreenCenter(), {
  animation: { duration: 200 },
})

Vec

TLCameraMoveOptions

this

Resize a shape.

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

TLShape | TLShapeId

VecLike

TLResizeShapeOptions

this

resolveAssetsInContent(
  content: TLContent | undefined
): Promise<TLContent | undefined>

TLContent | undefined

Promise<TLContent | undefined>

resolveAssetUrl(
  assetId: null | TLAssetId,
  context: {
    screenScale?: number
    shouldResolveToOriginal?: boolean
  }
): Promise<null | string>

null | TLAssetId

{
  screenScale?: number
  shouldResolveToOriginal?: boolean
}

Promise<null | string>

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

editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI)
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI / 2)

TLShape[] | TLShapeId[]

number

this

Run a function in a transaction with optional options for context. You can use the options to change the way that history is treated or allow changes to locked shapes.

run(fn: () => void, opts?: TLEditorRunOptions): this

// updating with
editor.run(
  () => {
    editor.updateShape({ ...myShape, x: 100 })
  },
  { history: 'ignore' }
)

// forcing changes / deletions for locked shapes
editor.toggleLock([myShape])
editor.run(
  () => {
    editor.updateShape({ ...myShape, x: 100 })
    editor.deleteShape(myShape)
  },
  { ignoreShapeLock: true }
)

() => void

TLEditorRunOptions

this

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

screenToPage(point: VecLike): Vec

editor.screenToPage({ x: 100, y: 100 })

VecLike

Vec

Select one or more shapes.

select(...shapes: TLShape[] | TLShapeId[]): this

editor.select('id1')
editor.select('id1', 'id2')

TLShape[] | TLShapeId[]

this

Select all direct children of the current page.

selectAll(): this

editor.selectAll()

Clear the selection.

selectNone(): this

editor.selectNone()

Send shapes backward in the page's object list.

sendBackward(shapes: TLShape[] | TLShapeId[]): this

editor.sendBackward(['id1', 'id2'])
editor.sendBackward([box1, box2])

TLShape[] | TLShapeId[]

this

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

sendToBack(shapes: TLShape[] | TLShapeId[]): this

editor.sendToBack(['id1', 'id2'])
editor.sendToBack(box1, box2)

TLShape[] | TLShapeId[]

this

Set the current camera.

setCamera(point: VecLike, opts?: TLCameraMoveOptions): this

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 } }
)

VecLike

TLCameraMoveOptions

this

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

editor.setCameraOptions(myCameraOptions)
editor.setCamera(editor.getCamera())

Partial<TLCameraOptions>

this

Set the current cropping shape.

setCroppingShape(shape: null | TLShape | TLShapeId): this

editor.setCroppingShape(myShape)
editor.setCroppingShape(myShape.id)

null | TLShape | TLShapeId

this

Set the current page.

setCurrentPage(page: TLPage | TLPageId): this

editor.setCurrentPage('page1')
editor.setCurrentPage(myPage1)

TLPage | TLPageId

this

Set the selected tool.

setCurrentTool(id: string, info?: {}): this

editor.setCurrentTool('hand')
editor.setCurrentTool('hand', { date: Date.now() })

string

{}

this

Set the current editing shape.

setEditingShape(shape: null | TLShape | TLShapeId): this

editor.setEditingShape(myShape)
editor.setEditingShape(myShape.id)

null | TLShape | TLShapeId

this

Set the editor's current erasing shapes.

setErasingShapes(shapes: TLShape[] | TLShapeId[]): this

editor.setErasingShapes([myShape])
editor.setErasingShapes([myShape.id])

TLShape[] | TLShapeId[]