App

Public Class

Signature

class App extends EventEmitter {}

References

EventEmitter

Constructor

Public Constructor

Constructs a new instance of the App class

Parameters

AppOptions

References

AppOptions

Properties

allShapesCommonBounds

Public Readonly Property

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

Signature

get allShapesCommonBounds(): Box2d | null

References

Box2d

assets

Public Readonly Property

Get all assets in the app.

Signature

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

References

TLBookmarkAsset, TLImageAsset, TLVideoAsset

brush

Public Readonly Property

Signature

get brush(): Box2dModel | null

References

Box2dModel

camera

Public Readonly Property

The current camera.

Signature

get camera(): TLCamera

References

TLCamera

canMoveCamera

Public Property

Set whether the editor's camera can move.

Example

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

config

Public Readonly Property

The editor's config

Signature

readonly config: TldrawEditorConfig

References

TldrawEditorConfig

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

Signature

get cursor(): TLCursor

References

TLCursor

devicePixelRatio

Public Readonly Property

Signature

get devicePixelRatio(): number

dispatch

Public Property

Dispatch an event to the app.

Example

app.dispatch(myPointerEvent)

Parameters

Signature

dispatch: (info: TLEventInfo) => this

References

TLEventInfo

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 applies to all users

Signature

get documentSettings(): import('@tldraw/tlschema').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

focusLayerId

Public Readonly Property

Signature

get focusLayerId(): TLPageId | TLShapeId

References

TLPageId, TLShapeId

focusLayerShape

Public Readonly Property

Signature

get focusLayerShape(): TLShape | undefined

References

TLShape

getContainer

Public Property

The current HTML element containing the editor.

Example

const container = app.getContainer()

Signature

getContainer: () => HTMLElement

References

HTMLElement

gridSize

Public Readonly Property

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

Signature

get hoveredId(): null | TLShapeId

References

TLShapeId

hoveredShape

Public Readonly Property

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

instanceId

Public Readonly Property

The editor's instanceId (defined in its store.props).

Example

const instanceId = app.instanceId

Signature

get instanceId(): TLInstanceId

References

TLInstanceId

instanceState

Public Readonly Property

The current tab 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

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

Signature

get isCoarsePointer(): boolean

set isCoarsePointer(v: boolean)

isFocused

Public Readonly Property

Whether or not the editor is focused.

Signature

get isFocused(): boolean

isGridMode

Public Readonly Property

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

Signature

get isPenMode(): boolean

isReadOnly

Public Readonly Property

Signature

get isReadOnly(): boolean

isSafari

Public Readonly Property

Whether the editor is running in Safari.

Signature

readonly isSafari: boolean

onlySelectedShape

Public Readonly Property

The app's only selected shape.

Example

app.onlySelectedShape

Signature

get onlySelectedShape():
  | import('@tldraw/tlschema').TLBaseShape<any, any>
  | null

References

TLBaseShape

openMenus

Public Property

A set of strings representing any open menus or modals.

Signature

openMenus: Set<string>

References

Set

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
  opacity: number
  isCulled: boolean
  isInViewport: boolean
}[]

References

TLShapeId

root

Public Readonly Property

The root state of the statechart.

Signature

readonly root: RootState

References

RootState

scribble

Public Readonly Property

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

app.selectedShapes

Signature

get selectedShapes(): import('@tldraw/tlschema').TLBaseShape<any, any>[]

References

TLBaseShape

selectionBounds

Public Readonly Property

Signature

get selectionBounds(): Box2d | undefined

References

Box2d

selectionPageCenter

Public Readonly Property

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

app.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]?: TLShapeUtil<TLUnknownShape>
}

References

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

app.sortedShapesArray

Signature

get sortedShapesArray(): TLShape[]

References

TLShape

startFollowingUser

Public Property

Start viewport-following a user.

Parameters

Signature

startFollowingUser: (userId: TLUserId) => this | undefined

References

TLUserId

stopFollowingUser

Public Property

Stop viewport-following a user.

Signature

stopFollowingUser: () => this

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

updateUserPresence

Public Property

Signature

