Editor

Public Class

Signature

class Editor extends EventEmitter<TLEventMap> {}

References

EventEmitter, TLEventMap

Constructor

Public Constructor

Constructs a new instance of the Editor class

Parameters

TLEditorOptions

References

TLEditorOptions

Properties

allShapesCommonBounds

Public Readonly Property

The common bounds of all of the shapes on the page.

Signature

get allShapesCommonBounds(): Box2d | null

References

Box2d

animationSpeed

Public Readonly Property

The user's chosen animation speed.

Signature

get animationSpeed(): number

assets

Public Readonly Property

Get all assets in the editor.

Signature

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

References

TLBookmarkAsset, TLImageAsset, TLVideoAsset

brush

Public Readonly Property

The instance's brush state.

Signature

get brush(): Box2dModel | null

References

Box2dModel

camera

Public Readonly Property

The current camera.

Signature

get camera(): import('@tldraw/tlschema').TLCamera

References

TLCamera

canMoveCamera

Public Property

Whether the editor's camera can move.

Example

editor.canMoveCamera = false

Parameters

Signature

get canMoveCamera(): boolean

set canMoveCamera(canMove: boolean)

canRedo

Public Readonly Property

Whether the app can redo.

Signature

get canRedo(): boolean

canUndo

Public Readonly Property

Whether the app can undo.

Signature

get canUndo(): boolean

croppingId

Public Readonly Property

The current cropping shape's id.

Signature

get croppingId(): null | TLShapeId

References

TLShapeId

cullingBounds

Public Readonly Property

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

Signature

get cullingBounds(): Box2d

References

Box2d

cullingBoundsExpanded

Public Readonly Property

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

Signature

get cullingBoundsExpanded(): Box2d

References

Box2d

currentPage

Public Readonly Property

The current page.

Signature

get currentPage(): TLPage

References

TLPage

currentPageId

Public Readonly Property

The current page id.

Signature

get currentPageId(): TLPageId

References

TLPageId

currentToolId

Public Readonly Property

The id of the current selected tool.

Signature

get currentToolId(): string

cursor

Public Readonly Property

The instance's cursor state.

Signature

get cursor(): TLCursor

References

TLCursor

devicePixelRatio

Public Readonly Property

The window's device pixel ratio.

Signature

get devicePixelRatio(): number

disposables

Public Readonly Property

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

Signature

readonly disposables: Set<() => void>

References

Set

documentSettings

Public Readonly Property

The global document settings that apply to all users.

Signature

get documentSettings(): TLDocument

References

TLDocument

editingId

Public Readonly Property

The current editing shape's id.

Signature

get editingId(): null | TLShapeId

References

TLShapeId

editingShape

Public Readonly Property

Signature

get editingShape(): null | TLUnknownShape

References

TLUnknownShape

erasingIds

Public Readonly Property

The editor's current erasing ids.

Signature

get erasingIds(): TLShapeId[]

References

TLShapeId

erasingIdsSet

Public Readonly Property

A derived set containing the current erasing ids.

Signature

get erasingIdsSet(): Set<TLShapeId>

References

Set, TLShapeId

externalContentManager

Public Property

Signature

externalContentManager: ExternalContentManager

References

ExternalContentManager

focusLayerId

Public Readonly Property

The shape id of the current focus layer.

Signature

get focusLayerId(): TLPageId | TLShapeId

References

TLPageId, TLShapeId

focusLayerShape

Public Readonly Property

The shape of the current focus layer.

Signature

get focusLayerShape(): TLShape | undefined

References

TLShape

getContainer

Public Property

The current HTML element containing the editor.

Example

const container = editor.getContainer()

Signature

getContainer: () => HTMLElement

References

HTMLElement

gridSize

Public Readonly Property

The document's grid size.

Signature

get gridSize(): number

hintingIds

Public Readonly Property

The editor's current hinting ids.

Signature

get hintingIds(): TLShapeId[]

References

TLShapeId

history

Public Readonly Property

A manager for the app's history.

Signature

readonly history: HistoryManager<this>

References

HistoryManager

hoveredId

Public Readonly Property

The current hovered shape id.

Signature

get hoveredId(): null | TLShapeId

References

TLShapeId

hoveredShape

Public Readonly Property

The current hovered shape.

Signature

get hoveredShape(): null | TLUnknownShape

References

TLUnknownShape

inputs

Public Property

The app's current input state.

Signature

inputs: {
  originPagePoint: Vec2d
  originScreenPoint: Vec2d
  previousPagePoint: Vec2d
  previousScreenPoint: Vec2d
  currentPagePoint: Vec2d
  currentScreenPoint: Vec2d
  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: Vec2d
}

