Editor

See source code
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, textOptions, initialState, autoFocus, inferDarkMode, options, isShapeHidden, }

TLEditorOptions

Properties

bindingUtils

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

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

contextId

readonly
readonly contextId: string

disposables

readonly

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

readonly disposables: Set<() => void>

edgeScrollManager

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

edgeScrollManager: EdgeScrollManager

environment

readonly

Deprecated: This is deprecated and will be removed in a future version. Use the tlenv global export instead.

A manager for the editor's environment.

readonly environment: {
  isAndroid: boolean
  isChromeForIos: boolean
  isDarwin: boolean
  isFirefox: boolean
  isIos: boolean
  isSafari: boolean
  isWebview: boolean
}

getContainer

The current HTML element containing the editor.

getContainer: () => HTMLElement

Example

const container = editor.getContainer()

history

readonly

A manager for the app's history.

protected 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
  metaKey: boolean
  shiftKey: boolean
  isDragging: boolean
  isEditing: boolean
  isPanning: boolean
  isPinching: boolean
  isPointing: boolean
  isSpacebarPanning: boolean
}

isDisposed

Whether the editor is disposed.

isDisposed: boolean
menus: {
  addOpenMenu: (id: string) => void
  clearOpenMenus: () => void
  deleteOpenMenu: (id: string) => void
  getOpenMenus: () => string[]
  hasAnyOpenMenus: () => boolean
  hasOpenMenus: () => boolean
  isMenuOpen: (id: string) => boolean
}

options

readonly
readonly options: TldrawOptions

root

readonly

The root state of the statechart.

readonly root: StateNode

scribbles

readonly

A manager for the editor's scribbles.

readonly scribbles: ScribbleManager

shapeUtils

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

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

sideEffects

readonly

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

readonly sideEffects: StoreSideEffects<TLRecord>

snaps

readonly

A manager for the app's snapping feature.

readonly snaps: SnapManager

store

readonly

The editor's store

readonly store: TLStore

styleProps

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

textMeasure

readonly

A helper for measuring text.

readonly textMeasure: TextManager

timers

readonly

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

readonly timers: {
  dispose: () => void
  requestAnimationFrame: (callback: FrameRequestCallback) => number
  setInterval: (
    handler: TimerHandler,
    timeout?: number | undefined,
    ...args: any[]
  ) => number
  setTimeout: (
    handler: TimerHandler,
    timeout?: number | undefined,
    ...args: any[]
  ) => number
}

user

readonly

A manager for the user and their preferences.

readonly user: UserPreferencesManager

Methods

addOpenMenu()

Deprecated: Use editor.menus.addOpenMenu instead.

addOpenMenu(id: string): this

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?: TLCameraMoveOptions
): 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

TLCameraMoveOptions

The animation's options.

Returns

this

animateShapes()

Animate shapes.

animateShapes(
  partials: (null | TLShapePartial | undefined)[],
  opts?: TLCameraMoveOptions
): 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

TLCameraMoveOptions

The animation's options.

Returns

this

bail()

Undo to the closest mark, discarding the changes so they cannot be redone.

bail(): this

Example

editor.bail()

bailToMark()

Undo to the given mark, discarding the changes so they cannot be redone.

bailToMark(id: string): this

Example

const beginDrag = editor.markHistoryStoppingPoint()
// ... some changes
editor.bailToMark(beginDrag)

Parameters

NameDescription

id

string

Returns

this

batch()

Deprecated: Use Editor.run instead.

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

Parameters

NameDescription

fn

() => void

opts

TLEditorRunOptions

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[],
  opts?: {
    considerAllShapes?: boolean
  }
): this

Example

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

By default, the operation will only consider overlapping shapes. To consider all shapes, pass { considerAllShapes: true } in the options.

editor.bringForward(['id1', 'id2'], { considerAllShapes: true })

Parameters

NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

opts

{
  considerAllShapes?: boolean
}

The options for the forward operation.

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

The camera move options.

Returns

this

clearHistory()

clearHistory(): this

clearOpenMenus()

Deprecated: Use editor.menus.clearOpenMenus instead.

clearOpenMenus(): this

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

Turns the given URL into a deep link by adding a query parameter.

e.g. https://my-app.com/my-document?d=100.100.200.200.xyz123

If no URL is provided, it will use the current window.location.href.

createDeepLink(opts?: {
  param?: string
  to?: TLDeepLink
  url?: string | URL
}): URL