updateUserPresence: ({
  cursor,
  color,
  viewportPageBounds,
}?: {
  cursor?: undefined | Vec2dModel
  color?: string | undefined
  viewportPageBounds?: Box2dModel | undefined
}) => void

References

Vec2dModel, Box2dModel

user

Public Readonly Property

The current user state.

Signature

get user(): TLUser

References

TLUser

userDocumentSettings

Public Readonly Property

Signature

get userDocumentSettings(): TLUserDocument

References

TLUserDocument

userId

Public Readonly Property

The editor's userId (defined in its store.props).

Example

const userId = app.userId

Signature

get userId(): TLUserId

References

TLUserId

userPresence

Public Readonly Property

Signature

get userPresence(): import('@tldraw/tlschema').TLUserPresence | undefined

References

TLUserPresence

userSettings

Public Readonly Property

The user's global settings.

Signature

get userSettings(): TLUser

References

TLUser

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

Signature

get zoomBrush(): Box2dModel | null

References

Box2dModel

zoomLevel

Public Readonly Property

The current camera zoom level.

Signature

get zoomLevel(): number

Methods

alignShapes()

Public Method

Align shape positions.

Example

app.alignShapes('left')
app.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

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

Parameters

number

number

number

AnimationOptions

Returns

this

References

AnimationOptions

animateShapes()

Public Method

Animate shapes.

Example

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

Parameters

TLShapeId

AnimationOptions

Returns

this

References

TLShapeId, AnimationOptions

bail()

Public Method

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

Example

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

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

app.batch(() => {
  app.selectAll()
  app.deleteShapes()
  app.createShapes(myShapes)
  app.selectNone()
})

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

Parameters

() => void

Returns

this

blur()

Public Method

Blur the app, cancelling any interaction state.

Example

app.blur()

Parameters

None

Returns

this

bringForward()

Public Method

Bring shapes forward in the page's object list.

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

bringToFront()

Public Method

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

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

cancel()

Public Method

Dispatch a cancel event.

Example

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

app.centerOnPoint(100, 100)

Parameters

number

number

AnimationOptions

Returns

this

References

AnimationOptions

complete()

Public Method

Dispatch a complete event.

Example

app.complete()

Parameters

None

Returns

this

createAssets()

Public Method

Create one or more assets.

Example

app.createAssets([...myAssets])

Parameters

TLAsset[]

Returns

this

References

TLAsset

createPage()

Public Method

Create a page.

Example

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

Parameters

string

TLPageId

string

Returns

this

References

TLPageId

createShapeId()

Public Method

Get a unique id for a shape.

Example

app.createShapeId()
app.createShapeId('box1')

Parameters

string

Returns

TLShapeId

References

TLShapeId

createShapes()

Public Method

Create shapes.

Example

app.createShapes([{ id: 'box1', type: 'box' }])

Parameters

TLShapePartial[]

boolean

Returns

this

References

TLShapePartial

deleteAssets()

Public Method

Delete one or more assets.

Example

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

Parameters

TLAssetId[]

Returns

this

References

TLAssetId

deletePage()

Public Method

Delete a page.

Example

app.deletePage('page1')

Parameters

TLPageId

Returns

void

References

TLPageId

deleteShapes()

Public Method

Delete shapes.

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

deselect()

Public Method

Remove a shpae from the existing set of selected shapes.

Example

app.deselect(shape.id)

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

dispose()

Public Method

Dispose the app.

Parameters

None

Returns

void

distributeShapes()

Public Method

Distribute shape positions.

Example

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

Parameters

'horizontal' | 'vertical'

TLShapeId[]

Returns

this

References

TLShapeId

duplicatePage()

Public Method

Parameters

TLPageId

TLPageId

Returns

void

References

TLPageId

duplicateShapes()

Public Method

Duplicate shapes.

Example

app.duplicateShapes()
app.duplicateShapes(['id1', 'id2'])
app.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 = app.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

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

Parameters

'horizontal' | 'vertical'

TLShapeId[]

Returns

this

References

TLShapeId

focus()

Public Method

Focus the app.

Example

app.focus()

Parameters

None

Returns

this

getAncestors()

Public Method

Get the ancestors of a shape.

Example