References

Vec2d, Set

instanceState

Public Readonly Property

The current instance's state.

Signature

get instanceState(): TLInstance

References

TLInstance

isChangingStyle

Public Property

Whether the user is currently changing the style of a shape. This may cause the UI to change.

Example

editor.isChangingStyle = true

Signature

get isChangingStyle(): boolean

set isChangingStyle(v: boolean)

isChromeForIos

Public Readonly Property

Whether the editor is running on iOS.

Signature

readonly isChromeForIos: boolean

isCoarsePointer

Public Property

Whether the user is using a "coarse" pointer, such as on a touch screen. This is automatically set by the canvas.

Signature

get isCoarsePointer(): boolean

set isCoarsePointer(v: boolean)

isDarkMode

Public Readonly Property

Whether the user has dark mode enabled.

Signature

get isDarkMode(): boolean

isFocused

Public Readonly Property

Whether or not the editor is focused.

Signature

get isFocused(): boolean

isFocusMode

Public Readonly Property

Whether the instance is in focus mode or not.

Signature

get isFocusMode(): boolean

isGridMode

Public Readonly Property

Whether the instance's grid is enabled.

Signature

get isGridMode(): boolean

isIos

Public Readonly Property

Whether the editor is running on iOS.

Signature

readonly isIos: boolean

isMenuOpen

Public Readonly Property

Get whether any menus are open.

Signature

get isMenuOpen(): boolean

isPenMode

Public Readonly Property

Whether the editor is in pen mode or not.

Signature

get isPenMode(): boolean

isReadOnly

Public Readonly Property

Whether the editor is in read-only mode or not.

Signature

get isReadOnly(): boolean

isSafari

Public Readonly Property

Whether the editor is running in Safari.

Signature

readonly isSafari: boolean

isSnapMode

Public Readonly Property

Whether the user has "always snap" mode enabled.

Signature

get isSnapMode(): boolean

isToolLocked

Public Readonly Property

Whether the instance has "tool lock" mode enabled.

Signature

get isToolLocked(): boolean

locale

Public Readonly Property

Get the user's locale.

Signature

get locale(): string

onlySelectedShape

Public Readonly Property

The app's only selected shape.

Example

editor.onlySelectedShape

Signature

get onlySelectedShape(): null | TLShape

References

TLShape

opacity

Public Readonly Property

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

Signature

get opacity(): null | number

openMenus

Public Readonly Property

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

get openMenus(): string[]

pages

Public Readonly Property

Info about the project's current pages.

Signature

get pages(): TLPage[]

References

TLPage

pageState

Public Readonly Property

The current page state.

Signature

get pageState(): TLInstancePageState

References

TLInstancePageState

renderingShapes

Public Readonly Property

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

Signature

get renderingShapes(): {
  id: TLShapeId
  index: number
  backgroundIndex: number
  opacity: number
  isCulled: boolean
  isInViewport: boolean
  maskedPageBounds: Box2d | undefined
}[]

References

TLShapeId, Box2d

root

Public Readonly Property

The root state of the statechart.

Signature

readonly root: RootState

References

RootState

scribble

Public Readonly Property

The instance's scribble state.

Signature

get scribble(): null | TLScribble

References

TLScribble

selectedIds

Public Readonly Property

The current selected ids.

Signature

get selectedIds(): TLShapeId[]

References

TLShapeId

selectedIdsSet

Public Readonly Property

The current selected ids as a set

Signature

get selectedIdsSet(): ReadonlySet<TLShapeId>

References

ReadonlySet, TLShapeId

selectedPageBounds

Public Readonly Property

The current page bounds of all the selected shapes (Not the same thing as the page bounds of the selection bounding box when the selection has been rotated)

Signature

get selectedPageBounds(): Box2d | null

References

Box2d

selectedShapes

Public Readonly Property

An array containing all of the currently selected shapes.

Example

editor.selectedShapes

Signature

get selectedShapes(): TLShape[]

References

TLShape

selectionBounds

Public Readonly Property

The bounds of the selection bounding box.

Signature

get selectionBounds(): Box2d | undefined

References

Box2d

selectionPageCenter

Public Readonly Property

The center of the selection bounding box.

Signature

get selectionPageCenter(): null | Vec2d

References

Vec2d

selectionRotation

Public Readonly Property

The rotation of the selection bounding box.

Signature

get selectionRotation(): number

shapeIds

Public Readonly Property

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

Signature

