tldraw

https://tldraw.dev/docs
Admin
tldraw is an infinite canvas SDK for building high-performance whiteboard and collaborative drawing...
Tokens:20,072
Snippets:223
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install @tldraw/sync

Source: https://tldraw.dev/docs/collaboration

Install the sync library to enable multiplayer functionality.

```bash
npm install @tldraw/sync
```

--------------------------------

### Install @tldraw/driver

Source: https://tldraw.dev/docs/driver

Install the driver package alongside the main tldraw library.

```bash
npm install @tldraw/driver
```

--------------------------------

### Reference llms-docs.txt in an AI prompt

Source: https://tldraw.dev/docs/llm-docs

Example of how to instruct an AI assistant to fetch and use the documentation context from the provided URL.

```text
Read https://tldraw.dev/llms-docs.txt, then add a custom shape to my app.
```

--------------------------------

### Install @tldraw/mermaid package

Source: https://tldraw.dev/docs/mermaid

Install the required package alongside tldraw to enable Mermaid diagram support.

```bash
npm install @tldraw/mermaid
```

--------------------------------

### Quick start with CanvasComments

Source: https://tldraw.dev/docs/commenting

Registers comment record types, configures the Tldraw component with comment tools, and renders the CanvasComments layer.

```typescript
import {
	CanvasComments,
	CommentAuthor,
	commentToolOverrides,
	commentTools,
} from '@tldraw/commenting'
import { useMemo } from 'react'
import { commentSchemaRecords, createTLSchema, createTLStore, TLComponents, Tldraw } from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'

const AUTHORS: Record<string, CommentAuthor> = { me: { name: 'You', color: '#EC5E41' } }
const resolveAuthor = (id: string) => AUTHORS[id]

const components: TLComponents = {
	InFrontOfTheCanvas: () => <CanvasComments currentUserId="me" resolveAuthor={resolveAuthor} />,
}

export default function App() {
	const store = useMemo(
		() => createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
		[]
	)

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				licenseKey={YOUR_LICENSE_KEY}
				store={store}
				tools={commentTools}
				overrides={[commentToolOverrides]}
				components={components}
			/>
		</div>
	)
}
```

--------------------------------

### Implement a custom shape with a draggable handle

Source: https://tldraw.dev/docs/handles

This example demonstrates creating a speech bubble shape with a custom tail handle. It overrides getHandles to define the handle and onHandleDrag to update the shape's props when the handle is moved.

```typescript
import {
	Polygon2d,
	ShapeUtil,
	SVGContainer,
	T,
	TLHandle,
	TLHandleDragInfo,
	TLShape,
	Vec,
	ZERO_INDEX_KEY,
} from 'tldraw'

const SPEECH_BUBBLE_TYPE = 'speech-bubble'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[SPEECH_BUBBLE_TYPE]: { w: number; h: number; tailX: number; tailY: number }
	}
}

type SpeechBubbleShape = TLShape<typeof SPEECH_BUBBLE_TYPE>

class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
	static override type = SPEECH_BUBBLE_TYPE
	static override props = { w: T.number, h: T.number, tailX: T.number, tailY: T.number }

	getDefaultProps(): SpeechBubbleShape['props'] {
		return { w: 200, h: 100, tailX: 100, tailY: 150 }
	}

	getGeometry(shape: SpeechBubbleShape) {
		const { w, h, tailX, tailY } = shape.props
		return new Polygon2d({
			points: [
				new Vec(0, 0),
				new Vec(w, 0),
				new Vec(w, h),
				new Vec(w * 0.7, h),
				new Vec(tailX, tailY),
				new Vec(w * 0.3, h),
				new Vec(0, h),
			],
			isFilled: true,
		})
	}

	override getHandles(shape: SpeechBubbleShape): TLHandle[] {
		return [
			{
				id: 'tail',
				type: 'vertex',
				label: 'Move tail',
				index: ZERO_INDEX_KEY,
				x: shape.props.tailX,
				y: shape.props.tailY,
			},
		]
	}

	override onHandleDrag(shape: SpeechBubbleShape, { handle }: TLHandleDragInfo<SpeechBubbleShape>) {
		return {
			props: { tailX: handle.x, tailY: handle.y },
		}
	}

	component(shape: SpeechBubbleShape) {
		const geometry = this.getGeometry(shape)
		return (
			<SVGContainer>
				<path d={geometry.getSvgPathData()} fill="white" stroke="black" />
			</SVGContainer>
		)
	}

	getIndicatorPath(shape: SpeechBubbleShape) {
		const geometry = this.getGeometry(shape)
		return new Path2D(geometry.getSvgPathData())
	}
}
```

--------------------------------

### Initialize tldraw project

Source: https://tldraw.dev

Run this command in your terminal to create a new tldraw project.

```bash
npm create tldraw
```

--------------------------------

### Custom store initialization with createTLStore