const ancestors = app.getAncestors(myShape)

Parameters

TLShape

TLShape[]

Returns

TLShape[]

References

TLShape

getAncestorsById()

Public Method

Get the ancestors of a shape by its id.

Example

const ancestors = app.getAncestorsById(myShape)

Parameters

TLShapeId

TLShape[]

Returns

TLShape[]

References

TLShapeId, TLShape

getArrowsBoundTo()

Public Method

GetArrowsBoundTo

Parameters

TLShapeId

Returns

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

References

TLShapeId

getAssetById()

Public Method

Get an asset by its id.

Example

app.getAssetById('asset1')

Parameters

TLAssetId

Returns

TLAsset | undefined

References

TLAssetId, TLAsset

getAssetBySrc()

Public Method

Get an asset by its src property.

Example

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

app.getBounds(myShape)

Parameters

TLShape

Returns

Box2d

References

TLShape, Box2d

getBoundsById()

Public Method

Get the local bounds of a shape by its id.

Example

app.getBoundsById(myShape)

Parameters

TLShapeId

Returns

Box2d | undefined

References

TLShapeId, Box2d

getClipPathById()

Public Method

Get the clip path for a shape.

Example

const clipPath = app.getClipPathById(shape.id)

Parameters

TLShapeId

Returns

string | undefined

The clip path or undefined.

References

TLShapeId

getContent()

Public Method

Parameters

TLShapeId[]

Returns

TLClipboardModel | undefined

References

TLShapeId, TLClipboardModel

getCssColor()

Public Method

Get the CSS color value for a given color id.

Example

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

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

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

Parameters

TLShape

VecLike

Returns

Vec2d

References

TLShape, VecLike, Vec2d

getDroppingShape()

Public Method

Parameters

VecLike

TLShape[]

Returns

TLUnknownShape | undefined

References

VecLike, TLShape, TLUnknownShape

getHighestIndexForParent()

Public Method

Parameters

TLPageId | TLShapeId

Returns

string

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

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

app.getMaskedPageBoundsById(myShape)

Parameters

TLShapeId

Returns

Box2d | undefined

References

TLShapeId, Box2d

getOutermostSelectableShape()

Public Method

Parameters

TLShape

(shape: TLShape) => boolean

Returns

TLShape

References

TLShape

getOutline()

Public Method

Get the local outline of a shape.

Example

app.getOutline(myShape)

Parameters

TLShape

Returns

Vec2dModel[]

References

TLShape, Vec2dModel

getOutlineById()

Public Method

Get the local outline of a shape.

Example

app.getOutlineById(myShape)

Parameters

TLShapeId

Returns

Vec2dModel[]

References

TLShapeId, Vec2dModel

getPageBounds()

Public Method

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

Example

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

app.getPageBoundsById(myShape)

Parameters

TLShapeId

Returns

Box2d | undefined

References

TLShapeId, Box2d

getPageById()

Public Method

Get a page by its ID.

Example

app.getPageById(myPage.id)

Parameters

TLPage['id']

Returns

TLPage | undefined

References

TLPage

getPageCenter()

Public Method

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

Example

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

app.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 = app.getPageCorners(myShape)

Parameters

TLShape

Returns

Vec2d[]

References

TLShape, Vec2d

getPageInfoById()

Public Method

Get a page by its ID.

Example

app.getPageById(myPage.id)

Parameters

TLPage['id']

Returns

TLPage | undefined

References

TLPage

getPageMaskById()

Public Method

Get the page mask for a shape.

Example

const pageMask = app.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

app.getPagePoint(myShape)

Parameters

TLShapeId

Returns

undefined | Vec2d

References

TLShapeId, Vec2d

getPageRotation()

Public Method

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

Example

app.getPageRotation(myShape)

Parameters

TLShape

Returns

number

References

TLShape

getPageRotationById()

Public Method

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

Parameters

TLShapeId

Returns

number

References

TLShapeId

getPageStateByPageId()

Public Method

Get a page state by its id.

Example

app.getPageStateByPageId('page1')

Parameters

TLPageId

Returns

TLInstancePageState | undefined

References

TLPageId, TLInstancePageState