get shapeIds(): Set<TLShapeId>

References

Set, TLShapeId

shapesArray

Public Readonly Property

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

Example

editor.shapesArray

Signature

get shapesArray(): TLShape[]

References

TLShape

shapeUtils

Public Property

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

Signature

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

References

ShapeUtil, TLUnknownShape

snaps

Public Readonly Property

A manager for the app's snapping feature.

Signature

readonly snaps: SnapManager

References

SnapManager

sortedShapesArray

Public Readonly Property

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.

Example

editor.sortedShapesArray

Signature

get sortedShapesArray(): TLShape[]

References

TLShape

store

Public Readonly Property

The editor's store

Signature

readonly store: TLStore

References

TLStore

styles

Public Static Property

The app's set of styles.

Signature

static styles: import('@tldraw/tlschema').TLStyleCollections

References

TLStyleCollections

textMeasure

Public Property

A helper for measuring text.

Signature

textMeasure: TextManager

References

TextManager

user

Public Readonly Property

A manager for the user and their preferences.

Signature

readonly user: UserPreferencesManager

References

UserPreferencesManager

viewportPageBounds

Public Readonly Property

The current viewport in page space.

Signature

get viewportPageBounds(): Box2d

References

Box2d

viewportPageCenter

Public Readonly Property

The center of the viewport in page space.

Signature

get viewportPageCenter(): Vec2d

References

Vec2d

viewportScreenBounds

Public Readonly Property

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

Signature

get viewportScreenBounds(): Box2d

References

Box2d

viewportScreenCenter

Public Readonly Property

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

Signature

get viewportScreenCenter(): Vec2d

References

Vec2d

zoomBrush

Public Readonly Property

The instance's zoom brush state.

Signature

get zoomBrush(): Box2dModel | null

References

Box2dModel

zoomLevel

Public Readonly Property

The current camera zoom level.

Signature

get zoomLevel(): number

Methods

addOpenMenu()

Public Method

Add an open menu.

Example

editor.addOpenMenu('menu-id')

Parameters

string

Returns

this

alignShapes()

Public Method

Align shape positions.

Example

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

Parameters

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

TLShapeId[]

Returns

this

References

TLShapeId

animateCamera()

Public Method

Animate the camera.

Example

editor.animateCamera(0, 0)
editor.animateCamera(0, 0, 1)
editor.animateCamera(0, 0, 1, { duration: 1000, easing: (t) => t * t })

Parameters

number

number

number

TLAnimationOptions

Returns

this

References

TLAnimationOptions

animateShapes()

Public Method

Animate shapes.

Example

editor.animateShapes([{ id: 'box1', type: 'box', x: 100, y: 100 }])

Parameters

(null | TLShapePartial | undefined)[]

{
  duration?: number
  ease?: (t: number) => number
}

Returns

this

References

TLShapePartial

animateToShape()

Public Method

Animate the camera to a shape.

Parameters

TLShapeId

TLAnimationOptions

Returns

this

References

TLShapeId, TLAnimationOptions

bail()

Public Method

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

Example

editor.bail()

Parameters

None

Returns

this

bailToMark()

Public Method

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

Example

editor.bailToMark('creating')

Parameters

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.createShapes(myShapes)
  editor.selectNone()
})

editor.undo() // will undo all of the above

Parameters

() => void

Returns

this

blur()

Public Method

Blur the app, cancelling any interaction state.

Example

editor.blur()

Parameters

None

Returns

this

bringForward()

Public Method

Bring shapes forward in the page's object list.

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

bringToFront()

Public Method

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

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

cancel()

Public Method

Dispatch a cancel event.

Example

editor.cancel()

Parameters

None

Returns

this

cancelDoubleClick()

Public Method

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

Parameters

None

Returns

void

centerOnPoint()

Public Method

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

Example

editor.centerOnPoint(100, 100)

Parameters

number

number

TLAnimationOptions

Returns

this

References

TLAnimationOptions

complete()

Public Method

Dispatch a complete event.

Example

editor.complete()

Parameters

None

Returns

this

createAssets()

Public Method

Create one or more assets.

Example

editor.createAssets([...myAssets])

Parameters

TLAsset[]

Returns

this

References

TLAsset

createPage()

Public Method

Create a page.

Example

editor.createPage('New Page')
editor.createPage('New Page', 'page1')

Parameters

string

TLPageId

string

Returns

this

References

TLPageId

createShapes()

Public Method

Create shapes.

Example

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

Parameters

TLShapePartial<T>[]

boolean

Returns

this

References

TLUnknownShape, TLShapePartial