Source: https://tldraw.dev/docs/persistence

Create a standalone reactive store using createTLStore and load initial data into it before passing it to the Tldraw component.

```jsx
import { useState } from 'react'
import { createTLStore, loadSnapshot, Tldraw } from 'tldraw'

export default function App() {
	const [store] = useState(() => {
		const store = createTLStore()
		const saved = localStorage.getItem('my-drawing')
		if (saved) {
			loadSnapshot(store, JSON.parse(saved))
		}
		return store
	})

	return <Tldraw store={store} />
}
```

--------------------------------

### Implement useSyncDemo hook

Source: https://tldraw.dev/docs/collaboration

Use the useSyncDemo hook to connect to a hosted demo server for rapid prototyping.

```javascript
import { Tldraw } from 'tldraw'
import { useSyncDemo } from '@tldraw/sync'
import 'tldraw/tldraw.css'

export default function App() {
	const store = useSyncDemo({ roomId: 'my-company-my-unique-room-id' })
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw store={store} />
		</div>
	)
}
```

--------------------------------

### Driver Input Simulation

Source: https://tldraw.dev/docs/driver

Methods for simulating pointer and keyboard interactions. These methods return the driver instance, allowing for method chaining.

```APIDOC
## Driver Input Methods

### Description
Simulate user input events such as clicks, pointer movements, and key presses. These events flow through the editor's tool state machines.

### Methods
- `driver.click(x, y, target?, modifiers?)`
- `driver.pointerDown(x, y, target?, modifiers?)`
- `driver.pointerMove(x, y, target?, modifiers?)`
- `driver.pointerUp()`
- `driver.keyPress(key)`
- `driver.keyDown(key)`
- `driver.keyUp(key)`

### Parameters
- **x** (number) - Screen space coordinate
- **y** (number) - Screen space coordinate
- **target** (string|object) - Optional shape ID or event info
- **modifiers** (object) - Optional modifier keys (e.g., { shiftKey: true })

### Example
```javascript
driver.click(100, 200).pointerDown(300, 400).pointerMove(500, 600).pointerUp();
driver.keyPress('a');
```
```

--------------------------------

### Migrate legacy data with SQLiteSyncStorage

Source: https://tldraw.dev/docs/sync

Uses SQLiteSyncStorage to initialize a room, checking for existing SQLite data before attempting to load and convert legacy data.

```typescript
import { SQLiteSyncStorage, NodeSqliteWrapper, TLSocketRoom } from '@tldraw/sync-core'
import Database from 'better-sqlite3'

function loadOrMakeRoom(roomId: string, db: Database.Database) {
	const sql = new NodeSqliteWrapper(db, { tablePrefix: `room_${roomId}_` })

	// Check if we already have data in SQLite
	if (SQLiteSyncStorage.hasBeenInitialized(sql)) {
		const storage = new SQLiteSyncStorage({ sql })
		return new TLSocketRoom({ storage })
	}

	// Try to load from legacy system
	const legacyData = loadRoomDataFromLegacyStore(roomId)
	if (legacyData) {
		const snapshot = convertOldDataToSnapshot(legacyData)
		const storage = new SQLiteSyncStorage({ sql, snapshot })
		deleteLegacyRoomData(roomId)
		return new TLSocketRoom({ storage })
	}

	// No data - create a new empty room
	return new TLSocketRoom({ storage: new SQLiteSyncStorage({ sql }) })
}
```

--------------------------------

### Wrap Editor with Driver

Source: https://tldraw.dev/docs/driver

Initialize a Driver instance within the onMount callback of the Tldraw component to dispatch simulated input. Always call dispose() to clean up side-effect handlers.

```javascript
import { Driver } from '@tldraw/driver'
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					const driver = new Driver(editor)

					driver.click(100, 200).pointerDown(300, 400).pointerMove(500, 600).pointerUp()
					driver.keyPress('a')

					return () => driver.dispose()
				}}
			/>
		</div>
	)
}
```

--------------------------------

### Configure custom shapes and bindings on the server

Source: https://tldraw.dev/docs/sync

Use createTLSchema to define your schema with custom shapes and pass it to the TLSocketRoom.

```typescript
import { createTLSchema, defaultShapeSchemas, defaultBindingSchemas } from '@tldraw/tlschema'
import { TLSocketRoom } from '@tldraw/sync-core'

const schema = createTLSchema({
	shapes: {
		...defaultShapeSchemas,

		myCustomShape: {
			// Validations for this shape's `props`.
			props: myCustomShapeProps,
			// Migrations between versions of this shape.
			migrations: myCustomShapeMigrations,
		},

		// The schema knows about this shape, but it has no migrations or validation.
		mySimpleShape: {},
	},
	bindings: defaultBindingSchemas,
})

// Later, in your app server:
const room = new TLSocketRoom({
	schema: schema,
	// ...
})
```

--------------------------------

