Table of contents

Public class

Signature
class Editor extends EventEmitter<TLEventMap> {}
References

TLEventMap

Source

packages/editor/src/lib/editor/Editor.ts


Constructor

Public constructor

Constructs a new instance of the Editor class

Parameters
NameDescription

{ store, user, shapeUtils, tools, getContainer, initialState, inferDarkMode, }

TLEditorOptions
References

TLEditorOptions


Properties

dispatch

Public property

Dispatch an event to the editor.

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

info

The event info.

References

TLEventInfo


disposables

Public readonly property

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

Signature
readonly disposables: Set<() => void>

environment

Public readonly property

A manager for the editor's environment.

Signature
readonly environment: EnvironmentManager

getContainer

Public property

The current HTML element containing the editor.

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

history

Public readonly property

A manager for the app's history.

Signature
readonly history: HistoryManager<this>

inputs

Public property

The app's current input state.

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

Vec


renderingBoundsMargin

Public property

The distance to expand the viewport when measuring culling. A larger distance will mean that shapes near to the viewport (but still outside of it) will not be culled.

Signature
renderingBoundsMargin: number

root

Public readonly property

The root state of the statechart.

Signature
readonly root: RootState

scribbles

Public readonly property

A manager for the editor's scribbles.

Signature
readonly scribbles: ScribbleManager

setCursor

Public property

Set the cursor.

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

type

The cursor type.

rotation

The cursor rotation.

References

TLCursor


shapeUtils

Public property

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

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

ShapeUtil, TLUnknownShape


sideEffects

Public readonly property

A manager for side effects and correct state enforcement.

Signature
readonly sideEffects: SideEffectManager<this>

snaps

Public readonly property

A manager for the app's snapping feature.

Signature
readonly snaps: SnapManager
References

SnapManager


store

Public readonly property

The editor's store

Signature
readonly store: TLStore
References

TLStore


styleProps

Public property

Signature
styleProps: {
  [key: string]: Map<StyleProp<unknown>, string>
}
References

StyleProp


textMeasure

Public readonly property

A helper for measuring text.

Signature
readonly textMeasure: TextManager

user

Public readonly property

A manager for the user and their preferences.

Signature
readonly user: UserPreferencesManager

Methods

addOpenMenu()

Public method

Add an open menu.

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

id

string
Returns
this

alignShapes()

Public method

Align shape positions.

Example
editor.alignShapes([box1, box2], 'left')
editor.alignShapes(editor.getSelectedShapeIds(), 'left')
Signature
alignShapes(
  shapes: TLShape[] | TLShapeId[],
  operation:
    | 'bottom'
    | 'center-horizontal'
    | 'center-vertical'
    | 'left'
    | 'right'
    | 'top'
): this
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
References

TLShape, TLShapeId


animateShape()

Public method

Animate a shape.

Example
editor.animateShape({ id: 'box1', type: 'box', x: 100, y: 100 })
editor.animateShape(
  { id: 'box1', type: 'box', x: 100, y: 100 },
  { duration: 100, ease: (t) => t * t }
)
Signature
animateShape(
  partial: null | TLShapePartial | undefined,
  animationOptions?: TLAnimationOptions
): this
Parameters
NameDescription

partial

null | TLShapePartial | undefined

The shape partial to update.

animationOptions

TLAnimationOptions
Returns
this
References

TLShapePartial, TLAnimationOptions


animateShapes()

Public method

Animate shapes.

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

partials

(null | TLShapePartial | undefined)[]

The shape partials to update.

animationOptions

Partial<{
  duration: number
  easing: (t: number) => number
}>
Returns
this
References

TLShapePartial


animateToShape()

Public method

Animate the camera to a shape.

Signature
animateToShape(shapeId: TLShapeId, opts?: TLAnimationOptions): this
Parameters
NameDescription

shapeId

TLShapeId

opts

TLAnimationOptions
Returns
this
References

TLShapeId, TLAnimationOptions


animateToUser()

Public method

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

Signature
animateToUser(userId: string): this
Parameters
NameDescription

userId

string

The id of the user to aniamte to.

Returns
this

bail()

Public method

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

Example
editor.bail()
Signature
bail(): this

bailToMark()

Public method

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

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

id

string
Returns
this

batch()

Public method

Run a function in a batch, which will be undone/redone as a single action.

Example
editor.batch(() => {
  editor.selectAll()
  editor.deleteShapes(editor.getSelectedShapeIds())
  editor.createShapes(myShapes)
  editor.selectNone()
})

editor.undo() // will undo all of the above
Signature
batch(fn: () => void): this
Parameters
NameDescription

fn

() => void
Returns
this

bringForward()

Public method

Bring shapes forward in the page's object list.

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this
References

TLShape, TLShapeId


bringToFront()

Public method

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

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this
References

TLShape, TLShapeId


cancel()

Public method

Dispatch a cancel event.

Example
editor.cancel()
Signature
cancel(): this

cancelDoubleClick()

