Editor
See source codeTable of contents
- bindingUtils
- contextId
- disposables
- edgeScrollManager
- environment
- getContainer
- history
- inputs
- isDisposed
- menus
- options
- root
- scribbles
- shapeUtils
- sideEffects
- snaps
- store
- styleProps
- textMeasure
- timers
- user
- Properties
- Methods
- _decayCameraStateTimeout
- _flushEventForTick
- _tickCameraState
- _updateCurrentPageState
- addOpenMenu
- alignShapes
- animateShape
- animateShapes
- bail
- bailToMark
- batch
- blur
- bringForward
- bringToFront
- canBindShapes
- cancel
- cancelDoubleClick
- centerOnPoint
- clearHistory
- clearOpenMenus
- complete
- createAssets
- createBinding
- createBindings
- createDeepLink
- createPage
- createShape
- createShapes
- createTemporaryAssetPreview
- deleteAssets
- deleteBinding
- deleteBindings
- deleteOpenMenu
- deletePage
- deleteShape
- deleteShapes
- deselect
- dispatch
- dispose
- distributeShapes
- duplicatePage
- duplicateShapes
- findCommonAncestor
- findShapeAncestor
- flipShapes
- focus
- getAncestorPageId
- getAsset
- getAssetForExternalContent
- getAssets
- getBaseZoom
- getBinding
- getBindingsFromShape
- getBindingsInvolvingShape
- getBindingsToShape
- getBindingUtil
- getCamera
- getCameraOptions
- getCameraState
- getCanRedo
- getCanUndo
- getCollaborators
- getCollaboratorsOnCurrentPage
- getContentFromCurrentPage
- getCroppingShapeId
- getCulledShapes
- getCurrentPage
- getCurrentPageBounds
- getCurrentPageId
- getCurrentPageRenderingShapesSorted
- getCurrentPageShapeIds
- getCurrentPageShapes
- getCurrentPageShapesSorted
- getCurrentPageState
- getCurrentTool
- getCurrentToolId
- getDocumentSettings
- getDroppingOverShape
- getEditingShape
- getEditingShapeId
- getErasingShapeIds
- getErasingShapes
- getFocusedGroup
- getFocusedGroupId
- getHighestIndexForParent
- getHintingShape
- getHintingShapeIds
- getHoveredShape
- getHoveredShapeId
- getInitialMetaForShape
- getInitialZoom
- getInstanceState
- getIsFocused
- getIsMenuOpen
- getIsReadonly
- getOnlySelectedShape
- getOnlySelectedShapeId
- getOpenMenus
- getOutermostSelectableShape
- getPage
- getPages
- getPageShapeIds
- getPageStates
- getPath
- getPointInParentSpace
- getPointInShapeSpace
- getRenderingShapes
- getSelectedShapeAtPoint
- getSelectedShapeIds
- getSelectedShapes
- getSelectionPageBounds
- getSelectionRotatedPageBounds
- getSelectionRotatedScreenBounds
- getSelectionRotation
- getShape
- getShapeAncestors
- getShapeAndDescendantIds
- getShapeAtPoint
- getShapeClipPath
- getShapeGeometry
- getShapeHandles
- getShapeLocalTransform
- getShapeMask
- getShapeMaskedPageBounds
- getShapePageBounds
- getShapePageTransform
- getShapeParent
- getShapeParentTransform
- getShapesAtPoint
- getShapeStyleIfExists
- getShapeUtil
- getSharedOpacity
- getSharedStyles
- getSnapshot
- getSortedChildIdsForParent
- getStateDescendant
- getStyleForNextShape
- getSvg
- getSvgElement
- getSvgString
- getTemporaryAssetPreview
- getViewportPageBounds
- getViewportScreenBounds
- getViewportScreenCenter
- getZoomLevel
- groupShapes
- hasAncestor
- hasExternalAssetHandler
- interrupt
- isAncestorSelected
- isIn
- isInAny
- isPointInShape
- isShapeHidden
- isShapeInPage
- isShapeOfType
- isShapeOrAncestorLocked
- loadSnapshot
- mark
- markHistoryStoppingPoint
- moveShapesToPage
- navigateToDeepLink
- nudgeShapes
- packShapes
- pageToScreen
- pageToViewport
- popFocusedGroupId
- putContentOntoCurrentPage
- putExternalContent
- redo
- registerDeepLinkListener
- registerExternalAssetHandler
- registerExternalContentHandler
- renamePage
- reparentShapes
- resetZoom
- resizeShape
- resolveAssetsInContent
- resolveAssetUrl
- rotateShapesBy
- run
- screenToPage
- select
- selectAll
- selectNone
- sendBackward
- sendToBack
- setCamera
- setCameraOptions
- setCroppingShape
- setCurrentPage
- setCurrentTool
- setCursor
- setEditingShape
- setErasingShapes
- setFocusedGroup
- setHintingShapes
- setHoveredShape
- setOpacityForNextShapes
- setOpacityForSelectedShapes
- setSelectedShapes
- setStyleForNextShapes
- setStyleForSelectedShapes
- slideCamera
- squashToMark
- stackShapes
- startFollowingUser
- stopCameraAnimation
- stopFollowingUser
- stretchShapes
- toggleLock
- undo
- ungroupShapes
- updateAssets
- updateBinding
- updateBindings
- updateCurrentPageState
- updateDocumentSettings
- updateInstanceState
- updatePage
- updateShape
- updateShapes
- updateViewportScreenBounds
- uploadAsset
- visitDescendants
- zoomIn
- zoomOut
- zoomToBounds
- zoomToFit
- zoomToSelection
- zoomToUser
Extends EventEmitter<TLEventMap>
.
class Editor extends EventEmitter<TLEventMap> {}
Constructor
Constructs a new instance of the Editor
class
Parameters
Name | Description |
---|---|
|
Properties
bindingUtils
A map of shape utility classes (TLShapeUtils) by shape type.
bindingUtils: {
readonly [K in string]?: BindingUtil<TLUnknownBinding>
}
contextId
readonly contextId: string
disposables
A set of functions to call when the app is disposed.
readonly disposables: Set<() => void>
edgeScrollManager
A manager for moving the camera when the mouse is at the edge of the screen.
edgeScrollManager: EdgeScrollManager
environment
Deprecated:
This is deprecated and will be removed in a future version. Use the tlenv
global export instead.
A manager for the editor's environment.
readonly environment: {
isAndroid: boolean
isChromeForIos: boolean
isDarwin: boolean
isFirefox: boolean
isIos: boolean
isSafari: boolean
isWebview: boolean
}
getContainer
The current HTML element containing the editor.
getContainer: () => HTMLElement
Example
const container = editor.getContainer()
history
A manager for the app's history.
protected readonly history: HistoryManager<TLRecord>
inputs
The app's current input state.
inputs: {
buttons: Set<number>
keys: Set<string>
originScreenPoint: Vec
originPagePoint: Vec
currentScreenPoint: Vec
currentPagePoint: Vec
previousScreenPoint: Vec
previousPagePoint: Vec
pointerVelocity: Vec
altKey: boolean
ctrlKey: boolean
isPen: boolean
metaKey: boolean
shiftKey: boolean
isDragging: boolean
isEditing: boolean
isPanning: boolean
isPinching: boolean
isPointing: boolean
isSpacebarPanning: boolean
}
isDisposed
Whether the editor is disposed.
isDisposed: boolean
menus
menus: {
addOpenMenu: (id: string) => void
clearOpenMenus: () => void
deleteOpenMenu: (id: string) => void
getOpenMenus: () => string[]
hasAnyOpenMenus: () => boolean
hasOpenMenus: () => boolean
isMenuOpen: (id: string) => boolean
}
options
readonly options: TldrawOptions
root
The root state of the statechart.
readonly root: StateNode
scribbles
A manager for the editor's scribbles.
readonly scribbles: ScribbleManager
shapeUtils
A map of shape utility classes (TLShapeUtils) by shape type.
shapeUtils: {
readonly [K in string]?: ShapeUtil<TLUnknownShape>
}
sideEffects
A manager for side effects and correct state enforcement. See StoreSideEffects for details.
readonly sideEffects: StoreSideEffects<TLRecord>
snaps
A manager for the app's snapping feature.
readonly snaps: SnapManager
store
The editor's store
readonly store: TLStore
styleProps
styleProps: {
[key: string]: Map<StyleProp<any>, string>
}
textMeasure
A helper for measuring text.
readonly textMeasure: TextManager
timers
A manager for the any asynchronous events and making sure they're cleaned up upon disposal.
readonly timers: {
dispose: () => void
requestAnimationFrame: (callback: FrameRequestCallback) => number
setInterval: (
handler: TimerHandler,
timeout?: number | undefined,
...args: any[]
) => number
setTimeout: (
handler: TimerHandler,
timeout?: number | undefined,
...args: any[]
) => number
}
user
A manager for the user and their preferences.
readonly user: UserPreferencesManager
Methods
addOpenMenu()
Deprecated:
Use editor.menus.addOpenMenu
instead.
addOpenMenu(id: string): this
Parameters
Name | Description |
---|---|
|
|
Returns
this
alignShapes()
Align shape positions.
alignShapes(
shapes: TLShape[] | TLShapeId[],
operation:
| 'bottom'
| 'center-horizontal'
| 'center-vertical'
| 'left'
| 'right'
| 'top'
): this
Example
editor.alignShapes([box1, box2], 'left')
editor.alignShapes(editor.getSelectedShapeIds(), 'left')
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to align. |
|
The align operation to apply. |
Returns
this
animateShape()
Animate a shape.
animateShape(
partial: null | TLShapePartial | undefined,
opts?: TLCameraMoveOptions
): this
Example
editor.animateShape({ id: 'box1', type: 'box', x: 100, y: 100 })
editor.animateShape(
{ id: 'box1', type: 'box', x: 100, y: 100 },
{ animation: { duration: 100, ease: (t) => t * t } }
)
Parameters
Name | Description |
---|---|
|
The shape partial to update. |
| The animation's options. |
Returns
this
animateShapes()
Animate shapes.
animateShapes(
partials: (null | TLShapePartial | undefined)[],
opts?: TLCameraMoveOptions
): this
Example
editor.animateShapes([{ id: 'box1', type: 'box', x: 100, y: 100 }])
editor.animateShapes([{ id: 'box1', type: 'box', x: 100, y: 100 }], {
animation: { duration: 100, ease: (t) => t * t },
})
Parameters
Name | Description |
---|---|
|
The shape partials to update. |
| The animation's options. |
Returns
this
bail()
Undo to the closest mark, discarding the changes so they cannot be redone.
bail(): this
Example
editor.bail()
bailToMark()
Undo to the given mark, discarding the changes so they cannot be redone.
bailToMark(id: string): this
Example
const beginDrag = editor.markHistoryStoppingPoint()
// ... some changes
editor.bailToMark(beginDrag)
Parameters
Name | Description |
---|---|
|
|
Returns
this
batch()
Deprecated:
Use Editor.run
instead.
batch(fn: () => void, opts?: TLEditorRunOptions): this
Parameters
Name | Description |
---|---|
|
|
|
Returns
this
blur()
Switches off the editor's focused mode.
This makes the editor ignore keyboard events and some pointer events (move, wheel).
blur({ blurContainer }?: { blurContainer?: boolean | undefined }): this
Example
editor.blur()
By default this also dispatches a 'blur' event to the container element. To prevent this, pass blurContainer: false
.
editor.blur({ blurContainer: false })
Parameters
Name | Description |
---|---|
|
|
Returns
this
bringForward()
Bring shapes forward in the page's object list.
Example
editor.bringForward(['id1', 'id2'])
editor.bringForward(box1, box2)
Parameters
Returns
this
bringToFront()
Bring shapes to the front of the page's object list.
Example
editor.bringToFront(['id1', 'id2'])
editor.bringToFront([box1, box2])
Parameters
Returns
this
canBindShapes()
canBindShapes({
fromShape,
toShape,
binding,
}: {
binding:
| {
type: TLBinding['type']
}
| TLBinding
| TLBinding['type']
fromShape:
| {
type: TLShape['type']
}
| TLShape
| TLShape['type']
toShape:
| {
type: TLShape['type']
}
| TLShape
| TLShape['type']
}): boolean
Parameters
Name | Description |
---|---|
|
Returns
boolean
cancel()
Dispatch a cancel event.
cancel(): this
Example
editor.cancel()
cancelDoubleClick()
Prevent a double click event from firing the next time the user clicks
cancelDoubleClick(): void
centerOnPoint()
Center the camera on a point (in the current page space).
centerOnPoint(point: VecLike, opts?: TLCameraMoveOptions): this
Example
editor.centerOnPoint({ x: 100, y: 100 })
editor.centerOnPoint({ x: 100, y: 100 }, { animation: { duration: 200 } })
Parameters
Name | Description |
---|---|
| The point in the current page space to center on. |
| The camera move options. |
Returns
this
clearHistory()
clearHistory(): this
clearOpenMenus()
Deprecated:
Use editor.menus.clearOpenMenus
instead.
clearOpenMenus(): this
complete()
Dispatch a complete event.
complete(): this
Example
editor.complete()
createAssets()
Create one or more assets.
createAssets(assets: TLAsset[]): this
Example
editor.createAssets([...myAssets])
Parameters
Name | Description |
---|---|
|
The assets to create. |
Returns
this
createBinding()
Create a single binding from a partial. You can omit the ID and most props of a binding, but
the type
, toId
, and fromId
must all be provided.
createBinding<B extends TLBinding = TLBinding>(
partial: TLBindingCreate<B>
): this
Parameters
Name | Description |
---|---|
|
Returns
this
createBindings()
Create bindings from a list of partial bindings. You can omit the ID and most props of a
binding, but the type
, toId
, and fromId
must all be provided.
createBindings(partials: TLBindingCreate[]): this
Parameters
Name | Description |
---|---|
|
Returns
this
createDeepLink()
Turns the given URL into a deep link by adding a query parameter.
e.g. https://my-app.com/my-document?d=100.100.200.200.xyz123
If no URL is provided, it will use the current window.location.href
.
createDeepLink(opts?: {
param?: string
to?: TLDeepLink
url?: string | URL
}): URL
Example
// create a deep link to the current page + viewport
navigator.clipboard.writeText(editor.createDeepLink())
You can link to a particular set of shapes by providing a to
parameter.
// create a deep link to the set of currently selected shapes
navigator.clipboard.writeText(
editor.createDeepLink({
to: { type: 'selection', shapeIds: editor.getSelectedShapeIds() },
})
)
The default query param is 'd'. You can override this by providing a param
parameter.
// Use `x` as the param name instead
editor.createDeepLink({ param: 'x' })
Parameters
Name | Description |
---|---|
|
Options for adding the state to the URL. |
Returns
URL
the updated URL
createPage()
Create a page.
createPage(page: Partial<TLPage>): this
Example
editor.createPage(myPage)
editor.createPage({ name: 'Page 2' })
Parameters
Name | Description |
---|---|
|
The page (or page partial) to create. |
Returns
this
createShape()
Create a single shape.
createShape<T extends TLUnknownShape>(
shape: OptionalKeys<TLShapePartial<T>, 'id'>
): this
Example
editor.createShape(myShape)
editor.createShape({ id: 'box1', type: 'text', props: { text: 'ok' } })
Parameters
Name | Description |
---|---|
|
The shape (or shape partial) to create. |
Returns
this
createShapes()
Create shapes.
createShapes<T extends TLUnknownShape>(
shapes: OptionalKeys<TLShapePartial<T>, 'id'>[]
): this
Example
editor.createShapes([myShape])
editor.createShapes([{ id: 'box1', type: 'text', props: { text: 'ok' } }])
Parameters
Name | Description |
---|---|
|
The shapes (or shape partials) to create. |
Returns
this
createTemporaryAssetPreview()
Register a temporary preview of an asset. This is useful for showing a ghost image of something that is being uploaded. Retrieve the placeholder with Editor.getTemporaryAssetPreview. Placeholders last for 3 minutes by default, but this can be configured using
createTemporaryAssetPreview(
assetId: TLAssetId,
file: File
): string | undefined
Example
editor.createTemporaryAssetPreview(assetId, file)
Parameters
Name | Description |
---|---|
| The asset's id. |
|
The raw file. |
Returns
string | undefined
deleteAssets()
Delete one or more assets.
Example
editor.deleteAssets(['asset1', 'asset2'])
Parameters
Returns
this
deleteBinding()
Delete a binding by its ID. If the binding doesn't exist, it's ignored.
deleteBinding(
binding: TLBinding | TLBindingId,
opts?: Parameters<this['deleteBindings']>[1]
): this
Parameters
Name | Description |
---|---|
| |
|
|
Returns
this
deleteBindings()
Delete several bindings by their IDs. If a binding ID doesn't exist, it's ignored.
deleteBindings(
bindings: (TLBinding | TLBindingId)[],
{
isolateShapes,
}?: {
isolateShapes?: boolean | undefined
}
): this
Parameters
Name | Description |
---|---|
|
|
|
|
Returns
this
deleteOpenMenu()
Deprecated:
Use editor.menus.deleteOpenMenu
instead.
deleteOpenMenu(id: string): this
Parameters
Name | Description |
---|---|
|
|
Returns
this
deletePage()
Delete a page.
Example
editor.deletePage('page1')
Parameters
Returns
this
deleteShape()
Delete a shape.
deleteShape(id: TLShapeId): this
Example
editor.deleteShape(shape.id)
Parameters
Name | Description |
---|---|
| The id of the shape to delete. |
Returns
this
deleteShapes()
Delete shapes.
deleteShapes(ids: TLShapeId[]): this
Example
editor.deleteShapes(['box1', 'box2'])
Parameters
Name | Description |
---|---|
| The ids of the shapes to delete. |
Returns
this
deselect()
Remove a shape from the existing set of selected shapes.
Example
editor.deselect(shape.id)
Parameters
Returns
this
dispatch()
Dispatch an event to the editor.
dispatch(info: TLEventInfo): this
Example
editor.dispatch(myPointerEvent)
Parameters
Name | Description |
---|---|
| The event info. |
Returns
this
dispose()
Dispose the editor.
dispose(): void
distributeShapes()
Distribute shape positions.
Example
editor.distributeShapes([box1, box2], 'horizontal')
editor.distributeShapes(editor.getSelectedShapeIds(), 'horizontal')
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to distribute. |
|
Whether to distribute shapes horizontally or vertically. |
Returns
this
duplicatePage()
Duplicate a page.
Parameters
Name | Description |
---|---|
| The page (or the page id) to duplicate. Defaults to the current page. |
| The id of the new page. Defaults to a new id. |
Returns
this
duplicateShapes()
Duplicate shapes.
Example
editor.duplicateShapes(['box1', 'box2'], { x: 8, y: 8 })
editor.duplicateShapes(editor.getSelectedShapes(), { x: 8, y: 8 })
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to duplicate. |
| The offset (in pixels) to apply to the duplicated shapes. |
Returns
this
findCommonAncestor()
Get the common ancestor of two or more shapes that matches a predicate.
findCommonAncestor(
shapes: TLShape[] | TLShapeId[],
predicate?: (shape: TLShape) => boolean
): TLShapeId | undefined
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to check. |
|
The predicate to match. |
Returns
TLShapeId | undefined
findShapeAncestor()
Find the first ancestor matching the given predicate
findShapeAncestor(
shape: TLShape | TLShapeId,
predicate: (parent: TLShape) => boolean
): TLShape | undefined
Example
const ancestor = editor.findShapeAncestor(myShape)
const ancestor = editor.findShapeAncestor(myShape.id)
const ancestor = editor.findShapeAncestor(
myShape.id,
(shape) => shape.type === 'frame'
)
Parameters
Name | Description |
---|---|
| The shape to check the ancestors for. |
|
The predicate to match. |
Returns
TLShape | undefined
flipShapes()
Flip shape positions.
Example
editor.flipShapes([box1, box2], 'horizontal', 32)
editor.flipShapes(editor.getSelectedShapeIds(), 'horizontal', 32)
Parameters
Name | Description |
---|---|
| The ids of the shapes to flip. |
|
Whether to flip horizontally or vertically. |
Returns
this
focus()
Puts the editor into focused mode.
This makes the editor eligible to receive keyboard events and some pointer events (move, wheel).
focus({ focusContainer }?: { focusContainer?: boolean | undefined }): this
Example
editor.focus()
By default this also dispatches a 'focus' event to the container element. To prevent this, pass focusContainer: false
.
editor.focus({ focusContainer: false })
Parameters
Name | Description |
---|---|
|
|
Returns
this
getAncestorPageId()
Get the id of the containing page for a given shape.
Parameters
Returns
TLPageId | undefined
The id of the page that contains the shape, or undefined if the shape is undefined.
getAsset()
Get an asset by its id.
Example
editor.getAsset('asset1')
Parameters
Returns
TLAsset | undefined
getAssetForExternalContent()
Get an asset for an external asset content type.
getAssetForExternalContent(
info: TLExternalAssetContent
): Promise<TLAsset | undefined>
Example
const asset = await editor.getAssetForExternalContent({
type: 'file',
file: myFile,
})
const asset = await editor.getAssetForExternalContent({
type: 'url',
url: myUrl,
})
Parameters
Name | Description |
---|---|
| Info about the external content. |
Returns
Promise<TLAsset | undefined>
The asset.
getAssets()
Get all assets in the editor.
getAssets(): (
| import('@tldraw/tlschema').TLBookmarkAsset
| TLImageAsset
| TLVideoAsset
)[]
getBaseZoom()
Get the camera's base level for calculating actual zoom levels based on the zoom steps.
getBaseZoom(): number
Example
editor.getBaseZoom()
getBinding()
Get a binding from the store by its ID if it exists.
getBinding(id: TLBindingId): TLBinding | undefined
Parameters
Name | Description |
---|---|
|
Returns
TLBinding | undefined
getBindingsFromShape()
Get all bindings of a certain type from a particular shape. These are the bindings whose
fromId
matched the shape's ID.
getBindingsFromShape<Binding extends TLUnknownBinding = TLBinding>(
shape: TLShape | TLShapeId,
type: Binding['type']
): Binding[]
Parameters
Returns
Binding[]
getBindingsInvolvingShape()
Get all bindings involving a particular shape. This includes bindings where the shape is the
fromId
or toId
. If a type is provided, only bindings of that type are returned.
getBindingsInvolvingShape<Binding extends TLUnknownBinding = TLBinding>(
shape: TLShape | TLShapeId,
type?: Binding['type']
): Binding[]
Parameters
Returns
Binding[]
getBindingsToShape()
Get all bindings of a certain type to a particular shape. These are the bindings whose
toId
matches the shape's ID.
getBindingsToShape<Binding extends TLUnknownBinding = TLBinding>(
shape: TLShape | TLShapeId,
type: Binding['type']
): Binding[]
Parameters
Returns
Binding[]
getBindingUtil()
Get a binding util from a binding itself.
getBindingUtil<S extends TLUnknownBinding>(
binding:
| {
type: S['type']
}
| S
): BindingUtil<S>
Example
const util = editor.getBindingUtil(myArrowBinding)
const util = editor.getBindingUtil('arrow')
const util = editor.getBindingUtil<TLArrowBinding>(myArrowBinding)
const util = editor.getBindingUtil(TLArrowBinding)('arrow')
Parameters
Name | Description |
---|---|
|
A binding, binding partial, or binding type. |
Returns
BindingUtil<S>
getCamera()
The current camera.
getCamera(): TLCamera
getCameraOptions()
Get the current camera options.
getCameraOptions(): TLCameraOptions
Example
editor.getCameraOptions()
getCameraState()
Whether the camera is moving or idle.
getCameraState(): 'idle' | 'moving'
Example
editor.getCameraState()
getCanRedo()
Whether the app can redo.
getCanRedo(): boolean
getCanUndo()
Whether the app can undo.
getCanUndo(): boolean
getCollaborators()
Returns a list of presence records for all peer collaborators. This will return the latest presence record for each connected user.
getCollaborators(): import('@tldraw/tlschema').TLInstancePresence[]
getCollaboratorsOnCurrentPage()
Returns a list of presence records for all peer collaborators on the current page. This will return the latest presence record for each connected user.
getCollaboratorsOnCurrentPage(): import('@tldraw/tlschema').TLInstancePresence[]
getContentFromCurrentPage()
Get content that can be exported for the given shape ids.
Parameters
Returns
TLContent | undefined
The exported content.
getCroppingShapeId()
The current cropping shape's id.
getCroppingShapeId(): null | TLShapeId
getCulledShapes()
Get culled shapes.
getCulledShapes(): Set<TLShapeId>
getCurrentPage()
The current page.
getCurrentPage(): TLPage
Example
editor.getCurrentPage()
getCurrentPageBounds()
The bounds of the current page (the common bounds of all of the shapes on the page).
getCurrentPageBounds(): Box | undefined
getCurrentPageId()
The current page id.
getCurrentPageId(): TLPageId
Example
editor.getCurrentPageId()
getCurrentPageRenderingShapesSorted()
An array containing all of the rendering shapes in the current page, sorted in z-index order (accounting for nested shapes): e.g. A, B, BA, BB, C.
getCurrentPageRenderingShapesSorted(): TLShape[]
getCurrentPageShapeIds()
An array of all of the shapes on the current page.
getCurrentPageShapeIds(): Set<TLShapeId>
Example
editor.getCurrentPageIds()
getCurrentPageShapes()
An array containing all of the shapes in the current page.
getCurrentPageShapes(): TLShape[]
getCurrentPageShapesSorted()
An array containing all of the shapes in the current page, sorted in z-index order (accounting for nested shapes): e.g. A, B, BA, BB, C.
getCurrentPageShapesSorted(): TLShape[]
getCurrentPageState()
The current page state.
getCurrentPageState(): TLInstancePageState
getCurrentTool()
The current selected tool.
getCurrentTool(): StateNode
getCurrentToolId()
The id of the current selected tool.
getCurrentToolId(): string
getDocumentSettings()
The global document settings that apply to all users.
getDocumentSettings(): TLDocument
getDroppingOverShape()
Get the shape that some shapes should be dropped on at a given point.
getDroppingOverShape(
point: VecLike,
droppingShapes?: TLShape[]
): TLUnknownShape | undefined
Parameters
Name | Description |
---|---|
| The point to find the parent for. |
|
The shapes that are being dropped. |
Returns
TLUnknownShape | undefined
The shape to drop on.
getEditingShape()
The current editing shape.
getEditingShape(): TLShape | undefined
getEditingShapeId()
The current editing shape's id.
getEditingShapeId(): null | TLShapeId
getErasingShapeIds()
The editor's current erasing ids.
getErasingShapeIds(): TLShapeId[]
getErasingShapes()
The editor's current erasing shapes.
getErasingShapes(): NonNullable<TLShape | undefined>[]
getFocusedGroup()
The current focused group.
getFocusedGroup(): TLShape | undefined
getFocusedGroupId()
The current focused group id.
getHighestIndexForParent()
Get the index above the highest child of a given parent.
getHighestIndexForParent(parent: TLPage | TLParentId | TLShape): IndexKey
Parameters
Name | Description |
---|---|
|
The parent (or the id) of the parent. |
Returns
IndexKey
The index.
getHintingShape()
The editor's current hinting shapes.
getHintingShape(): NonNullable<TLShape | undefined>[]
getHintingShapeIds()
The editor's current hinting shape ids.
getHintingShapeIds(): TLShapeId[]
getHoveredShape()
The current hovered shape.
getHoveredShape(): TLShape | undefined
getHoveredShapeId()
The current hovered shape id.
getHoveredShapeId(): null | TLShapeId
getInitialMetaForShape()
Get the initial meta value for a shape.
getInitialMetaForShape(_shape: TLShape): JsonObject
Example
editor.getInitialMetaForShape = (shape) => {
if (shape.type === 'note') {
return { createdBy: myCurrentUser.id }
}
}
Parameters
Name | Description |
---|---|
|
Returns
JsonObject
getInitialZoom()
Get the camera's initial or reset zoom level.
getInitialZoom(): number
Example
editor.getInitialZoom()
getInstanceState()
The current instance's state.
getInstanceState(): TLInstance
getIsFocused()
getIsFocused(): boolean
getIsMenuOpen()
Deprecated:
Use editor.menus.hasAnyOpenMenus
instead.
getIsMenuOpen(): boolean
getIsReadonly()
getIsReadonly(): boolean
getOnlySelectedShape()
The app's only selected shape.
getOnlySelectedShape(): null | TLShape
getOnlySelectedShapeId()
The id of the app's only selected shape.
getOnlySelectedShapeId(): null | TLShapeId
getOpenMenus()
Deprecated:
Use editor.menus.getOpenMenus
instead.
getOpenMenus(): string[]
getOutermostSelectableShape()
Get the shape that should be selected when you click on a given shape, assuming there is nothing already selected. It will not return anything higher than or including the current focus layer.
getOutermostSelectableShape(
shape: TLShape | TLShapeId,
filter?: (shape: TLShape) => boolean
): TLShape
Parameters
Name | Description |
---|---|
| The shape to get the outermost selectable shape for. |
|
A function to filter the selectable shapes. |
Returns
The outermost selectable shape.
getPage()
Get a page.
Example
editor.getPage(myPage.id)
editor.getPage(myPage)
Parameters
Returns
TLPage | undefined
getPages()
Info about the project's current pages.
getPages(): TLPage[]
Example
editor.getPages()
getPageShapeIds()
Get the ids of shapes on a page.
Example
const idsOnPage1 = editor.getPageShapeIds('page1')
const idsOnPage2 = editor.getPageShapeIds(myPage2)
Parameters
Returns
Set<TLShapeId>
getPageStates()
Page states.
getPageStates(): TLInstancePageState[]
getPath()
The editor's current path of active states.
getPath(): string
Example
editor.getPath() // "select.idle"
getPointInParentSpace()
Convert a delta in the current page space to a point in the local space of a shape's parent.
Example
editor.getPointInParentSpace(myShape.id, { x: 100, y: 100 })
Parameters
Name | Description |
---|---|
| The shape to get the point in the local space of. |
| The page point to get in the local space of the shape. |
Returns
getPointInShapeSpace()
Convert a point in the current page space to a point in the local space of a shape. For example, if a
shape's page point were { x: 100, y: 100 }
, a page point at { x: 110, y: 110 }
would be at
{ x: 10, y: 10 }
in the shape's local space.
Example
editor.getPointInShapeSpace(myShape, { x: 100, y: 100 })
Parameters
Name | Description |
---|---|
| The shape to get the point in the local space of. |
| The page point to get in the local space of the shape. |
Returns
getRenderingShapes()
Get the shapes that should be displayed in the current viewport.
getRenderingShapes(): TLRenderingShape[]
Example
editor.getRenderingShapes()
getSelectedShapeAtPoint()
Get the top-most selected shape at the given point, ignoring groups.
Parameters
Name | Description |
---|---|
| The point to check. |
Returns
TLShape | undefined
The top-most selected shape at the given point, or undefined if there is no shape at the point.
getSelectedShapeIds()
The current selected ids.
getSelectedShapeIds(): TLShapeId[]
getSelectedShapes()
An array containing all of the currently selected shapes.
getSelectedShapes(): TLShape[]
getSelectionPageBounds()
The current page bounds of all the selected shapes. If the selection is rotated, then these bounds are the axis-aligned box that the rotated bounds would fit inside of.
getSelectionPageBounds(): Box | null
getSelectionRotatedPageBounds()
The bounds of the selection bounding box in the current page space.
getSelectionRotatedPageBounds(): Box | undefined
getSelectionRotatedScreenBounds()
The bounds of the selection bounding box in the current page space.
getSelectionRotatedScreenBounds(): Box | undefined
getSelectionRotation()
The rotation of the selection bounding box in the current page space.
getSelectionRotation(): number
getShape()
Get a shape by its id.
getShape<T extends TLShape = TLShape>(
shape: TLParentId | TLShape
): T | undefined
Example
editor.getShape('box1')
Parameters
Name | Description |
---|---|
| The shape (or the id of the shape) to get. |
Returns
T | undefined
getShapeAncestors()
Get the ancestors of a shape.
Example
const ancestors = editor.getShapeAncestors(myShape)
const ancestors = editor.getShapeAncestors(myShapeId)
Parameters
Name | Description |
---|---|
| The shape (or shape id) to get the ancestors for. |
|
The accumulator. |
Returns
TLShape[]
getShapeAndDescendantIds()
Get the shape ids of all descendants of the given shapes (including the shapes themselves). IDs are returned in z-index order.
Parameters
Name | Description |
---|---|
| The ids of the shapes to get descendants of. |
Returns
Set<TLShapeId>
The descendant ids.
getShapeAtPoint()
Get the shape at the current point.
getShapeAtPoint(
point: VecLike,
opts?: {
filter?(shape: TLShape): boolean
hitFrameInside?: boolean | undefined
hitInside?: boolean | undefined
hitLabels?: boolean | undefined
hitLocked?: boolean | undefined
margin?: number | undefined
renderingOnly?: boolean | undefined
}
): TLShape | undefined
Parameters
Name | Description |
---|---|
| The point to check. |
|
Options for the check: |
Returns
TLShape | undefined
The shape at the given point, or undefined if there is no shape at the point.
getShapeClipPath()
Get the clip path for a shape.
Example
const clipPath = editor.getShapeClipPath(shape)
const clipPath = editor.getShapeClipPath(shape.id)
Parameters
Returns
string | undefined
The clip path or undefined.
getShapeGeometry()
Get the geometry of a shape.
getShapeGeometry<T extends Geometry2d>(shape: TLShape | TLShapeId): T
Example
editor.getShapeGeometry(myShape)
editor.getShapeGeometry(myShapeId)
Parameters
Returns
T
getShapeHandles()
Get the handles (if any) for a shape.
Example
editor.getShapeHandles(myShape)
editor.getShapeHandles(myShapeId)
Parameters
Name | Description |
---|---|
|
The shape (or shape id) to get the handles for. |
Returns
TLHandle[] | undefined
getShapeLocalTransform()
Get the local transform for a shape as a matrix model. This transform reflects both its translation (x, y) from from either its parent's top left corner, if the shape's parent is another shape, or else from the 0,0 of the page, if the shape's parent is the page; and the shape's rotation.
Example
editor.getShapeLocalTransform(myShape)
Parameters
Returns
getShapeMask()
Get the mask (in the current page space) for a shape.
Example
const pageMask = editor.getShapeMask(shape.id)
Parameters
Name | Description |
---|---|
| The shape (or the shape id) of the shape to get the mask for. |
Returns
undefined | VecLike[]
The mask for the shape.
getShapeMaskedPageBounds()
Get the bounds of a shape in the current page space, incorporating any masks. For example, if the shape were the child of a frame and was half way out of the frame, the bounds would be the half of the shape that was in the frame.
Example
editor.getShapeMaskedPageBounds(myShape)
editor.getShapeMaskedPageBounds(myShapeId)
Parameters
Returns
Box | undefined
getShapePageBounds()
Get the bounds of a shape in the current page space.
Example
editor.getShapePageBounds(myShape)
editor.getShapePageBounds(myShapeId)
Parameters
Returns
Box | undefined
getShapePageTransform()
Get the transform of a shape in the current page space.
Example
editor.getShapePageTransform(myShape)
editor.getShapePageTransform(myShapeId)
Parameters
Returns
getShapeParent()
Get the parent shape for a given shape. Returns undefined if the shape is the direct child of the page.
Example
editor.getShapeParent(myShape)
Parameters
Returns
TLShape | undefined
getShapeParentTransform()
Get the local transform of a shape's parent as a matrix model.
Example
editor.getShapeParentTransform(myShape)
Parameters
Returns
getShapesAtPoint()
Get the shapes, if any, at a given page point.
getShapesAtPoint(
point: VecLike,
opts?: {
hitInside?: boolean | undefined
margin?: number | undefined
}
): TLShape[]
Example
editor.getShapesAtPoint({ x: 100, y: 100 })
editor.getShapesAtPoint({ x: 100, y: 100 }, { hitInside: true, exact: true })
Parameters
Name | Description |
---|---|
| The page point to test. |
|
The options for the hit point testing. |
Returns
TLShape[]
getShapeStyleIfExists()
Parameters
Returns
T | undefined
getShapeUtil()
Get a shape util from a shape itself.
getShapeUtil<S extends TLUnknownShape>(
shape: S | TLShapePartial<S>
): ShapeUtil<S>
Example
const util = editor.getShapeUtil(myArrowShape)
const util = editor.getShapeUtil('arrow')
const util = editor.getShapeUtil<TLArrowShape>(myArrowShape)
const util = editor.getShapeUtil(TLArrowShape)('arrow')
Parameters
Name | Description |
---|---|
|
A shape, shape partial, or shape type. |
Returns
ShapeUtil<S>
getSharedOpacity()
Get the currently selected shared opacity. If any shapes are selected, this returns the shared opacity of the selected shapes. Otherwise, this returns the chosen opacity for the next shape.
getSharedOpacity(): SharedStyle<number>
getSharedStyles()
A map of all the current styles either in the current selection, or that are relevant to the current tool.
getSharedStyles(): ReadonlySharedStyleMap
Example
const color = editor.getSharedStyles().get(DefaultColorStyle)
if (color && color.type === 'shared') {
print('All selected shapes have the same color:', color.value)
}
getSnapshot()
getSnapshot(): TLEditorSnapshot
getSortedChildIdsForParent()
Get an array of all the children of a shape.
getSortedChildIdsForParent(parent: TLPage | TLParentId | TLShape): TLShapeId[]
Example
editor.getSortedChildIdsForParent('frame1')
Parameters
Name | Description |
---|---|
|
The parent (or the id) of the parent shape. |
Returns
getStateDescendant()
Get a descendant by its path.
getStateDescendant<T extends StateNode>(path: string): T | undefined
Example
state.getStateDescendant('select')
state.getStateDescendant('select.brushing')
Parameters
Name | Description |
---|---|
|
The descendant's path of state ids, separated by periods. |
Returns
T | undefined
getStyleForNextShape()
Get the style for the next shape.
getStyleForNextShape<T>(style: StyleProp<T>): T
Example
const color = editor.getStyleForNextShape(DefaultColorStyle)
Parameters
Name | Description |
---|---|
|
The style to get. |
Returns
T
getSvg()
Deprecated: Use Editor.getSvgString or Editor.getSvgElement instead.
getSvg(
shapes: TLShape[] | TLShapeId[],
opts?: TLImageExportOptions
): Promise<SVGSVGElement | undefined>
Parameters
Name | Description |
---|---|
| |
|
Returns
Promise<SVGSVGElement | undefined>
getSvgElement()
Get an exported SVG element of the given shapes.
getSvgElement(
shapes: TLShape[] | TLShapeId[],
opts?: TLImageExportOptions
): Promise<
| {
height: number
svg: SVGSVGElement
width: number
}
| undefined
>
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to export. |
| Options for the export. |
Returns
Promise<
| {
height: number
svg: SVGSVGElement
width: number
}
| undefined
>
The SVG element.
getSvgString()
Get an exported SVG string of the given shapes.
getSvgString(
shapes: TLShape[] | TLShapeId[],
opts?: TLImageExportOptions
): Promise<
| {
height: number
svg: string
width: number
}
| undefined
>
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to export. |
| Options for the export. |
Returns
Promise<
| {
height: number
svg: string
width: number
}
| undefined
>
The SVG element.
getTemporaryAssetPreview()
Get temporary preview of an asset. This is useful for showing a ghost image of something that is being uploaded.
getTemporaryAssetPreview(assetId: TLAssetId): string | undefined
Example
editor.getTemporaryAssetPreview('someId')
Parameters
Name | Description |
---|---|
| The asset's id. |
Returns
string | undefined
getViewportPageBounds()
The current viewport in the current page space.
getViewportPageBounds(): Box
getViewportScreenBounds()
The bounds of the editor's viewport in screen space.
getViewportScreenBounds(): Box
getViewportScreenCenter()
The center of the editor's viewport in screen space.
getViewportScreenCenter(): Vec
getZoomLevel()
The current camera zoom level.
getZoomLevel(): number
groupShapes()
Create a group containing the provided shapes.
Example
editor.groupShapes([myShape, myOtherShape])
editor.groupShapes([myShape, myOtherShape], {
groupId: myGroupId,
select: false,
})
Parameters
Name | Description |
---|---|
|
The shapes (or shape ids) to group. Defaults to the selected shapes. |
|
An options object. |
Returns
this
hasAncestor()
Returns true if the the given shape has the given ancestor.
Parameters
Name | Description |
---|---|
| The shape. |
| The id of the ancestor. |
Returns
boolean
hasExternalAssetHandler()
hasExternalAssetHandler(type: TLExternalAssetContent['type']): boolean
Parameters
Name | Description |
---|---|
|
|
Returns
boolean
interrupt()
Dispatch an interrupt event.
interrupt(): this
Example
editor.interrupt()
isAncestorSelected()
Determine whether or not any of a shape's ancestors are selected.
Parameters
Returns
boolean
isIn()
Get whether a certain tool (or other state node) is currently active.
isIn(path: string): boolean
Example
editor.isIn('select')
editor.isIn('select.brushing')
Parameters
Name | Description |
---|---|
|
The path of active states, separated by periods. |
Returns
boolean
isInAny()
Get whether the state node is in any of the given active paths.
isInAny(...paths: string[]): boolean
Example
state.isInAny('select', 'erase')
state.isInAny('select.brushing', 'erase.idle')
Parameters
Name | Description |
---|---|
|
|
Returns
boolean
isPointInShape()
Test whether a point (in the current page space) will will a shape. This method takes into account masks, such as when a shape is the child of a frame and is partially clipped by the frame.
isPointInShape(
shape: TLShape | TLShapeId,
point: VecLike,
opts?: {
hitInside?: boolean | undefined
margin?: number | undefined
}
): boolean
Example
editor.isPointInShape({ x: 100, y: 100 }, myShape)
Parameters
Name | Description |
---|---|
| The shape to test against. |
| The page point to test (in the current page space). |
|
The options for the hit point testing. |
Returns
boolean
isShapeHidden()
Parameters
Returns
boolean
isShapeInPage()
Get whether the given shape is the descendant of the given page.
Example
editor.isShapeInPage(myShape)
editor.isShapeInPage(myShape, 'page1')
Parameters
Name | Description |
---|---|
| The shape to check. |
| The id of the page to check against. Defaults to the current page. |
Returns
boolean
isShapeOfType()
Get whether a shape matches the type of a TLShapeUtil.
isShapeOfType<T extends TLUnknownShape>(
shape: TLUnknownShape,
type: T['type']
): shape is T
Example
const isArrowShape = isShapeOfType<TLArrowShape>(someShape, 'arrow')
Parameters
Name | Description |
---|---|
| the shape to test |
|
|
Returns
shape is T
isShapeOrAncestorLocked()
Check whether a shape or its parent is locked.
isShapeOrAncestorLocked(shape?: TLShape): boolean
Parameters
Name | Description |
---|---|
| The shape (or shape id) to check. |
Returns
boolean
loadSnapshot()
Loads a snapshot into the editor.
loadSnapshot(
snapshot: Partial<TLEditorSnapshot> | TLStoreSnapshot,
opts?: TLLoadSnapshotOptions
): this
Parameters
Name | Description |
---|---|
|
The snapshot to load. |
| The options for loading the snapshot. |
Returns
this
mark()
Deprecated: use Editor.markHistoryStoppingPoint instead
Create a new "mark", or stopping point, in the undo redo history. Creating a mark will clear any redos.
mark(markId?: string): this
Example
editor.mark()
editor.mark('flip shapes')
Parameters
Name | Description |
---|---|
|
The mark's id, usually the reason for adding the mark. |
Returns
this
markHistoryStoppingPoint()
Create a new "mark", or stopping point, in the undo redo history. Creating a mark will clear any redos. You typically want to do this just before a user interaction begins or is handled.
markHistoryStoppingPoint(name?: string): string
Example
editor.markHistoryStoppingPoint()
editor.flipShapes(editor.getSelectedShapes())
const beginRotateMark = editor.markHistoryStoppingPoint()
// if the use cancels the rotation, you can bail back to this mark
editor.bailToMark(beginRotateMark)
Parameters
Name | Description |
---|---|
|
The name of the mark, useful for debugging the undo/redo stacks |
Returns
string
a unique id for the mark that can be used with squashToMark
or bailToMark
.
moveShapesToPage()
Move shapes to page.
Example
editor.moveShapesToPage(['box1', 'box2'], 'page1')
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) of the shapes to move. |
| The id of the page where the shapes will be moved. |
Returns
this
navigateToDeepLink()
Handles navigating to the content specified by the query param in the given URL.
Use to create a URL with a deep link query param.
If no URL is provided, it will look for the param in the current window.location.href
.
navigateToDeepLink(
opts?:
| {
param?: string
url?: string | URL
}
| TLDeepLink
): Editor
Example
editor.navigateToDeepLink()
The default parameter name is 'd'. You can override this by providing the param
option.
// disable page parameter and change viewport parameter to 'c'
editor.navigateToDeepLink({
param: 'x',
url: 'https://my-app.com/my-document?x=200.12.454.23.xyz123',
})
Parameters
Name | Description |
---|---|
|
Options for loading the state from the URL. |
Returns
nudgeShapes()
Move shapes by a delta.
Example
editor.nudgeShapes(['box1', 'box2'], { x: 8, y: 8 })
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to move. |
| The offset to apply to the shapes. |
Returns
this
packShapes()
Pack shapes into a grid centered on their current position. Based on potpack (https://github.com/mapbox/potpack).
Example
editor.packShapes([box1, box2], 32)
editor.packShapes(editor.getSelectedShapeIds(), 32)
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) to pack. |
|
The padding to apply to the packed shapes. Defaults to 16. |
Returns
this
pageToScreen()
Convert a point in the current page space to a point in current screen space.
Example
editor.pageToScreen({ x: 100, y: 100 })
Parameters
Name | Description |
---|---|
| The point in page space. |
Returns
pageToViewport()
Convert a point in the current page space to a point in current viewport space.
Example
editor.pageToViewport({ x: 100, y: 100 })
Parameters
Name | Description |
---|---|
| The point in page space. |
Returns
popFocusedGroupId()
Exit the current focused group, moving up to the next parent group if there is one.
popFocusedGroupId(): this
putContentOntoCurrentPage()
Place content into the editor.
putContentOntoCurrentPage(
content: TLContent,
opts?: {
point?: VecLike
preserveIds?: boolean
preservePosition?: boolean
select?: boolean
}
): this
Parameters
Name | Description |
---|---|
| The content. |
|
Options for placing the content. |
Returns
this
putExternalContent()
Handle external content, such as files, urls, embeds, or plain text which has been put into the app, for example by pasting external text or dropping external images onto canvas.
putExternalContent<E>(info: TLExternalContent<E>): Promise<void>
Parameters
Name | Description |
---|---|
| Info about the external content. |
Returns
Promise<void>
redo()
Redo to the next mark.
redo(): this
Example
editor.redo()
registerDeepLinkListener()
Register a listener for changes to a deep link for the current document.
You'll typically want to use this indirectly via the TldrawEditorBaseProps.deepLinks prop on the <Tldraw />
component.
By default this will update window.location
in place, but you can provide a custom callback
to handle state changes on your own.
registerDeepLinkListener(opts?: TLDeepLinkOptions): () => void
Example
editor.registerDeepLinkListener({
onChange(url) {
window.history.replaceState({}, document.title, url.toString())
},
})
You can also provide a custom URL to update, in which case you must also provide onChange
.
editor.registerDeepLinkListener({
getUrl: () => `https://my-app.com/my-document`,
onChange(url) {
setShareUrl(url.toString())
},
})
By default this will update with a debounce interval of 500ms, but you can provide a custom interval.
editor.registerDeepLinkListener({ debounceMs: 1000 })
The default parameter name is d
. You can override this by providing a param
option.
editor.registerDeepLinkListener({ param: 'x' })
Parameters
Name | Description |
---|---|
| Options for setting up the listener. |
Returns
() => void
a function that will stop the listener.
registerExternalAssetHandler()
Register an external asset handler. This handler will be called when the editor needs to create an asset for some external content, like an image/video file or a bookmark URL. For example, the 'file' type handler will be called when a user drops an image onto the canvas.
The handler should extract any relevant metadata for the asset, upload it to blob storage using Editor.uploadAsset if needed, and return the asset with the metadata & uploaded URL.
registerExternalAssetHandler<T extends TLExternalAssetContent['type']>(
type: T,
handler:
| ((
info: TLExternalAssetContent & {
type: T
}
) => Promise<TLAsset>)
| null
): this
Example
editor.registerExternalAssetHandler('file', myHandler)
Parameters
Name | Description |
---|---|
|
The type of external content. |
|
The handler to use for this content type. |
Returns
this
registerExternalContentHandler()
Register an external content handler. This handler will be called when the editor receives external content of the provided type. For example, the 'image' type handler will be called when a user drops an image onto the canvas.
registerExternalContentHandler<T extends TLExternalContent<E>['type'], E>(
type: T,
handler:
| ((
info: T extends TLExternalContent<E>['type']
? TLExternalContent<E> & {
type: T
}
: TLExternalContent<E>
) => void)
| null
): this
Example
editor.registerExternalContentHandler('text', myHandler)
editor.registerExternalContentHandler<'embed', MyEmbedType>('embed', myHandler)
Parameters
Name | Description |
---|---|
|
The type of external content. |
|
The handler to use for this content type. |
Returns
this
renamePage()
Rename a page.
Example
editor.renamePage('page1', 'My Page')
Parameters
Returns
this
reparentShapes()
Reparent shapes to a new parent. This operation preserves the shape's current page positions / rotations.
reparentShapes(
shapes: TLShape[] | TLShapeId[],
parentId: TLParentId,
insertIndex?: IndexKey
): this
Example
editor.reparentShapes([box1, box2], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1')
editor.reparentShapes([box1.id, box2.id], 'frame1', 4)
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) of the shapes to reparent. |
| The id of the new parent shape. |
|
The index to insert the children. |
Returns
this
resetZoom()
Set the zoom back to 100%.
resetZoom(point?: Vec, opts?: TLCameraMoveOptions): this
Example
editor.resetZoom()
editor.resetZoom(editor.getViewportScreenCenter(), {
animation: { duration: 200 },
})
editor.resetZoom(editor.getViewportScreenCenter(), {
animation: { duration: 200 },
})
Parameters
Name | Description |
---|---|
| The screen point to zoom out on. Defaults to the viewport screen center. |
| The camera move options. |
Returns
this
resizeShape()
Resize a shape.
resizeShape(
shape: TLShape | TLShapeId,
scale: VecLike,
opts?: TLResizeShapeOptions
): this
Parameters
Name | Description |
---|---|
| The shape (or the shape id of the shape) to resize. |
| The scale factor to apply to the shape. |
| Additional options. |
Returns
this
resolveAssetsInContent()
Parameters
Name | Description |
---|---|
|
|
Returns
Promise<TLContent | undefined>
resolveAssetUrl()
resolveAssetUrl(
assetId: null | TLAssetId,
context: {
screenScale?: number
shouldResolveToOriginal?: boolean
}
): Promise<null | string>
Parameters
Name | Description |
---|---|
|
|
|
|
Returns
Promise<null | string>
rotateShapesBy()
Rotate shapes by a delta in radians.
Example
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI)
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI / 2)
Parameters
Name | Description |
---|---|
| The shapes (or shape ids) of the shapes to move. |
|
The delta in radians to apply to the selection rotation. |
|
The options for the rotation. |
Returns
this
run()
Run a function in a transaction with optional options for context. You can use the options to change the way that history is treated or allow changes to locked shapes.
run(fn: () => void, opts?: TLEditorRunOptions): this
Example
// updating with
editor.run(
() => {
editor.updateShape({ ...myShape, x: 100 })
},
{ history: 'ignore' }
)
// forcing changes / deletions for locked shapes
editor.toggleLock([myShape])
editor.run(
() => {
editor.updateShape({ ...myShape, x: 100 })
editor.deleteShape(myShape)
},
{ ignoreShapeLock: true }
)
Parameters
Name | Description |
---|---|
|
The callback function to run. |
| The options for the batch. |
Returns
this
screenToPage()
Convert a point in screen space to a point in the current page space.
Example
editor.screenToPage({ x: 100, y: 100 })
Parameters
Name | Description |
---|---|
| The point in screen space. |
Returns
select()
Select one or more shapes.
Example
editor.select('id1')
editor.select('id1', 'id2')
Parameters
Returns
this
selectAll()
Select all direct children of the current page.
selectAll(): this
Example
editor.selectAll()
selectNone()
Clear the selection.
selectNone(): this
Example
editor.selectNone()
sendBackward()
Send shapes backward in the page's object list.
Example
editor.sendBackward(['id1', 'id2'])
editor.sendBackward([box1, box2])
Parameters
Returns
this
sendToBack()
Send shapes to the back of the page's object list.
Example
editor.sendToBack(['id1', 'id2'])
editor.sendToBack(box1, box2)
Parameters
Returns
this
setCamera()
Set the current camera.
setCamera(point: VecLike, opts?: TLCameraMoveOptions): this
Example
editor.setCamera({ x: 0, y: 0 })
editor.setCamera({ x: 0, y: 0, z: 1.5 })
editor.setCamera(
{ x: 0, y: 0, z: 1.5 },
{ animation: { duration: 1000, easing: (t) => t * t } }
)
Parameters
Name | Description |
---|---|
| The new camera position. |
| The camera move options. |
Returns
this
setCameraOptions()
Set the camera options. Changing the options won't immediately change the camera itself, so you may want to call setCamera
after changing the options.
setCameraOptions(opts: Partial<TLCameraOptions>): this
Example
editor.setCameraOptions(myCameraOptions)
editor.setCamera(editor.getCamera())
Parameters
Name | Description |
---|---|
|
The camera options to set. |
Returns
this
setCroppingShape()
Set the current cropping shape.
Example
editor.setCroppingShape(myShape)
editor.setCroppingShape(myShape.id)
Parameters
Returns
this
setCurrentPage()
Set the current page.
Example
editor.setCurrentPage('page1')
editor.setCurrentPage(myPage1)
Parameters
Returns
this
setCurrentTool()
Set the selected tool.
setCurrentTool(id: string, info?: {}): this
Example
editor.setCurrentTool('hand')
editor.setCurrentTool('hand', { date: Date.now() })
Parameters
Name | Description |
---|---|
|
The id of the tool to select. |
|
Arbitrary data to pass along into the transition. |
Returns
this
setCursor()
Set the cursor.
setCursor(cursor: Partial<TLCursor>): this
Parameters
Name | Description |
---|---|
|
The cursor to set. |
Returns
this
setEditingShape()
Set the current editing shape.
Example
editor.setEditingShape(myShape)
editor.setEditingShape(myShape.id)
Parameters
Returns
this
setErasingShapes()
Set the editor's current erasing shapes.
Example
editor.setErasingShapes([myShape])
editor.setErasingShapes([myShape.id])
Parameters
Returns
this
setFocusedGroup()
Set the current focused group shape.
setFocusedGroup(shape: null | TLGroupShape | TLShapeId): this
Parameters
Name | Description |
---|---|
|
The group shape id (or group shape's id) to set as the focused group shape. |
Returns
this
setHintingShapes()
Set the editor's current hinting shapes.
Example
editor.setHintingShapes([myShape])
editor.setHintingShapes([myShape.id])
Parameters
Returns
this
setHoveredShape()
Set the editor's current hovered shape.
Example
editor.setHoveredShape(myShape)
editor.setHoveredShape(myShape.id)
Parameters
Returns
this
setOpacityForNextShapes()
Set the opacity for the next shapes. This will effect subsequently created shapes.
setOpacityForNextShapes(
opacity: number,
historyOptions?: TLHistoryBatchOptions
): this
Example
editor.setOpacityForNextShapes(0.5)
Parameters
Name | Description |
---|---|
|
The opacity to set. Must be a number between 0 and 1 inclusive. |
| The history options for the change. |
Returns
this
setOpacityForSelectedShapes()
Set the current opacity. This will effect any selected shapes.
setOpacityForSelectedShapes(opacity: number): this
Example
editor.setOpacityForSelectedShapes(0.5)
Parameters
Name | Description |
---|---|
|
The opacity to set. Must be a number between 0 and 1 inclusive. |
Returns
this
setSelectedShapes()
Select one or more shapes.
Example
editor.setSelectedShapes(['id1'])
editor.setSelectedShapes(['id1', 'id2'])
Parameters
Returns
this
setStyleForNextShapes()
Set the value of a StyleProp for the next shapes. This change will be applied to subsequently created shapes.
setStyleForNextShapes<T>(
style: StyleProp<T>,
value: T,
historyOptions?: TLHistoryBatchOptions
): this
Example
editor.setStyleForNextShapes(DefaultColorStyle, 'red')
editor.setStyleForNextShapes(DefaultColorStyle, 'red', { ephemeral: true })
Parameters
Name | Description |
---|---|
|
The style to set. |
|
The value to set. |
| The history options for the change. |
Returns
this
setStyleForSelectedShapes()
Set the value of a StyleProp. This change will be applied to the currently selected shapes.
setStyleForSelectedShapes<S extends StyleProp<any>>(
style: S,
value: StylePropValue<S>
): this
Example
editor.setStyleForSelectedShapes(DefaultColorStyle, 'red')
Parameters
Name | Description |
---|---|
|
The style to set. |
| The value to set. |
Returns
this
slideCamera()
Slide the camera in a certain direction.
slideCamera(opts?: {
direction: VecLike
force?: boolean | undefined
friction?: number | undefined
speed: number
speedThreshold?: number | undefined
}): this
Example
editor.slideCamera({ speed: 1, direction: { x: 1, y: 0 }, friction: 0.1 })
Parameters
Name | Description |
---|---|
|
Options for the slide |
Returns
this
squashToMark()
Coalesces all changes since the given mark into a single change, removing any intermediate marks.
This is useful if you need to 'compress' the recent history to simplify the undo/redo experience of a complex interaction.
squashToMark(markId: string): this
Example
const bumpShapesMark = editor.markHistoryStoppingPoint()
// ... some changes
editor.squashToMark(bumpShapesMark)
Parameters
Name | Description |
---|---|
|
The mark id to squash to. |
Returns
this
stackShapes()
Stack shape.
stackShapes(
shapes: TLShape[] | TLShapeId[],
operation: 'horizontal' | 'vertical',
gap: number
): this
Example
editor.stackShapes([box1, box2], 'horizontal', 32)
editor.stackShapes(editor.getSelectedShapeIds(), 'horizontal', 32)