Example

// create a deep link to the current page + viewport
navigator.clipboard.writeText(editor.createDeepLink())

You can link to a particular set of shapes by providing a to parameter.

// create a deep link to the set of currently selected shapes
navigator.clipboard.writeText(
  editor.createDeepLink({
    to: { type: 'selection', shapeIds: editor.getSelectedShapeIds() },
  })
)

The default query param is 'd'. You can override this by providing a param parameter.

// Use `x` as the param name instead
editor.createDeepLink({ param: 'x' })

Parameters

NameDescription

opts

{
  param?: string
  to?: TLDeepLink
  url?: string | URL
}

Options for adding the state to the URL.

Returns

URL

the updated URL

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: { richText: toRichText('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: { richText: toRichText('ok') } },
])

Parameters

NameDescription

shapes

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

The shapes (or shape partials) to create.

Returns

this

createTemporaryAssetPreview()

Register a temporary preview of an asset. This is useful for showing a ghost image of something that is being uploaded. Retrieve the placeholder with Editor.getTemporaryAssetPreview. Placeholders last for 3 minutes by default, but this can be configured using

createTemporaryAssetPreview(
  assetId: TLAssetId,
  file: File
): string | undefined

Example

editor.createTemporaryAssetPreview(assetId, file)

Parameters

NameDescription

assetId

TLAssetId

The asset's id.

file

File

The raw file.

Returns

string | undefined

deleteAssets()

Delete one or more assets.

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

Example

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

Parameters

NameDescription

assets

TLAsset[] | TLAssetId[]

The assets (or asset ids) to delete.

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

Deprecated: Use editor.menus.deleteOpenMenu instead.

deleteOpenMenu(id: string): this

Parameters

NameDescription

id

string

Returns

this

deletePage()

Delete a page.

deletePage(page: TLPage | TLPageId): this

Example

editor.deletePage('page1')

Parameters

NameDescription

page

TLPage | TLPageId

The page (or the page id) to delete.

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

dispatch()

Dispatch an event to the editor.

dispatch(info: TLEventInfo): this

Example

editor.dispatch(myPointerEvent)

Parameters

NameDescription

info

TLEventInfo

The event info.

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

The page (or the page id) to duplicate. Defaults to the current page.

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

The predicate to match.

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<T extends TLAsset>(asset: T | T['id']): T | undefined

Example

editor.getAsset('asset1')

Parameters

NameDescription

asset

T | T['id']

The asset (or asset id) to get.

Returns

T | 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

getEditingShapeTipTapTextEditor()

The current editing shape's text editor.

getEditingShapeTipTapTextEditor(): null | TextEditor

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

The parent (or the id) of the parent.

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

Deprecated: Use editor.menus.hasAnyOpenMenus instead.

getIsMenuOpen(): boolean

getIsReadonly()

getIsReadonly(): boolean

getOnlySelectedShape()

The app's only selected shape.

getOnlySelectedShape(): null | TLShape

getOnlySelectedShapeId()

The id of the app's only selected shape.

getOnlySelectedShapeId(): null | TLShapeId

getOpenMenus()

Deprecated: Use editor.menus.getOpenMenus instead.

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 the 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 the page id) to get the shape ids for.

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(): TLRenderingShape[]

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

getSelectionRotatedViewportBounds()

The bounds of the selection bounding box in the current page space. Updated to include the page's zoom level.

getSelectionRotatedViewportBounds(): Box

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

The shape (or the id of the shape) to get.

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

The accumulator.

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

The shape (or the shape id) of the shape to get the mask for.

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
}

The options for the hit point testing.

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

The parent (or the id) of the parent shape.

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

Deprecated: Use Editor.getSvgString or Editor.getSvgElement instead.

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

Parameters

NameDescription

shapes

TLShape[] | TLShapeId[]

opts

TLImageExportOptions

Returns

Promise<SVGSVGElement | undefined>

getSvgElement()

Get an exported SVG element of the given shapes.

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

Parameters

NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to export.

opts

TLImageExportOptions

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?: TLImageExportOptions
): Promise<
  | {
      height: number
      svg: string
      width: number
    }
  | undefined
>

Parameters

NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to export.

opts

TLImageExportOptions

Options for the export.

Returns

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

The SVG element.

getTemporaryAssetPreview()

Get temporary preview of an asset. This is useful for showing a ghost image of something that is being uploaded.

getTemporaryAssetPreview(assetId: TLAssetId): string | undefined