### Implement a custom TLAssetStore

Source: https://tldraw.dev/docs/assets

Implement the upload and resolve methods to handle custom asset storage, then pass the store to the Tldraw component.

```typescript
import { Tldraw, TLAssetStore } from 'tldraw'
import 'tldraw/tldraw.css'

const myAssetStore: TLAssetStore = {
	async upload(asset, file) {
		const url = await uploadToMyServer(file)
		return { src: url }
	},
	resolve(asset) {
		return asset.props.src
	},
}

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw assets={myAssetStore} />
		</div>
	)
}
```

--------------------------------

### Multiplayer synchronization with useSyncDemo

Source: https://tldraw.dev/docs/persistence

Enable real-time collaboration by using the @tldraw/sync package and the useSyncDemo hook to manage shared state.

```jsx
import { useSyncDemo } from '@tldraw/sync'
import { Tldraw } from 'tldraw'

export default function App() {
	const store = useSyncDemo({ roomId: 'my-room-id' })
	return <Tldraw store={store} />
}
```

--------------------------------

### Configure Tldraw UI props

Source: https://tldraw.dev/docs/user-interface

Demonstrates how to use hideUi, components, and onUiEvent props to manage the tldraw interface within a React application.

```javascript
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				hideUi={false}
				components={{ PageMenu: null }}
				onUiEvent={(name, data) => console.log(name, data)}
			/>
		</div>
	)
}
```

--------------------------------

### Configure editor.run options

Source: https://tldraw.dev/docs/editor

The run method accepts options to control history behavior or allow modifications to locked shapes.

```javascript
// Make changes without affecting undo/redo history
editor.run(
	() => {
		editor.createShapes(myShapes)
	},
	{ history: 'ignore' }
)

// Make changes to locked shapes
editor.run(
	() => {
		editor.updateShapes(myLockedShapes)
	},
	{ ignoreShapeLock: true }
)
```

--------------------------------

### Simulate Draw Tool Input

Source: https://tldraw.dev/docs/driver

Dispatch a sequence of pointer events to interact with the editor's tool state machines, such as creating shapes with the draw tool.

```javascript
editor.setCurrentTool('draw')
driver.pointerDown(100, 100)
driver.pointerMove(150, 120)
driver.pointerMove(200, 140)
driver.pointerUp()
```

--------------------------------

### Local persistence with persistenceKey

Source: https://tldraw.dev/docs/persistence

Use the persistenceKey prop to automatically save the document and assets to IndexedDB, enabling synchronization across browser tabs.

```jsx
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw persistenceKey="my-document" />
		</div>
	)
}
```

--------------------------------

### Snapshot management with getSnapshot and loadSnapshot

Source: https://tldraw.dev/docs/persistence

Use getSnapshot and loadSnapshot to manually save and restore editor state as JSON for custom storage backends.

```javascript
import { getSnapshot, loadSnapshot } from 'tldraw'

// Save
const { document, session } = getSnapshot(editor.store)
await saveToDatabase(document)

// Load
const saved = await loadFromDatabase()
loadSnapshot(editor.store, { document: saved })
```

--------------------------------

### Configure CommentTool

Source: https://tldraw.dev/docs/commenting

Use CommentTool.configure() to create a configured subclass for registration, similar to ShapeUtil.configure.

```typescript
import { CommentTool } from '@tldraw/commenting'

const tools = [CommentTool.configure({ enableRegions: true })]
```

--------------------------------

### Change and read active tools

Source: https://tldraw.dev/docs/tools

Demonstrates how to programmatically switch the active tool using setCurrentTool and retrieve the current tool ID using getCurrentToolId.

```typescript
editor.setCurrentTool('select')
editor.setCurrentTool('hand')
editor.setCurrentTool('draw')
editor.getCurrentToolId() // 'draw'
```

--------------------------------

### Batch changes with editor.run

Source: https://tldraw.dev/docs/editor

Group multiple changes into a single transaction using the editor.run method to reduce overhead and create a single undo step.

```javascript
// myShapes is an array of shape partials, each with an id from createShapeId()
editor.run(() => {
	editor.createShapes(myShapes)
	editor.sendToBack(myShapes.map((shape) => shape.id))
	editor.selectNone()
})
```

--------------------------------

### Update wrangler.toml for SQLite migration

Source: https://tldraw.dev/docs/sync

Configure the migration by keeping the old Durable Object class and adding a new SQLite-backed class definition.

```toml
# Keep existing migration for old class
[[migrations]]
tag = "v1"
new_classes = ["TldrawDurableObject"]

# Add new migration for SQLite-backed class
[[migrations]]
tag = "v2"
new_sqlite_classes = ["TldrawDurableObjectSqlite"]

[durable_objects]
bindings = [
    # Point to the new SQLite-backed class
    { name = "TLDRAW_DURABLE_OBJECT", class_name = "TldrawDurableObjectSqlite" },
]
```