deleteAssets()

Public Method

Delete one or more assets.

Example

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

Parameters

TLAssetId[]

Returns

this

References

TLAssetId

deleteOpenMenu()

Public Method

Delete an open menu.

Example

editor.deleteOpenMenu('menu-id')

Parameters

string

Returns

this

deletePage()

Public Method

Delete a page.

Example

editor.deletePage('page1')

Parameters

TLPageId

Returns

void

References

TLPageId

deleteShapes()

Public Method

Delete shapes.

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

deselect()

Public Method

Remove a shape from the existing set of selected shapes.

Example

editor.deselect(shape.id)

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

dispatch()

Public Method

Dispatch an event to the editor.

Example

editor.dispatch(myPointerEvent)

Parameters

TLEventInfo

Returns

this

References

TLEventInfo

dispose()

Public Method

Dispose the editor.

Parameters

None

Returns

void

distributeShapes()

Public Method

Distribute shape positions.

Example

editor.distributeShapes('left')
editor.distributeShapes('left', ['box1', 'box2'])

Parameters

'horizontal' | 'vertical'

TLShapeId[]

Returns

this

References

TLShapeId

duplicatePage()

Public Method

Duplicate a page.

Parameters

TLPageId

TLPageId

Returns

this

References

TLPageId

duplicateShapes()

Public Method

Duplicate shapes.

Example

editor.duplicateShapes()
editor.duplicateShapes(['id1', 'id2'])
editor.duplicateShapes(['id1', 'id2'], { x: 8, y: 8 })

Parameters

TLShapeId[]

VecLike

Returns

this

References

TLShapeId, VecLike

findAncestor()

Public Method

Find the first ancestor matching the given predicate

Example

const ancestor = editor.findAncestor(myShape)

Parameters

TLShape

(parent: TLShape) => boolean

Returns

TLShape | undefined

References

TLShape

findCommonAncestor()

Public Method

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

Parameters

TLShape[]

(shape: TLShape) => boolean

Returns

TLShapeId | undefined

References

TLShape, TLShapeId

flipShapes()

Public Method

Flip shape positions.

Example

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

Parameters

'horizontal' | 'vertical'

TLShapeId[]

Returns

this

References

TLShapeId

focus()

Public Method

Focus the editor.

Example

editor.focus()

Parameters

None

Returns

this

getAncestors()

Public Method

Get the ancestors of a shape.

Example

const ancestors = editor.getAncestors(myShape)

Parameters

TLShape

TLShape[]

Returns

TLShape[]

References

TLShape

getAncestorsById()

Public Method

Get the ancestors of a shape by its id.

Example

const ancestors = editor.getAncestorsById(myShape)

Parameters

TLShapeId

TLShape[]

Returns

TLShape[]

References

TLShapeId, TLShape

getArrowsBoundTo()

Public Method

Get all arrows bound to a shape.

Parameters

TLShapeId

Returns

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

References

TLShapeId

getAssetById()

Public Method

Get an asset by its id.

Example

editor.getAssetById('asset1')

Parameters

TLAssetId

Returns

TLAsset | undefined

References

TLAssetId, TLAsset

getAssetBySrc()

Public Method

Get an asset by its src property.

Example

editor.getAssetBySource('https://example.com/image.png')

Parameters

string

Returns

  | import('@tldraw/tlschema').TLBookmarkAsset
  | TLImageAsset
  | TLVideoAsset
  | undefined

References

TLBookmarkAsset, TLImageAsset, TLVideoAsset

getBounds()

Public Method

Get the local bounds of a shape.

Example

editor.getBounds(myShape)

Parameters

TLShape

Returns

Box2d

References

TLShape, Box2d

getBoundsById()

Public Method

Get the local bounds of a shape by its id.

Example

editor.getBoundsById(myShape)

Parameters

TLShapeId

Returns

Box2d | undefined

References

TLShapeId, Box2d

getClipPathById()

Public Method

Get the clip path for a shape.

Example

const clipPath = editor.getClipPathById(shape.id)

Parameters

TLShapeId

Returns

string | undefined

The clip path or undefined.

References

TLShapeId

getContent()

Public Method

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

Parameters

TLShapeId[]

Returns

TLContent | undefined

The exported content.

References

TLShapeId, TLContent

getCssColor()

Public Method

Get the CSS color value for a given color id.

Example

editor.getCssColor('red')

Parameters

TLColorStyle['id']

Returns

string

References

TLColorStyle

getDeltaInParentSpace()

Public Method

Convert a delta in page space to a delta in the parent space of a shape.