Example

editor.getTemporaryAssetPreview('someId')

Parameters

NameDescription

assetId

TLAssetId

The asset's id.

Returns

string | undefined

getTextOptions()

Get the current text options.

getTextOptions(): TLTextOptions

Example

editor.getTextOptions()

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[],
  opts?: 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.

opts

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

hasExternalAssetHandler()

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

Parameters

NameDescription

type

TLExternalAssetContent['type']

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

The shape (or shape id) of the shape to check.

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
}

The options for the hit point testing.

Returns

boolean

isShapeHidden()

isShapeHidden(shapeOrId: TLShape | TLShapeId): boolean

Parameters

NameDescription

shapeOrId

TLShape | TLShapeId

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,
  opts?: TLLoadSnapshotOptions
): this

Parameters

NameDescription

snapshot

Partial<TLEditorSnapshot> | TLStoreSnapshot

The snapshot to load.

opts

TLLoadSnapshotOptions

The options for loading the snapshot.

Returns

this

mark()

Deprecated: use Editor.markHistoryStoppingPoint instead

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

markHistoryStoppingPoint()

Create a new "mark", or stopping point, in the undo redo history. Creating a mark will clear any redos. You typically want to do this just before a user interaction begins or is handled.

markHistoryStoppingPoint(name?: string): string

Example

editor.markHistoryStoppingPoint()
editor.flipShapes(editor.getSelectedShapes())
const beginRotateMark = editor.markHistoryStoppingPoint()
// if the use cancels the rotation, you can bail back to this mark
editor.bailToMark(beginRotateMark)

Parameters

NameDescription

name

string

The name of the mark, useful for debugging the undo/redo stacks

Returns

string

a unique id for the mark that can be used with squashToMark or bailToMark.

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

Handles navigating to the content specified by the query param in the given URL.

Use to create a URL with a deep link query param.

If no URL is provided, it will look for the param in the current window.location.href.

navigateToDeepLink(
  opts?:
    | {
        param?: string
        url?: string | URL
      }
    | TLDeepLink
): Editor

Example

editor.navigateToDeepLink()

The default parameter name is 'd'. You can override this by providing the param option.

// disable page parameter and change viewport parameter to 'c'
editor.navigateToDeepLink({
  param: 'x',
  url: 'https://my-app.com/my-document?x=200.12.454.23.xyz123',
})

Parameters

NameDescription

opts

  | {
      param?: string
      url?: string | URL
    }
  | TLDeepLink

Options for loading the state from the URL.

Returns

Editor

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

The offset to apply to the shapes.

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,
  opts?: {
    point?: VecLike
    preserveIds?: boolean
    preservePosition?: boolean
    select?: boolean
  }
): this

Parameters

NameDescription

content

TLContent

The content.

opts