getPageTransform()

Public Method

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

Example

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

app.getPageTransformById(myShape)

Parameters

TLShapeId

Returns

Matrix2d | undefined

References

TLShapeId, Matrix2d

getParentIdForNewShapeAtPoint()

Public Method

Parameters

VecLike

TLShapeType

Returns

TLPageId | TLShapeId

References

VecLike, TLShapeType, TLPageId, TLShapeId

getParentPageId()

Public Method

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

Parameters

TLShape

Returns

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

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

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

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

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

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

Parameters

TLShape

VecLike

Returns

Vec2d

References

TLShape, VecLike, Vec2d

getShapeById()

Public Method

Get a shape by its id.

Example

app.getShapeById('box1')

Parameters

TLParentId

Returns

T | undefined

References

TLShape, TLParentId

getShapesAndDescendantsInOrder()

Public Method

Parameters

TLShapeId[]

Returns

TLShape[]

References

TLShapeId, TLShape

getShapesAtPoint()

Public Method

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

Example

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

Parameters

VecLike

Returns

TLShape[]

References

VecLike, TLShape

getShapesInPage()

Public Method

Get shapes on a page.

Parameters

TLPageId

Returns

TLShape[]

References

TLPageId, TLShape

getShapeUtil()

Public Method

Get a shape util for a given shape or shape type.

Example

app.getShapeUtil(myBoxShape)

Parameters

T

Returns

TLShapeUtil<T>

References

TLShape, TLShapeUtil

getShapeUtilByDef()

Public Method

Get a shape util by its definition.

Example

app.getShapeUtilByDef(TLDrawShapeDef)

Parameters

Def

Returns

ReturnType<Def['createShapeUtils']>

References

TLShapeDef, ReturnType

getSortedChildIds()

Public Method

Get an array of all the children of a shape.

Example

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

app.getStrokeWidth('m')

Parameters

TLSizeStyle['id']

Returns

number

References

TLSizeStyle

getSvg()

Public Method

Parameters

TLShapeId[]

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

Returns

Promise<SVGSVGElement | undefined>

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

app.getTransform(myShape)

Parameters

TLShape

Returns

Matrix2d

References

TLShape, Matrix2d

groupShapes()

Public Method

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

app.interrupt()

Parameters

None

Returns

this

isIn()

Public Method

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

Example

app.isIn('select')
app.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

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

app.isSelected('id1')

Parameters

TLShapeId

Returns

boolean

References

TLShapeId

isShapeInPage()

Public Method

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

Example

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

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

lockShapes()

Public Method

Parameters

TLShapeId[]

Returns

this

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

app.mark()
app.mark('flip shapes')

Parameters

string

boolean

boolean

Returns

string

moveShapesToPage()

Public Method

Move shapes to page.

Example

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

Parameters

TLShapeId[]

TLPageId

Returns

this

References

TLShapeId, TLPageId

nudgeShapes()

Public Method

Move shapes by a delta.

Example

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

Parameters

TLShapeId[]

Vec2dModel

boolean

boolean

Returns

this

References

TLShapeId, Vec2dModel

onCreateAssetFromFile()

Public Method

A callback fired when a file is converted to an asset. This callback should return the asset partial.

Example

app.onCreateAssetFromFile(myFile)

Parameters

File

Returns

Promise<TLAsset>

References

File, Promise, TLAsset

onCreateBookmarkFromUrl()

Public Method

A callback fired when a URL is converted to a bookmark. This callback should return the metadata for the bookmark.

Example

app.onCreateBookmarkFromUrl(url, id)

Parameters

string

Returns

Promise<{
  image: string
  title: string
  description: string
}>

References

Promise

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

app.pageToScreen(100, 100)

Parameters

number

number

number

Vec2dModel

Returns

{
  x: number
  y: number
  z: number
}

References

Vec2dModel

pan()

Public Method

Pan the camera.

Example

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

Parameters

number

number

AnimationOptions

Returns

this

References

AnimationOptions

panZoomIntoView()

Public Method

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

Parameters

TLShapeId[]

AnimationOptions

Returns

this

References

TLShapeId, AnimationOptions