Public method

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

Signature
cancelDoubleClick(): void

centerOnPoint()

Public method

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

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

point

VecLike

The point in the current page space to center on.

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

VecLike, TLAnimationOptions


clearOpenMenus()

Public method

Clear all open menus.

Example
editor.clearOpenMenus()
Signature
clearOpenMenus(): this

complete()

Public method

Dispatch a complete event.

Example
editor.complete()
Signature
complete(): this

createAssets()

Public method

Create one or more assets.

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

assets

TLAsset[]

The assets to create.

Returns
this
References

TLAsset


createPage()

Public method

Create a page.

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

page

Partial<TLPage>

The page (or page partial) to create.

Returns
this
References

TLPage


createShape()

Public method

Create a single shape.

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

shape

OptionalKeys<TLShapePartial<T>, 'id'>

The shape (or shape partial) to create.

Returns
this
References

TLUnknownShape, TLShapePartial


createShapes()

Public method

Create shapes.

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

shapes

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

The shapes (or shape partials) to create.

Returns
this
References

TLUnknownShape, TLShapePartial


deleteAssets()

Public method

Delete one or more assets.

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

assets

TLAsset[] | TLAssetId[]
Returns
this
References

TLAsset, TLAssetId


deleteOpenMenu()

Public method

Delete an open menu.

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

id

string
Returns
this

deletePage()

Public method

Delete a page.

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

page

TLPage | TLPageId
Returns
this
References

TLPage, TLPageId


deleteShape()

Public method

Delete a shape.

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

id

TLShapeId

The id of the shape to delete.

Returns
this
References

TLShapeId


deleteShape()

Public method

Signature
deleteShape(shape: TLShape): this
Parameters
NameDescription

shape

TLShape
Returns
this
References

TLShape


deleteShapes()

Public method

Delete shapes.

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

ids

TLShapeId[]

The ids of the shapes to delete.

Returns
this
References

TLShapeId


deleteShapes()

Public method

Signature
deleteShapes(shapes: TLShape[]): this
Parameters
NameDescription

shapes

TLShape[]
Returns
this
References

TLShape


deselect()

Public method

Remove a shape from the existing set of selected shapes.

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

shapes

TLShape[] | TLShapeId[]
Returns
this
References

TLShape, TLShapeId


dispose()

Public method

Dispose the editor.

Signature
dispose(): void

distributeShapes()

Public method

Distribute shape positions.

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to distribute.

operation

'horizontal' | 'vertical'

Whether to distribute shapes horizontally or vertically.

Returns
this
References

TLShape, TLShapeId


duplicatePage()

Public method

Duplicate a page.

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

page

TLPage | TLPageId

createId

TLPageId

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

Returns
this
References

TLPage, TLPageId


duplicateShapes()

Public method

Duplicate shapes.

Example
editor.duplicateShapes(['box1', 'box2'], { x: 8, y: 8 })
editor.duplicateShapes(editor.getSelectedShapes(), { x: 8, y: 8 })
Signature
duplicateShapes(shapes: TLShape[] | TLShapeId[], offset?: VecLike): this
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
References

TLShape, TLShapeId, VecLike


findCommonAncestor()

Public method

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

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

TLShape, TLShapeId


findShapeAncestor()

Public method

Find the first ancestor matching the given predicate

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

shape

TLShape | TLShapeId

The shape to check the ancestors for.

predicate

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

TLShape, TLShapeId


flipShapes()

Public method

Flip shape positions.

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

shapes

TLShape[] | TLShapeId[]

The ids of the shapes to flip.

operation

'horizontal' | 'vertical'

Whether to flip horizontally or vertically.

Returns
this
References

TLShape, TLShapeId


getAncestorPageId()

Public method

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

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

References

TLShape, TLShapeId, TLPageId


getArrowInfo()

Public method

Get cached info about an arrow.

Example
const arrowInfo = editor.getArrowInfo(myArrow)
Signature
getArrowInfo(shape: TLArrowShape | TLShapeId): TLArrowInfo | undefined
Parameters
NameDescription

shape

TLArrowShape | TLShapeId

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

Returns
TLArrowInfo | undefined
References

TLArrowShape, TLShapeId, TLArrowInfo


getArrowsBoundTo()

Public method

Get all arrows bound to a shape.

Signature
getArrowsBoundTo(shapeId: TLShapeId): {
  arrowId: TLShapeId
  handleId: 'end' | 'start'
}[]
Parameters
NameDescription

shapeId

TLShapeId

The id of the shape.

Returns
{
  arrowId: TLShapeId
  handleId: 'end' | 'start'
}[]
References

TLShapeId


getAsset()

Public method

Get an asset by its id.

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

asset

TLAsset | TLAssetId

The asset (or asset id) to get.

Returns
TLAsset | undefined
References

TLAsset, TLAssetId


getAssetForExternalContent()

Public method

Get an asset for an external asset content type.

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

info

TLExternalAssetContent

Info about the external content.