{
  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<E>(info: TLExternalContent<E>): Promise<void>

Parameters

NameDescription

info

TLExternalContent<E>

Info about the external content.

Returns

Promise<void>

redo()

Redo to the next mark.

redo(): this

Example

editor.redo()

registerDeepLinkListener()

Register a listener for changes to a deep link for the current document.

You'll typically want to use this indirectly via the TldrawEditorBaseProps.deepLinks prop on the <Tldraw /> component.

By default this will update window.location in place, but you can provide a custom callback to handle state changes on your own.

registerDeepLinkListener(opts?: TLDeepLinkOptions): () => void

Example

editor.registerDeepLinkListener({
  onChange(url) {
    window.history.replaceState({}, document.title, url.toString())
  },
})

You can also provide a custom URL to update, in which case you must also provide onChange.

editor.registerDeepLinkListener({
  getUrl: () => `https://my-app.com/my-document`,
  onChange(url) {
    setShareUrl(url.toString())
  },
})

By default this will update with a debounce interval of 500ms, but you can provide a custom interval.

editor.registerDeepLinkListener({ debounceMs: 1000 })

The default parameter name is d. You can override this by providing a param option.

editor.registerDeepLinkListener({ param: 'x' })

Parameters

NameDescription

opts

TLDeepLinkOptions

Options for setting up the listener.

Returns

() => void

a function that will stop the listener.

registerExternalAssetHandler()

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

Example

editor.registerExternalAssetHandler('file', 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<E>['type'], E>(
  type: T,
  handler:
    | ((
        info: T extends TLExternalContent<E>['type']
          ? TLExternalContent<E> & {
              type: T
            }
          : TLExternalContent<E>
      ) => void)
    | null
): this

Example

editor.registerExternalContentHandler('text', myHandler)
editor.registerExternalContentHandler<'embed', MyEmbedType>('embed', myHandler)

Parameters

NameDescription

type

T

The type of external content.

handler

  | ((
      info: T extends TLExternalContent<E>['type']
        ? TLExternalContent<E> & {
            type: T
          }
        : TLExternalContent<E>
    ) => 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

The page (or the page id) to rename.

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,
  opts?: TLResizeShapeOptions
): this

Parameters

NameDescription

shape

TLShape | TLShapeId

The shape (or the shape id of the shape) to resize.

scale

VecLike

The scale factor to apply to the shape.

opts

TLResizeShapeOptions

Additional options.

Returns

this

resolveAssetsInContent()

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

Parameters

NameDescription

content

TLContent | undefined

Returns

Promise<TLContent | undefined>

resolveAssetUrl()

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

Parameters

NameDescription

assetId

null | TLAssetId

context

{
  screenScale?: number
  shouldResolveToOriginal?: boolean
}

Returns

Promise<null | string>

rotateShapesBy()

Rotate shapes by a delta in radians.

rotateShapesBy(
  shapes: TLShape[] | TLShapeId[],
  delta: number,
  opts?: {
    center?: VecLike
  }
): 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.

opts

{
  center?: VecLike
}

The options for the rotation.

Returns

this

run()

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

Example

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

Parameters

NameDescription

fn

() => void

The callback function to run.

opts

TLEditorRunOptions

The options for the batch.

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

The shape (or the shape ids) to select.

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[],
  opts?: {
    considerAllShapes?: boolean
  }
): this

Example

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

By default, the operation will only consider overlapping shapes. To consider all shapes, pass { considerAllShapes: true } in the options.

editor.sendBackward(['id1', 'id2'], { considerAllShapes: true })

Parameters

NameDescription

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

opts

{
  considerAllShapes?: boolean
}

The options for the backward operation.

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(opts: Partial<TLCameraOptions>): this

Example

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

Parameters

NameDescription

opts

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 the 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

setCursor()

Set the cursor.

setCursor(cursor: Partial<TLCursor>): this

Parameters

NameDescription

cursor

Partial<TLCursor>

The cursor to set.

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

setEditingShapeTipTapTextEditor()

Set the current editing shape's text editor.

setEditingShapeTipTapTextEditor(textEditor: null | TextEditor): void

Example

editor.setEditingShapeTipTapTextEditor(richTextEditorView)

Parameters

NameDescription

textEditor

null | TextEditor

The text editor to set as the current editing shape's text editor.

Returns

void

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

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

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

The shape (or shape ids) to select.

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
  force?: boolean | undefined
  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
  force?: boolean | undefined
  friction?: number | undefined
  speed: number
  speedThreshold?: number | undefined
}

Options for the slide

Returns

this

squashToMark()

Coalesces all changes since the given mark into a single change, removing any intermediate marks.

This is useful if you need to 'compress' the recent history to simplify the undo/redo experience of a complex interaction.

squashToMark(markId: string): this

Example

const bumpShapesMark = editor.markHistoryStoppingPoint()
// ... some changes
editor.squashToMark(bumpShapesMark)

Parameters

NameDescription

markId

string

The mark id to squash to.

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[],
  opts?: Partial<{
    select: boolean
  }>
): this

Example

editor.ungroupShapes([myGroup, myOtherGroup])
editor.ungroupShapes([myGroup], { select: false })

Parameters

NameDescription

ids

TLShapeId[]

opts

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'
    >
  >
): this

Example

editor.updateCurrentPageState({ id: 'page1', editingShapeId: 'shape:123' })

Parameters

NameDescription

partial

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

The partial of the page state object containing the changes.

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

History batch options.

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 | HTMLElement,
  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 | HTMLElement

The new screen bounds of the viewport.

center

boolean

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

Returns

this

uploadAsset()

Upload an asset to the store's asset service, returning a URL that can be used to resolve the asset.

uploadAsset(
  asset: TLAsset,
  file: File,
  abortSignal?: AbortSignal
): Promise<string>

Parameters

NameDescription

asset

TLAsset

file

File

abortSignal

AbortSignal

Returns

Promise<string>

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

The parent (or the id) of the parent shape.

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

The camera move options.

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
Prev
EdgeScrollManager
Next
Ellipse2d