Example

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

Parameters

TLShape

VecLike

Returns

Vec2d

References

TLShape, VecLike, Vec2d

getDeltaInShapeSpace()

Public Method

Convert a delta in page space to a delta in the local space of a shape.

Example

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

Parameters

TLShape

VecLike

Returns

Vec2d

References

TLShape, VecLike, Vec2d

getDroppingShape()

Public Method

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

Parameters

VecLike

TLShape[]

Returns

TLUnknownShape | undefined

The shape to drop on.

References

VecLike, TLShape, TLUnknownShape

getHighestIndexForParent()

Public Method

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

Parameters

TLPageId | TLShapeId

Returns

string

The index.

References

TLPageId, TLShapeId

getMaskedPageBounds()

Public Method

Get the page (or absolute) bounds of a shape, 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.getMaskedPageBounds(myShape)

Parameters

TLShape

Returns

Box2d | undefined

References

TLShape, Box2d

getMaskedPageBoundsById()

Public Method

Get the page (or absolute) bounds of a shape by its id, 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.getMaskedPageBoundsById(myShape)

Parameters

TLShapeId

Returns

Box2d | undefined

References

TLShapeId, Box2d

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.

Parameters

TLShape

(shape: TLShape) => boolean

Returns

TLShape

The outermost selectable shape.

References

TLShape

getOutline()

Public Method

Get the local outline of a shape.

Example

editor.getOutline(myShape)

Parameters

TLShape

Returns

Vec2dModel[]

References

TLShape, Vec2dModel

getOutlineById()

Public Method

Get the local outline of a shape.

Example

editor.getOutlineById(myShape)

Parameters

TLShapeId

Returns

Vec2dModel[]

References

TLShapeId, Vec2dModel

getPageBounds()

Public Method

Get the page (or absolute) bounds of a shape.

Example

editor.getPageBounds(myShape)

Parameters

TLShape

Returns

Box2d | undefined

References

TLShape, Box2d

getPageBoundsById()

Public Method

Get the page (or absolute) bounds of a shape by its id.

Example

editor.getPageBoundsById(myShape)

Parameters

TLShapeId

Returns

Box2d | undefined

References

TLShapeId, Box2d

getPageById()

Public Method

Get a page by its ID.

Example

editor.getPageById(myPage.id)

Parameters

TLPageId

Returns

TLPage | undefined

References

TLPageId, TLPage

getPageCenter()

Public Method

Get the page point (or absolute point) of a shape.

Example

editor.getPagePoint(myShape)

Parameters

TLShape

Returns

null | Vec2d

References

TLShape, Vec2d

getPageCenterById()

Public Method

Get the page point (or absolute point) of a shape by its id.

Example

editor.getPagePoint(myShape)

Parameters

TLShapeId

Returns

null | Vec2d

References

TLShapeId, Vec2d

getPageCorners()

Public Method

Get the corners of a shape in page space.

Example

const corners = editor.getPageCorners(myShape)

Parameters

TLShape

Returns

Vec2d[]

References

TLShape, Vec2d

getPageInfoById()

Public Method

Get a page by its ID.

Example

editor.getPageById(myPage.id)

Parameters

TLPage['id']

Returns

TLPage | undefined

References

TLPage

getPageMaskById()

Public Method

Get the page mask for a shape.

Example

const pageMask = editor.getPageMaskById(shape.id)

Parameters

TLShapeId

Returns

undefined | VecLike[]

The page mask for the shape.

References

TLShapeId, VecLike

getPagePointById()

Public Method

Get the page point (or absolute point) of a shape.

Example

editor.getPagePoint(myShape)

Parameters

TLShapeId

Returns

undefined | Vec2d

References

TLShapeId, Vec2d

getPageRotation()

Public Method

Get the page rotation (or absolute rotation) of a shape.

Example

editor.getPageRotation(myShape)

Parameters

TLShape

Returns

number

References

TLShape

getPageRotationById()

Public Method

Get the page rotation (or absolute rotation) of a shape by its id.

Example

editor.getPageRotationById(myShapeId)

Parameters

TLShapeId

Returns

number

References

TLShapeId

getPageStateByPageId()

Public Method

Get a page state by its id.

Example

editor.getPageStateByPageId('page1')

Parameters

TLPageId

Returns

TLInstancePageState | undefined

References

TLPageId, TLInstancePageState

getPageTransform()

Public Method

Get the page transform (or absolute transform) of a shape.

Example

editor.getPageTransform(myShape)

Parameters

TLShape

Returns

Matrix2d | undefined