Returns
Promise<TLAsset | undefined>

The asset.

References

TLExternalAssetContent, TLAsset


getAssets()

Public method

Get all assets in the editor.

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

TLBookmarkAsset, TLImageAsset, TLVideoAsset


getCamera()

Public method

The current camera.

Signature
getCamera(): import('@tldraw/tlschema').TLCamera
References

TLCamera


getCameraState()

Public method

Whether the camera is moving or idle.

Signature
getCameraState(): 'idle' | 'moving'

getCanRedo()

Public method

Whether the app can redo.

Signature
getCanRedo(): boolean

getCanUndo()

Public method

Whether the app can undo.

Signature
getCanUndo(): boolean

getContentFromCurrentPage()

Public method

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

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

References

TLShape, TLShapeId, TLContent


getCroppingShapeId()

Public method

The current cropping shape's id.

Signature
getCroppingShapeId(): null | TLShapeId
References

TLShapeId


getCurrentPage()

Public method

The current page.

Signature
getCurrentPage(): TLPage
References

TLPage


getCurrentPageBounds()

Public method

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

Signature
getCurrentPageBounds(): Box | undefined
References

Box


getCurrentPageId()

Public method

The current page id.

Signature
getCurrentPageId(): TLPageId
References

TLPageId


getCurrentPageRenderingShapesSorted()

Public method

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.

Signature
getCurrentPageRenderingShapesSorted(): TLShape[]
References

TLShape


getCurrentPageShapeIds()

Public method

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

Signature
getCurrentPageShapeIds(): Set<TLShapeId>
References

TLShapeId


getCurrentPageShapes()

Public method

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

Signature
getCurrentPageShapes(): TLShape[]
References

TLShape


getCurrentPageShapesSorted()

Public method

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.

Signature
getCurrentPageShapesSorted(): TLShape[]
References

TLShape


getCurrentPageState()

Public method

The current page state.

Signature
getCurrentPageState(): TLInstancePageState
References

TLInstancePageState


getCurrentTool()

Public method

The current selected tool.

Signature
getCurrentTool(): StateNode
References

StateNode


getCurrentToolId()

Public method

The id of the current selected tool.

Signature
getCurrentToolId(): string

getDocumentSettings()

Public method

The global document settings that apply to all users.

Signature
getDocumentSettings(): TLDocument
References

TLDocument


getDroppingOverShape()

Public method

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

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

References

VecLike, TLShape, TLUnknownShape


getEditingShape()

Public method

The current editing shape.

Signature
getEditingShape(): TLShape | undefined
References

TLShape


getEditingShapeId()

Public method

The current editing shape's id.

Signature
getEditingShapeId(): null | TLShapeId
References

TLShapeId


getErasingShapeIds()

Public method

The editor's current erasing ids.

Signature
getErasingShapeIds(): TLShapeId[]
References

TLShapeId


getErasingShapes()

Public method

The editor's current erasing shapes.

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

TLShape


getFocusedGroup()

Public method

The current focused group.

Signature
getFocusedGroup(): TLShape | undefined
References

TLShape


getFocusedGroupId()

Public method

The current focused group id.

Signature
getFocusedGroupId(): TLPageId | TLShapeId
References

TLPageId, TLShapeId


getHighestIndexForParent()

Public method

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

Signature
getHighestIndexForParent(parent: TLPage | TLParentId | TLShape): string
Parameters
NameDescription

parent

TLPage | TLParentId | TLShape
Returns
string

The index.

References

TLPage, TLParentId, TLShape


getHintingShape()

Public method

The editor's current hinting shapes.

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

TLShape


getHintingShapeIds()

Public method

The editor's current hinting shape ids.

Signature
getHintingShapeIds(): TLShapeId[]
References

TLShapeId


getHoveredShape()

Public method

The current hovered shape.

Signature
getHoveredShape(): TLShape | undefined
References

TLShape


getHoveredShapeId()

Public method

The current hovered shape id.

Signature
getHoveredShapeId(): null | TLShapeId
References

TLShapeId


getInitialMetaForShape()

Public method

Get the initial meta value for a shape.

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

_shape

TLShape
Returns
JsonObject
References

TLShape


getInstanceState()

Public method

The current instance's state.

Signature
getInstanceState(): TLInstance
References

TLInstance


getIsMenuOpen()

Public method

Get whether any menus are open.

Example
editor.isMenuOpen()
Signature
getIsMenuOpen(): boolean

getOnlySelectedShape()

Public method

The app's only selected shape.

Signature
getOnlySelectedShape(): null | TLShape
References

TLShape


getOpenMenus()

Public method

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

Signature
getOpenMenus(): string[]

getOutermostSelectableShape()

Public method

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.

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

References

TLShape, TLShapeId


getPage()

Public method

Get a page.

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

page

TLPage | TLPageId

The page (or page id) to get.

Returns
TLPage | undefined
References

TLPage, TLPageId


getPages()

Public method

Info about the project's current pages.