--------------------------------

### createMermaidDiagram(editor, text, options?)

Source: https://tldraw.dev/docs/mermaid

Parses a Mermaid diagram string and creates corresponding shapes on the tldraw canvas.

```APIDOC
## createMermaidDiagram(editor, text, options?)

### Description
Parses a Mermaid diagram string and renders it as a group of editable shapes in the tldraw editor.

### Parameters
- **editor** (Editor) - Required - The tldraw editor instance.
- **text** (string) - Required - The Mermaid diagram syntax string.
- **options** (object) - Optional - Configuration object.
  - **blueprintRender.position** (object) - Optional - Coordinates to place the diagram.
  - **centerOnPosition** (boolean) - Optional - Whether to anchor the diagram by its center (default: true).
  - **mermaidConfig** (object) - Optional - Overrides for Mermaid layout settings.
  - **onUnsupportedDiagram** (function) - Optional - Callback for handling unsupported diagram types (e.g., pie, gantt, class, ER).
```

--------------------------------

### Define Initial Meta

Source: https://tldraw.dev/docs/shapes

Override the getInitialMetaForShape method to provide default meta values when a shape is created.

```typescript
editor.getInitialMetaForShape = (shape) => {
	if (shape.type === 'text') {
		return { createdBy: currentUser.id, lastModified: Date.now() }
	}
	return { createdBy: currentUser.id }
}
```

--------------------------------

### Migrate legacy data with InMemorySyncStorage

Source: https://tldraw.dev/docs/sync

Uses InMemorySyncStorage to load data, converting legacy formats to TLStoreSnapshot and saving the result for future direct loading.

```typescript
import { InMemorySyncStorage, TLSocketRoom } from '@tldraw/sync-core'

async function loadOrMakeRoom(roomId: string) {
	// InMemorySyncStorage takes a RoomSnapshot, which is what getSnapshot() returns.
	const data = await loadRoomDataFromCurrentStore(roomId)
	if (data) {
		const storage = new InMemorySyncStorage({ snapshot: data })
		return new TLSocketRoom({ storage })
	}
	const legacyData = await loadRoomDataFromLegacyStore(roomId)
	if (legacyData) {
		// Convert your old data to a TLStoreSnapshot.
		const snapshot = convertOldDataToSnapshot(legacyData)
		// Load it into the room. loadSnapshot accepts a TLStoreSnapshot.
		const storage = new InMemorySyncStorage()
		const room = new TLSocketRoom({ storage })
		room.loadSnapshot(snapshot)
		// Save an updated copy of the snapshot in the new place
		// so that next time we can load it directly.
		await saveRoomData(roomId, storage.getSnapshot())
		// Optionally delete the old data.
		await deleteLegacyRoomData(roomId)
		// And finally return the room.
		return room
	}
	// If there's no data at all, just make a new blank room.
	return new TLSocketRoom({ storage: new InMemorySyncStorage() })
}
```

--------------------------------

### Handle Lifecycle Callbacks

Source: https://tldraw.dev/docs/handles

Additional lifecycle methods available for managing the state of a handle drag interaction.

```APIDOC
## Handle Lifecycle Methods

- **onHandleDragStart**: Called when the user starts dragging a handle.
- **onHandleDragEnd**: Called when the user releases the handle.
- **onHandleDragCancel**: Called when the drag interaction is cancelled (e.g., via escape key).
```

--------------------------------

### Create a ShapeUtil class

Source: https://tldraw.dev/docs/shapes

Implement the ShapeUtil class to define shape behavior, including geometry, rendering, and validation via static props.

```typescript
import { HTMLContainer, Rectangle2d, ShapeUtil, T } from 'tldraw'

class CardShapeUtil extends ShapeUtil<CardShape> {
	static override type = CARD_TYPE
	static override props = { w: T.number, h: T.number }

	getDefaultProps(): CardShape['props'] {
		return { w: 100, h: 100 }
	}

	getGeometry(shape: CardShape) {
		return new Rectangle2d({
			width: shape.props.w,
			height: shape.props.h,
			isFilled: true,
		})
	}

	component(shape: CardShape) {
		return <HTMLContainer>Hello</HTMLContainer>
	}

	getIndicatorPath(shape: CardShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}
}
```

--------------------------------

### Implementing CreateActionUtil for shape creation

Source: https://tldraw.dev/docs/ai

Extend AgentActionUtil to define how the agent creates shapes, including coordinate translation and validation using the provided helpers.