popFocusLayer()

Public Method

Parameters

None

Returns

this

putContent()

Public Method

Parameters

TLClipboardModel

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

Returns

this

References

TLClipboardModel, VecLike

redo()

Public Method

Redo to the next mark.

Example

app.redo()

Parameters

None

Returns

this

renamePage()

Public Method

Rename a page.

Example

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

Parameters

TLPageId

string

boolean

Returns

this

References

TLPageId

reorderShapes()

Public Method

Reorder shapes.

Parameters

TLReorderOperation

TLShapeId[]

Returns

this

References

TLReorderOperation, TLShapeId

reparentShapesById()

Public Method

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

Example

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

Parameters

TLShapeId[]

TLParentId

string

Returns

this

References

TLShapeId, TLParentId

replaceStoreContentsWithRecordsForOtherDocument()

Public Method

Parameters

TLRecord[]

Returns

void

References

TLRecord

resetZoom()

Public Method

Set the zoom back to 100%.

Example

app.resetZoom()

Parameters

Vec2d

AnimationOptions

Returns

this

References

Vec2d, AnimationOptions

resizeShape()

Public Method

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

app.rotateShapesBy(['box1', 'box2'], Math.PI)
app.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

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

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

selectAll()

Public Method

Select all direct children of the current page.

Example

app.selectAll()

Parameters

None

Returns

this

selectNone()

Public Method

Clear the selection.

Example

app.selectNone()

Parameters

None

Returns

this

sendBackward()

Public Method

Send shapes backward in the page's object list.

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

sendToBack()

Public Method

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

Example

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

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

setBrush()

Public Method

Set the current brush.

Example

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

Parameters

Box2dModel | null

Returns

this

References

Box2dModel

setCamera()

Public Method

Set the current camera.

Example

app.setCamera(0, 0)
app.setCamera(0, 0, 1)

Parameters

number

number

number

ViewportOptions

Returns

this

References

ViewportOptions

setCroppingId()

Public Method

Parameters

null | TLShapeId

Returns

this

References

TLShapeId

setCurrentPageId()

Public Method

Set the current page.

Example

app.setCurrentPageId('page1')

Parameters

TLPageId

ViewportOptions

Returns

this

References

TLPageId, ViewportOptions

setCursor()

Public Method

Set the current cursor.

Example

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

Parameters

Partial<TLCursor>

Returns

this

References

Partial, TLCursor

setDarkMode()

Public Method

Parameters

boolean

Returns

void

setEditingId()

Public Method

Set the current editing id.

Parameters

null | TLShapeId

Returns

this

References

TLShapeId

setErasingIds()

Public Method

Set the current erasing shapes.

Example

app.setErasingIds(['box1', 'box2'])
app.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

setGridMode()

Public Method

Parameters

boolean

Returns

void

setHintingIds()

Public Method

Set the hinted shape ids.

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

setHoveredId()

Public Method

Set the current hovered shape.

Example

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

Parameters

null | TLShapeId

Returns

this

References

TLShapeId

setInstancePageState()

Public Method

Update a page state.

Example

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

Parameters

Partial<TLInstancePageState>

boolean

Returns

void

References

Partial, TLInstancePageState

setPenMode()

Public Method

Parameters

boolean

Returns

void

setProp()

Public Method

Set the current props (generally styles).

Example

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

Parameters

TLShapeProp

any

boolean

boolean

Returns

this

References

TLShapeProp

setReadOnly()

Public Method

Parameters

boolean

Returns

void

setScribble()

Public Method

Set the current scribble.

Example

app.setScribble(nextScribble)
app.setScribble() // clears the scribble

Parameters

null | TLScribble

Returns

this

References

TLScribble

setSelectedIds()

Public Method

Select one or more shapes.

Example

app.setSelectedIds(['id1'])
app.setSelectedIds(['id1', 'id2'])

Parameters

TLShapeId[]

boolean

Returns

this

References

TLShapeId

setSelectedTool()

Public Method

Set the selected tool.

Example

app.setSelectedTool('hand')
app.setSelectedTool('hand', { date: Date.now() })

Parameters

string

{}

Returns

this

setZoomBrush()