Signature
getPages(): TLPage[]
References

TLPage


getPageShapeIds()

Public method

Get the ids of shapes on a page.

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

page

TLPage | TLPageId

The page (or page id) to get.

Returns
Set<TLShapeId>
References

TLPage, TLPageId, TLShapeId


getPageStates()

Public method

Page states.

Signature
getPageStates(): TLInstancePageState[]
References

TLInstancePageState


getPath()

Public method

The editor's current path of active states.

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

getPointInParentSpace()

Public method

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

Example
editor.getPointInParentSpace(myShape.id, { x: 100, y: 100 })
Signature
getPointInParentSpace(shape: TLShape | TLShapeId, point: VecLike): Vec
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
References

TLShape, TLShapeId, VecLike, Vec


getPointInShapeSpace()

Public method

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.

Example
editor.getPointInShapeSpace(myShape, { x: 100, y: 100 })
Signature
getPointInShapeSpace(shape: TLShape | TLShapeId, point: VecLike): Vec
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
References

TLShape, TLShapeId, VecLike, Vec


getRenderingBounds()

Public method

The current rendering bounds in the current page space, used for checking which shapes are "on screen".

Signature
getRenderingBounds(): Box
References

Box


getRenderingBoundsExpanded()

Public method

The current rendering bounds in the current page space, expanded slightly. Used for determining which shapes to render and which to "cull".

Signature
getRenderingBoundsExpanded(): Box
References

Box


getRenderingShapes()

Public method

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

Signature
getRenderingShapes(): {
  id: TLShapeId
  shape: TLShape
  util: ShapeUtil<TLUnknownShape>
  index: number
  backgroundIndex: number
  opacity: number
  isCulled: boolean
  maskedPageBounds: Box | undefined
}[]
References

TLShapeId, TLShape, ShapeUtil, TLUnknownShape, Box


getSelectedShapeAtPoint()

Public method

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

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

References

VecLike, TLShape


getSelectedShapeIds()

Public method

The current selected ids.

Signature
getSelectedShapeIds(): TLShapeId[]
References

TLShapeId


getSelectedShapes()

Public method

An array containing all of the currently selected shapes.

Signature
getSelectedShapes(): TLShape[]
References

TLShape


getSelectionPageBounds()

Public method

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.

Signature
getSelectionPageBounds(): Box | null
References

Box


getSelectionRotatedPageBounds()

Public method

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

Signature
getSelectionRotatedPageBounds(): Box | undefined
References

Box


getSelectionRotation()

Public method

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

Signature
getSelectionRotation(): number

getShape()

Public method

Get a shape by its id.

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

shape

TLParentId | TLShape
Returns
T | undefined
References

TLShape, TLParentId


getShapeAncestors()

Public method

Get the ancestors of a shape.

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

shape

TLShape | TLShapeId

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

acc

TLShape[]
Returns
TLShape[]
References

TLShape, TLShapeId


getShapeAndDescendantIds()

Public method

Get the shape ids of all descendants of the given shapes (including the shapes themselves).

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

ids

TLShapeId[]

The ids of the shapes to get descendants of.

Returns
Set<TLShapeId>

The decscendant ids.

References

TLShapeId


getShapeAtPoint()

Public method

Get the shape at the current point.

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

point

VecLike

The point to check.

opts