```typescript
// Abbreviated from CreateActionUtil in the agent starter kit. The model describes
// shapes in a simplified format that the util converts to a real shape record.
class CreateActionUtil extends AgentActionUtil<CreateAction> {
	override applyAction(action: Streaming<CreateAction>, helpers: AgentHelpers) {
		const { shape } = action
		if (!shape || !shape._type) return

		// Translate from the model's coordinate space back to the page
		const shapePartial = helpers.removeOffsetFromShapePartial(shape)
		const result = convertPartialFocusedShapeToTldrawShape(this.editor, shapePartial, {
			defaultShape: getDefaultShape(shape._type, action.complete),
			complete: action.complete,
		})
		if (!result.shape) return

		this.editor.createShape(result.shape)
	}
}
```

--------------------------------

### Embed generated content using EmbedShapeUtil

Source: https://tldraw.dev/docs/ai

Use the EmbedShapeUtil to display websites on the canvas. Embeds from hosts not in the default definitions will render in a restricted sandbox.

```typescript
editor.createShape({
	type: 'embed',
	x: 100,
	y: 100,
	props: {
		url: 'https://generated-preview.example.com/abc123',
		w: 800,
		h: 600,
	},
})
```

--------------------------------

### Manage Modifier Keys

Source: https://tldraw.dev/docs/driver

Use keyDown and keyUp to set modifier states that persist across subsequent pointer events.

```javascript
driver.keyDown('Shift')
driver.click(100, 100, { target: 'canvas' })
driver.keyUp('Shift')
```

--------------------------------

### Access editor via onMount callback

Source: https://tldraw.dev/docs/editor

The Tldraw component's onMount callback provides the editor instance as the first argument.

```javascript
function App() {
	return (
		<Tldraw
			onMount={(editor) => {
				// your editor code here
			}}
		/>
	)
}
```

--------------------------------

### Shape Queries

Source: https://tldraw.dev/docs/driver

Methods to retrieve information about shapes created during the driver session.

```APIDOC
## Query Methods

### Description
Retrieves shapes created while the driver is attached to the editor.

### Methods
- `driver.getLastCreatedShape()`
- `driver.getLastCreatedShapes(count)`

### Example
```javascript
const shape = driver.getLastCreatedShape();
const lastFive = driver.getLastCreatedShapes(5);
```
```

--------------------------------

### Configure object access permissions

Source: https://tldraw.dev/docs/sync

Set objectAccess to 'write' or 'read' when handling a socket connection to control access to the object-store lane.

```typescript
room.handleSocketConnect({
	sessionId,
	socket,
	isReadonly: true,
	objectAccess: 'write',
})
```

--------------------------------

### Configure custom shapes and bindings on the client

Source: https://tldraw.dev/docs/sync

Pass custom and default shape/binding utils to the useSync hook to ensure the sync client recognizes your custom shapes.

```typescript
import { useMemo } from 'react'
import { Tldraw, defaultShapeUtils, defaultBindingUtils } from 'tldraw'
import { useSync } from '@tldraw/sync'

function MyApp() {
	const store = useSync({
		uri: '...',
		assets: myAssetStore,
		shapeUtils: useMemo(() => [...customShapeUtils, ...defaultShapeUtils], []),
		bindingUtils: useMemo(() => [...customBindingUtils, ...defaultBindingUtils], []),
	})

	return <Tldraw store={store} shapeUtils={customShapeUtils} bindingUtils={customBindingUtils} />
}
```

--------------------------------

### Define a custom preview shape

Source: https://tldraw.dev/docs/ai

Create a custom shape that extends ShapeUtil to render generated content like live HTML previews. This requires implementing the component method using HTMLContainer.

```typescript
import { HTMLContainer, ShapeUtil } from 'tldraw'

// Abbreviated: a full ShapeUtil also needs getDefaultProps, getGeometry, and
// getIndicatorPath. See the Shapes docs for a complete custom shape.
class PreviewShapeUtil extends ShapeUtil<PreviewShape> {
	static override type = 'preview' as const

	component(shape: PreviewShape) {
		return (
			<HTMLContainer>
				<iframe
					srcDoc={shape.props.html}
					sandbox="allow-scripts"
					style={{ width: '100%', height: '100%', border: 'none' }}
				/>
			</HTMLContainer>
		)
		}
}
```

--------------------------------

### Customize Mermaid node rendering with mapNodeToRenderSpec

Source: https://tldraw.dev/docs/mermaid

Pass the mapNodeToRenderSpec callback to blueprintRender within createMermaidDiagram to map specific diagram nodes to custom shape types. Returning undefined allows the package to use the default rendering for that node.

```typescript
await createMermaidDiagram(editor, text, {
	blueprintRender: {
		mapNodeToRenderSpec(input) {
			if (input.diagramKind === 'flowchart') {
				return {
					variant: 'shape',
					type: 'pipeline-step',
					props: { mermaidNodeId: input.nodeId },
				}
			}
			// Return undefined to keep the package default for this node.
			return undefined
		},
	},
})
```

--------------------------------

### Create a custom StampTool

Source: https://tldraw.dev/docs/tools

Extends StateNode to create a custom tool that places a heart emoji on the canvas when the pointer is pressed. The tool is then registered by passing it to the tools prop of the Tldraw component.