References

TLShape, Matrix2d

getPageTransformById()

Public Method

Get the page transform (or absolute transform) of a shape by its id.

Example

editor.getPageTransformById(myShape)

Parameters

TLShapeId

Returns

Matrix2d | undefined

References

TLShapeId, Matrix2d

getParentIdForNewShapeAtPoint()

Public Method

Get the id of what should be the parent of a new shape at a given point. The parent can be a page or shape.

Parameters

VecLike

TLShape['type']

Returns

TLPageId | TLShapeId

The id of the parent.

References

VecLike, TLShape, TLPageId, TLShapeId

getParentPageId()

Public Method

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

Parameters

TLShape

Returns

TLPageId | undefined

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

References

TLShape, TLPageId

getParentShape()

Public Method

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

Example

editor.getParentShape(myShape)

Parameters

TLShape

Returns

TLShape | undefined

References

TLShape

getParentsMappedToChildren()

Public Method

For a given set of ids, get a map containing the ids of their parents and the children of those parents.

Example

editor.getParentsMappedToChildren(['id1', 'id2', 'id3'])

Parameters

TLShapeId[]

Returns

Map<TLParentId, Set<TLShape>>

References

TLShapeId, Map, TLParentId, Set, TLShape

getParentTransform()

Public Method

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

Example

editor.getParentTransform(myShape)

Parameters

TLShape

Returns

Matrix2d

References

TLShape, Matrix2d

getPointInParentSpace()

Public Method

Convert a delta in 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.id, { x: 100, y: 100 })

Parameters

TLShapeId

VecLike

Returns

Vec2d

References

TLShapeId, VecLike, Vec2d

getPointInShapeSpace()

Public Method

Convert a point in 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 })

Parameters

TLShape

VecLike

Returns

Vec2d

References

TLShape, VecLike, Vec2d

getShapeAndDescendantIds()

Public Method

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

Parameters

TLShapeId[]

Returns

Set<TLShapeId>

The decscendant ids.

References

TLShapeId, Set

getShapeById()

Public Method

Get a shape by its id.

Example

editor.getShapeById('box1')

Parameters

TLParentId

Returns

T | undefined

References

TLShape, TLParentId

getShapeIdsInPage()

Public Method

Get the ids of shapes on a page.

Parameters

TLPageId

Returns

Set<TLShapeId>

References

TLPageId, Set, TLShapeId

getShapesAtPoint()

Public Method

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

Example

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

Parameters

VecLike

Returns

TLShape[]

References

VecLike, TLShape

getShapeUtil()

Public Method

Get a shape util by its definition.

Example

editor.getShapeUtil(ArrowShapeUtil)

Parameters

C

Returns

InstanceType<C>

References

ShapeUtil, InstanceType

getShapeUtil()

Public Method

Get a shape util from a shape itself.

Example

const util = editor.getShapeUtil(myShape)
const util = editor.getShapeUtil<ArrowShapeUtil>(myShape)
const util = editor.getShapeUtil(ArrowShapeUtil)

Parameters

S | TLShapePartial<S>

Returns

ShapeUtil<S>

References

TLUnknownShape, TLShapePartial, ShapeUtil

getSortedChildIds()

Public Method

Get an array of all the children of a shape.

Example

editor.getSortedChildIds('frame1')

Parameters

TLParentId

Returns

TLShapeId[]

References

TLParentId, TLShapeId

getStateDescendant()

Public Method

Get a descendant by its path.

Example

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

Parameters

string

Returns

StateNode | undefined

References

StateNode

getStrokeWidth()

Public Method

Get the stroke width value for a given size id.

Example

editor.getStrokeWidth('m')

Parameters

TLSizeStyle['id']

Returns

number

References

TLSizeStyle

getSvg()

Public Method

Get an exported SVG of the given shapes.

Parameters

TLShapeId[]

Partial<{
  scale: number
  background: boolean
  padding: number
  darkMode?: boolean | undefined
  preserveAspectRatio: React.SVGAttributes<SVGSVGElement>['preserveAspectRatio']
}>

Returns

Promise<SVGSVGElement | undefined>

The SVG element.

References

TLShapeId, Partial, React.SVGAttributes, SVGSVGElement, Promise

getTransform()

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.getTransform(myShape)

Parameters

TLShape

Returns

Matrix2d

References

TLShape, Matrix2d

groupShapes()

Public Method

Group some shapes together.

Parameters

TLShapeId[]

TLShapeId

Returns

this

References

TLShapeId

hasAncestor()

Public Method

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

Parameters