{
  renderingOnly?: boolean | undefined
  margin?: number | undefined
  hitInside?: boolean | undefined
  hitLabels?: boolean | undefined
  hitFrameInside?: boolean | undefined
  filter?: ((shape: TLShape) => 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.

References

VecLike, TLShape


getShapeClipPath()

Public method

Get the clip path for a shape.

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

shape

TLShape | TLShapeId

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

Returns
string | undefined

The clip path or undefined.

References

TLShape, TLShapeId


getShapeGeometry()

Public method

Get the geometry of a shape.

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

shape

TLShape | TLShapeId

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

Returns
T
References

Geometry2d, TLShape, TLShapeId


getShapeHandles()

Public method

Get the handles (if any) for a shape.

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

shape

T | T['id']

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

Returns
TLHandle[] | undefined
References

TLShape, TLHandle


getShapeLocalTransform()

Public method

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.

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

shape

TLShape | TLShapeId

The shape to get the local transform for.

Returns
Mat
References

TLShape, TLShapeId, Mat


getShapeMask()

Public method

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

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

shape

TLShape | TLShapeId
Returns
undefined | VecLike[]

The mask for the shape.

References

TLShape, TLShapeId, VecLike


getShapeMaskedPageBounds()

Public method

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.

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

shape

TLShape | TLShapeId

The shape to get the masked bounds for.

Returns
Box | undefined
References

TLShape, TLShapeId, Box


getShapeOutlineSegments()

Public method

Get the local outline segments of a shape.

Example
editor.getShapeOutlineSegments(myShape)
editor.getShapeOutlineSegments(myShapeId)
Signature
getShapeOutlineSegments<T extends TLShape>(shape: T | T['id']): Vec[][]
Parameters
NameDescription

shape

T | T['id']

The shape (or shape id) to get the outline segments for.

Returns
Vec[][]
References

TLShape, Vec


getShapePageBounds()

Public method

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

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

shape

TLShape | TLShapeId

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

Returns
Box | undefined
References

TLShape, TLShapeId, Box


getShapePageTransform()

Public method

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

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

shape

TLShape | TLShapeId

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

Returns
Mat
References

TLShape, TLShapeId, Mat


getShapeParent()

Public method

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

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

shape

TLShape | TLShapeId
Returns
TLShape | undefined
References

TLShape, TLShapeId


getShapeParentTransform()

Public method

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

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

shape

TLShape | TLShapeId

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

Returns
Mat
References

TLShape, TLShapeId, Mat


getShapesAtPoint()

Public method

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

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

point

VecLike

The page point to test.

opts

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

VecLike, TLShape


getShapeStyleIfExists()

Public method

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

shape

TLShape

style

StyleProp<T>
Returns
T | undefined
References

TLShape, StyleProp


getShapeUtil()

Public method

Get a shape util from a shape itself.

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

shape

S | TLShapePartial<S>

A shape, shape partial, or shape type.

Returns
ShapeUtil<S>
References

TLUnknownShape, TLShapePartial, ShapeUtil


getShapeUtil()

Public method

Signature
getShapeUtil<S extends TLUnknownShape>(type: S['type']): ShapeUtil<S>
Parameters
NameDescription

type

S['type']
Returns
ShapeUtil<S>
References

TLUnknownShape, ShapeUtil


getShapeUtil()

Public method

Signature
getShapeUtil<T extends ShapeUtil>(
  type: T extends ShapeUtil<infer R> ? R['type'] : string
): T
Parameters
NameDescription

type

T extends ShapeUtil<infer R>
  ? R['type']
  : string
Returns
T
References

ShapeUtil


getSharedOpacity()

Public method

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.

Signature
getSharedOpacity(): SharedStyle<number>
References

SharedStyle


getSharedStyles()

Public method

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

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

ReadonlySharedStyleMap


getSortedChildIdsForParent()

Public method

Get an array of all the children of a shape.

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

parent

TLPage | TLParentId | TLShape
Returns
TLShapeId[]
References

TLPage, TLParentId, TLShape, TLShapeId


getStateDescendant()

Public method

Get a descendant by its path.

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

path

string

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

Returns
T | undefined
References

StateNode


getSvg()

Public method

Get an exported SVG of the given shapes.

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

shapes

TLShape[] | TLShapeId[]

opts

Partial<TLSvgOptions>

Options for the export.

Returns
Promise<SVGSVGElement | undefined>

The SVG element.

References

TLShape, TLShapeId, TLSvgOptions


getViewportPageBounds()

Public method

The current viewport in the current page space.

Signature
getViewportPageBounds(): Box
References

Box


getViewportPageCenter()

Public method

The center of the viewport in the current page space.

Signature
getViewportPageCenter(): Vec
References

Vec


getViewportScreenBounds()

Public method

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

Signature
getViewportScreenBounds(): Box
References

Box


getViewportScreenCenter()

Public method

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

Signature
getViewportScreenCenter(): Vec
References

Vec


getZoomLevel()

Public method

The current camera zoom level.

Signature
getZoomLevel(): number

groupShapes()

Public method

Create a group containing the provided shapes.

Signature
groupShapes(shapes: TLShape[] | TLShapeId[], groupId?: TLShapeId): this
Parameters
NameDescription

shapes

TLShape[] | TLShapeId[]

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

groupId

TLShapeId

The id of the group to create.

Returns
this
References

TLShape, TLShapeId


hasAncestor()

Public method

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

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

TLShape, TLShapeId


interrupt()

Public method

Dispatch an interrupt event.

Example
editor.interrupt()
Signature
interrupt(): this

isAncestorSelected()

Public method

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

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

shape

TLShape | TLShapeId
Returns
boolean
References

TLShape, TLShapeId


isIn()

Public method

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

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

path

string

The path of active states, separated by periods.

Returns
boolean

isInAny()

Public method

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

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

paths

string[]
Returns
boolean

isPointInShape()

Public method

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.

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

shape

TLShape | TLShapeId

The shape to test against.

point

VecLike

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

opts

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

TLShape, TLShapeId, VecLike


isShapeInPage()

Public method

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

Example
editor.isShapeInPage(myShape)
editor.isShapeInPage(myShape, 'page1')
Signature
isShapeInPage(shape: TLShape | TLShapeId, pageId?: TLPageId): boolean
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
References

TLShape, TLShapeId, TLPageId


isShapeOfType()

Public method

Get whether a shape matches the type of a TLShapeUtil.

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

shape

TLUnknownShape

the shape to test

type

T['type']
Returns
shape is T
References

TLUnknownShape


isShapeOfType()

Public method

Signature
isShapeOfType<T extends TLUnknownShape>(
  shapeId: TLUnknownShape['id'],
  type: T['type']
): shapeId is T['id']
Parameters
NameDescription

shapeId

TLUnknownShape['id']

type

T['type']
Returns
shapeId is T['id']
References

TLUnknownShape


isShapeOrAncestorLocked()

Public method

Check whether a shape or its parent is locked.

Signature
isShapeOrAncestorLocked(shape?: TLShape): boolean
Parameters
NameDescription

shape

TLShape

The shape (or shape id) to check.

Returns
boolean
References

TLShape


isShapeOrAncestorLocked()

Public method

Signature
isShapeOrAncestorLocked(id?: TLShapeId): boolean
Parameters
NameDescription

id

TLShapeId
Returns
boolean
References

TLShapeId


mark()

Public method

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

Example
editor.mark()
editor.mark('flip shapes')
Signature
mark(markId?: string, onUndo?: boolean, onRedo?: boolean): this
Parameters
NameDescription

markId

string

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

onUndo

boolean

Whether to stop at the mark when undoing.

onRedo

boolean

Whether to stop at the mark when redoing.

Returns
this

moveShapesToPage()

Public method

Move shapes to page.

Example
editor.moveShapesToPage(['box1', 'box2'], 'page1')
Signature
moveShapesToPage(shapes: TLShape[] | TLShapeId[], pageId: TLPageId): this
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
References

TLShape, TLShapeId, TLPageId


nudgeShapes()

Public method

Move shapes by a delta.

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

offset

VecLike

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLShape, TLShapeId, VecLike, TLCommandHistoryOptions


packShapes()

Public method

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

Example
editor.packShapes([box1, box2], 32)
editor.packShapes(editor.getSelectedShapeIds(), 32)
Signature
packShapes(shapes: TLShape[] | TLShapeId[], gap: number): this
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
References

TLShape, TLShapeId


pageToScreen()

Public method

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

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

point

VecLike

The point in screen space.

Returns
{
  x: number
  y: number
  z: number
}
References

VecLike


pan()

Public method

Pan the camera.

Example
editor.pan({ x: 100, y: 100 })
editor.pan({ x: 100, y: 100 }, { duration: 1000 })
Signature
pan(offset: VecLike, animation?: TLAnimationOptions): this
Parameters
NameDescription

offset

VecLike

The offset in the current page space.

animation

TLAnimationOptions

The animation options.

Returns
this
References

VecLike, TLAnimationOptions


panZoomIntoView()

Public method

Pan or pan/zoom the selected ids into view. This method tries to not change the zoom if possible.

Signature
panZoomIntoView(ids: TLShapeId[], animation?: TLAnimationOptions): this
Parameters
NameDescription

ids

TLShapeId[]

The ids of the shapes to pan and zoom into view.

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

TLShapeId, TLAnimationOptions


popFocusedGroupId()

Public method

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

Signature
popFocusedGroupId(): this

putContentOntoCurrentPage()

Public method

Place content into the editor.

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

content

TLContent

The content.

options

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

Options for placing the content.

Returns
this
References

TLContent, VecLike


putExternalContent()

Public method

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.

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

info

TLExternalContent

Info about the external content.

Returns
Promise<void>
References

TLExternalContent


redo()

Public method

Redo to the next mark.

Example
editor.redo()
Signature
redo(): this

registerExternalAssetHandler()

Public method

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.

Example
editor.registerExternalAssetHandler('text', myHandler)
Signature
registerExternalAssetHandler<T extends TLExternalAssetContent['type']>(
  type: T,
  handler:
    | ((
        info: TLExternalAssetContent & {
          type: T
        }
      ) => Promise<TLAsset>)
    | null
): this
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
References

TLExternalAssetContent, TLAsset


registerExternalContentHandler()

Public method

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.

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

type

T

The type of external content.

handler

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

The handler to use for this content type.

Returns
this
References

TLExternalContent


renamePage()

Public method

Rename a page.

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

page

TLPage | TLPageId

name

string

The new name.

historyOptions

TLCommandHistoryOptions
Returns
this
References

TLPage, TLPageId, TLCommandHistoryOptions


reparentShapes()

Public method

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

Example
editor.reparentShapes([box1, box2], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1', 4)
Signature
reparentShapes(
  shapes: TLShape[] | TLShapeId[],
  parentId: TLParentId,
  insertIndex?: string
): this
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

string

The index to insert the children.

Returns
this
References

TLShape, TLShapeId, TLParentId


resetZoom()

Public method

Set the zoom back to 100%.

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

point

Vec

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

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

Vec, TLAnimationOptions


resizeShape()

Public method

Resize a shape.

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

shape

TLShape | TLShapeId

scale

VecLike

The scale factor to apply to the shape.

options

TLResizeShapeOptions

Additional options.

Returns
this
References

TLShape, TLShapeId, VecLike, TLResizeShapeOptions


rotateShapesBy()

Public method

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

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

shapes

TLShape[] | TLShapeId[]

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

delta

number

The delta in radians to apply to the selection rotation.

Returns
this
References

TLShape, TLShapeId


screenToPage()

Public method

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

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

point

VecLike

The point in screen space.

Returns
{
  x: number
  y: number
  z: number
}
References

VecLike


select()

Public method

Select one or more shapes.

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

shapes

TLShape[] | TLShapeId[]
Returns
this
References

TLShape, TLShapeId


selectAll()

Public method

Select all direct children of the current page.

Example
editor.selectAll()
Signature
selectAll(): this

selectNone()

Public method

Clear the selection.

Example
editor.selectNone()
Signature
selectNone(): this

sendBackward()

Public method

Send shapes backward in the page's object list.

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this
References

TLShape, TLShapeId


sendToBack()

Public method

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

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to move.

Returns
this
References

TLShape, TLShapeId


setCamera()

Public method

Set the current camera.

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 },
  { duration: 1000, easing: (t) => t * t }
)
Signature
setCamera(point: VecLike, animation?: TLAnimationOptions): this
Parameters
NameDescription

point

VecLike

The new camera position.

animation

TLAnimationOptions

Options for an animation.

Returns
this
References

VecLike, TLAnimationOptions


setCroppingShape()

Public method

Set the current cropping shape.

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

shape

null | TLShape | TLShapeId

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

Returns
this
References

TLShape, TLShapeId


setCurrentPage()

Public method

Set the current page.

Example
editor.setCurrentPage('page1')
editor.setCurrentPage(myPage1)
Signature
setCurrentPage(
  page: TLPage | TLPageId,
  historyOptions?: TLCommandHistoryOptions
): this
Parameters
NameDescription

page

TLPage | TLPageId

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

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLPage, TLPageId, TLCommandHistoryOptions


setCurrentTool()

Public method

Set the selected tool.

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

id

string

The id of the tool to select.

info

{}

Arbitrary data to pass along into the transition.

Returns
this

setEditingShape()

Public method

Set the current editing shape.

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

shape

null | TLShape | TLShapeId

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

Returns
this
References

TLShape, TLShapeId


setErasingShapes()

Public method

Set the editor's current erasing shapes.

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

shapes

TLShape[] | TLShapeId[]

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

Returns
this
References

TLShape, TLShapeId


setFocusedGroup()

Public method

Set the current focused group shape.

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

TLGroupShape, TLShapeId


setHintingShapes()

Public method

Set the editor's current hinting shapes.

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

shapes

TLShape[] | TLShapeId[]

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

Returns
this
References

TLShape, TLShapeId


setHoveredShape()

Public method

Set the editor's current hovered shape.

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

shape

null | TLShape | TLShapeId
Returns
this
References

TLShape, TLShapeId


setOpacityForNextShapes()

Public method

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

Example
editor.setOpacityForNextShapes(0.5)
editor.setOpacityForNextShapes(0.5, { squashing: true })
Signature
setOpacityForNextShapes(
  opacity: number,
  historyOptions?: TLCommandHistoryOptions
): this
Parameters
NameDescription

opacity

number

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

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLCommandHistoryOptions


setOpacityForSelectedShapes()

Public method

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

Example
editor.setOpacityForSelectedShapes(0.5)
editor.setOpacityForSelectedShapes(0.5, { squashing: true })
Signature
setOpacityForSelectedShapes(
  opacity: number,
  historyOptions?: TLCommandHistoryOptions
): this
Parameters
NameDescription

opacity

number

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

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLCommandHistoryOptions


setSelectedShapes()

Public method

Select one or more shapes.

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

shapes

TLShape[] | TLShapeId[]

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLShape, TLShapeId, TLCommandHistoryOptions


setStyleForNextShapes()

Public method

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

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

style

StyleProp<T>

The style to set.

value

T

The value to set.

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

StyleProp, TLCommandHistoryOptions


setStyleForSelectedShapes()

Public method

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

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

style

StyleProp<T>

The style to set.

value

T

The value to set.

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

StyleProp, TLCommandHistoryOptions


slideCamera()

Public method

Slide the camera in a certain direction.

Signature
slideCamera(opts?: {
  speed: number
  direction: VecLike
  friction: number
  speedThreshold?: number | undefined
}): this
Parameters
NameDescription

opts

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

Options for the slide

Returns
this
References

VecLike


stackShapes()

Public method

Stack shape.

Example
editor.stackShapes([box1, box2], 'horizontal', 32)
editor.stackShapes(editor.getSelectedShapeIds(), 'horizontal', 32)
Signature
stackShapes(
  shapes: TLShape[] | TLShapeId[],
  operation: 'horizontal' | 'vertical',
  gap: number
): this
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
References

TLShape, TLShapeId


startFollowingUser()

Public method

Start viewport-following a user.

Signature
startFollowingUser(userId: string): this
Parameters
NameDescription

userId

string

The id of the user to follow.

Returns
this

stopCameraAnimation()

Public method

Stop the current camera animation, if any.

Signature
stopCameraAnimation(): this

stopFollowingUser()

Public method

Stop viewport-following a user.

Signature
stopFollowingUser(): this

stretchShapes()

Public method

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

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to stretch.

operation

'horizontal' | 'vertical'

Whether to stretch shapes horizontally or vertically.

Returns
this
References

TLShape, TLShapeId


toggleLock()

Public method

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

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

shapes

TLShape[] | TLShapeId[]

The shapes (or shape ids) to toggle.

Returns
this
References

TLShape, TLShapeId


undo()

Public method

Undo to the last mark.

Example
editor.undo()
Signature
undo(): this

ungroupShapes()

Public method

Ungroup some shapes.

Signature
ungroupShapes(ids: TLShapeId[]): this
Parameters
NameDescription

ids

TLShapeId[]

Ids of the shapes to ungroup. Defaults to the selected shapes.

Returns
this
References

TLShapeId


ungroupShapes()

Public method

Signature
ungroupShapes(ids: TLShape[]): this
Parameters
NameDescription

ids

TLShape[]
Returns
this
References

TLShape


updateAssets()

Public method

Update one or more assets.

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

assets

TLAssetPartial[]

The assets to update.

Returns
this
References

TLAssetPartial


updateCurrentPageState()

Public method

Update this instance's page state.

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

partial

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

The partial of the page state object containing the changes.

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLInstancePageState, TLCommandHistoryOptions


updateDocumentSettings()

Public method

Update the global document settings that apply to all users.

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

settings

Partial<TLDocument>
Returns
this
References

TLDocument


updateInstanceState()

Public method

Update the instance's state.

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

partial

Partial<Omit<TLInstance, 'currentPageId'>>

A partial object to update the instance state with.

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLInstance, TLCommandHistoryOptions


updatePage()

Public method

Update a page.

Example
editor.updatePage({ id: 'page2', name: 'Page 2' })
editor.updatePage({ id: 'page2', name: 'Page 2' }, { squashing: true })
Signature
updatePage(
  partial: RequiredKeys<TLPage, 'id'>,
  historyOptions?: TLCommandHistoryOptions
): this
Parameters
NameDescription

partial

RequiredKeys<TLPage, 'id'>

The partial of the shape to update.

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

RequiredKeys, TLPage, TLCommandHistoryOptions


updateShape()

Public method

Update a shape using a partial of the shape.

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

partial

null | TLShapePartial<T> | undefined

The shape partial to update.

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLUnknownShape, TLShapePartial, TLCommandHistoryOptions


updateShapes()

Public method

Update shapes using partials of each shape.

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

partials

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

The shape partials to update.

historyOptions

TLCommandHistoryOptions

The history options for the change.

Returns
this
References

TLUnknownShape, TLShapePartial, TLCommandHistoryOptions


updateViewportScreenBounds()

Public method

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.

Example
editor.updateViewportScreenBounds()
editor.updateViewportScreenBounds(true)
Signature
updateViewportScreenBounds(center?: boolean): this
Parameters
NameDescription

center

boolean

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

Returns
this

visitDescendants()

Public method

Run a visitor function for all descendants of a shape.

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

parent

TLPage | TLParentId | TLShape

visitor

(id: TLShapeId) => false | void

The visitor function.

Returns
this
References

TLPage, TLParentId, TLShape, TLShapeId


zoomIn()

Public method

Zoom the camera in.

Example
editor.zoomIn()
editor.zoomIn(editor.getViewportScreenCenter(), { duration: 120 })
editor.zoomIn(editor.inputs.currentScreenPoint, { duration: 120 })
Signature
zoomIn(point?: Vec, animation?: TLAnimationOptions): this
Parameters
NameDescription

point

Vec

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

Vec, TLAnimationOptions


zoomOut()

Public method

Zoom the camera out.

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

point

Vec

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

Vec, TLAnimationOptions


zoomToBounds()

Public method

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

Example
editor.zoomToBounds(myBounds)
editor.zoomToBounds(myBounds, 1)
editor.zoomToBounds(myBounds, 1, { duration: 100 })
Signature
zoomToBounds(
  bounds: Box,
  targetZoom?: number,
  animation?: TLAnimationOptions
): this
Parameters
NameDescription

bounds

Box

The bounding box.

targetZoom

number

The desired zoom level. Defaults to 0.1.

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

Box, TLAnimationOptions


zoomToContent()

Public method

Move the camera to the nearest content.

Example
editor.zoomToContent()
editor.zoomToContent({ duration: 200 })
Signature
zoomToContent(): this

zoomToFit()

Public method

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

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

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

TLAnimationOptions


zoomToSelection()

Public method

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

Example
editor.zoomToSelection()
Signature
zoomToSelection(animation?: TLAnimationOptions): this
Parameters
NameDescription

animation

TLAnimationOptions

The options for an animation.

Returns
this
References

TLAnimationOptions


Edge2dEllipse2d