Public Method

Set the current zoom brush.

Example

app.setZoomBrush({ x: 0, y: 0, w: 100, h: 100 })
app.setZoomBrush() // Clears the zoom

Parameters

Box2dModel | null

Returns

this

References

Box2dModel

slideCamera()

Public Method

Parameters

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

Returns

this

References

Vec2d

stackShapes()

Public Method

Stack shape.

Example

app.stackShapes('horizontal')
app.stackShapes('horizontal', ['box1', 'box2'])
app.stackShapes('horizontal', ['box1', 'box2'], 20)

Parameters

'horizontal' | 'vertical'

TLShapeId[]

number

Returns

this

References

TLShapeId

stopCameraAnimation()

Public Method

Stop the current camera animation, if any.

Parameters

None

Returns

this

stretchShapes()

Public Method

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

Example

app.stretchShapes('horizontal')
app.stretchShapes('horizontal', ['box1', 'box2'])

Parameters

'horizontal' | 'vertical'

TLShapeId[]

Returns

this

References

TLShapeId

undo()

Public Method

Undo to the last mark.

Example

app.undo()

Parameters

None

Returns

HistoryManager<this>

References

HistoryManager

ungroupShapes()

Public Method

Parameters

TLShapeId[]

Returns

this

References

TLShapeId

updateAssets()

Public Method

Update one or more assets.

Example

app.updateAssets([{ id: 'asset1', name: 'New name' }])

Parameters

TLAssetPartial[]

Returns

this

References

TLAssetPartial

updateInstanceState()

Public Method

Set the current user tab state

Parameters

Partial<
  Omit<
    TLInstance,
    'currentPageId' | 'documentId' | 'userId'
  >
>

boolean

boolean

Returns

this

References

Partial, Omit, TLInstance

updatePage()

Public Method

Update a page.

Example

app.updatePage({ id: 'page2', name: 'Page 2' })

Parameters

RequiredKeys<TLPage, 'id'>

boolean

Returns

this

References

RequiredKeys, TLPage

updateShapes()

Public Method

Update shapes.

Example

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

Parameters

(null | TLShapePartial | undefined)[]

boolean

Returns

this

References

TLShapePartial

updateUser()

Public Method

Set user state. Always ephemeral for now.

Example

app.updateUser({ color: '#923433' })

Parameters

Partial<TLUser>

Returns

void

References

Partial, TLUser

updateUserDocumentSettings()

Public Method

Update user document settings

Example

app.updateUserDocumentSettings({ isGridMode: true })

Parameters

Partial<TLUserDocument>

boolean

Returns

this

References

Partial, TLUserDocument

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

app.updateViewportScreenBounds()

Parameters

boolean

Returns

this

visitDescendants()

Public Method

Run a visitor function for all descendants of a shape.

Example

app.visitDescendants('frame1', myCallback)

Parameters

TLParentId

(id: TLShapeId) => false | void

Returns

void

References

TLParentId, TLShapeId

zoomIn()

Public Method

Zoom the camera in.

Example

app.zoomIn()
app.zoomIn(app.viewportScreenCenter, { duration: 120 })
app.zoomIn(app.inputs.currentScreenPoint, { duration: 120 })

Parameters

Vec2d

AnimationOptions

Returns

this

References

Vec2d, AnimationOptions

zoomOut()

Public Method

Zoom the camera out.

Example

app.zoomOut()
app.zoomOut(app.viewportScreenCenter, { duration: 120 })
app.zoomOut(app.inputs.currentScreenPoint, { duration: 120 })

Parameters

Vec2d

AnimationOptions

Returns

this

References

Vec2d, AnimationOptions

zoomToBounds()

Public Method

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

Example

app.zoomToBounds(0, 0, 100, 100)

Parameters

number

number

number

number

number

AnimationOptions

Returns

this

References

AnimationOptions

zoomToFit()

Public Method

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

Example

app.zoomToFit()

Parameters

AnimationOptions

Returns

this

References

AnimationOptions

zoomToSelection()

Public Method

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

Example

app.zoomToSelection()

Parameters

AnimationOptions

Returns

this

References

AnimationOptions