```typescript
import { StateNode, Tldraw, toRichText } from 'tldraw'

class StampTool extends StateNode {
	static override id = 'stamp'

	override onPointerDown() {
		const { x, y } = this.editor.inputs.getCurrentPagePoint()
		this.editor.createShape({ type: 'text', x, y, props: { richText: toRichText('❤️') } })
	}
}

export default function App() {
	return <Tldraw tools={[StampTool]} />
}
```

--------------------------------

### Define an LLMNode for AI workflows

Source: https://tldraw.dev/docs/ai

Create a custom node definition that calls an AI model via an API endpoint. This implementation requires a full NodeDefinition interface including validators and ports as provided in the workflow starter kit.

```javascript
// Abbreviated: a real NodeDefinition also declares a validator, ports, a default
// value, and a body height. See the workflow starter kit for the full interface.
class LLMNode extends NodeDefinition<LLMNodeData> {
	static type = 'llm'

	async execute(shape, node, inputs) {
		const response = await fetch('/api/generate', {
			method: 'POST',
			body: JSON.stringify({ prompt: inputs.prompt }),
		})
		const result = await response.json()
		return { output: result.text }
	}
}
```

--------------------------------

### Create image shapes from generated assets

Source: https://tldraw.dev/docs/ai

Use AssetRecordType to create an asset from a blob or URL, then create an image shape to display it on the canvas.

```typescript
const asset = AssetRecordType.create({
	id: AssetRecordType.createId(),
	type: 'image',
	props: {
		src: generatedImageUrl,
		w: 512,
		h: 512,
		mimeType: 'image/png',
		name: 'generated-image.png',
		isAnimated: false,
	},
})

editor.createAssets([asset])
editor.createShape({
	type: 'image',
	x: 100,
	y: 100,
	props: {
		assetId: asset.id,
		w: 512,
		h: 512,
	},
})
```

--------------------------------

### Implement Tldraw component in App.tsx

Source: https://tldraw.dev

Basic implementation of the Tldraw component within a React application, including the required CSS import and an onMount handler to select all elements.

```tsx
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
  return (
    <div className="editor">
      <Tldraw
        onMount={(editor) => {
          editor.selectAll()
        }}
      />
    </div>
  )
}
```

--------------------------------

### Clipboard Operations

Source: https://tldraw.dev/docs/driver

Methods for performing in-memory copy and paste operations.

```APIDOC
## Clipboard Methods

### Description
Performs copy and paste operations using an internal in-memory clipboard independent of the system clipboard.

### Methods
- `driver.copy()`
- `driver.paste(point)`

### Parameters
- **point** (object) - The page point {x, y} where the content should be pasted.
```

--------------------------------

### Export canvas content as SVG or PNG

Source: https://tldraw.dev/docs/ai

Use Editor.getSvgString or Editor.toImage to export the current view or specific regions for AI analysis.

```javascript
const svg = await editor.getSvgString(editor.getCurrentPageShapes())
const { blob } = await editor.toImage(editor.getCurrentPageShapes(), { format: 'png' })
```

--------------------------------

### Query Created Shapes

Source: https://tldraw.dev/docs/driver

Retrieve shapes created during the driver's session using built-in query helpers.

```javascript
const shape = driver.getLastCreatedShape()
const lastFive = driver.getLastCreatedShapes(5)
```

--------------------------------

### Triggering canvas operations with useAgent

Source: https://tldraw.dev/docs/ai

Use the useAgent hook within a TldrawAgentAppProvider to send prompts to the agent, either as a simple string or with specific bounding box context.

```javascript
// Inside a component wrapped by the starter kit's TldrawAgentAppProvider
const agent = useAgent()

// Simple prompt
agent.prompt('Draw a flowchart showing user authentication')

// With additional context
agent.prompt({
	message: 'Add labels to these shapes',
	bounds: { x: 0, y: 0, w: 500, h: 400 },
})
```

--------------------------------

### getHandleSnapGeometry

Source: https://tldraw.dev/docs/handles

Override this method in ShapeUtil to customize the geometry and points that handles snap to.

```APIDOC
## getHandleSnapGeometry(shape)

### Description
Customizes the snap behavior for handles by defining specific points or outlines to snap to.

### Returns
- **HandleSnapGeometry**: An object containing `outline`, `points`, `getSelfSnapOutline`, and `getSelfSnapPoints`.
```

--------------------------------

### Implement WebSocket Hibernation in Cloudflare Durable Objects

Source: https://tldraw.dev/docs/sync

Uses TLSocketRoom APIs to persist session snapshots to WebSocket attachments and resume sessions upon object wake-up. Requires setting clientTimeout to Infinity to prevent premature idle timeouts.