TLShape | undefined

TLShapeId

Returns

boolean

References

TLShape, TLShapeId

interrupt()

Public Method

Dispatch an interrupt event.

Example

editor.interrupt()

Parameters

None

Returns

this

isIn()

Public Method

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

Example

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

Parameters

string

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

Parameters

string[]

Returns

boolean

isPointInShape()

Public Method

Test whether a point (in 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)

Parameters

VecLike

TLShape

Returns

boolean

References

VecLike, TLShape

isSelected()

Public Method

Determine whether or not a shape is selected

Example

editor.isSelected('id1')

Parameters

TLShapeId

Returns

boolean

References

TLShapeId

isShapeInPage()

Public Method

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

Example

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

Parameters

TLShape

TLPageId

Returns

boolean

References

TLShape, TLPageId

isShapeInViewport()

Public Method

Check whether a shape is within the bounds of the current viewport.

Parameters

TLShapeId

Returns

boolean

References

TLShapeId

isShapeOfType()

Public Method

Get whether a shape matches the type of a TLShapeUtil.

Example

const isArrowShape = isShapeOfType(someShape, ArrowShapeUtil)

Parameters

TLUnknownShape

{
  new (...args: any): ShapeUtil<T>
  type: string
}

Returns

shape is T

References

TLUnknownShape, ShapeUtil, shape

isShapeOrAncestorLocked()

Public Method

Check whether a shape or its parent is locked.

Parameters

TLShape

Returns

boolean

References

TLShape

isWithinSelection()

Public Method

Determine whether a not a shape is within the current selection. A shape is within the selection if it or any of its parents is selected.

Parameters

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

Parameters

string

boolean

boolean

Returns

string

moveShapesToPage()

Public Method

Move shapes to page.

Example

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

Parameters

TLShapeId[]

TLPageId

Returns

this

References

TLShapeId, TLPageId

nudgeShapes()

Public Method

Move shapes by a delta.

Example

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

Parameters

TLShapeId[]

Vec2dModel

boolean

boolean

Returns

this

References

TLShapeId, Vec2dModel

packShapes()

Public Method

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

Parameters

TLShapeId[]

number

Returns

this

References

TLShapeId

pageToScreen()

Public Method

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

Example

editor.pageToScreen(100, 100)

Parameters

number

number

number

Vec2dModel

Returns

{
  x: number
  y: number
  z: number
}

References

Vec2dModel

pan()

Public Method

Pan the camera.

Example

editor.pan(100, 100)
editor.pan(100, 100, { duration: 1000 })

Parameters

number

number

TLAnimationOptions

Returns

this

References

TLAnimationOptions

panZoomIntoView()

Public Method

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

Parameters

TLShapeId[]

TLAnimationOptions

Returns

this

References

TLShapeId, TLAnimationOptions

popFocusLayer()

Public Method

Exit the current focus layer, moving up to the next group if there is one.

Parameters

None

Returns

this

putContent()

Public Method

Place content into the editor.

Parameters

TLContent

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

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.

Parameters

TLExternalContent

Returns

Promise<void>

References

TLExternalContent, Promise

redo()

Public Method

Redo to the next mark.

Example

editor.redo()

Parameters

None

Returns

this

renamePage()

Public Method

Rename a page.

Example

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

Parameters

TLPageId

string

boolean

Returns

this

References

TLPageId

reorderShapes()

Public Method

Reorder shapes.

Parameters

'backward' | 'forward' | 'toBack' | 'toFront'

TLShapeId[]

Returns

this

References

TLShapeId

reparentShapesById()

Public Method

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

Example

editor.reparentShapesById(['box1', 'box2'], 'frame1')

Parameters

TLShapeId[]

TLParentId

string

Returns

this

References

TLShapeId, TLParentId

replaceStoreContentsWithRecordsForOtherDocument()

Public Method

Replace the store's contents with the given records.

Parameters

TLRecord[]

Returns

void

References

TLRecord

resetZoom()

Public Method

Set the zoom back to 100%.

Example

editor.resetZoom()

Parameters

Vec2d

TLAnimationOptions

Returns

this

References

Vec2d, TLAnimationOptions

resizeShape()

Public Method

Resize a shape.

Parameters

TLShapeId

VecLike

{
  initialBounds?: Box2d
  scaleOrigin?: VecLike
  scaleAxisRotation?: number
  initialShape?: TLShape
  initialPageTransform?: MatLike
  dragHandle?: TLResizeHandle
  mode?: TLResizeMode
}

Returns

this

References