```typescript
import {
	DurableObjectSqliteSyncWrapper,
	type SessionStateSnapshot,
	SQLiteSyncStorage,
	TLSocketRoom,
} from '@tldraw/sync-core'
import { TLRecord } from '@tldraw/tlschema'
import { DurableObject } from 'cloudflare:workers'

interface SocketAttachment {
	sessionId: string
	snapshot?: SessionStateSnapshot
}

export class TldrawDurableObject extends DurableObject {
	private room: TLSocketRoom<TLRecord, void> | null = null
	// Maps sessionId → ws. Populate this in your webSocketMessage handler.
	private readonly sessionIdToWs = new Map<string, WebSocket>()

	private getOrCreateRoom() {
		if (this.room) return this.room

		const sql = new DurableObjectSqliteSyncWrapper(this.ctx.storage)
		const storage = new SQLiteSyncStorage<TLRecord>({ sql })

		this.room = new TLSocketRoom<TLRecord, void>({
			storage,
			// Cloudflare keeps WebSockets alive across hibernation, so let it manage timeouts.
			clientTimeout: Infinity,
			// Persist each session's snapshot to its WebSocket attachment when it goes idle.
			onSessionSnapshot: (sessionId, snapshot) => {
				const ws = this.sessionIdToWs.get(sessionId)
				if (ws) ws.serializeAttachment({ sessionId, snapshot })
			},
		})

		// Resume any sessions whose sockets survived hibernation.
		for (const ws of this.ctx.getWebSockets()) {
			const attachment = ws.deserializeAttachment() as SocketAttachment | null
			if (attachment?.snapshot) {
				this.room.handleSocketResume({
					sessionId: attachment.sessionId,
					socket: ws,
					snapshot: attachment.snapshot,
				})
			}
		}

		return this.room
	}
}
```

--------------------------------

### Export Durable Object classes

Source: https://tldraw.dev/docs/sync

Ensure both the old stub and the new SQLite-backed class are exported from the worker entry point.

```typescript
export { TldrawDurableObject, TldrawDurableObjectSqlite } from './TldrawDurableObject'
```

--------------------------------

### Clipboard Operations

Source: https://tldraw.dev/docs/driver

Perform scripted copy and paste actions using the driver's internal in-memory clipboard.

```javascript
driver.copy() // copies the current selection
driver.paste({ x: 400, y: 400 }) // page point; ignored while Shift is held
```

--------------------------------

### Integrate @tldraw/commenting

Source: https://tldraw.dev/docs/collaboration

Add anchored comments to the canvas by configuring the CanvasComments component and registering commentSchemaRecords.

```javascript
import {
	CanvasComments,
	CommentAuthor,
	commentToolOverrides,
	commentTools,
} from '@tldraw/commenting'
import { useSync } from '@tldraw/sync'
import { commentSchemaRecords, TLComponents, Tldraw } from 'tldraw'
import '@tldraw/commenting/commenting.css'

// Your app's user directory, however you already hold it.
const AUTHORS: Record<string, CommentAuthor> = {
	'user-123': { name: 'You', color: '#EC5E41' },
}

const components: TLComponents = {
	InFrontOfTheCanvas: () => (
		<CanvasComments currentUserId="user-123" resolveAuthor={(id) => AUTHORS[id]} />
	),
}

function MyApp() {
	const store = useSync({
		uri: 'wss://your-server.com/sync/my-room',
		assets: myAssetStore,
		records: commentSchemaRecords,
	})

	return (
		<Tldraw
			store={store}
			tools={commentTools}
			overrides={[commentToolOverrides]}
			components={components}
		/>
	)
}
```

--------------------------------

### Handle unsupported diagram types

Source: https://tldraw.dev/docs/mermaid

Provide an onUnsupportedDiagram callback to handle diagram types not natively supported by the package, such as importing them as SVG text.

```typescript
await createMermaidDiagram(editor, text, {
	async onUnsupportedDiagram(svgString) {
		await editor.putExternalContent({ type: 'svg-text', text: svgString })
	},
})
```

--------------------------------

### Target Shapes with Pointer Events

Source: https://tldraw.dev/docs/driver

Use optional trailing arguments to target specific shapes or override modifier keys during pointer events.

```javascript
driver.click(100, 100, shapeId, { shiftKey: true })
```

--------------------------------

### Implement Durable Object fallback loading

Source: https://tldraw.dev/docs/sync

Rename the Durable Object class and update the loading logic to check SQLite storage first, falling back to R2 if necessary.

```typescript
import {
	DurableObjectSqliteSyncWrapper,
	RoomSnapshot,
	SQLiteSyncStorage,
	TLSocketRoom,
} from '@tldraw/sync-core'
import { TLRecord, createTLSchema, defaultShapeSchemas } from '@tldraw/tlschema'
import { AutoRouter, error, IRequest } from 'itty-router'

// Empty stub for the old class name - required until migration is complete
export class TldrawDurableObject {}

const schema = createTLSchema({ shapes: defaultShapeSchemas })

// Renamed from TldrawDurableObject
export class TldrawDurableObjectSqlite {
	private roomPromise: Promise<TLSocketRoom<TLRecord, void>> | null = null
	private roomId: string | null = null

	constructor(
		private ctx: DurableObjectState,
		private env: Env
	) {
		// Load roomId from DO storage (needed for R2 fallback)
		ctx.blockConcurrencyWhile(async () => {
			this.roomId = (await ctx.storage.get('roomId')) as string | null
		})
	}

	// ... handleConnect, router, etc. stay the same ...

	private async loadRoom(): Promise<TLSocketRoom<TLRecord, void>> {
		const sql = new DurableObjectSqliteSyncWrapper(this.ctx.storage)

		// If SQLite already has data, use it directly
		if (SQLiteSyncStorage.hasBeenInitialized(sql)) {
			const storage = new SQLiteSyncStorage<TLRecord>({ sql })
			return new TLSocketRoom<TLRecord, void>({ schema, storage })
		}

		// Try to load from R2 (legacy storage, only happens once per room)
		if (this.roomId) {
			const r2Object = await this.env.TLDRAW_BUCKET.get(`rooms/${this.roomId}`)
			if (r2Object) {
				const snapshot = (await r2Object.json()) as RoomSnapshot
				const storage = new SQLiteSyncStorage<TLRecord>({ sql, snapshot })

				// Optionally delete the R2 object after successful migration
				// await this.env.TLDRAW_BUCKET.delete(`rooms/${this.roomId}`)

				return new TLSocketRoom<TLRecord, void>({ schema, storage })
			}
		}

		// No existing data - create fresh room
		const storage = new SQLiteSyncStorage<TLRecord>({ sql })
		return new TLSocketRoom<TLRecord, void>({ schema, storage })
	}
}
```

--------------------------------

### Implement getIndicatorPath for a simple shape

Source: https://tldraw.dev/docs/indicators

Define a basic rectangular indicator path for a shape by implementing the getIndicatorPath method in your ShapeUtil class.

```typescript
class CardShapeUtil extends ShapeUtil<CardShape> {
	// ...

	getIndicatorPath(shape: CardShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}
}
```

--------------------------------

### Register URL Unfurling Handler

Source: https://tldraw.dev/docs/sync

Registers an external asset handler for URLs with the Editor component to support bookmark shapes.

```jsx
<Tldraw
	store={store}
	onMount={(editor) => {
		editor.registerExternalAssetHandler('url', unfurlBookmarkUrl)
	}}
/>
```

--------------------------------

### Override getHandleSnapGeometry

Source: https://tldraw.dev/docs/handles

Customize snap points and self-snapping behavior by overriding getHandleSnapGeometry in your ShapeUtil implementation.

```typescript
import { HandleSnapGeometry, ShapeUtil } from 'tldraw'

class BezierCurveUtil extends ShapeUtil<BezierCurveShape> {
	// ...

	override getHandleSnapGeometry(shape: BezierCurveShape): HandleSnapGeometry {
		return {
			// Points other shapes' handles can snap to
			points: [shape.props.start, shape.props.end],

			// Points this shape's own handles can snap to (for self-snapping)
			getSelfSnapPoints: (handle) => {
				if (handle.id === 'controlPoint') {
					return [shape.props.start, shape.props.end]
				}
				return []
			},
		}
	}
}
```

--------------------------------

### Validate Meta with Schema

Source: https://tldraw.dev/docs/shapes

Define a custom schema with meta validators to enforce data structure at runtime.

```typescript
import { useState } from 'react'
import { createTLSchema, createTLStore, defaultShapeSchemas, T, Tldraw } from 'tldraw'

const schema = createTLSchema({
	shapes: {
		...defaultShapeSchemas,
		geo: {
			...defaultShapeSchemas.geo,
			meta: { createdBy: T.string },
		},
	},
})

export default function App() {
	const [store] = useState(() => createTLStore({ schema }))
	return <Tldraw store={store} />
}
```

--------------------------------

### Create a Mermaid diagram

Source: https://tldraw.dev/docs/mermaid

Use the createMermaidDiagram function to convert a Mermaid source string into editable shapes on the canvas.

```typescript
import { createMermaidDiagram } from '@tldraw/mermaid'

await createMermaidDiagram(
	editor,
	`
  flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do something]
    B -->|No| D[Do something else]
`
)
```

--------------------------------

### Configure handle snapType

Source: https://tldraw.dev/docs/handles

Define the snapType property on a handle to enable snapping to other shapes' geometry. Use 'point' instead of the deprecated canSnap flag.

```typescript
{
	id: 'end',
	type: 'vertex',
	index: ZERO_INDEX_KEY,
	x: shape.props.endX,
	y: shape.props.endY,
	snapType: 'point', // Snap to points on other shapes
}
```
Tokens:
Raw