TLShapeId, VecLike, Box2d, TLShape, MatLike, TLResizeHandle, TLResizeMode

rotateShapesBy()

Public Method

Rotate shapes by a delta in radians.

Example

editor.rotateShapesBy(['box1', 'box2'], Math.PI)
editor.rotateShapesBy(['box1', 'box2'], Math.PI / 2)

Parameters

TLShapeId[]

number

Returns

this

References

TLShapeId

screenToPage()

Public Method

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

Example

editor.screenToPage(100, 100)

Parameters

number

number

number

Vec2dModel

Returns

{
  x: number
  y: number
  z: number
}

References

Vec2dModel

select()

Public Method

Select one or more shapes.

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

selectAll()

Public Method

Select all direct children of the current page.

Example

editor.selectAll()

Parameters

None

Returns

this

selectNone()

Public Method

Clear the selection.

Example

editor.selectNone()

Parameters

None

Returns

this

sendBackward()

Public Method

Send shapes backward in the page's object list.

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

sendToBack()

Public Method

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

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

setAnimationSpeed()

Public Method

Set the user's chosen animation speed. Set to 0.0 to disable animations. Set to 1.0 for full speed.

Parameters

number

Returns

this

setBrush()

Public Method

Set the current brush.

Example

editor.setBrush({ x: 0, y: 0, w: 100, h: 100 })
editor.setBrush() // Clears the brush

Parameters

Box2dModel | null

Returns

this

References

Box2dModel

setCamera()

Public Method

Set the current camera.

Example

editor.setCamera(0, 0)
editor.setCamera(0, 0, 1)

Parameters

number

number

number

TLViewportOptions

Returns

this

References

TLViewportOptions

setCroppingId()

Public Method

Set the current cropping shape's id.

Parameters

null | TLShapeId

Returns

this

References

TLShapeId

setCurrentPageId()

Public Method

Set the current page.

Example

editor.setCurrentPageId('page1')

Parameters

TLPageId

TLViewportOptions

Returns

this

References

TLPageId, TLViewportOptions

setCursor()

Public Method

Set the current cursor.

Example

editor.setCursor({ type: 'default' })
editor.setCursor({ type: 'default', rotation: Math.PI / 2, color: 'red' })

Parameters

Partial<TLCursor>

Returns

this

References

Partial, TLCursor

setDarkMode()

Public Method

Set whether the user has dark mode enabled.

Parameters

boolean

Returns

this

setEditingId()

Public Method

Set the current editing id.

Parameters

null | TLShapeId

Returns

this

References

TLShapeId

setErasingIds()

Public Method

Set the current erasing shapes.

Example

editor.setErasingIds(['box1', 'box2'])
editor.setErasingIds() // Clears the erasing set

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

setFocusLayer()

Public Method

Set the focus layer to the given shape id.

Parameters

null | TLShapeId

Returns

this

References

TLShapeId

setFocusMode()

Public Method

Set whether the instance is in focus mode or not.

Parameters

boolean

Returns

this

setGridMode()

Public Method

Set whether the instance's grid is enabled.

Parameters

boolean

Returns

this

setHintingIds()

Public Method

Set the hinted shape ids.

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

setHoveredId()

Public Method

Set the current hovered shape.

Example

editor.setHoveredId('box1')
editor.setHoveredId() // Clears the hovered shape.

Parameters

null | TLShapeId

Returns

this

References

TLShapeId

setInstancePageState()

Public Method

Update a page state.

Example

editor.setInstancePageState({ id: 'page1', editingId: 'shape:123' })
editor.setInstancePageState({ id: 'page1', editingId: 'shape:123' }, true)

Parameters

Partial<TLInstancePageState>

boolean

Returns

void

References

Partial, TLInstancePageState

setLocale()

Public Method

Update the user's locale. This affects which translations are used when rendering UI elements.

Example

editor.setLocale('fr')

Parameters

string

Returns

void

setOpacity()

Public Method

Set the current opacity. This will effect any selected shapes, or the next-created shape.

Example

editor.setOpacity(0.5)
editor.setOpacity(0.5, true)

Parameters

number

boolean

boolean

Returns

this

setPenMode()

Public Method

Set whether the editor is in pen mode or not.

Parameters

boolean

Returns

this

setProp()

Public Method

Set the current props (generally styles).

Example

editor.setProp('color', 'red')
editor.setProp('color', 'red', true)

Parameters

TLShapeProp

any

boolean

boolean

Returns

this

References

TLShapeProp

setReadOnly()

Public Method

Set whether the editor is in read-only mode or not.

Parameters

boolean

Returns

this