setFocusedEditor(null)} >

Focusing: {focusName}

<div
					style={{
						width: '100%',
						display: 'grid',
						gridTemplateColumns: 'repeat(auto-fit, minmax(420px, 1fr))',
						gap: 64,
					}}
				>
					<EditorB />
					<EditorC />
				</div>
				<p>
					These two editors share the same persistence key so they will share a (locally)
					synchronized document.
				</p>
				<ABunchOfText />
			</focusedEditorContext.Provider>
		</div>
	)
}

// [3]
function EditorA() {
	const { setFocusedEditor } = useContext(focusedEditorContext)

return (
		<div style={{ padding: 32 }}>
			<h2>A</h2>
			<div
				tabIndex={-1}
				onFocus={() => setFocusedEditor((window as any).EDITOR_A)}
				style={{ height: 600 }}
				// Capture pointer down events that happen within the editor
				onPointerDown={(e) => e.stopPropagation()}
			>
				<Tldraw
					persistenceKey="steve"
					className="A"
					autoFocus={false}
					onMount={(editor) => {
						;(window as any).EDITOR_A = editor
						setFocusedEditor(editor)
					}}
				/>
			</div>
		</div>
	)
}

// [4]
function EditorB() {
	const { setFocusedEditor } = useContext(focusedEditorContext)
	return (
		<div>
			<h2>B</h2>
			<div
				tabIndex={-1}
				onFocus={() => setFocusedEditor((window as any).EDITOR_B)}
				style={{ height: 600 }}
			>
				<Tldraw
					persistenceKey="david"
					className="B"
					autoFocus={false}
					onMount={(editor) => {
						;(window as any).EDITOR_B = editor
					}}
				/>
			</div>
		</div>
	)
}

function EditorC() {
	const { setFocusedEditor } = useContext(focusedEditorContext)
	return (
		<div>
			<h2>C</h2>
			<div
				tabIndex={-1}
				onFocus={() => setFocusedEditor((window as any).EDITOR_C)}
				style={{ height: 600 }}
			>
				<Tldraw
					persistenceKey="david"
					className="C"
					autoFocus={false}
					onMount={(editor) => {
						;(window as any).EDITOR_C = editor
					}}
				/>
			</div>
		</div>
	)
}

// [5]
function ABunchOfText() {
	return (
		<article style={{ maxWidth: 500 }}>
			<h1>White Board</h1>
			<h2>Chapter 1: The First Strokes</h2>
			<p>
				The fluorescent lights flickered overhead as John sat hunched over his desk, his fingers
				tapping rhythmically on the keyboard. He was a software developer, and tonight, he had a
				peculiar mission. A mission that would take him deep into the labyrinthine world of web
				development. John had stumbled upon a new whiteboard library called “tldraw”, a seemingly
				simple tool that promised to revolutionize collaborative drawing on the web. Little did he
				know that this discovery would set off a chain of events that would challenge his skills,
				test his perseverance, and blur the line between reality and imagination.
			</p>
			<p>
				With a newfound sense of excitement, John began integrating “tldraw” into his latest
				project. As lines of code danced across his screen, he imagined the possibilities that lay
				ahead. The potential to create virtual spaces where ideas could be shared, concepts could be
				visualized, and teams could collaborate seamlessly from different corners of the world. It
				was a dream that seemed within reach, a vision of a future where creativity and technology
				merged into a harmonious symphony.
			</p>
			<p>
				As the night wore on, John’s mind became consumed with the whiteboard library. He couldn’t
				help but marvel at its elegance and simplicity. With each stroke of his keyboard, he felt a
				surge of inspiration, a connection to something greater than himself. It was as if the lines
				of code he was writing were transforming into a digital canvas, waiting to be filled with
				the strokes of imagination. In that moment, John realized that he was not just building a
				tool, but breathing life into a new form of expression. The whiteboard was no longer just a
				blank slate; it had become a portal to a world where ideas could flourish and dreams could
				take shape.
			</p>
			<p>
				Little did John know, this integration of “tldraw” was only the beginning. It would lead him
				down a path filled with unforeseen challenges, where he would confront his own limitations
				and question the very nature of creation. The journey ahead would test his resolve, pushing
				him to the edge of his sanity. And as he embarked on this perilous adventure, he could not
				shake the feeling that the whiteboard held secrets far beyond his understanding. Secrets
				that would unfold before his eyes, one stroke at a time.
			</p>
		</article>
	)
}

/* 
This example shows how to use multiple editors on the same page. When doing this, you'll
need to make sure that only one editor is focused at a time. We can manage this using 
the autofocus prop on the tldraw component, along with React's context and set state 
APIs.

[1]
We first create a context that will hold the focused editor id and a setter for that id. 
We'll use this to keep track of which editor is focused.

[2]
Wrap the editors in the context provider. This will make the context available to all
of the editors.

[3]	
Get the focused editor id and the setter from the context. We'll use these to determine
if the editor should be focused or not. We wrap the Tldraw component in a div and use 
the onFocus event to set the focused editor id.

[4]
Same again, but we're using the same persistence key for editors B and C. This means
that they will share a document.

[5]
A long story that doesn't really go anywhere, clearly written by a computer. But it's	
a good way to test the scroll behavior of the page.
*/
```

--------

# External dialog

Category: Page layout

Keywords: css

Make dialogs open outside of the `Tldraw` component.

You can make dialogs open outside of the `Tldraw` component by overriding our default styles. To see this in action, open the Insert embed dialog through the menu or by pressing 'Cmd + I'.

## App.tsx

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

// This CSS file overrides the default styles for dialogs
import './external-dialog.css'

export default function ExternalDialog() {
	return (
		<div style={{ margin: 32, width: 600, height: 400 }}>
			<Tldraw />
		</div>
	)
}
```

## external-dialog.css

```css
.tlui-dialog__overlay {
	position: fixed;
}
```

--------

# External UI (using context)

Category: Page layout

Keywords: outside, editor, context

This example shows how to control the tldraw editor from an external UI, using React context.

This example shows how to control the tldraw editor from an external UI, outside
of the `Tldraw` component. There are a few ways of doing this—for example, by putting the editor on the window object, passing it around via props, or using React context.

In this example, we use React context to distribute a reference to the editor to child components.

## App.tsx

```tsx
import { createContext, useContext, useState } from 'react'
import { Editor, GeoShapeGeoStyle, Tldraw, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './external-ui.css'

// There's a guide at the bottom of this file!

// [1]
const editorContext = createContext({} as { editor: Editor })

export default function ExternalUiExample2() {
	const [editor, setEditor] = useState<Editor | null>(null)

// [4]
const ExternalToolbar = () => {
	const { editor } = useContext(editorContext)

const currentToolId = useValue('current tool id', () => editor?.getCurrentToolId(), [editor])

return (
		<div>
			<div className="external-toolbar">
				<button
					className="external-button"
					data-isactive={currentToolId === 'select'}
					onClick={() => editor.setCurrentTool('select')}
				>
					Select
				</button>
				<button
					className="external-button"
					data-isactive={currentToolId === 'draw'}
					onClick={() => editor.setCurrentTool('draw')}
				>
					Pencil
				</button>
				<button
					className="external-button"
					data-isactive={
						currentToolId === 'geo' && editor?.getStyleForNextShape(GeoShapeGeoStyle) === 'oval'
					}
					onClick={() => {
						editor.run(() => {
							editor.setStyleForNextShapes(GeoShapeGeoStyle, 'oval')
							editor.setCurrentTool('geo')
						})
					}}
				>
					Oval
				</button>
			</div>
		</div>
	)
}

[1] 
Use React context to store the editor at a higher place in the React component tree.

[2] 
Use the `onMount` prop to get the editor instance and store it in state.

[3]
When we have an editor in state, render the context provider and its descendants.

[4]
You can access the editor from any of the provider's descendants.
*/
```

## external-ui.css

```css
.external-toolbar {
	display: flex;
	align-items: center;
	justify-content: center;
	padding: 8px;
	gap: 8px;
}

.external-button {
	pointer-events: all;
	padding: 4px 12px;
	background: white;
	border: 1px solid black;
	border-radius: 16px;
}

.external-button[data-isactive='true'] {
	background-color: black;
	color: white;
}
```

--------

# External UI (using state)

Category: Page layout

Keywords: outside, editor

This example shows how to control the tldraw editor from an external UI, using state.

In this example, we'll just put the editor instance in state and use it in the same component. See the [other External UI example](https://tldraw.dev/examples/external-ui-context) for an alternative (and more realistic) solution using React context.

## App.tsx

```tsx
import { useState } from 'react'
import { Editor, GeoShapeGeoStyle, Tldraw, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './external-ui.css'

// There's a guide at the bottom of this file!

export default function ExternalUiExample() {
	// [1]
	const [editor, setEditor] = useState<Editor | null>(null)

const currentToolId = useValue('current tool id', () => editor?.getCurrentToolId(), [editor])

return (
		<div style={{ margin: 32, width: 600 }}>
			<div style={{ height: 400 }}>
				<Tldraw
					// [2]
					onMount={(editor) => setEditor(editor)}
					components={{ Toolbar: null }}
				/>
			</div>
			{/* [3] */}
			<div>
				<div className="external-toolbar">
					<button
						className="external-button"
						data-isactive={currentToolId === 'select'}
						onClick={() => editor?.setCurrentTool('select')}
					>
						Select
					</button>
					<button
						className="external-button"
						data-isactive={currentToolId === 'draw'}
						onClick={() => editor?.setCurrentTool('draw')}
					>
						Pencil
					</button>
					<button
						className="external-button"
						data-isactive={
							currentToolId === 'geo' && editor?.getStyleForNextShape(GeoShapeGeoStyle) === 'oval'
						}
						onClick={() => {
							if (!editor) return
							editor.run(() => {
								// [4]
								editor.setStyleForNextShapes(GeoShapeGeoStyle, 'oval')
								editor.setCurrentTool('geo')
							})
						}}
					>
						Oval
					</button>
				</div>
			</div>
		</div>
	)
}

/*
[1] 
Use React state to store the editor instance.

[2]
Use the `onMount` prop to get the editor instance and store it in state.

[3]
Use data from the editor instance or use the editor's methods to control the editor.
Note that these callbacks also need to work if the editor isn't mounted yet.

[4]
The geo tool is a bit special since it controls the creation of many geo shapes (oval, rectangle, etc).
This is why we first set the type of the shape we wish to add, then we set the tool to 'geo'.
You can see all the available geo shapes in the `GeoShapeGeoStyle` enum.
*/
```

## external-ui.css

```css
.external-toolbar {
	display: flex;
	align-items: center;
	justify-content: center;
	padding: 8px;
	gap: 8px;
}

.external-button {
	pointer-events: all;
	padding: 4px 12px;
	background: white;
	border: 1px solid black;
	border-radius: 16px;
}

.external-button[data-isactive='true'] {
	background-color: black;
	color: white;
}
```

--------

# Snapshot image component

Category: Page layout

Keywords: snapshot, export

Display a tldraw snapshot as an image by using the `TldrawImage` component.

The `TldrawImage` component is a simple way to display a tldraw snapshot as an image. This example shows how to use it.

## App.tsx

```tsx
import { useState } from 'react'
import {
	Box,
	Editor,
	StoreSnapshot,
	TLPageId,
	TLRecord,
	TLStoreSnapshot,
	Tldraw,
	TldrawImage,
	getSnapshot,
} from 'tldraw'
import 'tldraw/tldraw.css'
import initialSnapshot from './snapshot.json'

// There's a guide at the bottom of this file!

export default function TldrawImageExample() {
	const [editor, setEditor] = useState<Editor>()
	const [snapshot, setSnapshot] = useState<StoreSnapshot<TLRecord>>(
		initialSnapshot as TLStoreSnapshot
	)
	const [currentPageId, setCurrentPageId] = useState<TLPageId | undefined>()
	const [showBackground, setShowBackground] = useState(true)
	const [isDarkMode, setIsDarkMode] = useState(false)
	const [viewportPageBounds, setViewportPageBounds] = useState(new Box(0, 0, 600, 400))
	const [isEditing, setIsEditing] = useState(false)
	const [format, setFormat] = useState<'svg' | 'png'>('svg')

return (
		<div style={{ padding: 30 }}>
			<div>
				<button
					style={{ cursor: 'pointer', marginRight: 8 }}
					onClick={() => {
						if (isEditing) {
							if (!editor) return
							setIsDarkMode(editor.user.getIsDarkMode())
							setShowBackground(editor.getInstanceState().exportBackground)
							setViewportPageBounds(editor.getViewportPageBounds())
							setCurrentPageId(editor.getCurrentPageId())
							setSnapshot(getSnapshot(editor.store).document)
							setIsEditing(false)
						} else {
							setIsEditing(true)
						}
					}}
				>
					{isEditing ? '✓ Save drawing' : '✎ Edit drawing'}
				</button>
				{!isEditing && (
					<>
						<label htmlFor="format" style={{ marginRight: 8 }}>
							Format
						</label>
						<select
							name="format"
							value={format}
							onChange={(e) => {
								setFormat(e.currentTarget.value as 'svg' | 'png')
							}}
						>
							<option value="svg">SVG</option>
							<option value="png">PNG</option>
						</select>
					</>
				)}
			</div>
			<div style={{ width: 600, height: 400, marginTop: 15 }}>
				{isEditing ? (
					<Tldraw
						snapshot={snapshot}
						onMount={(editor: Editor) => {
							setEditor(editor)
							editor.user.updateUserPreferences({ colorScheme: isDarkMode ? 'dark' : 'light' })
							if (currentPageId) {
								editor.setCurrentPage(currentPageId)
							}
							if (viewportPageBounds) {
								editor.zoomToBounds(viewportPageBounds, { inset: 0 })
							}
						}}
					/>
				) : (
					<TldrawImage
						//[1]
						snapshot={snapshot}
						// [2]
						pageId={currentPageId}
						// [3]
						background={showBackground}
						darkMode={isDarkMode}
						bounds={viewportPageBounds}
						padding={0}
						scale={1}
						format={format}
					/>
				)}
			</div>
		</div>
	)
}

This example shows how to use the `TldrawImage` component to display a snapshot
as an image. The example also allows you to toggle between editing the snapshot
and viewing it.

[1] Pass your snapshot to the `snapshot` prop of the `TldrawImage` component.

[2] You can specify which page to display by using the `pageId` prop. By
    default, the first page is shown.

[3] You can customize the appearance of the image by passing other props to the
        `TldrawImage` component. For example, you can toggle the background, set
        the dark mode, and specify the viewport bounds.
 */
```

--------

# Unsaved changes

Category: Events & effects

Keywords: save, unsaved, changes, document, listen, state

Track unsaved changes and enable save functionality.

This example shows how to track when the document has unsaved changes by listening to document scope events. A save button is enabled only when there are unsaved changes, and clicking it clears the unsaved state. The example uses `Editor.store.listen` with the `document` scope to monitor changes to the tldraw document.

## App.tsx

```tsx
import { useCallback, useEffect, useRef, useState } from 'react'
import {
	RecordsDiff,
	TLComponents,
	TLEditorSnapshot,
	TLEventMapHandler,
	TLRecord,
	Tldraw,
	squashRecordDiffs,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

function SaveButton() {
	const editor = useEditor()
	const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false)

const rUnsavedChanges = useRef<RecordsDiff<TLRecord>>({ added: {}, removed: {}, updated: {} })

useEffect(() => {
		// [1]
		const handleDocumentChange: TLEventMapHandler<'change'> = (diff) => {
			squashRecordDiffs([rUnsavedChanges.current, diff.changes], { mutateFirstDiff: true })
			setHasUnsavedChanges(
				!isPlainObjectEmpty(rUnsavedChanges.current.added) ||
					!isPlainObjectEmpty(rUnsavedChanges.current.removed) ||
					!isPlainObjectEmpty(rUnsavedChanges.current.updated)
			)
		}

// [2]
		return editor.store.listen(handleDocumentChange, { scope: 'document' })
	}, [editor])

// [3]
	const handleSave = useCallback(() => {
		// The diff is the difference between the current document and the last saved document
		const diff = rUnsavedChanges.current

// Maybe also get the current document / schema snapshot
		const snapshot = editor.getSnapshot()

// Save everything somewhere...
		saveChanges(diff, snapshot)

// Clear the unsaved changes state
		setHasUnsavedChanges(false)

// Reset the diff
		rUnsavedChanges.current = {
			added: {},
			removed: {},
			updated: {},
		}
	}, [editor])

return (
		<button
			onClick={handleSave}
			disabled={!hasUnsavedChanges}
			style={{
				pointerEvents: 'all',
				padding: '8px 16px',
				marginTop: '6px',
				backgroundColor: hasUnsavedChanges ? '#2d7d32' : '#ccc',
				color: hasUnsavedChanges ? 'white' : '#666',
				border: 'none',
				borderRadius: '4px',
				cursor: hasUnsavedChanges ? 'pointer' : 'not-allowed',
				fontWeight: '500',
			}}
		>
			{hasUnsavedChanges ? 'Save Changes' : 'No Changes'}
		</button>
	)
}

function saveChanges(_diff: RecordsDiff<TLRecord>, _snapshot: TLEditorSnapshot) {
	// todo: do something with the diff, or save the whole document snapshot somewhere
}

function isPlainObjectEmpty(obj: object) {
	for (const key in obj) return false
	return true
}

// [4]
const components: TLComponents = {
	TopPanel: SaveButton,
}

export default function UnsavedChangesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw components={components} />
		</div>
	)
}

/*
This example shows how to track unsaved changes in a tldraw document using the store's 
listen method with document scope, and how to accumulate a diff of all changes since 
the last save.

[1]
We create a handler that will be called whenever there are changes to the document. 
The handler receives a diff of the changes that occurred. We use `squashRecordDiffs` 
to accumulate all changes since the last save into a single diff object. This gives 
us a complete picture of what has changed without storing redundant intermediate states.

[2]
We listen to store changes with the 'document' scope, which means we only get notified 
about changes to document content (shapes, pages, etc.) and not to instance data like 
camera position or selected shapes.

[3]
The save function demonstrates how you might handle saving in a real application. We 
pass both the accumulated diff (showing exactly what changed since last save) and a 
complete snapshot of the current document state to our save function. After saving, 
we reset both the unsaved changes flag and the accumulated diff. In a real application, 
you might send just the diff to minimize bandwidth, or save the full snapshot for 
simpler server-side handling.

[4]
We define our component overrides outside of the React component to keep them static. 
This prevents unnecessary re-renders and follows React best practices. The SaveButton 
component is placed in the TopPanel to provide a prominent save interface.
*/
```

--------

# Signals

Category: Events & effects

Keywords: signia, state, store, side, effects, subscribe, track

React to changes by using signals.

tldraw uses signals to manage its state and store. You can subscribe to values in the store and run
side effects when they change. This example shows some ways of doing that.

## App.tsx

```tsx
import { TLComponents, Tldraw, track, useEditor, useReactor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

// [1]
const InfoPanel = track(() => {
	const editor = useEditor()
	const tool = editor.getCurrentToolId()
	const zoom = editor.getZoomLevel().toFixed(2)
	useReactor(
		'change title',
		() => {
			const shapes = editor.getCurrentPageShapes()
			document.title = `shapes: ${shapes.length}`
		},
		[editor]
	)
	return (
		<div style={{ pointerEvents: 'all', backgroundColor: 'thistle', fontSize: 14, padding: 8 }}>
			<div>tool: {tool}</div>
			<div>zoom: {zoom}</div>
		</div>
	)
})

// [2]
// eslint-disable-next-line @typescript-eslint/no-unused-vars
function AlternativeInfoPanel() {
	const editor = useEditor()
	const tool = useValue(
		'current tool',
		() => {
			if (!editor) throw new Error('No editor')
			return `Current Tool: ${editor.getCurrentToolId()}`
		},
		[editor]
	)
	const zoom = useValue(
		'zoom',
		() => {
			if (!editor) throw new Error('No editor')
			return `Zoom Level: ${editor.getZoomLevel().toFixed(2)}`
		},
		[editor]
	)

return (
		<div style={{ pointerEvents: 'all', backgroundColor: 'thistle', fontSize: 14, padding: 8 }}>
			<div>{tool}</div>
			<div>{zoom}</div>
		</div>
	)
}

const components: TLComponents = {
	SharePanel: InfoPanel,
}

export default function StateStoreExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw components={components} />
		</div>
	)
}

tldraw uses signals to manage its state and store. You can subscribe to values in the store 
and run side effects when they change.

[1]
	Our InfoPanel component will display above the style panel. We want it to show the current
	selected tool and zoom level of the editor. In order to make sure it displays up-to-date
	information, we can wrap the component in the track function. This will track any signals
	used in the component and re-render it when they change. 
	
	We also use the useReactor hook to update the document title with the number of shapes. This 
	side effect will run whenever the shapes on the page change. We pass the editor as a 
	dependency to the useReactor hook so it will always have the latest editor instance. 
	useQuickReactor runs immediately, whereas useReactor runs on the next animation frame.

[2]
	We can also use the useValue hook to subscribe to a value in the store. You can pass it a 
	value or a function. Functions will be memoized and only re-run when the dependencies change.

*/
```

--------

# Canvas events

Category: Events & effects

Keywords: cursor, pointer, mouse, click, keyboard, handler, input

Listen to events from tldraw's canvas.

This example listens to events from tldraw's canvas and shows them on the right-hand-side. Try moving your cursor, dragging, using modifier keys, etc.

## App.tsx

```tsx
import { useCallback, useState } from 'react'
import { TLEventInfo, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!
type TimedEvent = TLEventInfo & { lastUpdated: number }

export default function CanvasEventsExample() {
	const [events, setEvents] = useState<Record<string, TimedEvent>>({})

const handleEvent = useCallback((data: TLEventInfo) => {
		// Update the event entry for this event type with new data
		// This replaces previous event data of this type completely, keeping one per type
		setEvents((prevEvents) => ({
			...prevEvents,
			[data.type]: {
				...data,
				lastUpdated: Date.now(),
			},
		}))
	}, [])

// Convert events to array and sort by lastUpdated ascending (newest at bottom)
	const eventsArray = Object.values(events).sort((a, b) => a.lastUpdated - b.lastUpdated)

return (
		<div style={{ display: 'flex' }}>
			<div style={{ width: '50%', height: '100vh' }}>
				<Tldraw
					onMount={(editor) => {
						editor.on('event', (event) => handleEvent(event))
					}}
				/>
			</div>
			<div
				style={{
					width: '50%',
					height: '100vh',
					padding: 8,
					background: '#eee',
					border: 'none',
					fontFamily: 'monospace',
					fontSize: 12,
					borderLeft: 'solid 2px #333',
					display: 'flex',
					flexDirection: 'column-reverse',
					overflow: 'auto',
					whiteSpace: 'pre-wrap',
				}}
				onCopy={(event) => event.stopPropagation()}
			>
				<pre>{JSON.stringify(eventsArray, undefined, 2)}</pre>
			</div>
		</div>
	)
}

/* 
This example shows how to listen to canvas events. This includes things like pointer and 
keyboard events, but not things such as undo/redo, create/delete shapes, etc. Those are store events.

To listen to changes to the store, check out the store events example.
*/
```

--------

# Store events

Category: Events & effects

Keywords: listen, changes

Listen to changes from tldraw's store.

This example listens to changes from tldraw's store and shows them on the right-hand-side. Try creating & deleting shapes, or switching pages. The changes will be logged next to the canvas.

## App.tsx

```tsx
import _ from 'lodash'
import { useCallback, useEffect, useState } from 'react'
import { Editor, TLEventMapHandler, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

export default function StoreEventsExample() {
	const [editor, setEditor] = useState<Editor>()

const setAppToState = useCallback((editor: Editor) => {
		setEditor(editor)
	}, [])

const [storeEvents, setStoreEvents] = useState<string[]>([])

useEffect(() => {
		if (!editor) return

function logChangeEvent(eventName: string) {
			setStoreEvents((events) => [...events, eventName])
		}

//[1]
		const handleChangeEvent: TLEventMapHandler<'change'> = (change) => {
			// Added
			for (const record of Object.values(change.changes.added)) {
				if (record.typeName === 'shape') {
					logChangeEvent(`created shape (${record.type})\n`)
				}
			}

// Updated
			for (const [from, to] of Object.values(change.changes.updated)) {
				if (
					from.typeName === 'instance' &&
					to.typeName === 'instance' &&
					from.currentPageId !== to.currentPageId
				) {
					logChangeEvent(`changed page (${from.currentPageId}, ${to.currentPageId})`)
				} else if (from.id.startsWith('shape') && to.id.startsWith('shape')) {
					let diff = _.reduce(
						from,
						(result: any[], value, key: string) =>
							_.isEqual(value, (to as any)[key]) ? result : result.concat([key, (to as any)[key]]),
						[]
					)
					if (diff?.[0] === 'props') {
						diff = _.reduce(
							(from as any).props,
							(result: any[], value, key) =>
								_.isEqual(value, (to as any).props[key])
									? result
									: result.concat([key, (to as any).props[key]]),
							[]
						)
					}
					logChangeEvent(`updated shape (${JSON.stringify(diff)})\n`)
				}
			}

// Removed
			for (const record of Object.values(change.changes.removed)) {
				if (record.typeName === 'shape') {
					logChangeEvent(`deleted shape (${record.type})\n`)
				}
			}
		}

// [2]
		const cleanupFunction = editor.store.listen(handleChangeEvent, { source: 'user', scope: 'all' })

return () => {
			cleanupFunction()
		}
	}, [editor])

return (
		<div style={{ display: 'flex' }}>
			<div style={{ width: '60%', height: '100vh' }}>
				<Tldraw onMount={setAppToState} />
			</div>
			<div
				style={{
					width: '40%',
					height: '100vh',
					padding: 8,
					background: '#eee',
					border: 'none',
					fontFamily: 'monospace',
					fontSize: 12,
					borderLeft: 'solid 2px #333',
					display: 'flex',
					flexDirection: 'column-reverse',
					overflow: 'auto',
				}}
				onCopy={(event) => event.stopPropagation()}
			>
				<pre>{storeEvents}</pre>
			</div>
		</div>
	)
}

/* 
This example shows how to listen to store events. This includes things creating/deleting shapes,
or moving between pages, but not things such as pointer and keyboard events. Those are canvas events.
To listen to changes to the canvas, check out the canvas events example.

[1]
This is the fire hose, it will be called at the end of every transaction. We're checking to see what 
kind of changes were made and logging a more readable message to the to our panel.

[2]
This is the function that subscribes to changes to the store. You pass in the callback function that 
you want to execute along with a handy filter object. In this case, we're only listening to changes
that were made by the user. It also returns a cleanup function that you can shove into the return of 
a useeffect hook.

*/
```

--------

# UI events

Category: Events & effects

Keywords: ui, events, api, x-ray

Listen to UI events.

This example listens to UI events and shows them on the right-hand-side. Try creating & deleting shapes, or switching pages. The events will be logged next to the canvas.

Try selecting tools, using keyboard shortcuts, undo/redo, etc. Events will be logged next to the canvas.

## App.tsx

```tsx
import { Fragment, useCallback, useState } from 'react'
import { TLUiEventHandler, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { getCodeSnippet } from './codeSnippets'

// There's a guide at the bottom of this file!

export default function UiEventsExample() {
	const [uiEvents, setUiEvents] = useState<string[]>([])

const handleUiEvent = useCallback<TLUiEventHandler>((name, data: any) => {
		const codeSnippet = getCodeSnippet(name, data)
		setUiEvents((events) => [
			...events,
			`event: ${name} ${JSON.stringify(data)}${codeSnippet && `\ncode:  ${codeSnippet}`}`,
		])
	}, [])

return (
		<div style={{ display: 'flex' }}>
			<div style={{ width: '60%', height: '100vh' }}>
				<Tldraw onUiEvent={handleUiEvent} />
			</div>
			<div
				style={{
					width: '40%',
					height: '100vh',
					padding: 8,
					background: '#eee',
					border: 'none',
					fontFamily: 'monospace',
					fontSize: 12,
					borderLeft: 'solid 2px #333',
					overflow: 'auto',
				}}
				onCopy={(event) => event.stopPropagation()}
			>
				{uiEvents.map((t, i) => (
					<Fragment key={i}>
						<pre style={{ borderBottom: '1px solid #000', marginBottom: 0, paddingBottom: '12px' }}>
							{t}
						</pre>
					</Fragment>
				))}
			</div>
		</div>
	)
}

/* 
This example shows how to listen to UI events. This includes includes things like selecting a tool,
grouping shapes, zooming etc. Events are included even if they are triggered by a keyboard shortcut.
However, interactions with the style panel are not included. For a full list of events and sources,
check out the TLUiEventSource and TLUiEventMap types.

It also shows the relevant code snippet for each event. This is useful for debugging and learning
the tldraw SDK.

We can pass a handler function to the onUiEvent prop of the Tldraw component. This handler function
will be called with the name of the event and the data associated with the event. We're going to 
display these events in a list on the right side of the screen.

To listen to canvas events or changes to the store, check out the canvas events and store events 
examples.

*/
```

## codeSnippets.ts

```ts
const STYLE_EVENT = {
	'tldraw:color': 'DefaultColorStyle',
	'tldraw:dash': 'DefaultDashStyle',
	'tldraw:fill': 'DefaultFillStyle',
	'tldraw:font': 'DefaultFontStyle',
	'tldraw:horizontalAlign': 'DefaultHorizontalAlignStyle',
	'tldraw:size': 'DefaultSizeStyle',
	'tldraw:verticalAlign': 'DefaultVerticalAlignStyle',
	'tldraw:geo': 'GeoShapeGeoStyle',
}

const REORDER_EVENT = {
	toFront: 'bringToFront',
	forward: 'bringForward',
	backward: 'sendBackward',
	toBack: 'sendToBack',
}

const SHAPES_META_EVENT = {
	'group-shapes': 'groupShapes',
	'ungroup-shapes': 'ungroupShapes',
	'delete-shapes': 'deleteShapes',
}

const SHAPES_EVENT = {
	'distribute-shapes': 'distributeShapes',
	'align-shapes': 'alignShapes',
	'stretch-shapes': 'stretchShapes',
	'flip-shapes': 'flipShapes',
}

const USER_PREFS_EVENT = {
	'toggle-snap-mode': 'isSnapMode',
	'toggle-dark-mode': 'isDarkMode',
	'toggle-reduce-motion': 'animationSpeed',
	'toggle-edge-scrolling': 'edgeScrollSpeed',
}

const PREFS_EVENT = {
	'toggle-transparent': 'exportBackground',
	'toggle-tool-lock': 'isToolLocked',
	'toggle-focus-mode': 'isFocusMode',
	'toggle-grid-mode': 'isGridMode',
	'toggle-debug-mode': 'isDebugMode',
}

const ZOOM_EVENT = {
	'zoom-in': 'zoomIn',
	'zoom-out': 'zoomOut',
	'reset-zoom': 'resetZoom',
	'zoom-to-fit': 'zoomToFit',
	'zoom-to-selection': 'zoomToSelection',
}

export function getCodeSnippet(name: string, data: any) {
	let codeSnippet = ''

if (name === 'set-style') {
		if (data.id === 'opacity') {
			codeSnippet = `editor.setOpacityForNextShapes(${data.value});`
		} else {
			codeSnippet = `editor.setStyleForNextShapes(${
				STYLE_EVENT[data.id as keyof typeof STYLE_EVENT] ?? '?'
			}, '${data.value}');`
		}
	} else if (['rotate-ccw', 'rotate-cw'].includes(name)) {
		codeSnippet = 'editor.rotateShapesBy(editor.getSelectedShapeIds(), <number>)'
	} else if (name === 'edit-link') {
		codeSnippet =
			'editor.updateShapes([{ id: editor.getOnlySelectedShape().id, type: editor.getOnlySelectedShape().type, props: { url: <url> }, }, ])'
	} else if (name.startsWith('export-as')) {
		codeSnippet = `exportAs(editor.getSelectedShapeIds(), '${data.format}')`
	} else if (name.startsWith('copy-as')) {
		codeSnippet = `copyAs(editor.getSelectedShapeIds(), '${data.format}')`
	} else if (name === 'select-all-shapes') {
		codeSnippet = `editor.selectAll()`
	} else if (name === 'select-none-shapes') {
		codeSnippet = `editor.selectNone()`
	} else if (name === 'reorder-shapes') {
		codeSnippet = `editor.${
			REORDER_EVENT[data.operation as keyof typeof REORDER_EVENT] ?? '?'
		}(editor.getSelectedShapeIds())`
	} else if (['group-shapes', 'ungroup-shapes', 'delete-shapes'].includes(name)) {
		codeSnippet = `editor.${
			SHAPES_META_EVENT[name as keyof typeof SHAPES_META_EVENT] ?? '?'
		}(editor.getSelectedShapeIds())`
	} else if (name === 'stack-shapes') {
		codeSnippet = `editor.stackShapes(editor.getSelectedShapeIds(), '${data.operation}', 16)`
	} else if (name === 'pack-shapes') {
		codeSnippet = `editor.packShapes(editor.getSelectedShapeIds(), 16)`
	} else if (name === 'duplicate-shapes') {
		codeSnippet = `editor.duplicateShapes(editor.getSelectedShapeIds(), {x: <value>, y: <value>})`
	} else if (name.endsWith('-shapes')) {
		codeSnippet = `editor.${
			SHAPES_EVENT[name as keyof typeof SHAPES_EVENT] ?? '?'
		}(editor.getSelectedShapeIds(), '${data.operation}')`
	} else if (name === 'select-tool') {
		if (data.id === 'media') {
			codeSnippet = 'insertMedia()'
		} else if (data.id.startsWith('geo-')) {
			codeSnippet = `\n  editor.updateInstanceState({
  stylesForNextShape: {
    ...editor.getInstanceState().stylesForNextShape,
    [GeoShapeGeoStyle.id]: '${data.id.replace('geo-', '')}',
  },
}, { ephemeral: true });
editor.setCurrentTool('${data.id}')`
		} else {
			codeSnippet = `editor.setCurrentTool('${data.id}')`
		}
	} else if (name === 'print') {
		codeSnippet = 'printSelectionOrPages()'
	} else if (name === 'unlock-all') {
		codeSnippet = `\n  const updates = [] as TLShapePartial[]
for (const shape of editor.getCurrentPageShapes()) {
  if (shape.isLocked) {
    updates.push({ id: shape.id, type: shape.type, isLocked: false })
  }
}
if (updates.length > 0) {
  editor.updateShapes(updates)
}`
	} else if (['undo', 'redo'].includes(name)) {
		codeSnippet = `editor.${name}()`
	} else if (['cut', 'copy'].includes(name)) {
		codeSnippet = `\n  const { ${name} } = useMenuClipboardEvents();\n  ${name}()`
	} else if (name === 'paste') {
		codeSnippet = `\n  const { paste } = useMenuClipboardEvents();\n  navigator.clipboard?.read().then((clipboardItems) => {\n    paste(clipboardItems)\n  })`
	} else if (name === 'stop-following') {
		codeSnippet = `editor.stopFollowingUser()`
	} else if (name === 'exit-pen-mode') {
		codeSnippet = `editor.updateInstanceState({ isPenMode: false })`
	} else if (name === 'remove-frame') {
		codeSnippet = `removeFrame(editor, editor.getSelectedShapes().map((shape) => shape.id))`
	} else if (name === 'fit-frame-to-content') {
		codeSnippet = `fitFrameToContent(editor, editor.getOnlySelectedShape().id)`
	} else if (name.startsWith('zoom-') || name === 'reset-zoom') {
		codeSnippet = `editor.${ZOOM_EVENT[name as keyof typeof ZOOM_EVENT]}(${
			name !== 'zoom-to-fit' && name !== 'zoom-to-selection'
				? 'editor.getViewportScreenCenter(), '
				: ''
		}{ duration: 320 })`
	} else if (name.startsWith('toggle-')) {
		if (name === 'toggle-lock') {
			codeSnippet = `editor.toggleLock(editor.getSelectedShapeIds())`
		} else {
			const userPrefName = USER_PREFS_EVENT[name as keyof typeof USER_PREFS_EVENT]
			const prefName = PREFS_EVENT[name as keyof typeof PREFS_EVENT]
			codeSnippet = userPrefName
				? `editor.user.updateUserPreferences({ ${userPrefName}: <value> })`
				: `editor.updateInstanceState({ ${prefName}: !editor.getInstanceState().${prefName} })`
		}
	}

return codeSnippet
}
```

--------

# Block events

Category: Events & effects

Keywords: event, block, propagation, stop, no, select, user-select

Stop events from reaching the canvas.

If you don't want the user's interactions to reach the canvas, you can call `stopPropagation` on the user's pointer events.

## App.tsx

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

function WelcomeScreen() {
	return (
		<div
			style={{
				position: 'absolute',
				inset: 0,
				display: 'flex',
				alignItems: 'center',
				justifyContent: 'center',
				pointerEvents: 'none', // [1]
			}}
		>
			<div
				style={{
					padding: 32,
					borderRadius: 20,
					boxShadow: '2px 2px 12px rgba(0,0,0,.2)',
					backgroundColor: 'white',
					pointerEvents: 'all', // [2]
					width: 400,
				}}
			>
				<p
					style={{
						userSelect: 'text', // [3]
					}}
				>
					Notice that if you click on this box or start a drag from in here, you will not be
					interacting with the canvas. However, you can still interact with the canvas by clicking
					anywhere else!
				</p>
				<div>
					<button onClick={() => window.alert('Thanks')}>Click here</button>
				</div>
			</div>
		</div>
	)
}

const components: TLComponents = {
	InFrontOfTheCanvas: WelcomeScreen,
}

export default function EventBlockerExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="example" components={components} />
		</div>
	)
}

/*
[1]
This div will overlay the whole canvas. We want the user's pointer events to
pass through this div rather than getting blocked by it div, so we turn
pointer events off.

[2]
This is the container that's centered on the screen. For this div, we want to
block pointer events so that the user can't interact with the canvas behind it,
so we turn pointer events on.

[3]
As a side note, we also turn off user-select for anything inside of the canvas.
If you want the user to be able to select text, you can set this style to 'all'.
*/
```

--------

# Prevent instance changes

Category: Events & effects

Keywords: side, effect, instance, grid, mode, prevent

Prevent a change to the "instance" record that would turn off grid mode.

You can use Editor's side effects API to prevent certain changes from occurring in the instance state. In this example, we prevent the user from changing the instance's `isGridMode` property.

## App.tsx

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

// There's a guide at the bottom of this page!

export default function PreventInstanceChangeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					editor.updateInstanceState({ isGridMode: true })

// [1]
					editor.sideEffects.registerBeforeChangeHandler('instance', (prev, next) => {
						if (!next.isGridMode) {
							return prev
						}
						return next
					})
				}}
			/>
		</div>
	)
}

/*
In this example, we want to prevent the user from changing the isGridMode property.

[1]
Here we register a handler that will run whenever a change is about to be made to
to an "instance" type record.

The logic we want is that: if the new instance has `isGridMode` set to `false`, then
we want to reject the change; otherwise, we want to allow it.

To reject the change, we return the previous record. To allow the change, we
return the next record.
*/
```

--------

# Prevent shape changes

Category: Events & effects

Keywords: side, effect, move, prevent

Prevent changes to a shape's properties.

You can use Editor's side effects API to prevent certain changes from occurring in a shape. In this example, we prevent any changes to the shape's position, rotation, or size.

## App.tsx

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

// There's a guide at the bottom of this page!

export default function PreventMoveExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					editor.createShape({
						type: 'geo',
						x: 100,
						y: 100,
						props: {
							w: 300,
							h: 300,
							richText: toRichText("style me but don't transform me"),
						},
					})

// [1]
					editor.sideEffects.registerBeforeChangeHandler('shape', (prev, next) => {
						if (
							editor.isShapeOfType(prev, 'geo') &&
							editor.isShapeOfType(next, 'geo') &&
							next.props.geo === 'rectangle'
						) {
							if (
								next.x !== prev.x ||
								next.y !== prev.y ||
								next.rotation !== prev.rotation ||
								next.props.w !== prev.props.w ||
								next.props.h !== prev.props.h
							) {
								return prev
							}
						}
						return next
					})
				}}
			/>
		</div>
	)
}

/*
[1]
Here we register a handler that will run whenever a change is about to be made to
a shape's record.

The logic we want is that: if the shape is a geo shape and a rectangle, and then
if the x, y, or rotation properties would be different in the next version of
the shape record, or if the props.w, or props.h properties would change, then
we want to reject the change; otherwise, we want to allow it.

To reject the change, we return the previous record. To allow the change, we
return the next record.
*/
```

--------

# Prevent multi-shape selection

Category: Events & effects

Keywords: selection, editor, instance, state

This example demonstrates how to prevent users from selecting multiple shapes at once in tldraw.

You can prevent multiple shape selection by registering a before-change handler for the `instance_page_state` type. This handler intercepts selection changes and ensures only one shape can be selected at a time.

## App.tsx

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

export default function PreventMultiShapeSelectionExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [1]
					editor.sideEffects.registerBeforeChangeHandler('instance_page_state', (prev, next) => {
						// [2]
						if (
							prev.selectedShapeIds !== next.selectedShapeIds &&
							next.selectedShapeIds.length > 1
						) {
							return {
								...next,
								selectedShapeIds: [next.selectedShapeIds[next.selectedShapeIds.length - 1]],
							}
						}
						return next
					})
				}}
			/>
		</div>
	)
}

/*
In this example, we want to prevent the user from selecting multiple shapes at once.

[1]
Here we register a handler that will run whenever a change is about to be made to
an "instance_page_state" type record, which contains the current selection state.

[2]
We check if this is a selection change and if it would result in multiple shapes being selected.
If both conditions are true, we modify the change to only select the most recently
selected shape by returning a new record with a single selected shape id.
*/
```

--------

# Before create/update shape

Category: Events & effects

Keywords: handler, register, side effects, records

You can intercept the creation or update of any record in the store and return a new record to be
used in it place. In this example, we lock shapes to a circle in the center of the screen.

## App.tsx

```tsx
import { Box, Editor, SVGContainer, TLShape, Tldraw, Vec, isShapeId } from 'tldraw'
import 'tldraw/tldraw.css'

// This function takes a shape and returns a new shape where the x/y origin is within `radius`
// distance of the center of the page. If the shape is already within `radius` (or isn't parented to
// the page) it returns the same shape.
function constrainShapeToRadius(editor: Editor, shape: TLShape, radius: number) {
	// if the shape is parented to another shape (instead of the page) leave it as-is
	if (isShapeId(shape.parentId)) return shape

// get the position of the shape
	const shapePoint = Vec.From(shape)
	const distanceFromCenter = shapePoint.len()

// if the shape is outside the radius, move it to the edge of the radius:
	if (distanceFromCenter > radius) {
		const newPoint = shapePoint.uni().mul(radius)
		return {
			...shape,
			x: newPoint.x,
			y: newPoint.y,
		}
	}

// otherwise, leave the shape as-is
	return shape
}

export default function BeforeCreateUpdateShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// we can run our `constrainShapeToRadius` function before any shape is created
					// or changed. These `sideEffects` handlers let us take modify the shape that
					// will be created or updated by returning a new one to be used in its place.
					editor.sideEffects.registerBeforeCreateHandler('shape', (shape) => {
						return constrainShapeToRadius(editor, shape, 500)
					})
					editor.sideEffects.registerBeforeChangeHandler('shape', (prevShape, nextShape) => {
						return constrainShapeToRadius(editor, nextShape, 500)
					})

// center the camera on the area we're constraining shapes to
					editor.zoomToBounds(new Box(-500, -500, 1000, 1000))

// lock the camera on that area
					editor.setCameraOptions({ isLocked: true })
				}}
				components={{
					// to make it a little clearer what's going on in this example, we'll draw a
					// circle on the canvas showing where shapes are being constrained to.
					OnTheCanvas: () => (
						<SVGContainer>
							<circle cx={0} cy={0} r={500} fill="none" stroke="black" />
						</SVGContainer>
					),
				}}
			/>
		</div>
	)
}
```

--------

# Before delete shape

Category: Events & effects

Keywords: handler, register, side effects, records

You can intercept the creation of any record in the store. This example intercepts arrow creation to
make sure each arrow has a label. You can do the same thing to change the props of any newly created
shape.

## App.tsx

```tsx
import { Editor, Tldraw, createShapeId, toRichText } from 'tldraw'
import 'tldraw/tldraw.css'

export default function BeforeDeleteShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// register a handler to run before any shape is deleted:
					editor.sideEffects.registerBeforeDeleteHandler('shape', (shape) => {
						// if the shape is red, prevent the deletion:
						if ('color' in shape.props && shape.props.color === 'red') {
							return false
						}

return
					})

createDemoShapes(editor)
				}}
			/>
		</div>
	)
}

// create some shapes to demonstrate the side-effect we added
function createDemoShapes(editor: Editor) {
	editor
		.createShapes([
			{
				id: createShapeId(),
				type: 'text',
				props: {
					richText: toRichText("Red shapes can't be deleted"),
					color: 'red',
				},
			},
			{
				id: createShapeId(),
				type: 'text',
				y: 30,
				props: {
					richText: toRichText('but other shapes can'),
					color: 'black',
				},
			},
		])
		.zoomToFit({ animation: { duration: 0 } })
}
```

--------

# Custom double-click behavior

Category: Events & effects

Keywords: double click, runtime override, state node, select tool, custom behavior

Override the default double-click behavior by replacing the SelectTool's Idle state method at runtime.

This example shows how to customize the double-click behavior on canvas by overriding the SelectTool's Idle state's `handleDoubleClickOnCanvas` method from the `onMount` callback.

The example demonstrates runtime method replacement, which is a powerful technique for customizing built-in tool behavior without creating entirely new tools. In this simplified version, double-clicking on the canvas shows an alert instead of creating a text shape, demonstrating the basic pattern for method override.

This pattern is useful when you want to extend existing tool behavior, add conditional logic, or customize built-in interactions without forking the entire tool.

## App.tsx

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

// There's a guide at the bottom of this file!

export default function CustomDoubleClickBehaviorExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// [1]
				onMount={(editor) => {
					// [2]
					type IdleStateNode = StateNode & {
						handleDoubleClickOnCanvas(info: TLClickEventInfo): void
					}

// [3]
					const selectIdleState = editor.getStateDescendant<IdleStateNode>('select.idle')
					if (!selectIdleState) throw Error('SelectTool Idle state not found')

// [4]
					function customDoubleClickOnCanvasHandler(_info: TLClickEventInfo) {
						// Your custom behavior goes here...
						window.alert('double clicked on the canvas')
					}

// [5]
					selectIdleState.handleDoubleClickOnCanvas =
						customDoubleClickOnCanvasHandler.bind(selectIdleState)
				}}
			/>
		</div>
	)
}

/*
This example demonstrates how to customize the double-click behavior on canvas
by overriding the SelectTool's Idle state's handleDoubleClickOnCanvas method.

Key concepts:

[1] onMount callback:
    The onMount callback gives us access to the editor instance after it's 
    fully initialized. This is where we can access and modify built-in tools.

[2] Type definition for IdleStateNode:
    We create a type that extends StateNode and includes the handleDoubleClickOnCanvas
    method. This gives us proper TypeScript support when accessing the method.

[3] Getting the SelectTool's Idle state:
    We use `editor.getStateDescendant<IdleStateNode>('select.idle')` to get a 
    reference to the Idle state of the SelectTool. The path 'select.idle' 
    refers to the SelectTool's 'idle' child state.

[4] Custom handler function:
    We define our custom behavior in a separate function. This keeps the code
    clean and makes it easy to test or reuse the handler logic.

[5] Method replacement with binding:
    We replace the original handleDoubleClickOnCanvas method with our custom
    implementation, binding it to the selectIdleState context so that `this`
    refers to the correct state node when the function is called. This 
    completely overrides the default behavior.

The handleDoubleClickOnCanvas method is called when the user double-clicks on
the canvas (not on a shape). By overriding this method, we can customize what
happens when the user double-clicks on empty space.

Note: This approach completely replaces the original method. If you want to 
preserve the original behavior and add to it, you should store a reference
to the original method before replacing it, then call it from your custom
implementation when appropriate.
*/
```

--------

# After create/update shape

Category: Events & effects

Keywords: handler, register, side effects, records

You can register handlers to run after any record is created or updated. This is most useful for
updating _other_ records in response to a particular record changing. In this example, we make sure
there's only ever one red shape on a page.

## App.tsx

```tsx
import { Editor, TLShape, TLShapeId, Tldraw, createShapeId, toRichText } from 'tldraw'

type ShapeWithColor = Extract<TLShape, { props: { color: string } }>

// this function takes a shape ID, and if that shape is red, sets all other red shapes on the same
// page to black.
function ensureOnlyOneRedShape(editor: Editor, shapeId: TLShapeId) {
	// grab the shape and check it's red:
	const shape = editor.getShape(shapeId)!
	if (!isRedShape(shape)) return

// get the ID of the page that shape belongs to:
	const pageId = editor.getAncestorPageId(shape.id)!

// find any other red shapes on the same page:
	const otherRedShapesOnPage = Array.from(editor.getPageShapeIds(pageId))
		.map((id) => editor.getShape(id)!)
		.filter(
			(otherShape): otherShape is ShapeWithColor =>
				otherShape.id !== shape.id && isRedShape(otherShape)
		)

// set the color of all those shapes to black:
	editor.updateShapes(
		otherRedShapesOnPage.map((shape) => ({
			id: shape.id,
			type: shape.type,
			props: {
				color: 'black',
			},
		}))
	)
}

function isRedShape(shape: TLShape) {
	return 'color' in shape.props && shape.props.color === 'red'
}

export default function AfterCreateUpdateShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// we can run our `ensureOnlyOneRedShape` function after any shape is created or
					// changed. this means we can enforce our "only one red shape at a time" rule,
					// while making sure that the shape most recently set to red is the one that
					// stays red.
					editor.sideEffects.registerAfterCreateHandler('shape', (shape) => {
						ensureOnlyOneRedShape(editor, shape.id)
					})
					editor.sideEffects.registerAfterChangeHandler('shape', (prevShape, nextShape) => {
						ensureOnlyOneRedShape(editor, nextShape.id)
					})

createDemoShapes(editor)
				}}
			/>
		</div>
	)
}

// create some shapes to demonstrate the side-effects we added
function createDemoShapes(editor: Editor) {
	editor
		.createShapes(
			'there can only be one red shape'.split(' ').map((word, i) => ({
				id: createShapeId(),
				type: 'text',
				y: i * 30,
				props: {
					color: i === 5 ? 'red' : 'black',
					richText: toRichText(word),
				},
			}))
		)
		.zoomToFit({ animation: { duration: 0 } })
}
```

--------

# After delete shape

Category: Events & effects

Keywords: handler, register, side effects, records

You can register handlers to run after any record is deleted. In this example, we delete frames
after the last shape inside them is deleted.

## App.tsx

```tsx
import { Editor, Tldraw, createShapeId, toRichText } from 'tldraw'
import 'tldraw/tldraw.css'

export default function AfterDeleteShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// register a handler to run after any shape is deleted:
					editor.sideEffects.registerAfterDeleteHandler('shape', (shape) => {
						// grab the parent of the shape and check if it's a frame:
						const parentShape = editor.getShape(shape.parentId)
						if (parentShape && parentShape.type === 'frame') {
							// if it is, get the IDs of all its remaining children:
							const siblings = editor.getSortedChildIdsForParent(parentShape.id)

// if there are none (so the frame is empty), delete the frame:
							if (siblings.length === 0) {
								editor.deleteShape(parentShape.id)
							}
						}
					})

createDemoShapes(editor)
				}}
			/>
		</div>
	)
}

// crate some demo shapes to show off the new side-effect we added
function createDemoShapes(editor: Editor) {
	const frameId = createShapeId()
	editor.createShapes([
		{
			id: frameId,
			type: 'frame',
			props: { w: 400, h: 200 },
		},
		{
			id: createShapeId(),
			type: 'text',
			parentId: frameId,
			x: 50,
			y: 40,
			props: {
				richText: toRichText('Frames will be deleted when their last child is.'),
				w: 300,
				autoSize: false,
			},
		},
		...[50, 180, 310].map((x) => ({
			id: createShapeId(),
			type: 'geo' as const,
			parentId: frameId,
			x,
			y: 120,
			props: { w: 40, h: 40 },
		})),
	])

editor.zoomToFit({ animation: { duration: 0 } })
}
```

--------

# Permissions

Category: Events & effects

Keywords: constraints, bounds, side effects, permissions, clamping

Use side effect APIs to constrain shape movement within a bounding box.

This example demonstrates how to use tldraw's side effect APIs to enforce permissions or
constraints on shapes. Try dragging the rectangle around - its movement is constrained to
stay within the dashed container using the `registerBeforeChangeHandler` side effect.
This pattern is useful for implementing permission systems, bounded regions, or any scenario
where you need to restrict where shapes can be positioned.

## App.tsx

```tsx
import { Box, Editor, SVGContainer, TLGeoShape, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

// [1]
const CONTAINER_BOUNDS = new Box(100, 100, 400, 300)

// [2]
function constrainShapeToBounds(editor: Editor, shape: TLGeoShape) {
	const shapeGeometry = editor.getShapeGeometry(shape)
	const shapeBounds = shapeGeometry.bounds

// Calculate the shape's world-space bounds
	const shapeWorldBounds = Box.From({
		x: shape.x + shapeBounds.x,
		y: shape.y + shapeBounds.y,
		w: shapeBounds.w,
		h: shapeBounds.h,
	})

// Check if the shape is completely within the container
	if (CONTAINER_BOUNDS.contains(shapeWorldBounds)) {
		return shape
	}

// [3]
	// Clamp the shape's position so it stays within bounds
	const clampedX = Math.max(
		CONTAINER_BOUNDS.x - shapeBounds.x,
		Math.min(shape.x, CONTAINER_BOUNDS.maxX - shapeBounds.x - shapeBounds.w)
	)
	const clampedY = Math.max(
		CONTAINER_BOUNDS.y - shapeBounds.y,
		Math.min(shape.y, CONTAINER_BOUNDS.maxY - shapeBounds.y - shapeBounds.h)
	)

return {
		...shape,
		x: clampedX,
		y: clampedY,
	}
}

export default function PermissionsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [4]
					editor.sideEffects.registerBeforeChangeHandler('shape', (prevShape, nextShape) => {
						// Only constrain geo shapes (our rectangle)
						if (nextShape.type === 'geo') {
							return constrainShapeToBounds(editor, nextShape as TLGeoShape)
						}
						return nextShape
					})

// [5]
					// Create the constrained rectangle
					editor.createShape({
						type: 'geo',
						x: 250,
						y: 200,
						props: {
							geo: 'rectangle',
							w: 150,
							h: 100,
						},
					})

// Zoom to show the container area
					editor.zoomToBounds(new Box(0, 0, 600, 500), { animation: { duration: 0 } })
				}}
				components={{
					// [6]
					OnTheCanvas: () => (
						<SVGContainer>
							<rect
								x={CONTAINER_BOUNDS.x}
								y={CONTAINER_BOUNDS.y}
								width={CONTAINER_BOUNDS.w}
								height={CONTAINER_BOUNDS.h}
								fill="none"
								stroke="rgba(0, 0, 0, 0.2)"
								strokeWidth={2}
								strokeDasharray="8 4"
							/>
						</SVGContainer>
					),
				}}
			/>
		</div>
	)
}

/*
[1]
Define the invisible container bounds that our shape will be constrained to. This is a box
with top-left at (100, 100) and dimensions of 400x300.

[2]
This function checks if a shape's bounds extend outside the container and returns a modified
shape with clamped position if needed. We use editor.getShapeGeometry() to get the shape's
actual geometry including any padding or offsets.

[3]
Clamp the shape's x and y coordinates so that the shape's bounds stay completely within
the container bounds. We account for the shape's geometry offset and dimensions.

[4]
Register a beforeChange handler that runs whenever any shape is about to be modified. We only
apply the constraint to geo shapes (rectangles). This handler intercepts changes and returns
a modified version of the shape with position clamped to the container.

[5]
Create a rectangle shape positioned inside our container bounds. Users can drag this shape,
but it will be prevented from leaving the container area.

[6]
Draw a dashed rectangle on the canvas to visualize the container bounds. This uses SVGContainer
to render directly on the canvas in world coordinates.
*/
```

--------

# Permissions 2

Category: Events & effects

Keywords: constraints, bounds, side effects, permissions, clamping

A second example of how to use side effect APIs to constrain shape movement within a bounding box.

This example demonstrates how to use tldraw's side effect APIs to enforce permissions or
constraints on shapes. We create a rectangle that can be dragged around, but its movement
is constrained to stay within an invisible container using the `registerBeforeChangeHandler`
side effect. This pattern is useful for implementing permission systems, bounded regions,
or any scenario where you need to restrict where shapes can be positioned.

## App.tsx

```tsx
import { Box, Editor, SVGContainer, TLGeoShape, Tldraw, toRichText } from 'tldraw'
import 'tldraw/tldraw.css'

// [1]
const CONTAINER_BOUNDS = new Box(100, 100, 400, 300)

// [2]
function constrainShapeToBounds(editor: Editor, shape: TLGeoShape) {
	const shapeGeometry = editor.getShapeGeometry(shape)
	const shapeBounds = shapeGeometry.bounds

// Calculate the shape's world-space bounds
	const shapeWorldBounds = editor.getShapePageBounds(shape)

if (!shapeWorldBounds) return shape

// Check if the shape is completely within the container
	if (CONTAINER_BOUNDS.contains(shapeWorldBounds)) {
		return shape
	}

// [3]
	// Calculate maximum allowed dimensions based on container size
	const maxWidth = CONTAINER_BOUNDS.w - shapeBounds.x * 2
	const maxHeight = CONTAINER_BOUNDS.h - shapeBounds.y * 2

// Clamp the shape's size if it would exceed the container
	const clampedW = Math.min(shape.props.w, maxWidth)
	const clampedH = Math.min(shape.props.h, maxHeight)

// Recalculate bounds with the clamped size
	const clampedShapeBounds = Box.From({
		x: shape.x + shapeBounds.x,
		y: shape.y + shapeBounds.y,
		w: (clampedW / shape.props.w) * shapeBounds.w,
		h: (clampedH / shape.props.h) * shapeBounds.h,
	})

// Clamp the shape's position so it stays within bounds
	let clampedX = Math.max(
		CONTAINER_BOUNDS.x - shapeBounds.x,
		Math.min(shape.x, CONTAINER_BOUNDS.maxX - shapeBounds.x - clampedShapeBounds.w)
	)
	let clampedY = Math.max(
		CONTAINER_BOUNDS.y - shapeBounds.y,
		Math.min(shape.y, CONTAINER_BOUNDS.maxY - shapeBounds.y - clampedShapeBounds.h)
	)

if (shapeBounds.w >= CONTAINER_BOUNDS.w) {
		clampedX = CONTAINER_BOUNDS.x
	}

if (shapeBounds.h >= CONTAINER_BOUNDS.h) {
		clampedY = CONTAINER_BOUNDS.y
	}
	return {
		...shape,
		x: clampedX,
		y: clampedY,
		props: {
			...shape.props,
			w: clampedW,
			h: clampedH,
		},
	}
}

// [5]
					// Create the constrained rectangle
					editor.createShape({
						type: 'geo',
						x: 250,
						y: 200,
						props: {
							geo: 'rectangle',
							w: 150,
							h: 100,
							richText: toRichText('Try to drag me around'),
						},
					})

// Zoom to show the container area
					editor.zoomToBounds(new Box(0, 0, 600, 500))
				}}
				components={{
					// [6]
					OnTheCanvas: () => (
						<SVGContainer>
							<rect
								x={CONTAINER_BOUNDS.x}
								y={CONTAINER_BOUNDS.y}
								width={CONTAINER_BOUNDS.w}
								height={CONTAINER_BOUNDS.h}
								fill="none"
								stroke="rgba(0, 0, 0, 0.2)"
								strokeWidth={2}
								strokeDasharray="8 4"
							/>
						</SVGContainer>
					),
				}}
			/>
		</div>
	)
}

/*
[1]
Define the invisible container bounds that our shape will be constrained to. This is a box
with top-left at (100, 100) and dimensions of 400x300.

[3]
First, calculate the maximum allowed dimensions and clamp the shape's size if needed. Then
clamp the position to keep the shape within bounds. This ensures the shape can neither be
moved nor resized outside the container.

[5]
Create a rectangle shape with text positioned inside our container bounds. Users can drag and
resize this shape, but it will be prevented from leaving or exceeding the container area.

[6]
Draw a dashed rectangle on the canvas to visualize the container bounds. This uses SVGContainer
to render directly on the canvas in world coordinates.
*/
```

--------

# Derived view

Category: Events & effects

Keywords: basic, intro, simple, quick, start

Derive data from the editor's document in an efficient way.

You can use incremental derivations to get a specific view of data.

## App.tsx

```tsx
import { isUninitialized, RESET_VALUE } from '@tldraw/state'
import { useMemo, useRef } from 'react'
import { computed, Editor, isShape, Tldraw, TLShapeId, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'

export default function DerivedViewExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="derived-view">
				<ShowNumberOfDrawShapesOnPage />
			</Tldraw>
		</div>
	)
}

function ShowNumberOfDrawShapesOnPage() {
	const editor = useEditor()
	const rRenders = useRef(0)

// Create a computed value that tracks the number of draw shapes in the document, returning a set of ids
	const computed = useMemo(() => deriveNumberOfDrawShapesInDocument(editor), [editor])
	// Get the size of the computed value whenever the computed value changes
	const value = useValue('computed value', () => computed.get().size, [computed])

return (
		<div style={{ position: 'absolute', top: 50, left: 20, zIndex: 99999 }}>
			<p>{value} draw shapes in project</p>
			{/* Will go up by two in dev, NAB */}
			<p>{rRenders.current++} renders</p>
		</div>
	)
}

export const deriveNumberOfDrawShapesInDocument = (editor: Editor) => {
	const { store } = editor
	const shapesIndex = store.query.ids('shape')

// Create an index of all the shape ids of all the draw shapes
	function fromScratch() {
		return new Set([...shapesIndex.get()].filter((id) => editor.getShape(id)!.type === 'draw'))
	}

return computed<Set<TLShapeId>>('_shapeIdsInCurrentPage', (prevValue, lastComputedEpoch) => {
		// On first load, return the initial value
		if (isUninitialized(prevValue)) {
			return fromScratch()
		}

// Get the changes since the last computed value
		const diff = store.history.getDiffSince(lastComputedEpoch)

// Something caused the store to reset, compute a new value from scratch
		if (diff === RESET_VALUE) {
			return fromScratch()
		}

// This will be the new set that includes the changes, if we find any
		let nextValue: Set<TLShapeId> | undefined

for (const changes of diff) {
			// Check all of the added records for new draw shapes
			for (const record of Object.values(changes.added)) {
				if (isShape(record) && record.type === 'draw') {
					// If we haven't created the new set yet, do it now
					if (!nextValue) {
						nextValue = new Set(prevValue)
					}
					// mutate the new set
					nextValue.add(record.id)
				}
			}

for (const record of Object.values(changes.removed)) {
				// Check all of the removed records for deleted draw shapes
				if (isShape(record) && record.type === 'draw') {
					// If we haven't created the new set yet, do it now
					if (!nextValue) {
						nextValue = new Set(prevValue)
					}
					// mutate the new set
					nextValue.delete(record.id)
				}
			}
		}

// if something changed, return the new value
		if (nextValue) return nextValue

// if nothing changed, return the previous value
		return prevValue
	})
}
```

--------

# Shape meta (on change)

Category: Events & effects

Keywords: side, effects, register, change, initial

Add custom metadata to shapes when they're changed.

We can update a shape's metadata whenever it changes. A UI displays the current selected shape's metadata. Create a shape, select it, and move it around. The metadata will updated any time the shape changes.

## App.tsx

```tsx
import { TLShape, Tldraw, track, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

export default function OnChangeShapeMetaExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="tldraw_change_meta_example"
				onMount={(editor) => {
					// [1]
					editor.getInitialMetaForShape = (_shape) => {
						return {
							updatedBy: editor.user.getId(),
							updatedAt: Date.now(),
						}
					}
					// [2]
					editor.sideEffects.registerBeforeChangeHandler('shape', (_prev, next, source) => {
						if (source !== 'user') return next
						return {
							...next,
							meta: {
								updatedBy: editor.user.getId(),
								updatedAt: Date.now(),
							},
						}
					})
				}}
			>
				<MetaUiHelper />
			</Tldraw>
		</div>
	)
}

// [3]
type ShapeWithMyMeta = TLShape & { meta: { updatedBy: string; updatedAt: string } }

// [4]
export const MetaUiHelper = track(function MetaUiHelper() {
	const editor = useEditor()
	const onlySelectedShape = editor.getOnlySelectedShape() as ShapeWithMyMeta | null

return (
		<pre style={{ position: 'absolute', zIndex: 300, top: 64, left: 12, margin: 0 }}>
			{onlySelectedShape
				? JSON.stringify(onlySelectedShape.meta, null, '\t')
				: 'Select one shape to see its meta data.'}
		</pre>
	)
})

/* 
This example shows how to add meta data to shapes when they are created and
updated. In this case we are adding `updatedBy` and `updatedAt` fields.

[1]
getInitialMetaForShape is a method you can replace at runtime. Here we use 
a callback on the onMount prop to replace the default implementation with 
our own.

[2]
Here we're using the side effects API to add meta data to shapes when they are
updated. You can use the side effects API to do something on create, update or
delete, and you can target many things including: shapes, pages, the camera, 
the pointer etc.

[3]
All tldraw shapes have a meta property with a type of unknown. To type your 
meta data you can use a union like this.

[4]
A minimal ui component that displays the meta data of the selected shape. We 
use track to make sure that the component is re-rendered when the signals it's 
tracking change. Check out the signals example for more info: 
https://tldraw.dev/examples/signals
*/
```

--------

# Shape meta (on create)

Category: Events & effects

Keywords: side, effects, initial, meta, register

Add custom metadata to shapes when they're created.

We can update a shape's metadata whenever it is created. A UI displays the current selected shape's metadata. Create a shape and select it. The metadata will display its created at / created by data.

## App.tsx

```tsx
import { TLShape, Tldraw, track, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

export default function OnCreateShapeMetaExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="example"
				onMount={(editor) => {
					//[1]
					editor.getInitialMetaForShape = (_shape) => {
						return {
							createdBy: editor.user.getId(),
							createdAt: Date.now(),
						}
					}
				}}
			>
				<MetaUiHelper />
			</Tldraw>
		</div>
	)
}

// [2]
type ShapeWithMyMeta = TLShape & { meta: { updatedBy: string; updatedAt: string } }

// [3]
export const MetaUiHelper = track(function MetaUiHelper() {
	const editor = useEditor()
	const onlySelectedShape = editor.getOnlySelectedShape() as ShapeWithMyMeta | null

/* 
This example demonstrates how to add your own data to shapes using the meta property as they're
created. Check out the docs for a more detailed explanation of the meta property: 
https://tldraw.dev/docs/shapes#Meta-information

[1]
getInitialMetaForShape is a method you can replace at runtime. Here we use a callback on the onMount
prop to replace the default implementation with our own.

[2]
All tldraw shapes have a meta property with a type of unknown. To type your meta data you can use 
a union like this.

[3]
A minimal ui component that displays the meta data of the selected shape. We use track to make sure
that the component is re-rendered when the signals it's tracking change. Check out the signals example
for more info: https://tldraw.dev/examples/signals

*/
```

--------

# Custom shape wrapper

Category: Shapes & tools

Keywords:

Customize the wrapper used for each shape in the DOM.

Use a custom shape wrapper to apply a special class names to shapes.

## App.tsx

```tsx
import { forwardRef } from 'react'
import {
	atom,
	DefaultShapeWrapper,
	Editor,
	TLComponents,
	Tldraw,
	TLShapeId,
	TLShapeWrapperProps,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

// [1]
const specialShapeId = atom<TLShapeId | null>('special shape id', null)

// [2]
const CustomShapeWrapper = forwardRef(function CustomShapeWrapper(
	{ children, shape, isBackground }: TLShapeWrapperProps,
	ref: React.Ref<HTMLDivElement>
) {
	// [a]
	const isSpecial = useValue('is special', () => specialShapeId.get() === shape.id, [shape.id])

// [b]
	return (
		<DefaultShapeWrapper
			ref={ref}
			shape={shape}
			isBackground={isBackground}
			className={isSpecial ? 'custom-special-shape' : undefined}
		>
			{children}
		</DefaultShapeWrapper>
	)
})

// [3]
const components: TLComponents = {
	ShapeWrapper: CustomShapeWrapper,
}

export default function BasicExample() {
	return (
		<div className="tldraw__editor">
			<style>{`
				.custom-special-shape {
					filter: drop-shadow(0 0 3px rgba(255, 0, 0));
				}
			`}</style>
			<Tldraw
				components={components}
				onMount={(editor) => {
					createSomeRandomShapes(editor)

const timer = setInterval(() => {
						const allShapes = editor.getCurrentPageShapesSorted()
						const randomShape = allShapes[Math.floor(Math.random() * allShapes.length)]
						specialShapeId.set(randomShape.id)
					}, 1000)

return () => {
						clearInterval(timer)
					}
				}}
			/>
		</div>
	)
}

function createSomeRandomShapes(editor: Editor) {
	const bounds = editor.getViewportPageBounds()
	for (let i = 0; i < 10; i++) {
		editor.createShape({
			type: 'geo',
			x: bounds.x + Math.random() * bounds.width,
			y: bounds.y + Math.random() * bounds.height,
		})
	}
}

/*
Introduction:

You can customize how shapes are wrapped in tldraw by creating a custom shape wrapper component and
passing it to the Tldraw component. In this example, we'll create a custom shape wrapper that adds a
red drop shadow to a randomly selected shape every second.

[1] We create an atom to store the ID of the currently "special" shape. Atoms are part of tldraw's
reactive state system and allow us to create reactive values that can be observed and updated. This
atom will hold the ID of the shape that should have the special styling applied to it.

[2] This is our custom shape wrapper component. Shape wrappers are React components that wrap around
every shape in the editor, allowing you to add custom styling, behavior, or data attributes to
shapes. We use forwardRef to properly forward the ref that tldraw passes to us.

[a]
    We use the useValue hook to create a reactive value that checks if the current shape is the "special" shape.
    This will automatically update whenever the specialShapeId atom changes. We also check if the shape is filled
    by looking at its props.

[b]
    We re-use the DefaultShapeWrapper component, but add a custom class to the shape when it's the "special" shape.

[3] We create a components object that tells tldraw to use our custom shape wrapper. The
TLComponents type allows us to override various parts of the tldraw UI, including the ShapeWrapper
component.

[4] In the main component, we add CSS that applies a red drop shadow to any element with the
'custom-special-shape' class. We also set up a timer that randomly selects a shape every second and
makes it the "special" shape by updating the specialShapeId atom.

The shape wrapper approach is useful when you want to:
- Add custom styling to all shapes or specific shapes
- Add data attributes for CSS targeting
- Implement custom behavior that affects how shapes are rendered
- Create visual effects that apply to the shape container rather than the shape content

This is different from custom shapes (like in the CustomShapeExample) because it doesn't change what
the shape is, only how it's wrapped and styled in the editor.
*/
```

--------

# Globs

Category: Shapes & tools

Keywords:

A globs based vector editor, based on the https://jcgt.org/published/0004/03/01/paper-lowres.pdf paper.

Some useful shortcuts:

- Place a node by pressing 'n'
- Create a glob by selecting a node and pressing 'c' and either place a new node or connect to an existing one
- Hold 'cmd' whilst dragging "d" handles to drag that handle and its opposite
- Hold 'cmd' whilst dragging tension handles to drag its opposite handle
- Hold 'cmd + shift' to drag all four tension handles on a glob together

## App.tsx

```tsx
import { useState } from 'react'
import {
	DefaultToolbar,
	DefaultToolbarContent,
	StateNode,
	TLComponents,
	Tldraw,
	TldrawUiButtonIcon,
	TldrawUiMenuItem,
	TldrawUiPopover,
	TldrawUiPopoverContent,
	TldrawUiPopoverTrigger,
	TldrawUiToolbar,
	TldrawUiToolbarButton,
	TLKeyboardEventInfo,
	tlmenus,
	TLPointerEventInfo,
	TLShape,
	TLShapeId,
	TLUiAssetUrlOverrides,
	TLUiOverrides,
	track,
	useEditor,
	useTools,
	useValue,
} from 'tldraw'
import { CustomHandles } from './CustomHandles'
import { GlobBinding, GlobBindingUtil } from './GlobBindingUtil'
import { GlobShape, GlobShapeUtil } from './GlobShapeUtil'
import { GlobTool } from './GlobTool/GlobTool'
import { NodeShape, NodeShapeUtil } from './NodeShapeUtil'

const customAssetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'glob-icon': '/glob-icon.svg',
		'node-icon': '/node-icon.svg',
		'connect-node-icon': '/connect-node.svg',
	},
}

const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		tools['glob.node'] = {
			id: 'glob.node',
			icon: 'node-icon',
			label: 'Node',
			kbd: 'n',
			meta: { variant: 'node' },
			onSelect: () => {
				editor.setCurrentTool('glob.node')
			},
		}

tools['glob.connect'] = {
			id: 'glob.connect',
			icon: 'connect-node-icon',
			label: 'Connect Nodes',
			kbd: 'c',
			meta: { variant: 'connect' },
			onSelect: () => {
				// Only allow connecting if nodes are selected
				const selectedShapes = editor.getSelectedShapes()
				const hasNodesSelected =
					selectedShapes.length > 0 &&
					selectedShapes.every((shape) => editor.isShapeOfType<NodeShape>(shape, 'node'))
				if (hasNodesSelected) {
					editor.setCurrentTool('glob.connect')
				}
			},
		}

return tools
	},
}

const GlobToolWithPopover = track(() => {
	const tools = useTools()

const editor = useEditor()
	const [isOpen, setIsOpen] = useState(false)

const currentGlobTool = useValue(
		'current glob tool',
		() => {
			const tool = editor.getPath()
			if (tool === 'glob.connect') return 'glob.connect'
			return 'glob.node'
		},
		[editor]
	)

// Check if any nodes are selected
	const hasNodesSelected = useValue(
		'has nodes selected',
		() => {
			const selectedShapes = editor.getSelectedShapes()
			return (
				selectedShapes.length > 0 &&
				selectedShapes.every((shape) => editor.isShapeOfType<NodeShape>(shape, 'node'))
			)
		},
		[editor]
	)

const isSelected = editor.getPath() === currentGlobTool
	const popoverId = 'glob-tool-popover'

const handleToolSelect = (id: string) => {
		if (id === 'glob.connect' && !hasNodesSelected) return
		editor.setCurrentTool(id)
		tlmenus.deleteOpenMenu(popoverId, editor.contextId)
		setIsOpen(false)
	}

return (
		<>
			<TldrawUiPopover id={popoverId} open={isOpen} onOpenChange={setIsOpen}>
				<TldrawUiPopoverTrigger>
					<TldrawUiToolbarButton title="Glob" type="tool">
						<TldrawUiButtonIcon icon="glob-icon" />
					</TldrawUiToolbarButton>
				</TldrawUiPopoverTrigger>
				<TldrawUiPopoverContent side="top" align="center">
					<TldrawUiToolbar label="Glob">
						<TldrawUiToolbarButton
							title="Add Node"
							type="tool"
							onClick={() => handleToolSelect('glob.node')}
						>
							<TldrawUiButtonIcon icon="node-icon" />
						</TldrawUiToolbarButton>
						<TldrawUiToolbarButton
							title="Connect Nodes"
							type="tool"
							onClick={() => handleToolSelect('glob.connect')}
							disabled={!hasNodesSelected}
						>
							<TldrawUiButtonIcon icon="connect-node-icon" />
						</TldrawUiToolbarButton>
					</TldrawUiToolbar>
				</TldrawUiPopoverContent>
				<TldrawUiMenuItem {...tools[currentGlobTool]} isSelected={isSelected} />
			</TldrawUiPopover>
		</>
	)
})

const components: TLComponents = {
	Toolbar: (props) => {
		return (
			<DefaultToolbar {...props}>
				<GlobToolWithPopover />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	Handles: CustomHandles,
}

const shapes = [NodeShapeUtil, GlobShapeUtil]
const tools = [GlobTool]
const bindings = [GlobBindingUtil]

export default function GlobsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				options={{
					spacebarPanning: false,
				}}
				onMount={(editor) => {
					editor.updateInstanceState({ isDebugMode: true })

// Override dragging_handle state to prevent space from interrupting handle dragging
					const draggingHandleState = editor.getStateDescendant<StateNode>('select.dragging_handle')

if (draggingHandleState) {
						const originalOnKeyDown = draggingHandleState.onKeyDown?.bind(draggingHandleState)

draggingHandleState.onKeyDown = (info: TLKeyboardEventInfo) => {
							originalOnKeyDown?.(info)
						}
					}

// Override pointing_handle state to allow handle dragging with modifier keys, otherwise
					// it starts brushing instead
					const pointingHandleState = editor.getStateDescendant<StateNode>('select.pointing_handle')

if (!pointingHandleState) {
						throw new Error('SelectTool pointing_handle state not found')
					}

// Store original handlers with proper binding
					const originalOnPointerMove = pointingHandleState.onPointerMove?.bind(pointingHandleState)

// Return to idle state after dragging a handle
					pointingHandleState.onPointerMove = (info: TLPointerEventInfo) => {
						if (!info.shape) return

if (editor.isShapeOfType<GlobShape>(info.shape, 'glob')) {
							editor.updateInstanceState({ isToolLocked: true })
							editor.setCurrentTool('select.dragging_handle', {
								...info,
							})
							return
						}

originalOnPointerMove?.(info)
					}

// if we have a just a glob selected, expand the selection to include the nodes it's connected to
					const originalGetContent = editor.getContentFromCurrentPage.bind(editor)
					editor.getContentFromCurrentPage = (shapes) => {
						// Extract shape IDs
						const ids =
							typeof shapes[0] === 'string'
								? (shapes as TLShapeId[])
								: (shapes as TLShape[]).map((s) => s.id)

// Expand selection to include bound nodes for any globs
						const expandedIds = new Set(ids)

for (const id of ids) {
							const shape = editor.getShape(id)
							if (shape && editor.isShapeOfType<GlobShape>(shape, 'glob')) {
								const bindings = editor.getBindingsFromShape<GlobBinding>(id, 'glob')
								for (const binding of bindings) {
									expandedIds.add(binding.toId)
								}
							}
						}

// Call original with expanded selection
						return originalGetContent(Array.from(expandedIds))
					}
				}}
				shapeUtils={shapes}
				tools={tools}
				bindingUtils={bindings}
				overrides={uiOverrides}
				assetUrls={customAssetUrls}
				components={components}
			/>
		</div>
	)
}
```

## CustomHandles.tsx

```tsx
import {
	DefaultHandle,
	Mat,
	TLHandle,
	TLShapeId,
	toDomPrecision,
	useEditor,
	useValue,
} from 'tldraw'
import { ControlLine, getGlobInfo, getNeighborGlobs, GlobShape } from './GlobShapeUtil'

export function CustomHandles({ children }: { children: React.ReactNode }) {
	const editor = useEditor()

const shouldDisplayHandles = useValue(
		'shouldDisplayHandles',
		() => {
			if (
				editor.isInAny(
					'select.idle',
					'select.pointing_handle',
					'select.pointing_shape',
					'select.dragging_handle'
				)
			) {
				return true
			}
			if (editor.isInAny('select.editing_shape')) {
				const onlySelectedShape = editor.getOnlySelectedShape()
				return onlySelectedShape && editor.isShapeOfType(onlySelectedShape, 'note')
			}
			return false
		},
		[editor]
	)

const shouldDisplayGlobHandles = useValue(
		'shouldDisplayGlobHandles',
		() => {
			const selectedGlobs = editor
				.getSelectedShapeIds()
				.filter((shape) => editor.isShapeOfType<GlobShape>(shape, 'glob'))
				.map((shape) => editor.getShape<GlobShape>(shape))
			return selectedGlobs && selectedGlobs.length > 0
		},
		[editor]
	)

if (!shouldDisplayHandles) return null

const selectedGlobs = editor
		.getSelectedShapeIds()
		.filter((shape) => editor.isShapeOfType<GlobShape>(shape, 'glob'))
		.map((shape) => editor.getShape<GlobShape>(shape))

const neighborGlobs: Set<GlobShape> = new Set()
	for (const selectedGlob of selectedGlobs) {
		if (!selectedGlob) continue
		getNeighborGlobs(editor, selectedGlob).forEach((neighbor) => neighborGlobs.add(neighbor))
	}

return (
		<svg className="tl-user-handles tl-overlays__item" aria-hidden="true">
			{children}
			{shouldDisplayGlobHandles && (
				<>
					{Array.from(neighborGlobs).map((glob) => {
						if (!glob) return null
						return <GlobHandlesWithControlLines key={glob.id} glob={glob} />
					})}
				</>
			)}
		</svg>
	)
}

function GlobHandlesWithControlLines({ glob }: { glob: GlobShape }) {
	const editor = useEditor()
	const handles = editor.getShapeHandles(glob)
	const transform = editor.getShapePageTransform(glob.id)
	const zoomLevel = editor.getZoomLevel()
	const isCoarse = editor.getInstanceState().isCoarsePointer

const globPoints = getGlobInfo(editor, glob)

if (!handles || !transform || !globPoints) return null

const dxA = toDomPrecision(glob.props.edges.edgeA.d.x)
	const dyA = toDomPrecision(glob.props.edges.edgeA.d.y)
	const dxB = toDomPrecision(glob.props.edges.edgeB.d.x)
	const dyB = toDomPrecision(glob.props.edges.edgeB.d.y)

const txAA = toDomPrecision(globPoints.edgeA.tangentA.x)
	const tyAA = toDomPrecision(globPoints.edgeA.tangentA.y)
	const txAB = toDomPrecision(globPoints.edgeA.tangentB.x)
	const tyAB = toDomPrecision(globPoints.edgeA.tangentB.y)

const txBA = toDomPrecision(globPoints.edgeB.tangentA.x)
	const tyBA = toDomPrecision(globPoints.edgeB.tangentA.y)
	const txBB = toDomPrecision(globPoints.edgeB.tangentB.x)
	const tyBB = toDomPrecision(globPoints.edgeB.tangentB.y)

return (
		<g transform={Mat.toCssString(transform)}>
			<ControlLine x1={dxA} y1={dyA} x2={txAA} y2={tyAA} />
			<ControlLine x1={dxA} y1={dyA} x2={txAB} y2={tyAB} />
			<ControlLine x1={dxB} y1={dyB} x2={txBA} y2={tyBA} />
			<ControlLine x1={dxB} y1={dyB} x2={txBB} y2={tyBB} />

{handles.map((handle) => (
				<HandleWrapper
					key={handle.id}
					shapeId={glob.id}
					handle={handle}
					zoom={zoomLevel}
					isCoarse={isCoarse}
				/>
			))}
		</g>
	)
}

function HandleWrapper({
	shapeId,
	handle,
	zoom,
	isCoarse,
}: {
	shapeId: TLShapeId
	handle: TLHandle
	zoom: number
	isCoarse: boolean
}) {
	return (
		<g transform={`translate(${handle.x}, ${handle.y})`}>
			<DefaultHandle shapeId={shapeId} handle={handle} zoom={zoom} isCoarse={isCoarse} />
		</g>
	)
}
```

## GlobBindingUtil.tsx

```tsx
import {
	BindingOnShapeChangeOptions,
	BindingOnShapeDeleteOptions,
	BindingUtil,
	Editor,
	TLBinding,
	TLParentId,
	TLShapeId,
	Vec,
} from 'tldraw'
import { GlobShape } from './GlobShapeUtil'
import { NodeShape } from './NodeShapeUtil'
import { getGlobBindings, getGlobTangentUpdate } from './shared'

const GLOB_BINDING_TYPE = 'glob'

declare module 'tldraw' {
	export interface TLGlobalBindingPropsMap {
		[GLOB_BINDING_TYPE]: GlobBindingProps
	}
}

export type GlobBinding = TLBinding<'glob'>

interface GlobBindingProps {
	terminal: 'start' | 'end'
}
export class GlobBindingUtil extends BindingUtil<GlobBinding> {
	static override type = 'glob' as const

override getDefaultProps(): Partial<GlobBindingProps> {
		return {
			terminal: 'start',
		}
	}

override onAfterChangeFromShape({
		binding,
		shapeBefore,
		shapeAfter,
	}: BindingOnShapeChangeOptions<GlobBinding>): void {
		const glob = this.editor.getShape<GlobShape>(binding.fromId)
		const node = this.editor.getShape<NodeShape>(binding.toId)

if (!glob || !node) return
		if (glob.props.isGhosting) return

const selectedIds = this.editor.getSelectedShapeIds()
		if (selectedIds.includes(node.id)) return
		if (!selectedIds.includes(glob.id)) return

if (
			glob.parentId === node.parentId &&
			glob.parentId !== this.editor.getCurrentPageId() &&
			!selectedIds.includes(glob.id)
		) {
			return
		}

// if a glob has been reparented (moved into/out of a frame), we need to move the nodes along with it
		if (shapeBefore.parentId !== shapeAfter.parentId) {
			const bindings = getGlobBindings(this.editor, glob)
			const boundNodes: NodeShape[] = []
			if (bindings.start) {
				const node = this.editor.getShape<NodeShape>(bindings.start.toId)
				if (node) boundNodes.push(node)
			}
			if (bindings.end) {
				const node = this.editor.getShape<NodeShape>(bindings.end.toId)
				if (node) boundNodes.push(node)
			}

// Move each node to maintain its page position while reparenting to match the glob
			for (const node of boundNodes) {
				const nodePagePos = this.editor.getShapePageTransform(node).point()
				const newParentTransform = this.editor.getShapeParentTransform(shapeAfter)
				const newLocalPos = newParentTransform.clone().invert().applyToPoint(nodePagePos)

this.editor.reparentShapes([node.id], shapeAfter.parentId)
				this.editor.updateShape<NodeShape>({
					id: node.id,
					type: 'node',
					x: newLocalPos.x,
					y: newLocalPos.y,
				})
			}

// reparent and update
			reparentGlob(this.editor, glob.id)
			updateGlobGeometry(this.editor, glob.id)
			return
		}

const beforePageTransform = this.editor.getShapeParentTransform(shapeBefore)
		const afterPageTransform = this.editor.getShapeParentTransform(shapeAfter)

const beforePagePos = beforePageTransform.applyToPoint(shapeBefore)
		const afterPagePos = afterPageTransform.applyToPoint(shapeAfter)

const deltaInPageSpace = Vec.Sub(afterPagePos, beforePagePos)

const nodePagePos = this.editor.getShapePageTransform(node).point()

const newNodePagePos = Vec.Add(nodePagePos, deltaInPageSpace)

const nodeParentTransform = this.editor.getShapeParentTransform(node)
		const newNodeLocalPos = nodeParentTransform.clone().invert().applyToPoint(newNodePagePos)

this.editor.run(
			() => {
				this.editor.updateShape<NodeShape>({
					id: node.id,
					type: 'node',
					x: newNodeLocalPos.x,
					y: newNodeLocalPos.y,
				})
			},
			{ history: 'ignore' }
		)
	}

override onAfterChangeToShape({
		binding,
		shapeBefore,
		shapeAfter,
		reason,
	}: BindingOnShapeChangeOptions<GlobBinding>): void {
		const glob = this.editor.getShape<GlobShape>(binding.fromId)
		if (!glob) return
		if (glob.props.isGhosting) return

const selectedIds = this.editor.getSelectedShapeIds()
		const node = this.editor.getShape<NodeShape>(binding.toId)
		if (!node) return

if (!selectedIds.includes(node.id) && selectedIds.includes(glob.id)) {
			return
		}

// If both glob and node share a frame parent and neither is selected,
		// they're moving together (e.g., frame is being moved), don't update
		if (
			glob.parentId === node.parentId &&
			glob.parentId !== this.editor.getCurrentPageId() &&
			!selectedIds.includes(glob.id) &&
			!selectedIds.includes(node.id) &&
			reason !== 'ancestry'
		) {
			return
		}

if (
			reason !== 'ancestry' &&
			shapeBefore.parentId === shapeAfter.parentId &&
			shapeBefore.index === shapeAfter.index
		) {
			return
		}

reparentGlob(this.editor, binding.fromId)
		updateGlobGeometry(this.editor, binding.fromId)
	}

override onBeforeDeleteToShape({ binding }: BindingOnShapeDeleteOptions<GlobBinding>): void {
		this.editor.deleteShape(binding.fromId)
	}
}

function reparentGlob(editor: Editor, globId: TLShapeId) {
	const glob = editor.getShape<GlobShape>(globId)
	if (!glob) return
	const bindings = getGlobBindings(editor, glob)
	const { start, end } = bindings
	const startShape = start ? editor.getShape(start.toId) : undefined
	const endShape = end ? editor.getShape(end.toId) : undefined

const parentPageId = editor.getAncestorPageId(glob)
	if (!parentPageId) return

let nextParentId: TLParentId
	if (startShape && endShape) {
		nextParentId = editor.findCommonAncestor([startShape, endShape]) ?? parentPageId
	} else if (startShape || endShape) {
		const bindingParentId = (startShape || endShape)?.parentId
		if (bindingParentId && bindingParentId === glob.parentId) {
			nextParentId = glob.parentId
		} else {
			nextParentId = parentPageId
		}
	} else {
		return
	}

if (nextParentId && nextParentId !== glob.parentId) {
		editor.reparentShapes([globId], nextParentId)
	}
}

function updateGlobGeometry(editor: Editor, globId: TLShapeId) {
	const glob = editor.getShape<GlobShape>(globId)
	if (!glob) return
	if (glob.props.isGhosting) return

const bindings = getGlobBindings(editor, glob)
	const { start, end } = bindings
	const startShape = start ? editor.getShape<NodeShape>(start.toId) : undefined
	const endShape = end ? editor.getShape<NodeShape>(end.toId) : undefined

if (!startShape || !endShape) return

const startNodePagePos = editor.getShapePageTransform(startShape.id).point()
	const endNodePagePos = editor.getShapePageTransform(endShape.id).point()

const update = getGlobTangentUpdate(
		editor,
		globId,
		startNodePagePos,
		startShape.props.radius,
		endNodePagePos,
		endShape.props.radius
	)

editor.updateShape<GlobShape>(update)
}
```

## GlobShapeUtil.tsx

```tsx
import { round } from 'lodash'
import {
	createComputedCache,
	Editor,
	getIndicesAbove,
	HandleSnapGeometry,
	Mat,
	PathBuilder,
	PointsSnapIndicator,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	SVGContainer,
	T,
	TLHandle,
	TLHandleDragInfo,
	TLResizeInfo,
	TLShape,
	TLShapePartial,
	toDomPrecision,
	track,
	uniqueId,
	useEditor,
	useValue,
	Vec,
	VecModel,
	vecModelValidator,
	ZERO_INDEX_KEY,
} from 'tldraw'
import { GlobBinding } from './GlobBindingUtil'
import { getStartAndEndNodes } from './shared'
import {
	getArcFlag,
	getClosestPointOnCircle,
	getGlobEndPoint,
	getOuterTangentPoints,
	projectTensionPoint,
} from './utils'

export interface NodeGeometry {
	position: VecModel
	radius: number
}

export interface EdgeGeometry {
	tangentA: VecModel
	tangentB: VecModel
	tensionA: VecModel
	tensionB: VecModel
}
export interface GlobGeometry {
	startNode: NodeGeometry
	endNode: NodeGeometry
	edgeA: EdgeGeometry
	edgeB: EdgeGeometry
}
export interface EdgeProps {
	d: VecModel
	tensionRatioA: number
	tensionRatioB: number
}

export type EdgeCurveType = 'edgeA' | 'edgeB'
export interface GlobProps {
	edges: {
		edgeA: EdgeProps
		edgeB: EdgeProps
	}
	opacity: number
	isGhosting: boolean
}

const GLOB_TYPE = 'glob'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[GLOB_TYPE]: GlobProps
	}
}

export type GlobShape = TLShape<'glob'>

interface SnapData {
	nudge: VecModel
	indicators: PointsSnapIndicator[]
}

const edgeCurveValidator = T.object({
	d: vecModelValidator,
	tensionRatioA: T.number,
	tensionRatioB: T.number,
})

const globInfoCache = createComputedCache<Editor, GlobGeometry | null, GlobShape>(
	'glob info',
	(editor: Editor, shape: GlobShape): GlobGeometry | null => {
		const nodes = getStartAndEndNodes(editor, shape.id)
		if (!nodes) return null

const { startNodeShape, endNodeShape } = nodes

const startNodePagePos = editor.getShapePageTransform(startNodeShape.id).point()
		const endNodePagePos = editor.getShapePageTransform(endNodeShape.id).point()
		const globPagePos = editor.getShapePageTransform(shape.id).point()

const localStartNode = Vec.Sub(startNodePagePos, globPagePos)
		const localEndNode = Vec.Sub(endNodePagePos, globPagePos)

let tangentA_A = getGlobEndPoint(
			localStartNode,
			shape.props.edges.edgeA.d,
			startNodeShape.props.radius,
			0
		)
		let tangentB_A = getGlobEndPoint(
			localEndNode,
			shape.props.edges.edgeA.d,
			endNodeShape.props.radius,
			1
		)

let tangentA_B = getGlobEndPoint(
			localStartNode,
			shape.props.edges.edgeB.d,
			startNodeShape.props.radius,
			1
		)

let tangentB_B = getGlobEndPoint(
			localEndNode,
			shape.props.edges.edgeB.d,
			endNodeShape.props.radius,
			0
		)

// if we drag a node over an existing d handle, the solution does not exist so collapse the points
		//
		if (!tangentA_A && tangentA_B) {
			tangentA_A = tangentA_B
		} else if (!tangentA_B && tangentA_A) {
			tangentA_B = tangentA_A
		}

if (!tangentB_A && tangentB_B) {
			tangentB_A = tangentB_B
		} else if (!tangentB_B && tangentB_A) {
			tangentB_B = tangentB_A
		}

if (!tangentA_A || !tangentB_A || !tangentA_B || !tangentB_B) return null

return {
			startNode: {
				position: localStartNode,
				radius: startNodeShape.props.radius,
			},
			endNode: {
				position: localEndNode,
				radius: endNodeShape.props.radius,
			},
			edgeA: {
				tangentA: tangentA_A,
				tangentB: tangentB_A,
				tensionA: Vec.Lrp(
					tangentA_A,
					shape.props.edges.edgeA.d,
					shape.props.edges.edgeA.tensionRatioA
				),
				tensionB: Vec.Lrp(
					shape.props.edges.edgeA.d,
					tangentB_A,
					shape.props.edges.edgeA.tensionRatioB
				),
			},
			edgeB: {
				tangentA: tangentA_B,
				tangentB: tangentB_B,
				tensionA: Vec.Lrp(
					tangentA_B,
					shape.props.edges.edgeB.d,
					shape.props.edges.edgeB.tensionRatioA
				),
				tensionB: Vec.Lrp(
					shape.props.edges.edgeB.d,
					tangentB_B,
					shape.props.edges.edgeB.tensionRatioB
				),
			},
		}
	}
)

export function getGlobInfo(editor: Editor, shape: GlobShape): GlobGeometry | null {
	return globInfoCache.get(editor, shape.id) ?? null
}

export class GlobShapeUtil extends ShapeUtil<GlobShape> {
	static override type = 'glob' as const
	static override props: RecordProps<GlobShape> = {
		edges: T.object({
			edgeA: edgeCurveValidator,
			edgeB: edgeCurveValidator,
		}),
		opacity: T.number,
		isGhosting: T.boolean,
	}

override getDefaultProps(): GlobShape['props'] {
		return {
			edges: {
				edgeA: {
					d: { x: 0, y: 0 },
					tensionRatioA: 0.5,
					tensionRatioB: 0.5,
				},
				edgeB: {
					d: { x: 0, y: 0 },
					tensionRatioA: 0.5,
					tensionRatioB: 0.5,
				},
			},
			opacity: 1,
			isGhosting: false,
		}
	}

override hideSelectionBoundsBg(_shape: GlobShape): boolean {
		return true
	}

override hideResizeHandles(_shape: GlobShape): boolean {
		return true
	}

override hideRotateHandle(_shape: GlobShape): boolean {
		return true
	}

override hideSelectionBoundsFg(_shape: GlobShape): boolean {
		return true
	}

override onResize(_shape: GlobShape, info: TLResizeInfo<GlobShape>) {
		const { scaleX, scaleY, initialShape } = info

const scaledEdgeA_d = {
			x: initialShape.props.edges.edgeA.d.x * scaleX,
			y: initialShape.props.edges.edgeA.d.y * scaleY,
		}
		const scaledEdgeB_d = {
			x: initialShape.props.edges.edgeB.d.x * scaleX,
			y: initialShape.props.edges.edgeB.d.y * scaleY,
		}

const didFlipX = scaleX < 0
		const didFlipY = scaleY < 0

const shouldSwap = didFlipX !== didFlipY

const finalEdgeA = shouldSwap
			? {
					...initialShape.props.edges.edgeB,
					d: scaledEdgeB_d,
				}
			: {
					...initialShape.props.edges.edgeA,
					d: scaledEdgeA_d,
				}

const finalEdgeB = shouldSwap
			? {
					...initialShape.props.edges.edgeA,
					d: scaledEdgeA_d,
				}
			: {
					...initialShape.props.edges.edgeB,
					d: scaledEdgeB_d,
				}

return {
			props: {
				edges: {
					edgeA: finalEdgeA,
					edgeB: finalEdgeB,
				},
			},
		}
	}

override onRotate(initial: GlobShape, current: GlobShape): TLShapePartial<GlobShape> {
		const delta = current.rotation - initial.rotation

const rotatedDA = Vec.Rot(initial.props.edges.edgeA.d, delta).toJson()
		const rotatedDB = Vec.Rot(initial.props.edges.edgeB.d, delta).toJson()

// rotating nodes will handle rotating the glob, but we still need to update the d handles
		return {
			id: current.id,
			type: current.type,
			rotation: 0,
			props: {
				edges: {
					edgeA: {
						...initial.props.edges.edgeA,
						d: rotatedDA,
					},
					edgeB: {
						...initial.props.edges.edgeB,
						d: rotatedDB,
					},
				},
			},
		}
	}

override getGeometry(shape: GlobShape) {
		const globPoints = getGlobInfo(this.editor, shape)
		if (!globPoints) return new Rectangle2d({ width: 1, height: 1, isFilled: false })

const pathBuilder = buildGlobPath(globPoints, true)
		if (!pathBuilder) return new Rectangle2d({ width: 1, height: 1, isFilled: false })

return pathBuilder.toGeometry()
	}

override getHandles(shape: GlobShape) {
		const globPoints = getGlobInfo(this.editor, shape)
		if (!globPoints) return []

const NUM_D_POINTS = 2
		const NUM_TENSION_POINTS = 4

const indices = getIndicesAbove(ZERO_INDEX_KEY, NUM_D_POINTS + NUM_TENSION_POINTS)
		let idx = 0

const handles: TLHandle[] = []
		handles.push({
			id: 'edgeA.d',
			type: 'vertex',
			x: shape.props.edges.edgeA.d.x,
			y: shape.props.edges.edgeA.d.y,
			index: indices[idx++],
			snapType: 'point',
		})
		handles.push({
			id: 'edgeB.d',
			type: 'vertex',
			x: shape.props.edges.edgeB.d.x,
			y: shape.props.edges.edgeB.d.y,
			index: indices[idx++],
			snapType: 'point',
		})

const tensions = [
			'tensionA',
			'tensionB',
		] as const satisfies readonly (keyof GlobGeometry['edgeA'])[]

for (const edge of ['edgeA', 'edgeB'] as const satisfies readonly (keyof GlobGeometry)[]) {
			for (const tension of tensions) {
				handles.push({
					id: `${edge}.${tension}`,
					type: 'vertex',
					x: globPoints[edge][tension].x,
					y: globPoints[edge][tension].y,
					index: indices[idx++],
					snapType: 'point',
					snapReferenceHandleId: `${edge}.${tension}`, // this is a hack to make these handles not have angle snapping, when we shift drag which moves all tension handles at the same time
				})
			}
		}

return handles
	}

override getHandleSnapGeometry(shape: GlobShape): HandleSnapGeometry {
		const editor = this.editor
		const globPoints = getGlobInfo(editor, shape)
		if (!globPoints) return {}

return {
			getSelfSnapPoints(handle) {
				const { edgeType, point } = getHandleData(handle.id)
				const d = shape.props.edges[edgeType].d

switch (point) {
					case 'tensionA': {
						const mid = Vec.Lrp(globPoints[edgeType].tangentA, d, 0.5)
						return [mid]
					}
					case 'tensionB': {
						const mid = Vec.Lrp(globPoints[edgeType].tangentB, d, 0.5)
						return [mid]
					}
				}
				return []
			},
		}
	}

override onHandleDrag(shape: GlobShape, info: TLHandleDragInfo<GlobShape>) {
		const { handle, initial } = info
		if (!initial) return shape

const globPoints = getGlobInfo(this.editor, shape)
		if (!globPoints) return shape

const { edgeType, point } = getHandleData(handle.id)
		const edge = shape.props.edges[edgeType]

const oppositeEdgeType = edgeType === 'edgeA' ? 'edgeB' : 'edgeA'

const initialEdge = initial.props.edges[edgeType]
		const initialOppositeEdge = initial.props.edges[oppositeEdgeType]

switch (point) {
			case 'd': {
				let d = { x: handle.x, y: handle.y }

this.editor.snaps.clearIndicators()
				const snapPoint = this.getSnaps(shape, handle)

const isSnapMode = this.editor.user.getIsSnapMode()
				if (
					snapPoint &&
					!this.editor.inputs.getMetaKey() &&
					(isSnapMode ? !this.editor.inputs.getCtrlKey() : this.editor.inputs.getCtrlKey())
				) {
					this.editor.snaps.setIndicators(snapPoint.indicators)

return {
						...shape,
						props: {
							...shape.props,
							edges: {
								...shape.props.edges,
								[edgeType]: {
									...edge,
									d: Vec.Add(d, snapPoint.nudge).toJson(),
								},
							},
						},
					}
				}

// constrain the d handle around the node if we try drag it inside a node
				const distStart = Vec.Dist(handle, globPoints.startNode.position)
				if (distStart <= globPoints.startNode.radius) {
					d = getClosestPointOnCircle(
						globPoints.startNode.position,
						globPoints.startNode.radius,
						handle
					)
				}

// constrain the d handle around the node if we try drag it inside a node
				const distEnd = Vec.Dist(handle, globPoints.endNode.position)
				if (distEnd <= globPoints.endNode.radius) {
					d = getClosestPointOnCircle(
						globPoints.endNode.position,
						globPoints.endNode.radius,
						handle
					)
				}

// drag both d handles at the same time
				if (this.editor.inputs.getMetaKey()) {
					const delta = Vec.Sub(handle, initialEdge.d)

return {
						...shape,
						props: {
							...shape.props,
							edges: {
								...shape.props.edges,
								[oppositeEdgeType]: {
									...initialOppositeEdge,
									d: Vec.Add(initialOppositeEdge.d, delta).toJson(),
								},
								[edgeType]: {
									...edge,
									d: d,
								},
							},
						},
					}
				}

return {
					...shape,
					props: {
						...shape.props,
						edges: {
							...shape.props.edges,
							[edgeType]: {
								...edge,
								d: d,
							},
							[oppositeEdgeType]: {
								...initialOppositeEdge,
							},
						},
					},
				}
			}
			case 'tensionA': {
				const lineStart = globPoints[edgeType].tangentA
				const lineEnd = shape.props.edges[edgeType].d
				const projectedPoint = projectTensionPoint(lineStart, lineEnd, handle)

// drag ALL the tension handles
				if (this.editor.inputs.getMetaKey() && this.editor.inputs.getShiftKey()) {
					return {
						...shape,
						props: {
							...shape.props,
							edges: {
								...shape.props.edges,
								[edgeType]: {
									...initialEdge,
									tensionRatioA: projectedPoint,
									tensionRatioB: 1 - projectedPoint,
								},
								[oppositeEdgeType]: {
									...initialOppositeEdge,
									tensionRatioA: projectedPoint,
									tensionRatioB: 1 - projectedPoint,
								},
							},
						},
					}
				}

// drag opposite tension handles at the same time
				if (this.editor.inputs.getMetaKey()) {
					return {
						...shape,
						props: {
							...shape.props,
							edges: {
								...shape.props.edges,
								[edgeType]: {
									...initialEdge,
									tensionRatioA: projectedPoint,
									tensionRatioB: 1 - projectedPoint,
								},
							},
						},
					}
				}

return {
					...shape,
					props: {
						...shape.props,
						edges: {
							...shape.props.edges,
							[edgeType]: {
								...initialEdge,
								tensionRatioA: projectedPoint,
							},
							[oppositeEdgeType]: {
								...initialOppositeEdge,
							},
						},
					},
				}
			}
			case 'tensionB': {
				const lineStart = shape.props.edges[edgeType].d
				const lineEnd = globPoints[edgeType].tangentB
				const projectedPoint = projectTensionPoint(lineStart, lineEnd, handle)

// drag ALL the tension handles
				if (this.editor.inputs.getMetaKey() && this.editor.inputs.getShiftKey()) {
					return {
						...shape,
						props: {
							...shape.props,
							edges: {
								...shape.props.edges,
								[edgeType]: {
									...initialEdge,
									tensionRatioA: 1 - projectedPoint,
									tensionRatioB: projectedPoint,
								},
								[oppositeEdgeType]: {
									...initialOppositeEdge,
									tensionRatioA: 1 - projectedPoint,
									tensionRatioB: projectedPoint,
								},
							},
						},
					}
				}

// drag opposite tension handles at the same time
				if (this.editor.inputs.getMetaKey()) {
					return {
						...shape,
						props: {
							...shape.props,
							edges: {
								...shape.props.edges,
								[edgeType]: {
									...initialEdge,
									tensionRatioA: 1 - projectedPoint,
									tensionRatioB: projectedPoint,
								},
							},
						},
					}
				}

return {
					...shape,
					props: {
						...shape.props,
						edges: {
							...shape.props.edges,
							[edgeType]: {
								...initialEdge,
								tensionRatioB: projectedPoint,
							},
							[oppositeEdgeType]: {
								...initialOppositeEdge,
							},
						},
					},
				}
			}
		}

return shape
	}

override component(shape: GlobShape) {
		const showControlLines =
			this.editor.isInAny(
				'select.idle',
				'select.pointing_handle',
				'select.pointing_shape',
				'select.dragging_handle'
			) && this.editor.getOnlySelectedShape() === shape

return <GlobShape shape={shape} showControlLines={showControlLines} />
	}

override indicator(shape: GlobShape) {
		const zoomLevel = this.editor.getZoomLevel()

const globPoints = getGlobInfo(this.editor, shape)
		if (!globPoints) return null

const pathBuilder = buildGlobPath(globPoints)
		if (!pathBuilder) return null

return (
			<SVGContainer>
				<path
					pointerEvents="none"
					d={pathBuilder.toD()}
					stroke="black"
					strokeWidth={2 / zoomLevel}
					opacity={0.25}
					fill="blue"
				/>
			</SVGContainer>
		)
	}

override toSvg(shape: GlobShape) {
		const globPoints = getGlobInfo(this.editor, shape)
		if (!globPoints) return null

const pathBuilder = buildGlobPath(globPoints)
		if (!pathBuilder) return null

return pathBuilder.toSvg({
			style: 'solid',
			strokeWidth: 2,
			forceSolid: false,
			props: { stroke: 'black', fill: 'black' },
		})
	}

private getSnaps(shape: GlobShape, handle: TLHandle): SnapData | null {
		const INFINITE_LENGTH = 100000
		const pageToCurrentShape = this.editor.getShapePageTransform(shape.id).clone().invert()

const neighborGlobs: Set<GlobShape> = getNeighborGlobs(this.editor, shape)

// infinite lines going from direction of d handles to tangent points
		// for neighboring globs of the selected glob
		const snapEdges: { start: VecModel; end: VecModel; d: VecModel }[] = []
		for (const neighborGlob of neighborGlobs) {
			const transform = Mat.Compose(
				pageToCurrentShape,
				this.editor.getShapePageTransform(neighborGlob.id)
			)
			const neighborGeo = getGlobInfo(this.editor, neighborGlob)
			if (!neighborGeo) continue

for (const edge of ['edgeA', 'edgeB'] as const) {
				for (const tangent of ['tangentA', 'tangentB'] as const) {
					const dLocal = neighborGlob.props.edges[edge].d
					const tangentLocal = neighborGeo[edge][tangent]
					const direction = Vec.Sub(tangentLocal, dLocal).uni()

const infiniteEndPoint = Vec.Add(dLocal, Vec.Mul(direction, INFINITE_LENGTH))

const p1Transformed = transform.applyToPoint(dLocal)
					const p2Transformed = transform.applyToPoint(infiniteEndPoint)

snapEdges.push({
						start: p1Transformed,
						end: p2Transformed,
						d: p1Transformed,
					})
				}
			}
		}

let nearestPoint: Vec | null = null
		const endPoints: VecModel[] = []
		let minDistance = this.editor.snaps.getSnapThreshold()

for (const { start, end, d } of snapEdges) {
			const snapPoint = Vec.NearestPointOnLineSegment(start, end, handle, true)
			const distance = Vec.Dist(handle, snapPoint)

if (round(distance) <= round(minDistance)) {
				if (round(distance) < round(minDistance)) {
					endPoints.length = 0
					minDistance = distance
					nearestPoint = snapPoint
				}
				endPoints.push(d)
			}
		}

const globInfo = getGlobInfo(this.editor, shape)
		if (!globInfo) return null

const { edgeType } = getHandleData(handle.id)
		const outerTangentPoints = getOuterTangentPoints(
			globInfo.startNode.position,
			globInfo.startNode.radius,
			globInfo.endNode.position,
			globInfo.endNode.radius,
			edgeType
		)

// mid point, outer tangent edge, perp to that edge
		const midD = Vec.Lrp(outerTangentPoints[0], outerTangentPoints[1], 0.5)
		const outerLine = Vec.Sub(outerTangentPoints[0], outerTangentPoints[1]).uni()

// infinite line of the perpendicular outer line
		const perpendicularOuterLine = Vec.Per(outerLine).uni()
		const normalDStart = Vec.Add(midD, Vec.Mul(perpendicularOuterLine, -INFINITE_LENGTH))
		const normalDEnd = Vec.Add(midD, Vec.Mul(perpendicularOuterLine, INFINITE_LENGTH))

// check snap to the outer line
		let snappedToOuterLine = false
		const outerLineSnapPoint = Vec.NearestPointOnLineSegment(
			outerTangentPoints[0],
			outerTangentPoints[1],
			handle,
			false
		)
		const outerLineDistance = Vec.Dist(handle, outerLineSnapPoint)

if (round(outerLineDistance) <= round(minDistance)) {
			if (round(outerLineDistance) < round(minDistance)) {
				minDistance = outerLineDistance
				nearestPoint = outerLineSnapPoint
			}
			snappedToOuterLine = true
		}

// check snap to the perpendicular line
		let snappedToPerpLine = false
		const perpLineSnapPoint = Vec.NearestPointOnLineSegment(normalDStart, normalDEnd, handle, true)
		const perpLineDistance = Vec.Dist(handle, perpLineSnapPoint)

if (round(perpLineDistance) <= round(minDistance)) {
			if (round(perpLineDistance) < round(minDistance)) {
				minDistance = perpLineDistance
				nearestPoint = perpLineSnapPoint
			}
			snappedToPerpLine = true
		}

// if both outer line and perp line are snapped, snap to their intersection (midD)
		if (snappedToOuterLine && snappedToPerpLine) {
			nearestPoint = midD
		}

// if no snap found, return null
		if (!nearestPoint) return null

// transform to page space and calculate final snapped handle position
		const getShapePageTransform = this.editor.getShapePageTransform(shape.id)
		const handleInPageSpace = getShapePageTransform.applyToPoint(handle)
		const nearestPointInPageSpace = getShapePageTransform.applyToPoint(nearestPoint)

const snappedHandle = Vec.Add(
			handleInPageSpace,
			Vec.Sub(nearestPointInPageSpace, handleInPageSpace)
		)

const indicators: PointsSnapIndicator[] = endPoints.map((endPoint) => ({
			id: uniqueId(),
			type: 'points',
			points: [getShapePageTransform.applyToPoint(endPoint), snappedHandle],
		}))

if (snappedToOuterLine) {
			indicators.push({
				id: uniqueId(),
				type: 'points',
				points: [
					getShapePageTransform.applyToPoint(outerTangentPoints[0]),
					getShapePageTransform.applyToPoint(outerTangentPoints[1]),
				],
			})
		}

if (snappedToPerpLine) {
			indicators.push({
				id: uniqueId(),
				type: 'points',
				points: [snappedHandle, getShapePageTransform.applyToPoint(midD)],
			})
		}

return {
			nudge: Vec.Sub(nearestPoint, handle),
			indicators,
		}
	}
}

function buildGlobPath(globPoints: GlobGeometry, geometry: boolean = false) {
	const pathBuilder = new PathBuilder()
	pathBuilder.moveTo(globPoints.edgeA.tangentA.x, globPoints.edgeA.tangentA.y, {
		geometry: { isFilled: true },
	})

const arcFlagA = getArcFlag(
		globPoints.startNode.position,
		globPoints.edgeA.tangentA,
		globPoints.edgeB.tangentA
	)

const arcFlagB = getArcFlag(
		globPoints.endNode.position,
		globPoints.edgeB.tangentB,
		globPoints.edgeA.tangentB
	)

pathBuilder.circularArcTo(
		globPoints.startNode.radius,
		geometry ? !arcFlagA : arcFlagA,
		geometry ? false : true,
		globPoints.edgeB.tangentA.x,
		globPoints.edgeB.tangentA.y
	)

pathBuilder.cubicBezierTo(
		globPoints.edgeB.tangentB.x,
		globPoints.edgeB.tangentB.y,
		globPoints.edgeB.tensionA.x,
		globPoints.edgeB.tensionA.y,
		globPoints.edgeB.tensionB.x,
		globPoints.edgeB.tensionB.y
	)

pathBuilder.circularArcTo(
		globPoints.endNode.radius,
		geometry ? !arcFlagB : arcFlagB,
		geometry ? false : true,
		globPoints.edgeA.tangentB.x,
		globPoints.edgeA.tangentB.y
	)

pathBuilder.cubicBezierTo(
		globPoints.edgeA.tangentA.x,
		globPoints.edgeA.tangentA.y,
		globPoints.edgeA.tensionB.x,
		globPoints.edgeA.tensionB.y,
		globPoints.edgeA.tensionA.x,
		globPoints.edgeA.tensionA.y
	)

pathBuilder.close()

return pathBuilder
}

export const GlobShape = track(function GlobShape({
	shape,
	showControlLines,
}: {
	shape: GlobShape
	showControlLines: boolean
}) {
	const editor = useEditor()
	const zoomLevel = editor.getZoomLevel()

// Use reactive inputs to track if space key is pressed
	const fillGlob = useValue('space key pressed', () => editor.inputs.keys.has('Space'), [editor])

const globPoints = getGlobInfo(editor, shape)
	if (!globPoints) return null

const pathBuilder = buildGlobPath(globPoints)
	if (!pathBuilder) return null

const dxA = toDomPrecision(shape.props.edges.edgeA.d.x)
	const dyA = toDomPrecision(shape.props.edges.edgeA.d.y)
	const dxB = toDomPrecision(shape.props.edges.edgeB.d.x)
	const dyB = toDomPrecision(shape.props.edges.edgeB.d.y)

return (
		<SVGContainer>
			{showControlLines && (
				<>
					<ControlLine x1={dxA} y1={dyA} x2={txAA} y2={tyAA} />
					<ControlLine x1={dxA} y1={dyA} x2={txAB} y2={tyAB} />
					<ControlLine x1={dxB} y1={dyB} x2={txBA} y2={tyBA} />
					<ControlLine x1={dxB} y1={dyB} x2={txBB} y2={tyBB} />
				</>
			)}
			<path
				d={pathBuilder.toD()}
				stroke="black"
				fill={fillGlob ? 'black' : 'white'}
				opacity={fillGlob ? 1 : 0.75}
				strokeWidth={2 / zoomLevel}
			/>
		</SVGContainer>
	)
})

export function ControlLine({
	x1,
	y1,
	x2,
	y2,
}: {
	x1: number
	y1: number
	x2: number
	y2: number
}) {
	const editor = useEditor()
	const zoomLevel = editor.getZoomLevel()
	const dashArray = `${3 / zoomLevel} ${3 / zoomLevel}`

return (
		<line
			x1={x1}
			y1={y1}
			x2={x2}
			y2={y2}
			stroke="#4169E1"
			strokeDasharray={dashArray}
			strokeWidth={1 / zoomLevel}
		/>
	)
}

const getHandleData = (id: string) => {
	const [edgeType, point] = id.split('.') as [EdgeCurveType, keyof EdgeGeometry | keyof EdgeProps]

return { edgeType, point }
}

export const getNeighborGlobs = (editor: Editor, shape: GlobShape) => {
	const currentGlobBindings = editor.getBindingsFromShape<GlobBinding>(shape.id, 'glob')

const neighborGlobs: Set<GlobShape> = new Set()
	// try find nodes that attach to other globs
	for (const binding of currentGlobBindings) {
		const nodeBindings = editor.getBindingsToShape<GlobBinding>(binding.toId, 'glob')
		for (const nodeBinding of nodeBindings) {
			const neighborGlob = editor.getShape<GlobShape>(nodeBinding.fromId)

// if this is the glob we selecting or a glob we've already added, skip
			if (!neighborGlob || neighborGlob.id === shape.id) continue
			if (neighborGlobs.has(neighborGlob)) continue

neighborGlobs.add(neighborGlob)
		}
	}

return neighborGlobs
}
```

## NodeShapeUtil.tsx

```tsx
import {
	Circle2d,
	Editor,
	getColorValue,
	getIndicesAbove,
	RecordProps,
	ShapeUtil,
	SVGContainer,
	T,
	TLHandle,
	TLHandleDragInfo,
	TLResizeInfo,
	TLShape,
	useDefaultColorTheme,
	useValue,
	Vec,
	ZERO_INDEX_KEY,
} from 'tldraw'

export interface NodeProps {
	opacity: number
	radius: number
}

const NODE_TYPE = 'node'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[NODE_TYPE]: NodeProps
	}
}

export type NodeShape = TLShape<'node'>

export class NodeShapeUtil extends ShapeUtil<NodeShape> {
	static override type = 'node' as const
	static override props: RecordProps<NodeShape> = {
		opacity: T.number,
		radius: T.number,
	}

override getDefaultProps(): NodeShape['props'] {
		return {
			opacity: 1,
			radius: 50,
		}
	}

override hideResizeHandles(_shape: NodeShape): boolean {
		return true
	}

override hideRotateHandle(_shape: NodeShape): boolean {
		return true
	}

override hideSelectionBoundsBg(_shape: NodeShape): boolean {
		return true
	}

override hideSelectionBoundsFg(_shape: NodeShape): boolean {
		return true
	}

override getGeometry(shape: NodeShape) {
		return new Circle2d({
			x: -shape.props.radius,
			y: -shape.props.radius,
			radius: shape.props.radius,
			isFilled: true,
		})
	}

override onResize(_shape: NodeShape, info: TLResizeInfo<NodeShape>) {
		const { scaleX, scaleY, initialShape } = info
		const avgScale = (Math.abs(scaleX) + Math.abs(scaleY)) / 2

return {
			props: {
				radius: initialShape.props.radius * avgScale,
			},
		}
	}

override getHandles(shape: NodeShape): TLHandle[] {
		const east = Vec.Uni({ x: -1, y: 0 }).mul(shape.props.radius)
		const west = Vec.Uni({ x: 1, y: 0 }).mul(shape.props.radius)

const indices = getIndicesAbove(ZERO_INDEX_KEY, 2)

return [
			{
				id: 'east',
				type: 'vertex',
				index: indices[0],
				x: east.x,
				y: east.y,
			},
			{
				id: 'west',
				type: 'vertex',
				index: indices[1],
				x: west.x,
				y: west.y,
			},
		]
	}

override onHandleDrag(shape: NodeShape, info: TLHandleDragInfo<NodeShape>) {
		const { handle, initial } = info
		if (!initial) return shape

const mag = Vec.Len(handle) - initial.props.radius

return {
			...shape,
			props: {
				...shape.props,
				radius: initial.props.radius + mag,
			},
		}
	}

override indicator(shape: NodeShape) {
		const zoom = this.editor.getZoomLevel()

// eslint-disable-next-line react-hooks/rules-of-hooks
		const theme = useDefaultColorTheme()
		const blue = getColorValue(theme, 'blue', 'solid')

return <circle r={shape.props.radius} strokeWidth={1 / zoom} stroke={blue} fill="none" />
	}

override component(shape: NodeShape) {
		const isSingleNode = this.editor.getBindingsToShape(shape.id, 'glob').length === 0

return <NodeComponent shape={shape} editor={this.editor} isSingleNode={isSingleNode} />
	}
}

function NodeComponent({
	shape,
	editor,
	isSingleNode,
}: {
	shape: NodeShape
	editor: Editor
	isSingleNode: boolean
}) {
	const zoom = useValue('zoom', () => editor.getZoomLevel(), [editor])
	const { radius } = shape.props
	const dashArray = `${3 / zoom} ${3 / zoom}`

// Use reactive inputs to track if space key is pressed
	const isSpacePressed = useValue('space key pressed', () => editor.inputs.keys.has('Space'), [
		editor,
	])

const fillNode = isSingleNode && isSpacePressed
	if (!isSingleNode && isSpacePressed) return null

return (
		<SVGContainer>
			<g opacity={shape.props.opacity}>
				<circle
					r={radius}
					stroke={'black'}
					strokeDasharray={isSingleNode ? 'none' : dashArray}
					strokeWidth={1 / zoom}
					fill={fillNode ? 'black' : 'white'}
				/>
				<circle x={0} y={0} r={1 / zoom} stroke="black" strokeWidth={1 / zoom} fill="black" />
			</g>
		</SVGContainer>
	)
}
```

## shared.ts

```ts
import { Editor, TLShapeId, Vec, VecLike } from 'tldraw'
import { GlobBinding } from './GlobBindingUtil'
import { GlobShape } from './GlobShapeUtil'
import { NodeShape } from './NodeShapeUtil'
import { getOuterTangentPoints } from './utils'

export const getStartAndEndNodes = (editor: Editor, glob: TLShapeId) => {
	const bindings = editor.getBindingsFromShape<GlobBinding>(glob, 'glob')
	if (!bindings.length) return null

const startNode = bindings.find((b) => b.props.terminal === 'start')
	if (!startNode) return null
	const startNodeShape = editor.getShape<NodeShape>(startNode.toId)
	if (!startNodeShape) return null

const endNode = bindings.find((b) => b.props.terminal === 'end')
	if (!endNode) return null
	const endNodeShape = editor.getShape<NodeShape>(endNode.toId)
	if (!endNodeShape) return null

return { startNodeShape, endNodeShape }
}

export interface GlobBindings {
	start?: GlobBinding
	end?: GlobBinding
}

export function getGlobBindings(editor: Editor, shape: GlobShape): GlobBindings {
	const bindings = editor.getBindingsFromShape<GlobBinding>(shape.id, 'glob')

const start = bindings.find((b) => b.props.terminal === 'start')
	const end = bindings.find((b) => b.props.terminal === 'end')

return { start, end }
}

export const getGlobTangentUpdate = (
	editor: Editor,
	globId: TLShapeId,
	startNodePagePos: VecLike,
	startRadius: number,
	endNodePagePos: VecLike,
	endRadius: number
) => {
	// Calculate midpoint in page space
	const midPagePos = Vec.Average([startNodePagePos, endNodePagePos])

// Get the glob shape to determine its parent
	const glob = editor.getShape<GlobShape>(globId)
	if (!glob) return null

// Convert midpoint to glob's parent space
	const globParentTransform = editor.getShapeParentTransform(glob)
	const midInGlobParentSpace = globParentTransform.clone().invert().applyToPoint(midPagePos)

// Calculate local node positions relative to midpoint in page space
	const localStartNode = Vec.Sub(startNodePagePos, midPagePos)
	const localEndNode = Vec.Sub(endNodePagePos, midPagePos)

const tangentPoints = getOuterTangentPoints(localStartNode, startRadius, localEndNode, endRadius)

const d0 = Vec.Lrp(tangentPoints[0], tangentPoints[1], 0.5)
	const d1 = Vec.Lrp(tangentPoints[2], tangentPoints[3], 0.5)

return {
		id: globId,
		type: 'glob' as const,
		x: midInGlobParentSpace.x,
		y: midInGlobParentSpace.y,
		props: {
			edges: {
				edgeA: { d: { x: d0.x, y: d0.y }, tensionRatioA: 0.5, tensionRatioB: 0.5 },
				edgeB: { d: { x: d1.x, y: d1.y }, tensionRatioA: 0.5, tensionRatioB: 0.5 },
			},
		},
	}
}
```

## utils.ts

```ts
import { Vec, VecLike, VecModel } from 'tldraw'

export const getOuterTangentPoints = (
	c0: VecLike,
	r0: number,
	c1: VecLike,
	r1: number,
	side?: 'edgeA' | 'edgeB'
): VecModel[] => {
	const offsetAngle = Vec.Angle(c0, c1)
	const d = Vec.Dist(c0, c1)

const theta = Math.acos((r0 - r1) / d)

const angle0 = offsetAngle + theta
	const angle1 = offsetAngle - theta

const t00 = Vec.Add(c0, Vec.FromAngle(angle0).mul(r0))
	const t01 = Vec.Add(c1, Vec.FromAngle(angle0).mul(r1))

const t10 = Vec.Add(c0, Vec.FromAngle(angle1).mul(r0))
	const t11 = Vec.Add(c1, Vec.FromAngle(angle1).mul(r1))

if (side) {
		if (side === 'edgeA') {
			return [
				{ x: t00.x, y: t00.y },
				{ x: t01.x, y: t01.y },
			]
		}

return [
			{ x: t10.x, y: t10.y },
			{ x: t11.x, y: t11.y },
		]
	}

return [
		{ x: t00.x, y: t00.y },
		{ x: t01.x, y: t01.y },
		{ x: t10.x, y: t10.y },
		{ x: t11.x, y: t11.y },
	]
}

export const getGlobEndPoint = (c: VecModel, d: VecModel, r: number, side: number = 0) => {
	const angle = Vec.Angle(c, d)

const displacement = Vec.Sub(c, d)
	const dist = Vec.Len(displacement)

// we are inside the circle no solutions, so return null
	if (dist <= r) {
		return
	}

const theta = Math.acos(r / dist)

const sideTheta = side === 0 ? theta : -theta
	const p = Vec.Add(c, Vec.FromAngle(angle + sideTheta).mul(r))

return p
}

export const getArcFlag = (c: VecModel, e0: VecModel, e1: VecModel) => {
	const d0 = Vec.Angle(c, e0)
	const d1 = Vec.Angle(c, e1)

const diff = d1 - d0

const theta = Math.atan2(Math.sin(diff), Math.cos(diff))

return theta > 0 ? false : true
}

export const projectTensionPoint = (lineStart: VecModel, lineEnd: VecModel, handle: VecModel) => {
	const lineDir = Vec.Sub(lineEnd, lineStart)
	const lineLength = lineDir.len()

const toHandle = Vec.Sub(handle, lineStart)
	const projection = Vec.Dpr(toHandle, Vec.Uni(lineDir))
	const clampedProjection = Math.max(0, Math.min(lineLength, projection))

return clampedProjection / lineLength
}

export const circleCentresOverlap = (c0: VecModel, r0: number, c1: VecModel) => {
	const d = Vec.Dist(c0, c1)
	return d <= r0
}

export const getClosestPointOnCircle = (c: VecModel, r: number, p: VecModel) => {
	const pDirection = Vec.Sub(p, c).uni()

return Vec.Add(c, Vec.Mul(pDirection, r + 1)).toJson()
}
```

## GlobTool.tsx

```tsx
import {
	createShapeId,
	snapAngle,
	StateNode,
	TLBindingUpdate,
	TLParentId,
	TLPointerEventInfo,
	TLShapeId,
	Vec,
} from 'tldraw'
import { GlobBinding } from '../GlobBindingUtil'
import { GlobShape } from '../GlobShapeUtil'
import { NodeShape } from '../NodeShapeUtil'
import { getGlobTangentUpdate, getStartAndEndNodes } from '../shared'

export class GlobTool extends StateNode {
	static override id = 'glob'
	static override initial = 'idle'

static override children() {
		return [IdleState, NodeState, ConnectState]
	}
}

export class IdleState extends StateNode {
	static override id = 'idle'

override onCancel() {
		this.editor.setCurrentTool('select')
	}
}

export class NodeState extends StateNode {
	static override id = 'node'

private ghostShapeId: TLShapeId | null = null

override onEnter() {
		this.editor.setCursor({ type: 'cross' })
	}

override onPointerMove(_info: TLPointerEventInfo) {
		const pagePoint = this.editor.inputs.getCurrentPagePoint()

if (!this.ghostShapeId) {
			const id = createShapeId()
			this.editor.createShape<NodeShape>({
				id: id,
				type: 'node',
				x: pagePoint.x,
				y: pagePoint.y,
				props: {
					radius: 50,
					opacity: 0.25,
				},
			})
			this.ghostShapeId = id
			return
		}

const shape = this.editor.getShape<NodeShape>(this.ghostShapeId)
		if (!shape) return

// could be inside a frame, so we need to get the point in the parent space
		const parentPoint = this.editor.getPointInParentSpace(shape, pagePoint)

this.editor.updateShape<NodeShape>({
			...shape,
			x: parentPoint.x,
			y: parentPoint.y,
		})
	}

override onPointerDown(_info: TLPointerEventInfo) {
		if (!this.ghostShapeId) return

const node = this.editor.getShape<NodeShape>(this.ghostShapeId)!
		if (!node) return

// if we try place another node such that it overlaps with an existing node radii, don't allow it
		const pagePoint = this.editor.inputs.getCurrentPagePoint()
		const shapes = this.editor
			.getShapesAtPoint(pagePoint, {
				hitInside: true,
			})
			.filter(
				(shape) =>
					shape.id !== this.ghostShapeId && this.editor.isShapeOfType<NodeShape>(shape, 'node')
			)

if (shapes.length) {
			return
		}

const parentPoint = this.editor.getPointInParentSpace(node, pagePoint)
		this.editor.updateShape<NodeShape>({
			...node,
			x: parentPoint.x,
			y: parentPoint.y,
			props: {
				...node.props,
				opacity: 1,
			},
		})

this.ghostShapeId = null

this.complete()
	}

override onCancel() {
		this.complete()
	}

private complete() {
		if (this.ghostShapeId) {
			this.editor.deleteShapes([this.ghostShapeId])
			this.ghostShapeId = null
		}

this.editor.setCurrentTool('select')
	}
}

export class ConnectState extends StateNode {
	static override id = 'connect'

selectedNodeIds: TLShapeId[] = []
	ghostGlobIds: TLShapeId[] = []

ghostNodeId: TLShapeId | null = null

override onEnter() {
		this.selectedNodeIds = this.editor.getSelectedShapeIds()
		this.editor.setCursor({ type: 'cross' })
	}

override onPointerMove(info: TLPointerEventInfo) {
		// selected nodes go to the ghost node
		const selectedNode = this.editor.getShape<NodeShape>(this.selectedNodeIds[0])
		if (!selectedNode) return

// Apply shift snapping for angle constraints
		let pagePoint = this.editor.inputs.getCurrentPagePoint()
		if (info.shiftKey) {
			const selectedNodeCenter = new Vec(selectedNode.x, selectedNode.y)
			const angle = Vec.Angle(selectedNodeCenter, pagePoint)
			const snappedAngle = snapAngle(angle, 24)
			const distance = Vec.Dist(selectedNodeCenter, pagePoint)
			pagePoint = Vec.FromAngle(snappedAngle, distance).add(selectedNodeCenter)
		}

// if there is no ghost node, create one
		if (!this.ghostNodeId) {
			const id = createShapeId()
			this.editor.createShape<NodeShape>({
				id: id,
				type: 'node',
				x: pagePoint.x,
				y: pagePoint.y,
				props: {
					radius: selectedNode.props.radius,
				},
			})

this.ghostNodeId = id
		}

const parentPoint = this.editor.getPointInParentSpace(this.ghostNodeId, pagePoint)
		this.editor.updateShape<NodeShape>({
			id: this.ghostNodeId,
			type: 'node',
			x: parentPoint.x,
			y: parentPoint.y,
		})

// if there are no ghost globs, create them, we could be ghosting a whole selection of nodes
		if (!this.ghostGlobIds.length) {
			for (let i = 0; i < this.selectedNodeIds.length; i++) {
				const id = createShapeId()

// Determine the proper parent for the glob based on the bound nodes
				const startNode = this.editor.getShape(this.selectedNodeIds[i])
				const endNode = this.editor.getShape(this.ghostNodeId)

let globParentId: TLParentId = this.editor.getCurrentPageId()
				if (startNode && endNode) {
					// Find common ancestor of the two nodes
					const commonAncestor = this.editor.findCommonAncestor([startNode, endNode])
					if (commonAncestor) {
						globParentId = commonAncestor
					}
				}

this.editor.createShape<GlobShape>({
					id: id,
					type: 'glob',
					parentId: globParentId,
					x: 0,
					y: 0,
					props: {
						opacity: 0.25,
						isGhosting: true,
					},
				})

const glob = this.editor.getShape<GlobShape>(id)
				if (!glob) continue

this.ghostGlobIds.push(id)

// bind each node to the glob
				this.editor.createBindings<GlobBinding>([
					{
						fromId: id,
						toId: this.selectedNodeIds[i],
						type: 'glob',
						props: {
							terminal: 'start',
						},
					},
					{
						fromId: id,
						toId: this.ghostNodeId,
						type: 'glob',
						props: {
							terminal: 'end',
						},
					},
				])
			}
		}

// update each ghost globs as we drag the ghost node around
		for (let i = 0; i < this.ghostGlobIds.length; i++) {
			const selectedNode = this.editor.getShape<NodeShape>(this.selectedNodeIds[i])
			if (!selectedNode) continue

const pageNode = this.editor.getShapePageTransform(this.selectedNodeIds[i]).point()
			const update = getGlobTangentUpdate(
				this.editor,
				this.ghostGlobIds[i],
				pageNode,
				selectedNode.props.radius,
				pagePoint,
				selectedNode.props.radius
			)

this.editor.updateShape<GlobShape>(update)
		}
	}

override onPointerDown(info: TLPointerEventInfo) {
		if (!this.ghostNodeId) return

const pagePoint = this.editor.screenToPage(info.point)
		const shapes = this.editor.getShapesAtPoint(pagePoint, {
			hitInside: true,
		})

// find any existing node we may be trying to connect to
		const nodes = shapes.filter(
			(shape) =>
				this.editor.isShapeOfType<NodeShape>(shape, 'node') && shape.id !== this.ghostNodeId
		)

// if we don't find a node, just place the ghost node and complete
		if (!nodes.length) {
			this.complete()
			return
		}

// we found a node, we need to update the bindings to connect to the existing node,
		// recalculate the tangent points for the glob, with different radii as well as the bindings
		const updates: TLBindingUpdate[] = []
		const bindings = this.editor.getBindingsToShape(this.ghostNodeId, 'glob')
		if (!bindings.length) {
			this.complete()
			return
		}

// update all current bindings to connect to the existing node
		for (const binding of bindings) {
			updates.push({
				...binding,
				toId: nodes[0].id,
			})
		}

this.editor.updateBindings(updates)

// update the outer tangents because the radii may have changed
		for (const glob of this.ghostGlobIds) {
			const globShape = this.editor.getShape<GlobShape>(glob)
			if (!globShape) continue

const nodes = getStartAndEndNodes(this.editor, glob)
			if (!nodes) continue

const startNodePagePos = this.editor.getShapePageTransform(nodes.startNodeShape.id).point()
			const endNodePagePos = this.editor.getShapePageTransform(nodes.endNodeShape.id).point()

const update = getGlobTangentUpdate(
				this.editor,
				glob,
				startNodePagePos,
				nodes.startNodeShape.props.radius,
				endNodePagePos,
				nodes.endNodeShape.props.radius
			)
			this.editor.updateShape<GlobShape>(update)
		}

if (this.ghostNodeId) {
			this.editor.deleteShape(this.ghostNodeId)
		}

this.complete()
	}

override onCancel() {
		if (this.ghostGlobIds.length) {
			this.editor.deleteShapes(this.ghostGlobIds)
			this.ghostGlobIds = []
		}
		if (this.ghostNodeId) {
			this.editor.deleteShapes([this.ghostNodeId])
			this.ghostNodeId = null
		}

this.editor.setCurrentTool('select')
	}

override onComplete() {
		this.complete()
	}

private complete() {
		// remove the ghosting from the globs
		for (let i = 0; i < this.ghostGlobIds.length; i++) {
			this.editor.updateShape<GlobShape>({
				id: this.ghostGlobIds[i],
				type: 'glob',
				props: { isGhosting: false },
			})
		}

this.ghostNodeId = null

this.editor.setSelectedShapes(this.ghostGlobIds)
		this.selectedNodeIds = []
		this.ghostGlobIds = []

this.editor.setCurrentTool('select')
	}
}
```

--------

# Custom shape

Category: Shapes & tools

Keywords: util

A simple custom shape.

You can create custom shapes in tldraw by creating a shape util and passing it to the Tldraw component.
In this example, we'll create a custom shape that is a simple rectangle with some text inside of it.

## App.tsx

```tsx
import {
	Geometry2d,
	HTMLContainer,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	T,
	TLResizeInfo,
	TLShape,
	Tldraw,
	resizeBox,
} from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

const MY_CUSTOM_SHAPE_TYPE = 'my-custom-shape'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_CUSTOM_SHAPE_TYPE]: { w: number; h: number; text: string }
	}
}

// [2]
type ICustomShape = TLShape<typeof MY_CUSTOM_SHAPE_TYPE>

// [3]
export class MyShapeUtil extends ShapeUtil<ICustomShape> {
	// [a]
	static override type = MY_CUSTOM_SHAPE_TYPE
	static override props: RecordProps<ICustomShape> = {
		w: T.number,
		h: T.number,
		text: T.string,
	}

// [b]
	getDefaultProps(): ICustomShape['props'] {
		return {
			w: 200,
			h: 200,
			text: "I'm a shape!",
		}
	}

// [c]
	override canEdit() {
		return false
	}
	override canResize() {
		return true
	}
	override isAspectRatioLocked() {
		return false
	}

// [d]
	getGeometry(shape: ICustomShape): Geometry2d {
		return new Rectangle2d({
			width: shape.props.w,
			height: shape.props.h,
			isFilled: true,
		})
	}

// [e]
	override onResize(shape: any, info: TLResizeInfo<any>) {
		return resizeBox(shape, info)
	}

// [f]
	component(shape: ICustomShape) {
		return <HTMLContainer style={{ backgroundColor: '#efefef' }}>{shape.props.text}</HTMLContainer>
	}

// [g]
	indicator(shape: ICustomShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

// [4]
const customShape = [MyShapeUtil]

export default function CustomShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShape}
				onMount={(editor) => {
					editor.createShape({ type: MY_CUSTOM_SHAPE_TYPE, x: 100, y: 100 })
				}}
			/>
		</div>
	)
}

/*
Introduction:

[1]
First, we need to extend TLGlobalShapePropsMap to add our shape's props to the global type system.
This tells TypeScript about the shape's properties. For this shape, we define width (w), height (h),
and text as the shape's properties.

[2]
Define the shape type using TLShape with the shape's type as a type argument.

[3]
This is our shape util. In tldraw shape utils are classes that define how a shape behaves and renders.
We can extend the ShapeUtil class and provide the shape type as a generic. If we extended the
BaseBoxShapeUtil class instead, we wouldn't have define methods such as `getGeometry` and `onResize`.

[a]
	This is where we define out shape's props and type for the editor. It's important to use the same
	string for the type as we did in [2]. We need to define the shape's props using tldraw's validator
	library. The validator will help make sure the store always has shape data we can trust.

[b]
	This is a method that returns the default props for our shape.

[c]
	Some handy methods for controlling different shape behaviour. You don't have to define these, and
	they're only shown here so you know they exist. Check out the editable shape example to learn more
	about creating an editable shape.

[d]
	The getGeometry method is what the editor uses for hit-testing, binding etc. We're using the
	Rectangle2d class from tldraw's geometry library to create a rectangle shape. If we extended the
	BaseBoxShapeUtil class, we wouldn't have to define this method.

[e]
	We're using the resizeBox utility method to handle resizing our shape. If we extended the
	BaseBoxShapeUtil class, we wouldn't have to define this method.

[f]
	The component method defines how our shape renders. We're returning an HTMLContainer here, which
	is a handy component that tldraw exports. It's essentially a div with some special css. There's a
	lot of flexibility here, and you can use any React hooks you want and return any valid JSX.

[g]
	The indicator is the blue outline around a selected shape. We're just returning a rectangle with the
	same width and height as the shape here. You can return any valid JSX here.

[4]
This is where we render the Tldraw component with our custom shape. We're passing in our custom shape
util as an array to the shapeUtils prop. We're also using the onMount callback to create a shape on
the canvas. If you want to learn how to add a tool for your shape, check out the custom config example.
If you want to learn how to programmatically control the canvas, check out the Editor API examples.

*/
```

--------

# Custom tool (sticker)

Category: Shapes & tools

Keywords: state, machine, chart, node, sticker

A simple custom tool.

Tools are nodes in tldraw's state chart. They are responsible for handling user input.

You can create custom tools by extending the `StateNode` class and overriding its methods. In this example we make a very simple sticker tool that adds a heart emoji to the canvas when you click.

## App.tsx

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

// There's a guide at the bottom of this file!

const OFFSET = 12

// [1]
class StickerTool extends StateNode {
	static override id = 'sticker'

// [a]
	override onEnter() {
		this.editor.setCursor({ type: 'cross', rotation: 0 })
	}

// [b]
	override onPointerDown() {
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		this.editor.createShape({
			type: 'text',
			x: currentPagePoint.x - OFFSET,
			y: currentPagePoint.y - OFFSET,
			props: { richText: toRichText('❤️') },
		})
	}
}

// [2]
const customTools = [StickerTool]
export default function CustomToolExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// Pass in the array of custom tool classes
				tools={customTools}
				// Set the initial state to the sticker tool
				initialState="sticker"
				// hide the ui
				hideUi
				// Put some helpful text on the canvas
				onMount={(editor) => {
					editor.createShape({
						type: 'text',
						x: 100,
						y: 100,
						props: { richText: toRichText('Click anywhere to add a sticker') },
					})
				}}
			/>
		</div>
	)
}

/*
Introduction:

Tools are nodes in tldraw's state machine. They are responsible for handling user input.
You can create custom tools by extending the `StateNode` class and overriding its methods.
In this example we make a very simple sticker tool that adds a heart emoji to the canvas
when you click.

[1]
We extend the `StateNode` class to create a new tool called `StickerTool`. We set its id
to "sticker". We are not implementing any child states in this example, so we don't need
to set an initial state or define any children states. To see an example of a custom tool
with child states, check out the screenshot tool or minimal examples.

[a] The onEnter method is called when the tool is activated. We use it to set the cursor
		to a crosshair.

[b] The onPointerDown method is called when the user clicks on the canvas. We use it to
		create a new shape at the click location. We can get the click location from the
		editor's inputs.

[2]
We pass our custom tool to the Tldraw component using the `tools` prop. We also set the
initial state to our custom tool. We hide the ui and add some helpful text to the canvas
using the `onMount` prop. This is not necessary for the tool to work but it helps make the
example more visually clear.
*/
```

--------

# Custom tool (screenshot)

Category: Shapes & tools

Keywords: state chart, state machine, child states

A custom tool that takes a screenshot of the canvas.

Tools are the parts of tldraw's state chart. Most interactions in tldraw are tools.

This example shows how to create a custom tool that takes a screenshot of a specific area of the canvas.

## App.tsx

```tsx
import {
	Box,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TLUiAssetUrlOverrides,
	TLUiOverrides,
	Tldraw,
	TldrawUiMenuItem,
	useEditor,
	useIsToolSelected,
	useTools,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { ScreenshotTool } from './ScreenshotTool/ScreenshotTool'
import { ScreenshotDragging } from './ScreenshotTool/childStates/Dragging'

// There's a guide at the bottom of this file!

// [1]
const customTools = [ScreenshotTool]

// [2]
const customUiOverrides: TLUiOverrides = {
	tools: (editor, tools) => {
		return {
			...tools,
			screenshot: {
				id: 'screenshot',
				label: 'Screenshot',
				icon: 'tool-screenshot',
				kbd: 'j',
				onSelect() {
					editor.setCurrentTool('screenshot')
				},
			},
		}
	},
}

function CustomToolbar() {
	const tools = useTools()
	const isScreenshotSelected = useIsToolSelected(tools['screenshot'])
	return (
		<DefaultToolbar>
			<TldrawUiMenuItem {...tools['screenshot']} isSelected={isScreenshotSelected} />
			<DefaultToolbarContent />
		</DefaultToolbar>
	)
}

// [3]
const customAssetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'tool-screenshot': '/tool-screenshot.svg',
	},
}

// [4]
function ScreenshotBox() {
	const editor = useEditor()

const screenshotBrush = useValue(
		'screenshot brush',
		() => {
			// Check whether the screenshot tool (and its dragging state) is active
			if (editor.getPath() !== 'screenshot.dragging') return null

// Get screenshot.dragging state node
			const draggingState = editor.getStateDescendant<ScreenshotDragging>('screenshot.dragging')!

// Get the box from the screenshot.dragging state node
			const box = draggingState.screenshotBox.get()

// The box is in "page space", i.e. panned and zoomed with the canvas, but we
			// want to show it in front of the canvas, so we'll need to convert it to
			// "page space", i.e. uneffected by scale, and relative to the tldraw
			// page's top left corner.
			const zoomLevel = editor.getZoomLevel()
			const { x, y } = editor.pageToViewport({ x: box.x, y: box.y })
			return new Box(x, y, box.w * zoomLevel, box.h * zoomLevel)
		},
		[editor]
	)

if (!screenshotBrush) return null

return (
		<div
			style={{
				position: 'absolute',
				top: 0,
				left: 0,
				transform: `translate(${screenshotBrush.x}px, ${screenshotBrush.y}px)`,
				width: screenshotBrush.w,
				height: screenshotBrush.h,
				border: '1px solid var(--tl-color-text-0)',
				zIndex: 999,
			}}
		/>
	)
}

const customComponents: TLComponents = {
	InFrontOfTheCanvas: ScreenshotBox,
	Toolbar: CustomToolbar,
}

// [5]
export default function ScreenshotToolExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="tldraw_screenshot_example"
				tools={customTools}
				overrides={customUiOverrides}
				assetUrls={customAssetUrls}
				components={customComponents}
			/>
		</div>
	)
}

/*
Introduction:

This example shows how to create a custom tool. In tldraw, tools are parts of the
tldraw state chart. While the most common use for tools is creating shapes, you can
use tools to create other types of interactions too! In this example, we create a
"screenshot tool" that lets the user draw a box on the canvas. When the user finishes
drawing their box, we'll export (or copy) a screenshot of that area.

[1]
Our custom tool is a class that extends the StateNode class. See the ScreenshotTool
files for more about the too. We define an array (outside of any React component)
to hold the custom tools. We'll pass this into the Tldraw component's `tools` prop.

[2]
Here we make sure the UI knows about our new tool. We do this by adding it to the
`tools` object, which tells other parts of the UI a tool's label, icon, what should
happen when it's selected, etc. We'll pass our customUiOverrides object into the
Tldraw component's `overrides` prop.

[3]
Our toolbar item is using a custom icon, so we need to provide the asset url for it. 
We do this by providing a custom assetUrls object to the Tldraw component. 
This object is a map of icon ids to their urls. The icon ids are the same as the 
icon prop on the toolbar item. We'll pass our assetUrls object into the Tldraw
component's `assetUrls` prop.

[4]
We want to show a box on the canvas when the screenshot tool is active. We do this
by providing an override to the InFrontOfTheCanvas component. This component will be shown
in front of the canvas but behind any other UI elements, such as menus and the toolbar.
We'll pass our components object into the Tldraw component's `components` prop.

[5]
Finally we pass all of our customizations into the Tldraw component. It's important
that the customizations are defined outside of the React component, otherwise they
will cause the Tldraw component to see them as new values on every render, which may
produce unexpected results.
*/
```

## ScreenshotTool.ts

```ts
import { StateNode } from 'tldraw'
import { ScreenshotDragging } from './childStates/Dragging'
import { ScreenshotIdle } from './childStates/Idle'
import { ScreenshotPointing } from './childStates/Pointing'

// There's a guide at the bottom of this file!

export class ScreenshotTool extends StateNode {
	// [1]
	static override id = 'screenshot'
	static override initial = 'idle'
	static override children() {
		return [ScreenshotIdle, ScreenshotPointing, ScreenshotDragging]
	}

// [2]
	override onEnter() {
		this.editor.setCursor({ type: 'cross', rotation: 0 })
	}

override onExit() {
		this.editor.setCursor({ type: 'default', rotation: 0 })
	}

// [3]
	override onInterrupt() {
		this.complete()
	}

override onCancel() {
		this.complete()
	}

private complete() {
		this.parent.transition('select', {})
	}
}

/*
This file contains our screenshot tool. The tool is a StateNode with the `id` "screenshot".

[1]
It has three child state nodes, ScreenshotIdle, ScreenshotPointing, and ScreenshotDragging. 
Its initial state is `idle`.

[2]
When the screenshot tool is entered, we set the cursor to a crosshair. When it is exited, we
set the cursor back to the default cursor.

[3]
When the screenshot tool is interrupted or cancelled, we transition back to the select tool.
*/
```

## Dragging.ts

```ts
import { Box, StateNode, atom, copyAs, exportAs } from 'tldraw'

// There's a guide at the bottom of this file!

export class ScreenshotDragging extends StateNode {
	static override id = 'dragging'

// [1]
	screenshotBox = atom('screenshot brush', new Box())

// [2]
	override onEnter() {
		this.update()
	}

override onPointerMove() {
		this.update()
	}

override onKeyDown() {
		this.update()
	}

override onKeyUp() {
		this.update()
	}

private update() {
		const inputs = this.editor.inputs
		const shiftKey = inputs.getShiftKey()
		const altKey = inputs.getAltKey()
		const originPagePoint = inputs.getOriginPagePoint()
		const currentPagePoint = inputs.getCurrentPagePoint()

const box = Box.FromPoints([originPagePoint, currentPagePoint])

if (shiftKey) {
			if (box.w > box.h * (16 / 9)) {
				box.h = box.w * (9 / 16)
			} else {
				box.w = box.h * (16 / 9)
			}

if (currentPagePoint.x < originPagePoint.x) {
				box.x = originPagePoint.x - box.w
			}

if (currentPagePoint.y < originPagePoint.y) {
				box.y = originPagePoint.y - box.h
			}
		}

if (altKey) {
			box.w *= 2
			box.h *= 2
			box.x = originPagePoint.x - box.w / 2
			box.y = originPagePoint.y - box.h / 2
		}

this.screenshotBox.set(box)
	}

// [3]
	override onPointerUp() {
		const { editor } = this
		const box = this.screenshotBox.get()

// get all shapes contained by or intersecting the box
		const shapes = editor.getCurrentPageShapes().filter((s) => {
			const pageBounds = editor.getShapeMaskedPageBounds(s)
			if (!pageBounds) return false
			return box.includes(pageBounds)
		})

if (shapes.length) {
			if (editor.inputs.getCtrlKey()) {
				// Copy the shapes to the clipboard
				copyAs(
					editor,
					shapes.map((s) => s.id),
					{ format: 'png', bounds: box }
				)
			} else {
				// Export the shapes as a png
				exportAs(
					editor,
					shapes.map((s) => s.id),
					{
						format: 'png',
						name: 'Screenshot',
						bounds: box,
					}
				)
			}
		}

this.editor.setCurrentTool('select')
	}

// [4]
	override onCancel() {
		this.editor.setCurrentTool('select')
	}
}

/*
[1] 
This state has a reactive property (an Atom) called "screenshotBox". This is the box
that the user is drawing on the screen as they drag their pointer. We use an Atom here
so that our UI can subscribe to this property using `useValue` (see the ScreenshotBox
component in ScreenshotToolExample).

[2]
When the user enters this state, or when they move their pointer, we update the 
screenshotBox property to be drawn between the place where the user started pointing
and the place where their pointer is now. If the user is holding Shift, then we modify
the dimensions of this box so that it is in a 16:9 aspect ratio.

[3]
When the user makes a pointer up and stops dragging, we export the shapes contained by
the screenshot box as a png. If the user is holding the ctrl key, we copy the shapes
to the clipboard instead.

[4]
When the user cancels (esc key) or makes a pointer up event, we transition back to the
select tool.
*/
```

## Idle.ts

```ts
import { StateNode } from 'tldraw'

// There's a guide at the bottom of this file!

export class ScreenshotIdle extends StateNode {
	static override id = 'idle'

// [1]
	override onPointerDown() {
		this.parent.transition('pointing')
	}
}

/*
[1]
When we the user makes a pointer down event, we transition to the pointing state.
*/
```

## Pointing.ts

```ts
import { StateNode } from 'tldraw'

// There's a guide at the bottom of this file!

export class ScreenshotPointing extends StateNode {
	static override id = 'pointing'

// [1]
	override onPointerMove() {
		if (this.editor.inputs.getIsDragging()) {
			this.parent.transition('dragging')
		}
	}

// [2]
	override onPointerUp() {
		this.complete()
	}

override onCancel() {
		this.complete()
	}

private complete() {
		this.parent.transition('idle')
	}
}

/*
[1]
When the user makes a pointer move event, we check if they are dragging. If they are, 
we transition to the dragging state. If they are not yet dragging, we stay in this state.

[2]
When the user cancelles or makes a pointer up event (while this state is still active, 
so after the user has started pointing but before they've moved their pointer far enough 
to start dragging), then we transition back to the idle state.
*/
```

--------

# Cubic bezier curve shape

Category: Shapes & tools

Keywords: shape, util, handles, geometry, pen

A custom shape with interactive bezier curve editing.

This example demonstrates how to create a cubic bezier curve shape with draggable control handles. It includes a custom pen tool for entering edit mode and shows how to customize handle behavior and snapping.

The shape features four handles (start, end, and two control points) that can be dragged to adjust the curve. Control points snap to the start and end positions, and moving the endpoints automatically shifts their associated control points to maintain smooth editing.

## App.tsx

```tsx
import {
	createShapeId,
	StateNode,
	TLAnyShapeUtilConstructor,
	Tldraw,
	TLPointerEventInfo,
} from 'tldraw'
import { BezierCurveShapeUtil } from './CubicBezierShape'
import { CustomHandles } from './CustomHandles'
import { SneakyUndoRedoWhileEditing } from './SneakyUndoRedoWhileEditing'

const customShapes: TLAnyShapeUtilConstructor[] = [BezierCurveShapeUtil]

export default function BezierCurveShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// [9]
				components={{
					Handles: CustomHandles,
				}}
				shapeUtils={customShapes}
				onMount={(editor) => {
					editor.user.updateUserPreferences({ isSnapMode: true })

const viewportPageBounds = editor.getViewportPageBounds()
					const centerX = viewportPageBounds.center.x
					const centerY = viewportPageBounds.center.y

const id = createShapeId()
					editor.createShape({
						id,
						type: 'bezier-curve',
						x: centerX - 200,
						y: centerY - 150,
					})

// Select and edit the shape on appear
					editor.select(id)
					editor.setEditingShape(id)

// [10]
					// Get state nodes with proper type safety
					const pointingHandleState = editor.getStateDescendant<StateNode>('select.pointing_handle')
					const editingShapeState = editor.getStateDescendant<StateNode>('select.editing_shape')

if (!pointingHandleState) {
						throw new Error('SelectTool pointing_handle state not found')
					}
					if (!editingShapeState) {
						throw new Error('SelectTool editing_shape state not found')
					}

// store original handlers with proper binding
					const originalHandlers = {
						pointingHandle: {
							onPointerMove: pointingHandleState.onPointerMove?.bind(pointingHandleState),
							onPointerUp: pointingHandleState.onPointerUp?.bind(pointingHandleState),
						},
						editingShape: {
							onPointerDown: editingShapeState.onPointerDown?.bind(editingShapeState),
							onPointerMove: editingShapeState.onPointerMove?.bind(editingShapeState),
						},
					}

// clicking on start or end point should not go to select.idle
					pointingHandleState.onPointerUp = (info: TLPointerEventInfo & { target: 'handle' }) => {
						if (!info.shape) return

if (
							info.accelKey &&
							editor.isShapeOfType(info.shape, 'bezier-curve') &&
							info.target === 'handle'
						) {
							switch (info.handle.id) {
								case 'cp1': {
									editor.updateShape({
										id: info.shape.id,
										type: 'bezier-curve',
										props: {
											cp1: { x: info.shape.props.start.x, y: info.shape.props.start.y },
										},
									})

editor.setEditingShape(info.shape.id)
									return
								}
								case 'cp2': {
									editor.updateShape({
										id: info.shape.id,
										type: 'bezier-curve',
										props: {
											cp2: { x: info.shape.props.end.x, y: info.shape.props.end.y },
										},
									})

editor.setEditingShape(info.shape.id)
									return
								}
							}
						}

if (editor.isShapeOfType(info.shape, 'bezier-curve') && info.target === 'handle') {
							editor.setEditingShape(info.shape.id)
							return
						}

originalHandlers.pointingHandle.onPointerUp?.(info)
					}

// return to editing state after dragging a handle
					pointingHandleState.onPointerMove = (info: TLPointerEventInfo) => {
						if (!info.shape) return

if (editor.isShapeOfType(info.shape, 'bezier-curve')) {
							editor.updateInstanceState({ isToolLocked: true })
							editor.setCurrentTool('select.dragging_handle', {
								...info,
								onInteractionEnd: () => {
									editor.setEditingShape(info.shape.id)
								},
							})
							return
						}

originalHandlers.pointingHandle.onPointerMove?.(info)
					}

// allow translating in editing state
					editingShapeState.onPointerMove = (info: TLPointerEventInfo) => {
						if (editor.inputs.getIsDragging()) {
							const editingShape = editor.getEditingShape()
							if (editingShape && editor.isShapeOfType(editingShape, 'bezier-curve')) {
								editor.updateInstanceState({ isToolLocked: true })

editor.setCurrentTool('select.translating', {
									...info,
									target: 'shape',
									shape: editingShape,
									onInteractionEnd: () => {
										editor.setEditingShape(editingShape.id)
									},
								})
								return
							}
						}

originalHandlers.editingShape.onPointerMove?.(info)
					}
				}}
			>
				{/* 11 */}
				<SneakyUndoRedoWhileEditing />
			</Tldraw>
		</div>
	)
}

/*
Introduction:
This example demonstrates how to create a cubic bezier curve shape with interactive handles.

[9]
Use custom ControlHandles component to show handles for bezier curves when editing, translating, or
dragging handles.

[10]
Override state node methods to enable three custom interactions:
1. Meta + click on cp1/cp2 handles collapses them to their associated start/end points
2. After dragging any handle, stay in editing mode (instead of returning to select.idle)
3. Allow translating the curve while in editing mode by detecting drag and transitioning to select.translating

[11]
Add a sneaky undo/redo while editing. This is a hack to allow undo/redo while editing a shape.
It's not a perfect solution, but it's a workaround for the fact that tldraw doesn't support
undo/redo while editing a shape. Sometimes you gotta hack it.

These overrides maintain the editing context, allowing fluid adjustments without losing handle visibility.
*/
```

## CubicBezierShape.tsx

```tsx
import {
	BoundsSnapGeometry,
	CubicBezier2d,
	Geometry2d,
	getIndicesAbove,
	HandleSnapGeometry,
	HTMLContainer,
	RecordProps,
	ShapeUtil,
	TLHandle,
	TLHandleDragInfo,
	TLResizeInfo,
	TLShape,
	Vec,
	VecLike,
	vecModelValidator,
	ZERO_INDEX_KEY,
} from 'tldraw'

const BEZIER_CURVE_TYPE = 'bezier-curve'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[BEZIER_CURVE_TYPE]: { start: VecLike; cp1: VecLike; cp2: VecLike; end: VecLike }
	}
}

// [2]
export type MyBezierCurveShape = TLShape<typeof BEZIER_CURVE_TYPE>

// [3]
export class BezierCurveShapeUtil extends ShapeUtil<MyBezierCurveShape> {
	static override type = BEZIER_CURVE_TYPE
	static override props: RecordProps<MyBezierCurveShape> = {
		start: vecModelValidator,
		cp1: vecModelValidator,
		cp2: vecModelValidator,
		end: vecModelValidator,
	}

private isMetaKeyOnTranslateStart = false
	private didHitCurveOnTranslateStart = false

override getDefaultProps(): MyBezierCurveShape['props'] {
		return {
			start: { x: 0, y: 0 },
			cp1: { x: 0, y: 140 },
			cp2: { x: 350, y: 300 },
			end: { x: 400, y: 110 },
		}
	}

override canEdit(): boolean {
		return true
	}

// [4]
	getGeometry(shape: MyBezierCurveShape): Geometry2d {
		return new CubicBezier2d({
			start: new Vec(shape.props.start.x, shape.props.start.y),
			cp1: new Vec(shape.props.cp1.x, shape.props.cp1.y),
			cp2: new Vec(shape.props.cp2.x, shape.props.cp2.y),
			end: new Vec(shape.props.end.x, shape.props.end.y),
		})
	}

override hideSelectionBoundsBg(shape: MyBezierCurveShape): boolean {
		return this.editor.getEditingShapeId() === shape.id
	}

override hideSelectionBoundsFg(shape: MyBezierCurveShape): boolean {
		return this.editor.getEditingShapeId() === shape.id
	}

override hideResizeHandles(shape: MyBezierCurveShape): boolean {
		return this.editor.getEditingShapeId() === shape.id
	}

override onResize(shape: MyBezierCurveShape, info: TLResizeInfo<MyBezierCurveShape>) {
		const { scaleX, scaleY } = info
		return {
			props: {
				start: { x: shape.props.start.x * scaleX, y: shape.props.start.y * scaleY },
				cp1: { x: shape.props.cp1.x * scaleX, y: shape.props.cp1.y * scaleY },
				cp2: { x: shape.props.cp2.x * scaleX, y: shape.props.cp2.y * scaleY },
				end: { x: shape.props.end.x * scaleX, y: shape.props.end.y * scaleY },
			},
		}
	}

override getBoundsSnapGeometry(shape: MyBezierCurveShape): BoundsSnapGeometry {
		return {
			points: [shape.props.start, shape.props.end],
		}
	}

override toSvg(shape: MyBezierCurveShape) {
		const path = this.getGeometry(shape).getSvgPathData(true)
		return <path d={path} stroke="black" fill="transparent" strokeWidth={2} />
	}

// [5]
	override getHandles(shape: MyBezierCurveShape): TLHandle[] {
		const indices = [ZERO_INDEX_KEY, ...getIndicesAbove(ZERO_INDEX_KEY, 3)]

let handles: TLHandle[] = [
			{
				id: 'start',
				type: 'vertex',
				x: shape.props.start.x,
				y: shape.props.start.y,
				index: indices[0],
				snapType: 'align',
			},
			{
				id: 'cp1',
				type: 'vertex',
				x: shape.props.cp1.x,
				y: shape.props.cp1.y,
				index: indices[1],
				snapType: 'align',
				snapReferenceHandleId: 'start',
			},
			{
				id: 'cp2',
				type: 'vertex',
				x: shape.props.cp2.x,
				y: shape.props.cp2.y,
				index: indices[2],
				snapType: 'align',
			},
			{
				id: 'end',
				type: 'vertex',
				x: shape.props.end.x,
				y: shape.props.end.y,
				index: indices[3],
				snapType: 'align',
			},
		]

if (Vec.Equals(shape.props.cp1, shape.props.start)) {
			handles = handles.filter((handle) => handle.id !== 'cp1')
		}

if (Vec.Equals(shape.props.cp2, shape.props.end)) {
			handles = handles.filter((handle) => handle.id !== 'cp2')
		}

return handles
	}

// [6]
	override getHandleSnapGeometry(shape: MyBezierCurveShape): HandleSnapGeometry {
		return {
			points: [shape.props.start, shape.props.end],
			getSelfSnapPoints: (handle) => {
				if (handle.id === 'cp1' || handle.id === 'cp2') {
					return [shape.props.start, shape.props.end]
				}

return handle.id === 'end' ? [shape.props.start] : [shape.props.end]
			},
		}
	}

// [7]
	override onHandleDrag(shape: MyBezierCurveShape, info: TLHandleDragInfo<MyBezierCurveShape>) {
		const { handle } = info
		const { id, x, y } = handle

let props = {}
		let newProps: any = {}

// if you hold command or control key whilst dragging over a start or end handle,
		// move the associated control point to the new positions
		if (this.editor.inputs.getMetaKey()) {
			switch (id) {
				case 'start': {
					return {
						...shape,
						props: {
							...shape.props,
							cp1: { x, y },
						},
					}
				}
				case 'end': {
					return {
						...shape,
						props: {
							...shape.props,
							cp2: { x, y },
						},
					}
				}
			}
		}

// move the handles
		switch (id) {
			case 'start': {
				const delta = Vec.Sub(handle, shape.props.start)

newProps = {
					start: { x, y },
					cp1: { x: shape.props.cp1.x + delta.x, y: shape.props.cp1.y + delta.y },
				}
				break
			}
			case 'end': {
				const delta = Vec.Sub(handle, shape.props.end)

newProps = {
					end: { x, y },
					cp2: { x: shape.props.cp2.x + delta.x, y: shape.props.cp2.y + delta.y },
				}
				break
			}
			default: {
				newProps = {
					[id]: { x, y },
				}
				break
			}
		}

props = {
			...shape.props,
			...newProps,
		}

return {
			...shape,
			props,
		}
	}

// [8]
	override onTranslateStart(shape: MyBezierCurveShape) {
		// only bend if we start translating with the command or control key pressed
		// this avoids bending the curve midway through a translation where the user accidentally
		// holds the command or control key
		this.isMetaKeyOnTranslateStart = this.editor.inputs.getMetaKey()

// we should bend the curve if we hit the curve but not the start or end handles,
		const handles = this.getHandles(shape)
		const startAndEndHandles = handles.filter(
			(handle) => handle.id === 'start' || handle.id === 'end'
		)
		if (!startAndEndHandles.length) return

const hitStartOrEndHandle = startAndEndHandles.some((handle) => {
			const threshold = 8 / this.editor.getZoomLevel()
			const pageTransform = this.editor.getShapePageTransform(shape)
			const handleInPageSpace = pageTransform.applyToPoint(handle)

if (Vec.Dist(handleInPageSpace, this.editor.inputs.getCurrentPagePoint()) < threshold) {
				return true
			}
			return false
		})

const hitCurve = this.editor.isPointInShape(shape, this.editor.inputs.getCurrentPagePoint(), {
			margin: 10 / this.editor.getZoomLevel(),
		})

this.didHitCurveOnTranslateStart = hitCurve && !hitStartOrEndHandle
	}

override onTranslate(initial: MyBezierCurveShape, current: MyBezierCurveShape) {
		// bend the curve
		if (this.isMetaKeyOnTranslateStart && this.didHitCurveOnTranslateStart) {
			const delta = Vec.Sub(current, initial)
			const offsetX = Math.round(delta.x)
			const offsetY = Math.round(delta.y)

return {
				...initial,
				props: {
					...initial.props,
					cp1: { x: initial.props.cp1.x + offsetX, y: initial.props.cp1.y + offsetY },
					cp2: { x: initial.props.cp2.x + offsetX, y: initial.props.cp2.y + offsetY },
				},
			}
		}

return
	}

// [9]
	component(shape: MyBezierCurveShape) {
		const path = this.getGeometry(shape).getSvgPathData(true)
		const { start, end, cp1, cp2 } = shape.props

const zoomLevel = this.editor.getZoomLevel()

return (
			<HTMLContainer>
				<svg className="tl-svg-container">
					<path d={path} stroke="black" fill="transparent" />
					<>
						{this.shouldShowControlLines(shape) && (
							<>
								<line
									x1={start.x}
									y1={start.y}
									x2={cp1.x}
									y2={cp1.y}
									stroke="black"
									strokeWidth={1 / zoomLevel}
									strokeDasharray={`${6 / zoomLevel} ${6 / zoomLevel}`}
									opacity={0.5}
								/>
								<line
									x1={end.x}
									y1={end.y}
									x2={cp2.x}
									y2={cp2.y}
									stroke="black"
									strokeWidth={1 / zoomLevel}
									strokeDasharray={`${6 / zoomLevel} ${6 / zoomLevel}`}
									opacity={0.5}
								/>
							</>
						)}
					</>
				</svg>
			</HTMLContainer>
		)
	}

indicator(shape: MyBezierCurveShape) {
		const path = this.getGeometry(shape).getSvgPathData(true)
		return <path d={path} />
	}

private shouldShowControlLines(shape: MyBezierCurveShape) {
		const selectedShape = this.editor.getOnlySelectedShape() === shape
		if (!selectedShape) return false

return this.editor.isInAny(
			'select.editing_shape',
			'select.pointing_handle',
			'select.dragging_handle'
		)
	}
}

/*
This is our custom cubic bezier curve shape. A cubic bezier curve is defined by four points: start, end, and two control points (cp1, cp2).

[1]
First, we need to extend TLGlobalShapePropsMap to add our shape's props to the global type system.
This tells TypeScript about the shape's properties. For this shape, we define four points (start, cp1, cp2, end)
that define the curve.

[2]
Define the shape type using TLShape with the shape's type as a type argument.

[3]
The BezierCurveShapeUtil extends ShapeUtil to define all behavior for our custom shape. We specify
the static 'type' and 'props' with validators.

[4]
The getGeometry method returns a CubicBezier2d geometry used for hit-testing, bounds calculations,
and rendering.

[5]
Define four interactive handles: start, end, cp1, and cp2. Each has an id, type, position, and index.
Control point handles are hidden when they're at the same position as their associated endpoints (collapsed).

[6]
Custom handle snapping via getHandleSnapGeometry: control points (cp1, cp2) can snap to start/end points.
The snap system automatically handles screen-space thresholds (consistent across zoom levels) and visual
snap indicators. When a control point is snapped to an endpoint, it effectively "collapses" the curve at
that end, creating a sharp corner.

[7]
Handle drag behaviors:
- Meta key + drag start/end handles repositions the associated control point (cp1 or cp2)
- Dragging start/end handles moves the associated control point to maintain curve shape
- Dragging cp1/cp2 directly moves only that control point

[8]
Translation with curve bending: Hold meta key while dragging the curve (not handles) to bend it
by moving both control points together. This is detected on translate start to avoid accidental bending.

[9]
Visual feedback: Display dashed lines from start→cp1 and end→cp2 when the shape is selected
and actively being edited or translated.
*/
```

## CustomHandles.tsx

```tsx
import { TLHandlesProps, useEditor, useValue } from 'tldraw'

export function CustomHandles({ children }: TLHandlesProps) {
	const editor = useEditor()

const shouldDisplayDefaultHandles = useValue(
		'shouldDisplayDefaultHandles',
		() => {
			// bezier curve handles
			const onlySelectedShape = editor.getOnlySelectedShape()
			if (onlySelectedShape && editor.isShapeOfType(onlySelectedShape, 'bezier-curve')) {
				return editor.isInAny(
					'select.editing_shape',
					'select.pointing_handle',
					'select.dragging_handle'
				)
			}

// default handle behavior
			if (editor.isInAny('select.idle', 'select.pointing_handle', 'select.pointing_shape')) {
				return true
			}
			if (editor.isInAny('select.editing_shape')) {
				const onlySelectedShape = editor.getOnlySelectedShape()
				if (!onlySelectedShape) return false
				return onlySelectedShape && editor.isShapeOfType(onlySelectedShape, 'note')
			}
			return false
		},
		[editor]
	)

if (!shouldDisplayDefaultHandles) return null

return (
		<svg className="tl-user-handles tl-overlays__item" aria-hidden="true">
			{children}
		</svg>
	)
}
```

## SneakyUndoRedoWhileEditing.tsx

```tsx
import { useEffect } from 'react'
import { useEditor } from 'tldraw'

export function SneakyUndoRedoWhileEditing() {
	const editor = useEditor()

useEffect(() => {
		function handleKeydown(e: KeyboardEvent) {
			if (e.key === 'z' && (e.metaKey || e.ctrlKey)) {
				const editingShape = editor.getEditingShape()
				if (!editingShape) return

if (e.shiftKey) {
					editor.redo()
					editor.setEditingShape(editingShape)
				} else {
					editor.undo()
					editor.setEditingShape(editingShape)
				}
			}
		}

window.addEventListener('keydown', handleKeydown)
		return () => {
			window.removeEventListener('keydown', handleKeydown)
		}
	}, [editor])

return null
}
```

--------

# Custom shape and tool

Category: Shapes & tools

Keywords: toolbar, migrations, icon, util, ui overrides, card shape

A custom shape and tool.

This example shows how to define a custom shape, as well as a custom tool that can be used to create that shape.

In this case, the card tool (select ⚫️ in the toolbar) can be used to create a card shape.

## App.tsx

```tsx
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { CardShapeTool } from './CardShape/CardShapeTool'
import { CardShapeUtil } from './CardShape/CardShapeUtil'
import { components, uiOverrides } from './ui-overrides'

// There's a guide at the bottom of this file!

// [1]
const customShapeUtils = [CardShapeUtil]
const customTools = [CardShapeTool]

// [2]
export default function CustomConfigExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// Pass in the array of custom shape classes
				shapeUtils={customShapeUtils}
				// Pass in the array of custom tool classes
				tools={customTools}
				// Pass in any overrides to the user interface
				overrides={uiOverrides}
				// Pass in the new Keybaord Shortcuts component
				components={components}
			/>
		</div>
	)
}

/* 
Introduction:

This example shows how to create a custom shape, and add your own icon for it to the toolbar.
Check out CardShapeUtil.tsx and CardShapeTool.tsx to see how we define the shape util and tool. 
Check out ui-overrides.ts for more info on how to add your icon to the toolbar.

[1] 
We define an array to hold the custom shape util and custom tool. It's important to do this outside of
any React component so that this array doesn't get redefined on every render.

[2]
Now we'll pass these arrays into the Tldraw component's props, along with our ui overrides.

*/
```

## ui-overrides.tsx

// There's a guide at the bottom of this file!

export const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		// Create a tool item in the ui's context.
		tools.card = {
			id: 'card',
			icon: 'color',
			label: 'Card',
			kbd: 'c',
			onSelect: () => {
				editor.setCurrentTool('card')
			},
		}
		return tools
	},
}

export const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isCardSelected = useIsToolSelected(tools['card'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['card']} isSelected={isCardSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	KeyboardShortcutsDialog: (props) => {
		const tools = useTools()
		return (
			<DefaultKeyboardShortcutsDialog {...props}>
				<TldrawUiMenuItem {...tools['card']} />
				<DefaultKeyboardShortcutsDialogContent />
			</DefaultKeyboardShortcutsDialog>
		)
	},
}

This file contains overrides for the Tldraw UI. These overrides are used to add your custom tools to
the toolbar and the keyboard shortcuts menu.

First we have to add our new tool to the tools object in the tools override. This is where we define
all the basic information about our new tool - its icon, label, keyboard shortcut, what happens when
we select it, etc.

Then, we replace the UI components for the toolbar and keyboard shortcut dialog with our own, that
add our new tool to the existing default content. Ideally, we'd interleave our new tool into the
ideal place among the default tools, but for now we're just adding it at the start to keep things
simple.
*/
```

## CardShapeTool.tsx

```tsx
import { BaseBoxShapeTool, TLClickEventInfo } from 'tldraw'
export class CardShapeTool extends BaseBoxShapeTool {
	static override id = 'card'
	static override initial = 'idle'
	override shapeType = 'card' as const

override onDoubleClick(_info: TLClickEventInfo) {
		// you can handle events in handlers like this one;
		// check the BaseBoxShapeTool source as an example
	}
}

/*
This file contains our custom tool. The tool is a StateNode with the `id` "card".

We get a lot of functionality for free by extending the BaseBoxShapeTool. but we can
handle events in out own way by overriding methods like onDoubleClick. For an example
of a tool with more custom functionality, check out the screenshot-tool example.

*/
```

## CardShapeUtil.tsx

```tsx
import { useState } from 'react'
import {
	HTMLContainer,
	Rectangle2d,
	ShapeUtil,
	TLDefaultColorStyle,
	TLResizeInfo,
	TLShape,
	getColorValue,
	getDefaultColorTheme,
	resizeBox,
} from 'tldraw'
import { cardShapeMigrations } from './card-shape-migrations'
import { cardShapeProps } from './card-shape-props'

const CARD_TYPE = 'card'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[CARD_TYPE]: { w: number; h: number; color: TLDefaultColorStyle }
	}
}

// A type for our custom card shape
export type ICardShape = TLShape<typeof CARD_TYPE>

// There's a guide at the bottom of this file!

export class CardShapeUtil extends ShapeUtil<ICardShape> {
	static override type = CARD_TYPE
	// [1]
	static override props = cardShapeProps
	// [2]
	static override migrations = cardShapeMigrations

// [3]
	override isAspectRatioLocked(_shape: ICardShape) {
		return false
	}
	override canResize(_shape: ICardShape) {
		return true
	}

// [4]
	getDefaultProps(): ICardShape['props'] {
		return {
			w: 300,
			h: 300,
			color: 'black',
		}
	}

// [5]
	getGeometry(shape: ICardShape) {
		return new Rectangle2d({
			width: shape.props.w,
			height: shape.props.h,
			isFilled: true,
		})
	}

// [6]
	component(shape: ICardShape) {
		const bounds = this.editor.getShapeGeometry(shape).bounds
		const theme = getDefaultColorTheme({ isDarkMode: this.editor.user.getIsDarkMode() })

//[a]
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const [count, setCount] = useState(0)

return (
			<HTMLContainer
				id={shape.id}
				style={{
					border: '1px solid black',
					display: 'flex',
					flexDirection: 'column',
					alignItems: 'center',
					justifyContent: 'center',
					pointerEvents: 'all',
					backgroundColor: getColorValue(theme, shape.props.color, 'semi'),
					color: getColorValue(theme, shape.props.color, 'solid'),
				}}
			>
				<h2>Clicks: {count}</h2>
				<button
					// [b]
					onClick={() => setCount((count) => count + 1)}
					onPointerDown={(e) => e.stopPropagation()}
				>
					{bounds.w.toFixed()}x{bounds.h.toFixed()}
				</button>
			</HTMLContainer>
		)
	}

// [7]
	indicator(shape: ICardShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}

// [8]
	override onResize(shape: ICardShape, info: TLResizeInfo<ICardShape>) {
		return resizeBox(shape, info)
	}
}
/*
A utility class for the card shape. This is where you define the shape's behavior,
how it renders (its component and indicator), and how it handles different events.

[1]
A validation schema for the shape's props (optional)
Check out card-shape-props.ts for more info.

[2]
Migrations for upgrading shapes (optional)
Check out card-shape-migrations.ts for more info.

[3]
Letting the editor know if the shape's aspect ratio is locked, and whether it
can be resized or bound to other shapes.

[4]
The default props the shape will be rendered with when click-creating one.

[5]
We use this to calculate the shape's geometry for hit-testing, bindings and
doing other geometric calculations.

[6]
Render method — the React component that will be rendered for the shape. It takes the
shape as an argument. HTMLContainer is just a div that's being used to wrap our text
and button. We can get the shape's bounds using our own getGeometry method.

- [a] Check it out! We can do normal React stuff here like using setState.
   Annoying: eslint sometimes thinks this is a class component, but it's not.

- [b] You need to stop the pointer down event on buttons, otherwise the editor will
	   think you're trying to select drag the shape.

[7]
Indicator — used when hovering over a shape or when it's selected; must return only SVG elements here

[8]
Resize handler — called when the shape is resized. Sometimes you'll want to do some
custom logic here, but for our purposes, this is fine.
*/
```

## card-shape-migrations.ts

```ts
import { createShapePropsMigrationIds, createShapePropsMigrationSequence } from 'tldraw'

const versions = createShapePropsMigrationIds(
	// this must match the shape type in the shape definition
	'card',
	{
		AddSomeProperty: 1,
	}
)

// Migrations for the custom card shape (optional but very helpful)
export const cardShapeMigrations = createShapePropsMigrationSequence({
	sequence: [
		{
			id: versions.AddSomeProperty,
			up(props) {
				// it is safe to mutate the props object here
				props.someProperty = 'some value'
			},
			down(props) {
				delete props.someProperty
			},
		},
	],
})
```

## card-shape-props.ts

```ts
import { DefaultColorStyle, RecordProps, T } from 'tldraw'
import { ICardShape } from './CardShapeUtil'

// Validation for our custom card shape's props, using one of tldraw's default styles
export const cardShapeProps: RecordProps<ICardShape> = {
	w: T.number,
	h: T.number,
	color: DefaultColorStyle,
}

// To generate your own custom styles, check out the custom styles example.
```

--------

# Custom shape with custom styles

Category: Shapes & tools

Keywords: style panel, rating

Use the custom styles API with your custom shapes.

This example shows how to create your own styles and use them in your own shapes.

To use tldraw's existing styles with your shapes, check the [tldraw styles example](https://tldraw.dev/examples/shape-with-tldraw-styles).

## App.tsx

```tsx
import {
	BaseBoxShapeUtil,
	DefaultStylePanel,
	DefaultStylePanelContent,
	HTMLContainer,
	StyleProp,
	T,
	Tldraw,
	TLShape,
	useEditor,
	useRelevantStyles,
} from 'tldraw'
import 'tldraw/tldraw.css'

const MY_SHAPE_WITH_CUSTOM_STYLES_TYPE = 'myshapewithcustomstyles'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_SHAPE_WITH_CUSTOM_STYLES_TYPE]: {
			w: number
			h: number
			rating: MyRatingStyle
		}
	}
}

// [1]
const myRatingStyle = StyleProp.defineEnum('example:rating', {
	defaultValue: 1,
	values: [1, 2, 3, 4, 5],
})

// [2]
type MyRatingStyle = T.TypeOf<typeof myRatingStyle>

type IMyShape = TLShape<typeof MY_SHAPE_WITH_CUSTOM_STYLES_TYPE>

class MyShapeUtil extends BaseBoxShapeUtil<IMyShape> {
	static override type = MY_SHAPE_WITH_CUSTOM_STYLES_TYPE

// [3]
	static override props = {
		w: T.number,
		h: T.number,
		rating: myRatingStyle,
	}

getDefaultProps(): IMyShape['props'] {
		return {
			w: 300,
			h: 300,
			rating: 4, // [4]
		}
	}

component(shape: IMyShape) {
		// [5]
		const stars = ['☆', '☆', '☆', '☆', '☆']
		for (let i = 0; i < shape.props.rating; i++) {
			stars[i] = '★'
		}

return (
			<HTMLContainer
				id={shape.id}
				style={{ backgroundColor: 'var(--tl-color-low-border)', overflow: 'hidden' }}
			>
				{stars}
			</HTMLContainer>
		)
	}

indicator(shape: IMyShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

// [6]
function CustomStylePanel() {
	const editor = useEditor()
	const styles = useRelevantStyles()
	if (!styles) return null

const rating = styles.get(myRatingStyle)

return (
		<DefaultStylePanel>
			<DefaultStylePanelContent />
			{rating !== undefined && (
				<div>
					<select
						style={{ width: '100%', padding: 4 }}
						value={rating.type === 'mixed' ? '' : rating.value}
						onChange={(e) => {
							editor.markHistoryStoppingPoint()
							const value = myRatingStyle.validate(+e.currentTarget.value)
							editor.setStyleForSelectedShapes(myRatingStyle, value)
						}}
					>
						{rating.type === 'mixed' ? <option value="">Mixed</option> : null}
						<option value={1}>1</option>
						<option value={2}>2</option>
						<option value={3}>3</option>
						<option value={4}>4</option>
						<option value={5}>5</option>
					</select>
				</div>
			)}
		</DefaultStylePanel>
	)
}

export default function ShapeWithTldrawStylesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// [7]
				shapeUtils={[MyShapeUtil]}
				components={{
					StylePanel: CustomStylePanel,
				}}
				onMount={(editor) => {
					editor.createShape({ type: 'myshapewithcustomstyles', x: 100, y: 100 })
					editor.selectAll()
					editor.createShape({
						type: 'myshapewithcustomstyles',
						x: 450,
						y: 250,
						props: { rating: 5 },
					})
				}}
			/>
		</div>
	)
}

This file shows a custom shape that uses a user-created styles

For more on custom shapes, see our Custom Shape example.

[1]
In this example, our custom shape will use a new style called "rating".
We'll need to create the style so that we can pass it to the shape's props.

[2]
Here's we extract the type of the style's values. We use it below when
we define the shape's props.

[3]
We pass the style to the shape's props.

[4]
Since this property uses one a style, whatever value we put here in the
shape's default props will be overwritten by the editor's current value
for that style, which will either be the default value or the most
recent value the user has set. This is special behavior just for styles.

[5]
We can use the styles in the component just like any other prop.

[6]
Here we create a custom style panel that includes the default style panel
and also a dropdown for the rating style. We use the useRelevantStyles hook
to get the styles of the user's selected shapes, and the useEditor hook to
set the style for the selected shapes. For more on customizing the style
panel, see our custom style panel example.

[7]
We pass the custom shape util and custom components in as props.

[8]
And for this example, we create two shapes: the first does not specify a
rating, so it will use the editor's current style value (in this example,
this will be the style's default value of 4). The second specifies a
rating of 5, so it will use that value.
*/
```

--------

# Custom shape with tldraw styles

Category: Shapes & tools

Keywords: default styles, style panel

Use the tldraw style panel with your custom shapes.

The default tldraw UI will display UI for the styles of your selection or your current tool. For example, when you have two shapes selected that both have the tldraw's "size" style, the size selector will be displayed. If all of your selected shapes have the same value for this style, that value will be shown as selected in the panel. If they have different values, the panel will show the value as "mixed".

You can use tldraw's default styles in your own shapes. This example shows how to do that.

To create your own custom styles, check the [custom styles example](https://tldraw.dev/examples/shape-with-custom-styles).

## App.tsx

```tsx
import {
	BaseBoxShapeUtil,
	DefaultColorStyle,
	DefaultSizeStyle,
	getColorValue,
	HTMLContainer,
	T,
	TLDefaultColorStyle,
	TLDefaultSizeStyle,
	Tldraw,
	TLShape,
	useDefaultColorTheme,
} from 'tldraw'
import 'tldraw/tldraw.css'

const MY_SHAPE_WITH_TLDRAW_STYLES_TYPE = 'myshapewithtldrawstyles' as const

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_SHAPE_WITH_TLDRAW_STYLES_TYPE]: {
			w: number
			h: number
			size: TLDefaultSizeStyle
			color: TLDefaultColorStyle
		}
	}
}

// There's a guide at the bottom of this file!

const FONT_SIZES: Record<TLDefaultSizeStyle, number> = {
	s: 14,
	m: 25,
	l: 38,
	xl: 48,
}

type IMyShape = TLShape<typeof MY_SHAPE_WITH_TLDRAW_STYLES_TYPE>

class MyShapeUtil extends BaseBoxShapeUtil<IMyShape> {
	static override type = MY_SHAPE_WITH_TLDRAW_STYLES_TYPE

// [2]
	static override props = {
		w: T.number,
		h: T.number,
		size: DefaultSizeStyle,
		color: DefaultColorStyle,
	}

getDefaultProps(): IMyShape['props'] {
		return {
			w: 300,
			h: 300,
			size: 'm',
			color: 'black',
		}
	}

component(shape: IMyShape) {
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const theme = useDefaultColorTheme()

return (
			<HTMLContainer
				id={shape.id}
				style={{ backgroundColor: 'var(--tl-color-low-border)', overflow: 'hidden' }}
			>
				<div
					style={{
						// [3]
						fontSize: FONT_SIZES[shape.props.size],
						color: getColorValue(theme, shape.props.color, 'solid'),
					}}
				>
					Select the shape and use the style panel to change the font size and color
				</div>
			</HTMLContainer>
		)
	}

indicator(shape: IMyShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

const customShapeUtils = [MyShapeUtil]

export default function ShapeWithTldrawStylesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				onMount={(editor) => {
					editor.createShape({ type: 'myshapewithtldrawstyles', x: 100, y: 100 })
				}}
			/>
		</div>
	)
}

This file shows a custom shape that uses tldraw's default styles.
For more on custom shapes, see our Custom Shape example.

[1]
In this example, our custom shape will use the size and color styles from the
default styles. When typing a custom shape, you can use our types for
these styles.

[2]
For the shape's props, we'll pass the DefaultSizeStyle and DefaultColorStyle
styles for the two properties, size and color. There's nothing special about
these styles except that the editor will notice when two shapes are selected
that share the same style. (You can use the useRelevantStyles hook to get the
styles of the user's selected shapes.)

[3]
Here in the component, we'll use the styles to change the way that our shape
appears. The style values themselves are just strings, like 'xl' or 'black',
so it's up to you to decide how to use them. In this example, we're using the
size to set the text's font-size property, and also using the default theme
(via the useDefaultColorTheme hook) to get the color for the text.
*/
```

--------

# Clickable custom shape

Category: Shapes & tools

Keywords: interaction, pointer events, stop propagation, click, input

A custom shape that has its own onClick interactions.

By default the editor handles pointer events, but sometimes you want to handle interactions on your shape in your own ways, for example via a button. You can do this by using the css property `pointer events: all` and stopping event propagation. In this example we want our todo shape to have a checkbox so the user can mark them as done.

Check out my-interactive-shape-util.tsx to see how we create the shape.

## App.tsx

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

import { myInteractiveShape } from './my-interactive-shape-util'

// There's a guide at the bottom of this file!

// [1]
const customShapeUtils = [myInteractiveShape]

// [2]
export default function InteractiveShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				onMount={(editor) => {
					editor.createShape({ type: 'my-interactive-shape', x: 100, y: 100 })
				}}
			/>
		</div>
	)
}

/*
[1]
By default the editor handles pointer events, but sometimes you want to handle 
interactions on your shape in your own ways, for example via a button. You can do this 
by using the css property `pointer events: all` and stopping event propagation. In 
this example we want our todo shape to have a checkbox so the user can mark them as 
done.

[2]
Check out my-interactive-shape-util.tsx to see how we create the shape. 
 */
```

## my-interactive-shape-util.tsx

```tsx
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape } from 'tldraw'

// There's a guide at the bottom of this file!

const MY_INTERACTIVE_SHAPE_TYPE = 'my-interactive-shape'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_INTERACTIVE_SHAPE_TYPE]: { w: number; h: number; checked: boolean; text: string }
	}
}

export type IMyInteractiveShape = TLShape<typeof MY_INTERACTIVE_SHAPE_TYPE>

export class myInteractiveShape extends BaseBoxShapeUtil<IMyInteractiveShape> {
	static override type = MY_INTERACTIVE_SHAPE_TYPE
	static override props: RecordProps<IMyInteractiveShape> = {
		w: T.number,
		h: T.number,
		checked: T.boolean,
		text: T.string,
	}

getDefaultProps(): IMyInteractiveShape['props'] {
		return {
			w: 230,
			h: 230,
			checked: false,
			text: '',
		}
	}

// [1]
	component(shape: IMyInteractiveShape) {
		return (
			<HTMLContainer
				style={{
					padding: 16,
					height: shape.props.h,
					width: shape.props.w,
					// [a] This is where we allow pointer events on our shape
					pointerEvents: 'all',
					backgroundColor: '#efefef',
					overflow: 'hidden',
				}}
			>
				<input
					type="checkbox"
					checked={shape.props.checked}
					onChange={() =>
						this.editor.updateShape({
							id: shape.id,
							type: MY_INTERACTIVE_SHAPE_TYPE,
							props: { checked: !shape.props.checked },
						})
					}
					// [b] This is where we stop event propagation
					onPointerDown={(e) => e.stopPropagation()}
					onTouchStart={(e) => e.stopPropagation()}
					onTouchEnd={(e) => e.stopPropagation()}
				/>
				<input
					type="text"
					placeholder="Enter a todo..."
					readOnly={shape.props.checked}
					value={shape.props.text}
					onChange={(e) =>
						this.editor.updateShape({
							id: shape.id,
							type: MY_INTERACTIVE_SHAPE_TYPE,
							props: { text: e.currentTarget.value },
						})
					}
					// [c]
					onPointerDown={(e) => {
						if (!shape.props.checked) {
							e.stopPropagation()
						}
					}}
					onTouchStart={(e) => {
						if (!shape.props.checked) {
							e.stopPropagation()
						}
					}}
					onTouchEnd={(e) => {
						if (!shape.props.checked) {
							e.stopPropagation()
						}
					}}
				/>
			</HTMLContainer>
		)
	}

// [5]
	indicator(shape: IMyInteractiveShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

/*
This is a custom shape, for a more in-depth look at how to create a custom shape,
see our custom shape example.

[1]
This is where we describe how our shape will render

[a] We need to set pointer-events to all so that we can interact with our shape. This CSS property is
	set to "none" off by default. We need to manually opt-in to accepting pointer events by setting it to
	'all' or 'auto'.

[b] We need to stop event propagation so that the editor doesn't select the shape
		when we click on the checkbox. The 'canvas container' forwards events that it receives
		on to the editor, so stopping propagation here prevents the event from reaching the canvas.

[c] If the shape is not checked, we stop event propagation so that the editor doesn't
		select the shape when we click on the input. If the shape is checked then we allow that event to
		propagate to the canvas and then get sent to the editor, triggering clicks or drags as usual.

*/
```

--------

# Custom handle snap reference

Category: Shapes & tools

Keywords: handles, snapping, snap reference

An example demonstrating `snapReferenceHandleId` for control point angle snapping.

This example shows how to use the `snapReferenceHandleId` property to control which handle serves as the reference point for shift-modifier angle snapping.

## App.tsx

```tsx
import {
	Edge2d,
	Geometry2d,
	Group2d,
	HTMLContainer,
	RecordProps,
	ShapeUtil,
	TLHandle,
	TLHandleDragInfo,
	TLShape,
	Tldraw,
	Vec,
	VecLike,
	ZERO_INDEX_KEY,
	getIndicesAbove,
	vecModelValidator,
} from 'tldraw'
import 'tldraw/tldraw.css'

const Y_SHAPE_TYPE = 'y-shape'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[Y_SHAPE_TYPE]: {
			center: VecLike
			armTop: VecLike
			armLeft: VecLike
			armRight: VecLike
		}
	}
}

// [2]
type YShape = TLShape<typeof Y_SHAPE_TYPE>

// [3]
class YShapeUtil extends ShapeUtil<YShape> {
	static override type = Y_SHAPE_TYPE
	static override props: RecordProps<YShape> = {
		center: vecModelValidator,
		armTop: vecModelValidator,
		armLeft: vecModelValidator,
		armRight: vecModelValidator,
	}

override getDefaultProps(): YShape['props'] {
		return {
			center: { x: 100, y: 100 },
			armTop: { x: 100, y: 180 },
			armLeft: { x: 30, y: 20 },
			armRight: { x: 170, y: 20 },
		}
	}

override canEdit(): boolean {
		return true
	}

override hideSelectionBoundsBg(): boolean {
		return true
	}

override hideSelectionBoundsFg(): boolean {
		return true
	}

override hideResizeHandles(): boolean {
		return true
	}

override hideRotateHandle(): boolean {
		return true
	}

// [4]
	getGeometry(shape: YShape): Geometry2d {
		const { center, armTop, armLeft, armRight } = shape.props
		const c = Vec.From(center)
		const t = Vec.From(armTop)
		const l = Vec.From(armLeft)
		const r = Vec.From(armRight)

return new Group2d({
			children: [
				new Edge2d({ start: c, end: t }),
				new Edge2d({ start: c, end: l }),
				new Edge2d({ start: c, end: r }),
			],
		})
	}

// [5]
	override getHandles(shape: YShape): TLHandle[] {
		const indices = [ZERO_INDEX_KEY, ...getIndicesAbove(ZERO_INDEX_KEY, 3)]

return [
			{
				id: 'center',
				type: 'vertex',
				x: shape.props.center.x,
				y: shape.props.center.y,
				index: indices[0],
			},
			{
				id: 'armTop',
				type: 'vertex',
				x: shape.props.armTop.x,
				y: shape.props.armTop.y,
				index: indices[1],
				// [6]
				snapReferenceHandleId: 'center',
			},
			{
				id: 'armLeft',
				type: 'vertex',
				x: shape.props.armLeft.x,
				y: shape.props.armLeft.y,
				index: indices[2],
				// [7]
				snapReferenceHandleId: 'center',
			},
			{
				id: 'armRight',
				type: 'vertex',
				x: shape.props.armRight.x,
				y: shape.props.armRight.y,
				index: indices[3],
				// [8]
				snapReferenceHandleId: 'center',
			},
		]
	}

override onHandleDrag(shape: YShape, info: TLHandleDragInfo<YShape>) {
		const { handle } = info
		return {
			...shape,
			props: {
				...shape.props,
				[handle.id]: { x: handle.x, y: handle.y },
			},
		}
	}

// [9]
	component(shape: YShape) {
		const { center, armTop, armLeft, armRight } = shape.props

return (
			<HTMLContainer>
				<svg className="tl-svg-container">
					<line
						x1={center.x}
						y1={center.y}
						x2={armTop.x}
						y2={armTop.y}
						stroke="black"
						strokeWidth={2}
					/>
					<line
						x1={center.x}
						y1={center.y}
						x2={armLeft.x}
						y2={armLeft.y}
						stroke="black"
						strokeWidth={2}
					/>
					<line
						x1={center.x}
						y1={center.y}
						x2={armRight.x}
						y2={armRight.y}
						stroke="black"
						strokeWidth={2}
					/>
				</svg>
			</HTMLContainer>
		)
	}

indicator(shape: YShape) {
		const { center, armTop, armLeft, armRight } = shape.props
		return (
			<>
				<line x1={center.x} y1={center.y} x2={armTop.x} y2={armTop.y} />
				<line x1={center.x} y1={center.y} x2={armLeft.x} y2={armLeft.y} />
				<line x1={center.x} y1={center.y} x2={armRight.x} y2={armRight.y} />
			</>
		)
	}
}

const customShapes = [YShapeUtil]

export default function CustomRelativeSnappingYShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapes}
				onMount={(editor) => {
					const viewportPageBounds = editor.getViewportPageBounds()
					const centerX = viewportPageBounds.center.x
					const centerY = viewportPageBounds.center.y

editor.createShape({
						type: Y_SHAPE_TYPE,
						x: centerX - 100,
						y: centerY - 100,
					})

const shapeId = editor.getCurrentPageShapeIds().values().next().value
					if (shapeId) {
						editor.select(shapeId)
					}
				}}
			/>
		</div>
	)
}

/*
This example demonstrates the `snapReferenceHandleId` property using a Y-shaped connector.

The shape has three arms radiating from a center junction point:
- center (junction point)
- armTop (top arm endpoint)
- armLeft (bottom-left arm endpoint)
- armRight (bottom-right arm endpoint)

[1]
First, we need to extend TLGlobalShapePropsMap to add our shape's props to the global type system.
This tells TypeScript about the shape type with four points representing a Y-shaped connector.

[2]
Define the shape type using TLShape with the shape's type as a type argument.

[3]
The shape util with validators for each point.

[4]
Use Group2d geometry containing three line segments from center to each arm.

[5]
Four handles in array order: [center, armTop, armLeft, armRight]

[6]
With `snapReferenceHandleId: 'center'`, when you shift+drag armTop, it will snap to the center point.

[7]
Similarly, armLeft would snap relative to the center point.

[8]
And armRight would snap to the center point.

[9]
The component method defines how our shape renders.

*/
```

--------

# Custom shape with handles

Category: Shapes & tools

Keywords: handles, handle, geometry, interaction, text label

A speech bubble shape with custom handles.

This example shows how to create a custom shape with custom handles.

## App.tsx

```tsx
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { SpeechBubbleTool } from './SpeechBubble/SpeechBubbleTool'
import { SpeechBubbleUtil } from './SpeechBubble/SpeechBubbleUtil'
import { components, customAssetUrls, uiOverrides } from './SpeechBubble/ui-overrides'
import './customhandles.css'

// There's a guide at the bottom of this file!

// [1]
const shapeUtils = [SpeechBubbleUtil]
const tools = [SpeechBubbleTool]

// [2]
export default function CustomShapeWithHandles() {
	return (
		<div style={{ position: 'absolute', inset: 0 }}>
			<Tldraw
				shapeUtils={shapeUtils}
				tools={tools}
				overrides={uiOverrides}
				assetUrls={customAssetUrls}
				components={components}
				persistenceKey="whatever"
			/>
		</div>
	)
}

/*
Introduction:

This example shows how to create a custom shape using handles. You can use handles when you want
user interaction to alter the geometry of a shape. In this example, we create a speech bubble shape
with a handle on the tail so the user can alter its position and length. Most of the interesting stuff
is in SpeechBubbleUtil.tsx and helpers.tsx.

[1]
We define an array to hold the custom shape util and cusom tool. It's important to do this outside of
any React component so that this array doesn't get redefined on every render. We'll pass this into the 
Tldraw component's `shapeUtils` and `tools` props.

Check out SpeechBubbleUtil.tsx and SpeechBubbleTool.tsx to see how we define the shape util and tool.

[2]
We pass the custom shape util and tool into the Tldraw component's `shapeUtils` and `tools` props.
We also pass in the custom ui overrides and asset urls to make sure our icons render where we want them to. 
Check out ui-overrides.ts for more details.

*/
```

## customhandles.css

```css
/* Resize handles are normally on top, but We're going to give shape handles priority */
.tl-user-handles {
	z-index: 101;
}

/* The text label doesn't normally deal with text that goes sideways,
 * so this accounts for that */
.tl-shape[data-shape-type='speech-bubble'] .tl-text-label {
	justify-content: flex-start !important;
}
```

## SpeechBubbleTool.tsx

```tsx
import { BaseBoxShapeTool } from 'tldraw'

export class SpeechBubbleTool extends BaseBoxShapeTool {
	static override id = 'speech-bubble'
	static override initial = 'idle'
	override shapeType = 'speech-bubble' as const
}

/*
This file contains our speech bubble tool. The tool is a StateNode with the `id` "speech-bubble".

We get a lot of functionality for free by extending the BaseBoxShapeTool. For an example of a tool
with more custom functionality, check out the screenshot-tool example.

*/
```

## SpeechBubbleUtil.tsx

```tsx
import {
	DefaultColorStyle,
	DefaultFontStyle,
	DefaultHorizontalAlignStyle,
	DefaultSizeStyle,
	DefaultVerticalAlignStyle,
	FONT_FAMILIES,
	Geometry2d,
	LABEL_FONT_SIZES,
	PlainTextLabel,
	Polygon2d,
	RecordPropsType,
	ShapeUtil,
	T,
	TEXT_PROPS,
	TLHandle,
	TLHandleDragInfo,
	TLResizeInfo,
	TLShape,
	Vec,
	ZERO_INDEX_KEY,
	getColorValue,
	resizeBox,
	structuredClone,
	useDefaultColorTheme,
	vecModelValidator,
} from 'tldraw'
import { getSpeechBubbleVertices, getTailIntersectionPoint } from './helpers'

const SPEECH_BUBBLE_TYPE = 'speech-bubble'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[SPEECH_BUBBLE_TYPE]: SpeechBubbleShapeProps
	}
}

// Copied from tldraw/tldraw
export const STROKE_SIZES = {
	s: 2,
	m: 3.5,
	l: 5,
	xl: 10,
}

// There's a guide at the bottom of this file!

export const speechBubbleShapeProps = {
	w: T.number,
	h: T.number,
	size: DefaultSizeStyle,
	color: DefaultColorStyle,
	font: DefaultFontStyle,
	align: DefaultHorizontalAlignStyle,
	verticalAlign: DefaultVerticalAlignStyle,
	growY: T.positiveNumber,
	text: T.string,
	tail: vecModelValidator,
}

export type SpeechBubbleShapeProps = RecordPropsType<typeof speechBubbleShapeProps>
// [2]
export type SpeechBubbleShape = TLShape<typeof SPEECH_BUBBLE_TYPE>

export class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
	static override type = SPEECH_BUBBLE_TYPE

// [3]
	static override props = speechBubbleShapeProps

override isAspectRatioLocked(_shape: SpeechBubbleShape) {
		return false
	}

override canResize(_shape: SpeechBubbleShape) {
		return true
	}

override canEdit() {
		return true
	}

// [4]
	getDefaultProps(): SpeechBubbleShapeProps {
		return {
			w: 200,
			h: 130,
			color: 'black',
			size: 'm',
			font: 'draw',
			align: 'middle',
			verticalAlign: 'start',
			growY: 0,
			text: '',
			tail: { x: 0.5, y: 1.5 },
		}
	}

getHeight(shape: SpeechBubbleShape) {
		return shape.props.h + shape.props.growY
	}

getGeometry(shape: SpeechBubbleShape): Geometry2d {
		const speechBubbleGeometry = getSpeechBubbleVertices(shape)
		const body = new Polygon2d({
			points: speechBubbleGeometry,
			isFilled: true,
		})
		return body
	}

// [5]
	override getHandles(shape: SpeechBubbleShape): TLHandle[] {
		const { tail, w } = shape.props

return [
			{
				id: 'tail',
				type: 'vertex',
				label: 'Move tail',
				index: ZERO_INDEX_KEY,
				// props.tail coordinates are normalized
				// but here we need them in shape space
				x: tail.x * w,
				y: tail.y * this.getHeight(shape),
			},
		]
	}

override onHandleDrag(shape: SpeechBubbleShape, { handle }: TLHandleDragInfo<SpeechBubbleShape>) {
		return {
			...shape,
			props: {
				tail: {
					x: handle.x / shape.props.w,
					y: handle.y / this.getHeight(shape),
				},
			},
		}
	}

override onBeforeCreate(next: SpeechBubbleShape) {
		return this.getGrowY(next, next.props.growY)
	}

// [6]
	override onBeforeUpdate(prev: SpeechBubbleShape, shape: SpeechBubbleShape) {
		const { w, tail } = shape.props
		const fullHeight = this.getHeight(shape)

const { segmentsIntersection, insideShape } = getTailIntersectionPoint(shape)

const slantedLength = Math.hypot(w, fullHeight)
		const MIN_DISTANCE = slantedLength / 5
		const MAX_DISTANCE = slantedLength / 1.5

const tailInShapeSpace = new Vec(tail.x * w, tail.y * fullHeight)

const distanceToIntersection = tailInShapeSpace.dist(segmentsIntersection)
		const center = new Vec(w / 2, fullHeight / 2)
		const tailDirection = Vec.Sub(tailInShapeSpace, center).uni()

let newPoint = tailInShapeSpace

if (insideShape) {
			newPoint = Vec.Add(segmentsIntersection, tailDirection.mul(MIN_DISTANCE))
		} else {
			if (distanceToIntersection <= MIN_DISTANCE) {
				newPoint = Vec.Add(segmentsIntersection, tailDirection.mul(MIN_DISTANCE))
			} else if (distanceToIntersection >= MAX_DISTANCE) {
				newPoint = Vec.Add(segmentsIntersection, tailDirection.mul(MAX_DISTANCE))
			}
		}

const next = structuredClone(shape)
		next.props.tail.x = newPoint.x / w
		next.props.tail.y = newPoint.y / fullHeight

return this.getGrowY(next, prev.props.growY)
	}

component(shape: SpeechBubbleShape) {
		const {
			id,
			type,
			props: { color, font, size, align, text },
		} = shape
		const vertices = getSpeechBubbleVertices(shape)
		const pathData = 'M' + vertices[0] + 'L' + vertices.slice(1) + 'Z'
		const isSelected = shape.id === this.editor.getOnlySelectedShapeId()
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const theme = useDefaultColorTheme()

return (
			<>
				<svg className="tl-svg-container">
					<path
						d={pathData}
						strokeWidth={STROKE_SIZES[size]}
						stroke={getColorValue(theme, color, 'solid')}
						fill={'none'}
					/>
				</svg>
				<PlainTextLabel
					shapeId={id}
					type={type}
					font={font}
					textWidth={shape.props.w}
					fontSize={LABEL_FONT_SIZES[size]}
					lineHeight={TEXT_PROPS.lineHeight}
					align={align}
					verticalAlign="start"
					text={text}
					labelColor={getColorValue(theme, color, 'solid')}
					isSelected={isSelected}
					wrap
				/>
			</>
		)
	}

indicator(shape: SpeechBubbleShape) {
		const vertices = getSpeechBubbleVertices(shape)
		const pathData = 'M' + vertices[0] + 'L' + vertices.slice(1) + 'Z'
		return <path d={pathData} />
	}

override onResize(shape: SpeechBubbleShape, info: TLResizeInfo<SpeechBubbleShape>) {
		const resized = resizeBox(shape, info)
		const next = structuredClone(info.initialShape)
		next.x = resized.x
		next.y = resized.y
		next.props.w = resized.props.w
		next.props.h = resized.props.h
		return next
	}

getGrowY(shape: SpeechBubbleShape, prevGrowY = 0) {
		const PADDING = 17

const nextTextSize = this.editor.textMeasure.measureText(shape.props.text, {
			...TEXT_PROPS,
			fontFamily: FONT_FAMILIES[shape.props.font],
			fontSize: LABEL_FONT_SIZES[shape.props.size],
			maxWidth: shape.props.w - PADDING * 2,
		})

const nextHeight = nextTextSize.h + PADDING * 2

let growY = 0

if (nextHeight > shape.props.h) {
			growY = nextHeight - shape.props.h
		} else {
			if (prevGrowY) {
				growY = 0
			}
		}

return {
			...shape,
			props: {
				...shape.props,
				growY,
			},
		}
	}
}

/*
Introduction: This file contains our custom shape util. The shape util is a class that defines how
our shape behaves. Most of the logic for how the speech bubble shape works is in the onBeforeUpdate
handler [6]. Since this shape has a handle, we need to do some special stuff to make sure it updates
the way we want it to.

[2]
Define the shape type using TLShape with the shape's type as a type argument.

[3]
This is where we define the shape's props and a type validator for each key. tldraw exports a
bunch of handy validators for us to use. Props you define here will determine which style options
show up in the style menu, e.g. we define 'size' and 'color' props, but we could add 'dash', 'fill'
or any other of the default props.

[4]
Here is where we set the default props for our shape, this will determine how the shape looks
when we click-create it. You'll notice we don't store the tail's absolute position though, instead
we record its relative position. This is because we can also drag-create shapes. If we store the
tail's position absolutely it won't scale properly when drag-creating. Throughout the rest of the
util we'll need to convert the tail's relative position to an absolute position and vice versa.

[5]
`getHandles` tells tldraw how to turn our shape into a list of handles that'll show up when it's
selected. We only have one handle, the tail, which simplifies things for us a bit. In
`onHandleDrag`, we tell tldraw how our shape should be updated when the handle is dragged.

[6]
This is the last method that fires after a shape has been changed, we can use it to make sure
the tail stays the right length and position. Check out helpers.tsx to get into some of the more
specific geometry stuff.
*/
```

## helpers.tsx

```tsx
import { Vec, VecLike, lerp, pointInPolygon } from 'tldraw'
import { SpeechBubbleShape } from './SpeechBubbleUtil'

export const getSpeechBubbleVertices = (shape: SpeechBubbleShape): Vec[] => {
	const { w, tail } = shape.props

const fullHeight = shape.props.h + shape.props.growY
	const tailInShapeSpace = new Vec(tail.x * w, tail.y * fullHeight)

const [tl, tr, br, bl] = [
		new Vec(0, 0),
		new Vec(w, 0),
		new Vec(w, fullHeight),
		new Vec(0, fullHeight),
	]

const offsetH = w / 10
	const offsetV = fullHeight / 10

const { adjustedIntersection, intersectionSegmentIndex } = getTailIntersectionPoint(shape)

let vertices: Vec[]

// Inject the tail segments into the geometry of the shape
	switch (intersectionSegmentIndex) {
		case 0:
			// top
			vertices = [
				tl,
				new Vec(adjustedIntersection.x - offsetH, adjustedIntersection.y),
				new Vec(tailInShapeSpace.x, tailInShapeSpace.y),
				new Vec(adjustedIntersection.x + offsetH, adjustedIntersection.y),
				tr,
				br,
				bl,
			]
			break
		case 1:
			// right
			vertices = [
				tl,
				tr,
				new Vec(adjustedIntersection.x, adjustedIntersection.y - offsetV),
				new Vec(tailInShapeSpace.x, tailInShapeSpace.y),
				new Vec(adjustedIntersection.x, adjustedIntersection.y + offsetV),
				br,
				bl,
			]
			break
		case 2:
			// bottom
			vertices = [
				tl,
				tr,
				br,
				new Vec(adjustedIntersection.x + offsetH, adjustedIntersection.y),
				new Vec(tailInShapeSpace.x, tailInShapeSpace.y),
				new Vec(adjustedIntersection.x - offsetH, adjustedIntersection.y),
				bl,
			]
			break
		case 3:
			// left
			vertices = [
				tl,
				tr,
				br,
				bl,
				new Vec(adjustedIntersection.x, adjustedIntersection.y + offsetV),
				new Vec(tailInShapeSpace.x, tailInShapeSpace.y),
				new Vec(adjustedIntersection.x, adjustedIntersection.y - offsetV),
			]
			break
		default:
			throw Error("no intersection found, this shouldn't happen")
	}

return vertices
}

export function getTailIntersectionPoint(shape: SpeechBubbleShape) {
	const { w, tail } = shape.props
	const fullHeight = shape.props.h + shape.props.growY
	const tailInShapeSpace = new Vec(tail.x * w, tail.y * fullHeight)

const center = new Vec(w / 2, fullHeight / 2)
	const corners = [new Vec(0, 0), new Vec(w, 0), new Vec(w, fullHeight), new Vec(0, fullHeight)]
	const segments = [
		[corners[0], corners[1]],
		[corners[1], corners[2]],
		[corners[2], corners[3]],
		[corners[3], corners[0]],
	]

let segmentsIntersection: Vec | null = null
	let intersectionSegment: Vec[] | null = null

// If the point inside of the box's corners?
	const insideShape = pointInPolygon(tailInShapeSpace, corners)

// We want to be sure we get an intersection, so if the point is
	// inside the shape, push it away from the center by a big distance
	const pointToCheck = insideShape
		? Vec.Add(tailInShapeSpace, Vec.Sub(tailInShapeSpace, center).uni().mul(1000000))
		: tailInShapeSpace

// Test each segment for an intersection
	for (const segment of segments) {
		segmentsIntersection = intersectLineSegmentLineSegment(
			segment[0],
			segment[1],
			center,
			pointToCheck
		)

if (segmentsIntersection) {
			intersectionSegment = segment
			break
		}
	}

if (!(segmentsIntersection && intersectionSegment)) {
		throw Error("no intersection found, this shouldn't happen")
	}

const [start, end] = intersectionSegment
	const intersectionSegmentIndex = segments.indexOf(intersectionSegment)

// a normalised vector from start to end, so this can work in any direction
	const unit = Vec.Sub(end, start).uni()

// Where is the intersection relative to the start?
	const totalDistance = Vec.Dist(start, end)
	const distance = Vec.Dist(segmentsIntersection, start)

// make it stick to the middle
	const middleRelative = mapRange(0, totalDistance, -1, 1, distance) // absolute -> -1 to 1
	const squaredRelative = Math.abs(middleRelative) ** 2 * Math.sign(middleRelative) // square it and keep the sign
	const squared = mapRange(-1, 1, 0, totalDistance, squaredRelative) // -1 to 1 -> absolute

//keep it away from the edges
	const offset = (segments.indexOf(intersectionSegment) % 2 === 0 ? w / 10 : fullHeight / 10) * 3
	const constrained = mapRange(0, totalDistance, offset, totalDistance - offset, distance)

// combine the two
	const interpolated = lerp(constrained, squared, 0.5)

const adjustedIntersection = unit.mul(interpolated).add(start)

// We need the adjusted intersection to draw the tail, but the original intersection
	// for the onBeforeUpdate handler
	return {
		segmentsIntersection,
		adjustedIntersection,
		intersectionSegmentIndex,
		insideShape,
	}
}

// This function is copied from the tldraw codebase
function intersectLineSegmentLineSegment(a1: VecLike, a2: VecLike, b1: VecLike, b2: VecLike) {
	const ABx = a1.x - b1.x
	const ABy = a1.y - b1.y
	const BVx = b2.x - b1.x
	const BVy = b2.y - b1.y
	const AVx = a2.x - a1.x
	const AVy = a2.y - a1.y
	const ua_t = BVx * ABy - BVy * ABx
	const ub_t = AVx * ABy - AVy * ABx
	const u_b = BVy * AVx - BVx * AVy

if (ua_t === 0 || ub_t === 0) return null // coincident

if (u_b === 0) return null // parallel

if (u_b !== 0) {
		const ua = ua_t / u_b
		const ub = ub_t / u_b
		if (0 <= ua && ua <= 1 && 0 <= ub && ub <= 1) {
			return Vec.AddXY(a1, ua * AVx, ua * AVy)
		}
	}

return null // no intersection
}

/**
 * Inverse linear interpolation
 */
function invLerp(a: number, b: number, v: number) {
	return (v - a) / (b - a)
}
/**
 * Maps a value from one range to another.
 * e.g. mapRange(10, 20, 50, 100, 15) => 75
 */
function mapRange(a1: number, b1: number, a2: number, b2: number, s: number) {
	return lerp(a2, b2, invLerp(a1, b1, s))
}
```

## ui-overrides.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TLUiAssetUrlOverrides,
	TLUiOverrides,
	TldrawUiMenuItem,
	useIsToolSelected,
	useTools,
} from 'tldraw'

// There's a guide at the bottom of this file!

// [1]
export const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		tools.speech = {
			id: 'speech-bubble',
			icon: 'speech-bubble',
			label: 'Speech Bubble',
			kbd: 's',
			onSelect: () => {
				editor.setCurrentTool('speech-bubble')
			},
		}
		return tools
	},
}

// [2]
export const customAssetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'speech-bubble': '/speech-bubble.svg',
	},
}

export const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isSpeechBubbleSelected = useIsToolSelected(tools['speech'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['speech']} isSelected={isSpeechBubbleSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	KeyboardShortcutsDialog: (props) => {
		const tools = useTools()
		return (
			<DefaultKeyboardShortcutsDialog {...props}>
				<TldrawUiMenuItem {...tools['speech']} />
				<DefaultKeyboardShortcutsDialogContent />
			</DefaultKeyboardShortcutsDialog>
		)
	},
}

This file contains overrides for the Tldraw UI. These overrides are used to add your custom tools
to the toolbar and the keyboard shortcuts menu.

[1]
Here we add our new tool to the UI's tools object in the tools override. This is where we define
all the basic information about our new tool - its icon, label, keyboard shortcut, what happens when
we select it, etc.

[2]
Our toolbar item is using a custom icon, so we need to provide the asset url for it. 
We do this by providing a custom assetUrls object to the Tldraw component. 
This object is a map of icon ids to their urls. The icon ids are the same as the 
icon prop on the toolbar item. We'll pass our assetUrls object into the Tldraw
component's `assetUrls` prop.

[3]
We replace the UI components for the toolbar and keyboard shortcut dialog with our own, that
add our new tool to the existing default content. Ideally, we'd interleave our new tool into the
ideal place among the default tools, but for now we're just adding it at the start to keep things
simple.

*/
```

--------

# Custom tool with child states

Category: Shapes & tools

Keywords: state machine, custom tool, state node, interactions

You can implement more complex behaviour in a custom tool by using child states

Tools are nodes in tldraw's state machine. They are responsible for handling user input. You can create custom tools by extending the StateNode class and overriding its methods. In this example we expand on the sticker tool from the [custom tool example](https://tldraw.dev/examples/custom-tool) to show how to create a tool that can handle more complex interactions by using child states.

## App.tsx

```tsx
import {
	StateNode,
	TLClickEventInfo,
	TLPointerEventInfo,
	TLShapePartial,
	TLTextShape,
	Tldraw,
	createShapeId,
	toRichText,
} from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

const OFFSET = -12

// [1]
class StickerTool extends StateNode {
	static override id = 'sticker'
	static override initial = 'idle'
	static override children() {
		return [Idle, Pointing, Dragging]
	}
}

// [2]
class Idle extends StateNode {
	static override id = 'idle'
	//[a]
	override onEnter() {
		this.editor.setCursor({ type: 'cross' })
	}
	//[b]
	override onPointerDown(info: TLPointerEventInfo) {
		const { editor } = this
		switch (info.target) {
			case 'canvas': {
				const hitShape = editor.getShapeAtPoint(editor.inputs.getCurrentPagePoint())
				if (hitShape) {
					this.onPointerDown({
						...info,
						shape: hitShape,
						target: 'shape',
					})
					return
				}
				this.parent.transition('pointing', { shape: null })
				break
			}
			case 'shape': {
				if (editor.inputs.getShiftKey()) {
					editor.updateShape({
						id: info.shape.id,
						type: 'text',
						props: { richText: toRichText('👻 boo!') },
					})
				} else {
					this.parent.transition('pointing', { shape: info.shape })
				}
				break
			}
		}
	}
	//[c]
	override onDoubleClick(info: TLClickEventInfo) {
		const { editor } = this
		if (info.phase !== 'up') return
		switch (info.target) {
			case 'canvas': {
				const hitShape = editor.getShapeAtPoint(editor.inputs.getCurrentPagePoint())

if (hitShape) {
					this.onDoubleClick({
						...info,
						shape: hitShape,
						target: 'shape',
					})
					return
				}
				const currentPagePoint = editor.inputs.getCurrentPagePoint()
				editor.createShape({
					type: 'text',
					x: currentPagePoint.x + OFFSET,
					y: currentPagePoint.y + OFFSET,
					props: { richText: toRichText('❤️') },
				})
				break
			}
			case 'shape': {
				editor.deleteShapes([info.shape.id])
				break
			}
		}
	}
}
// [3]
class Pointing extends StateNode {
	static override id = 'pointing'
	private shape: TLTextShape | null = null

override onEnter(info: { shape: TLTextShape | null }) {
		this.shape = info.shape
	}
	override onPointerUp() {
		this.parent.transition('idle')
	}

override onPointerMove() {
		if (this.editor.inputs.getIsDragging()) {
			this.parent.transition('dragging', { shape: this.shape })
		}
	}
}

// [4]
class Dragging extends StateNode {
	static override id = 'dragging'
	// [a]
	private shape: TLShapePartial | null = null
	private emojiArray = ['❤️', '🔥', '👍', '👎', '😭', '🤣']

// [b]
	override onEnter(info: { shape: TLShapePartial }) {
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		const newShape: TLShapePartial<TLTextShape> = {
			id: createShapeId(),
			type: 'text',
			x: currentPagePoint.x + OFFSET,
			y: currentPagePoint.y + OFFSET,
			props: { richText: toRichText('❤️') },
		}
		if (info.shape) {
			this.shape = info.shape
		} else {
			this.editor.createShape(newShape)
			this.shape = { ...newShape }
		}
	}
	//[c]
	override onPointerUp() {
		this.parent.transition('idle')
	}
	//[d]

override onPointerMove() {
		const { shape } = this
		const originPagePoint = this.editor.inputs.getOriginPagePoint()
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		const distance = originPagePoint.dist(currentPagePoint)
		if (shape) {
			this.editor.updateShape({
				id: shape.id,
				type: 'text',
				props: {
					richText: toRichText(this.emojiArray[Math.floor(distance / 20) % this.emojiArray.length]),
				},
			})
		}
	}
}

// [5]
const customTools = [StickerTool]
export default function ToolWithChildStatesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// Pass in the array of custom tool classes
				tools={customTools}
				// Set the initial state to the sticker tool
				initialState="sticker"
				// hide the ui
				hideUi
				// Put some helpful text on the canvas
				onMount={(editor) => {
					editor.createShape({
						type: 'text',
						x: 50,
						y: 50,
						props: {
							richText: toRichText(
								'-Double click the canvas to add a sticker\n-Double click a sticker to delete it\n-Click and drag on a sticker to change it\n-Click and drag on the canvas to create a sticker\n-Shift click a sticker for a surprise!'
							),
							size: 's',
							textAlign: 'start',
						},
					})
				}}
			/>
		</div>
	)
}

/*
Introduction:

Tools are nodes in tldraw's state machine. They are responsible for handling user input.
You can create custom tools by extending the `StateNode` class and overriding its
methods. In this example we expand on the sticker tool from the custom tool example to
show how to create a tool that can handle more complex interactions by using child states.

[1]
This is our custom tool. It has three child states: `Idle`, `Pointing`, and `Dragging`.
We need to define the `id` and `initial` properties, the id is a unique string that
identifies the tool to the editor, and the initial property is the initial state of the
tool. We also need to define a `children` method that returns an array of the tool's
child states.

[2]
This is our Idle state. It is the initial state of the tool. It's job is to figure out
what the user is trying to do and transition to the appropriate state. When transitioning
between states we can use the second argument to pass data to the new state. It has three
methods:

[a] `onEnter`
	When entering any state, the `onEnter` method is called. In this case, we set the cursor to
	a crosshair.

[b] `onPointerDown`
	This method is called when the user presses the mouse button. The target parameter is always
	the canvas, so we can use an editor method to check if we're over a shape, and call the
	method again with the shape as the target. If we are over a shape, we transition to the
	`pointing` state with the shape in the info object. If we're over a shape and holding the
	shift key, we update the shape's text. If we're over the canvas, we transition to the
	`pointing` state with a null shape in the info object.

[c] `onDoubleClick`
	This method is called when the user double clicks the mouse button. We're using some similar
	logic here to check if we're over a shape, and if we are, we delete it. If we're over the canvas,
	we create a new shape.

[3]
This is our `Pointing` state. It's a transitionary state, we use it to store the shape we're pointing
at, and transition to the dragging state if the user starts dragging. It has three methods:

[a] `onEnter`
	When entering this state, we store the shape we're pointing at by getting it from the info object.

[b] `onPointerUp`
	This method is called when the user releases the mouse button. We transition to the `idle` state.

[c] `onPointerMove`
	This method is called when the user moves the mouse. If the user starts dragging, we transition to
	the `dragging` state and pass the shape we're pointing at.

[4]
This is our `Dragging` state. It's responsible for creating and updating the shape that the user is
dragging.

[a] `onEnter`
	When entering this state, we create a new shape if we're not dragging an existing one. If we are,
	we store the shape we're dragging.

[b] `onPointerUp`
	This method is called when the user releases the mouse button. We transition to the `idle` state.

[c] `onPointerMove`
	This method is called when the user moves the mouse. We use the distance between the origin and
	current mouse position to cycle through an array of emojis and update the shape's text.

[5]
We pass our custom tool to the `Tldraw` component as an array. We also set the initial state to our
custom tool. For the purposes of this demo, we're also hiding the UI and adding some helpful text to
the canvas.
*/
```

--------

# Editable custom shape

Category: Shapes & tools

Keywords: custom

A custom shape that you can edit by double-clicking it.

In tldraw, the Editor can have one editing shape at a time. When in its editing state, the editor will ignore events until the user exits the editing state by pressing Escape or clicking on the canvas.

Only shapes with a `canEdit` flag that returns true may become editable. A user may begin editing a shape by double clicking on the editable shape, or selecting the editable shape and pressing enter.

Many of our shapes use editing to allow for interactions inside of the shape. For example, a text shape behaves like a text graphic until the user begins editing it—and only then can the user use their keyboard to edit the text. Note that a shape can be interactive regardless of whether it's the editor's editing shape—the "editing" mechanic is just a way of managing a common pattern in canvas applications.

In this example we'll create a shape that renders an emoji and allows the user to change the emoji when the shape is in the editing state.
Most of the relevant code for this is in the EditableShapeUtil.tsx file. If you want a more in-depth explanation of the shape util, check out the custom shape example.

## App.tsx

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

const customShapeUtils = [EditableShapeUtil]

export default function EditableShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// Pass in the array of custom shape classes
				shapeUtils={customShapeUtils}
				// Create a shape when the editor mounts
				onMount={(editor) => {
					editor.createShape({ type: 'my-editable-shape', x: 100, y: 100 })
				}}
			/>
		</div>
	)
}

/*
Introduction:

In tldraw, shapes can exist in an editing state. When shapes are in the editing state
they are focused and can't be dragged, resized or rotated. Shapes enter this state 
when they are double-clicked. In our default shapes we mostly use this for editing text. 
In this example we'll create a shape that renders an emoji and allows the user to change 
the emoji when the shape is in the editing state.

Most of the relevant code for this is in the EditableShapeUtil.tsx file. If you want a more
in-depth explanation of the shape util, check out the custom shape example.
 */
```

## EditableShapeUtil.tsx

```tsx
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape } from 'tldraw'

// There's a guide at the bottom of this file!

const MY_EDITABLE_SHAPE_TYPE = 'my-editable-shape'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_EDITABLE_SHAPE_TYPE]: {
			w: number
			h: number
			animal: number
		}
	}
}

const ANIMAL_EMOJIS = ['🐶', '🐱', '🐨', '🐮', '🐴']

export type IMyEditableShape = TLShape<typeof MY_EDITABLE_SHAPE_TYPE>

export class EditableShapeUtil extends BaseBoxShapeUtil<IMyEditableShape> {
	static override type = MY_EDITABLE_SHAPE_TYPE
	static override props: RecordProps<IMyEditableShape> = {
		w: T.number,
		h: T.number,
		animal: T.number,
	}

// [1]
	override canEdit() {
		return true
	}

// [1b]
	override canEditWhileLocked() {
		return true
	}

getDefaultProps(): IMyEditableShape['props'] {
		return {
			w: 200,
			h: 200,
			animal: 0,
		}
	}

// [2]
	component(shape: IMyEditableShape) {
		// [a]
		const isEditing = this.editor.getEditingShapeId() === shape.id

return (
			<HTMLContainer
				id={shape.id}
				// [b]
				onPointerDown={isEditing ? this.editor.markEventAsHandled : undefined}
				style={{
					pointerEvents: isEditing ? 'all' : 'none',
					backgroundColor: '#efefef',
					fontSize: 24,
					padding: 16,
				}}
			>
				{ANIMAL_EMOJIS[shape.props.animal]}
				{/* [c] */}
				{isEditing ? (
					<button
						onClick={() => {
							this.editor.updateShape({
								id: shape.id,
								type: shape.type,
								props: {
									...shape.props,
									animal: (shape.props.animal + 1) % ANIMAL_EMOJIS.length,
								},
							})
						}}
					>
						Next
					</button>
				) : (
					// [d] when not editing...
					<p style={{ fontSize: 12 }}>Double Click to Edit</p>
				)}
			</HTMLContainer>
		)
	}

indicator(shape: IMyEditableShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}

// [3]
	override onEditEnd(shape: IMyEditableShape) {
		this.editor.animateShape(
			{ ...shape, rotation: shape.rotation + Math.PI * 2 },
			{ animation: { duration: 250 } }
		)
	}
}

This is our shape util, which defines how our shape renders and behaves. For
more information on the shape util, check out the custom shape example.

[1]
We override the canEdit method to allow the shape to enter the editing state.

[1b] We override canEditWhileLocked to allow the shape to be edited even
		when it is locked. This is useful for shapes that need to remain
		interactive despite being locked in place, preventing accidental
		movement while still allowing content changes.

[2]
We want to conditionally render the component based on whether it is being
edited or not.

[a] We can check whether our shape is being edited by comparing the
		editing shape id to the shape's id.

[b] We want to allow pointer events when the shape is being edited,
		and stop event propagation on pointer down. Check out the interactive
		shape example for more information on this.

[c] We render a button to change the animal emoji when the shape is being
		edited.

[e]	We also render a message when the shape is not being edited.

[3]
The onEditEnd method is called when the shape exits the editing state. In this
case we rotate the shape 360 degrees.

*/
```

--------

# Arrow binding options

Category: Shapes & tools

Keywords: arrow, binding, precise, exact, anchor, snap

Demonstrate arrow binding options for precise positioning.

This example shows the different arrow binding options that control how arrows connect to shapes:

- **isPrecise: false** - Arrow always targets the center of the shape (default safe behavior)
- **isPrecise: true** - Arrow respects the `normalizedAnchor` and targets the specified position
- **isExact: false** - Arrow stops at the shape's edge (default)
- **isExact: true** - Arrow passes through the shape to reach the exact target point

The `normalizedAnchor` property specifies where on the shape the arrow connects using normalized coordinates (0-1 on each axis). For example, `{x: 0.5, y: 0.5}` is the center, `{x: 0, y: 0}` is top-left, and `{x: 1, y: 1}` is bottom-right.

These options provide fine-grained control over arrow positioning for technical diagrams, architectural drawings, and other use cases requiring precise arrow placement.

## App.tsx

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

export default function ArrowBindingOptionsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					const spacing = 300

// [1]
					const shape1Id = createShapeId()
					editor.createShape({
						id: shape1Id,
						type: 'geo',
						x: 100,
						y: 100,
						props: {
							w: 150,
							h: 150,
							richText: toRichText('isPrecise: false\n(always center)'),
							color: 'blue',
						},
					})

// [2]
					const arrow1Id = createShapeId()
					editor.createShape({
						id: arrow1Id,
						type: 'arrow',
						props: {
							start: { x: 50, y: 175 },
							end: { x: 100, y: 175 },
						},
					})
					editor.createBindings([
						{
							fromId: arrow1Id,
							toId: shape1Id,
							type: 'arrow',
							props: {
								terminal: 'end',
								normalizedAnchor: { x: 0.25, y: 0.5 },
								isPrecise: false,
								isExact: false,
							},
						},
					])

// [3]
					const shape2Id = createShapeId()
					editor.createShape({
						id: shape2Id,
						type: 'geo',
						x: 100 + spacing,
						y: 100,
						props: {
							w: 150,
							h: 150,
							richText: toRichText('isPrecise: true\n(custom anchor)'),
							color: 'green',
						},
					})

// [4]
					const arrow2Id = createShapeId()
					editor.createShape({
						id: arrow2Id,
						type: 'arrow',
						props: {
							start: { x: 50 + spacing, y: 175 },
							end: { x: 100 + spacing, y: 175 },
						},
					})
					editor.createBindings([
						{
							fromId: arrow2Id,
							toId: shape2Id,
							type: 'arrow',
							props: {
								terminal: 'end',
								normalizedAnchor: { x: 0.25, y: 0.5 },
								isPrecise: true,
								isExact: false,
							},
						},
					])

// [5]
					const shape3Id = createShapeId()
					editor.createShape({
						id: shape3Id,
						type: 'geo',
						x: 100,
						y: 100 + spacing,
						props: {
							w: 150,
							h: 150,
							richText: toRichText('isExact: true\n(passes through)'),
							color: 'orange',
						},
					})

// [6]
					const arrow3Id = createShapeId()
					editor.createShape({
						id: arrow3Id,
						type: 'arrow',
						props: {
							start: { x: 50, y: 175 + spacing },
							end: { x: 100, y: 175 + spacing },
						},
					})
					editor.createBindings([
						{
							fromId: arrow3Id,
							toId: shape3Id,
							type: 'arrow',
							props: {
								terminal: 'end',
								normalizedAnchor: { x: 0.5, y: 0.5 },
								isPrecise: true,
								isExact: true,
							},
						},
					])

// [7]
					const shape4Id = createShapeId()
					editor.createShape({
						id: shape4Id,
						type: 'geo',
						x: 100 + spacing,
						y: 100 + spacing,
						props: {
							w: 150,
							h: 150,
							richText: toRichText('Combined\n(precise + exact)'),
							color: 'red',
						},
					})

const arrow4Id = createShapeId()
					editor.createShape({
						id: arrow4Id,
						type: 'arrow',
						props: {
							start: { x: 50 + spacing, y: 175 + spacing },
							end: { x: 100 + spacing, y: 175 + spacing },
						},
					})
					editor.createBindings([
						{
							fromId: arrow4Id,
							toId: shape4Id,
							type: 'arrow',
							props: {
								terminal: 'end',
								normalizedAnchor: { x: 0.75, y: 0.75 },
								isPrecise: true,
								isExact: true,
							},
						},
					])

editor.zoomToFit()
				}}
			/>
		</div>
	)
}

/*
[1]
Create the first shape demonstrating isPrecise: false. When isPrecise is false, the arrow
always targets the center of the shape, regardless of the normalizedAnchor value provided.

[2]
Create an arrow with isPrecise: false. Even though we specify normalizedAnchor at (0.25, 0.5)
(left side of the shape), the arrow will point to the center because isPrecise is false.
The arrow stops at the shape's edge.

[3]
Create the second shape demonstrating isPrecise: true. When isPrecise is true, the arrow
respects the normalizedAnchor and targets the specified position within the shape.

[4]
Create an arrow with isPrecise: true and the same normalizedAnchor at (0.25, 0.5). This time,
the arrow will actually target the left side of the shape as specified by the anchor. The arrow
still stops at the shape's edge (isExact: false).

[5]
Create the third shape demonstrating isExact: true. When isExact is true, the arrow passes
through the shape to reach its exact target point instead of stopping at the edge.

[6]
Create an arrow with both isPrecise: true and isExact: true. The normalizedAnchor at (0.5, 0.5)
targets the center of the shape, and isExact: true makes the arrow pass through the shape to
reach that exact point. This is useful for diagrams where arrows need to cross through shapes.

[7]
Create the fourth shape demonstrating the combination of precise and exact targeting. The arrow
targets the bottom-right quadrant (0.75, 0.75) and passes through the shape to that exact point.
This shows fine-grained control over arrow positioning.

Key takeaways:
- isPrecise: false = arrow always points to center (default safe behavior)
- isPrecise: true = arrow respects normalizedAnchor position
- isExact: false = arrow stops at shape edge (default)
- isExact: true = arrow passes through to exact target point
*/
```

--------

# Custom shape geometry

Category: Shapes & tools

Keywords: svg, path, house, door

A shape with custom geometry.

This example demonstrates how to create a shape with custom geometry in tldraw. The
shape we're creating is a simple house shape with a door.

## App.tsx

```tsx
import {
	Group2d,
	Polygon2d,
	RecordPropsType,
	Rectangle2d,
	ShapeUtil,
	T,
	TLResizeInfo,
	TLShape,
	Tldraw,
	Vec,
	resizeBox,
	structuredClone,
} from 'tldraw'
import 'tldraw/tldraw.css'

const HOUSE_TYPE = 'house'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[HOUSE_TYPE]: HouseShapeProps
	}
}

const houseShapeProps = {
	w: T.number,
	h: T.number,
}

type HouseShapeProps = RecordPropsType<typeof houseShapeProps>
type HouseShape = TLShape<typeof HOUSE_TYPE>
class HouseShapeUtil extends ShapeUtil<HouseShape> {
	static override type = HOUSE_TYPE
	static override props = houseShapeProps

override canResize() {
		return true
	}
	override getDefaultProps() {
		return {
			w: 100,
			h: 100,
		}
	}
	//[1]
	override getGeometry(shape: HouseShape) {
		const { house: houseGeometry } = getHouseVertices(shape)
		const house = new Polygon2d({
			points: houseGeometry,
			isFilled: true,
		})
		const door = new Rectangle2d({
			x: shape.props.w / 2 - shape.props.w / 10,
			y: shape.props.h - shape.props.h / 4,
			width: shape.props.w / 5,
			height: shape.props.h / 4,
			isFilled: true,
		})
		const geometry = new Group2d({
			children: [house, door],
		})
		return geometry
	}
	// [2]
	override component(shape: HouseShape) {
		const { house: houseVertices, door: doorVertices } = getHouseVertices(shape)
		const housePathData = 'M' + houseVertices[0] + 'L' + houseVertices.slice(1) + 'Z'
		const doorPathData = 'M' + doorVertices[0] + 'L' + doorVertices.slice(1) + 'Z'
		return (
			<svg className="tl-svg-container">
				<path strokeWidth={3} stroke="black" d={housePathData + doorPathData} fill="none" />
			</svg>
		)
	}
	// [3]
	override indicator(shape: HouseShape) {
		const { house: houseVertices, door: doorVertices } = getHouseVertices(shape)
		const housePathData = 'M' + houseVertices[0] + 'L' + houseVertices.slice(1) + 'Z'
		const doorPathData = 'M' + doorVertices[0] + 'L' + doorVertices.slice(1) + 'Z'
		return <path d={housePathData + doorPathData} />
	}
	override onResize(shape: HouseShape, info: TLResizeInfo<HouseShape>) {
		const resized = resizeBox(shape, info)
		const next = structuredClone(info.initialShape)
		next.x = resized.x
		next.y = resized.y
		next.props.w = resized.props.w
		next.props.h = resized.props.h
		return next
	}
}
// [4]
function getHouseVertices(shape: HouseShape): { house: Vec[]; door: Vec[] } {
	const { w, h } = shape.props
	const halfW = w / 2
	const roofStart = h / 2.5
	const house = [
		new Vec(0, roofStart), // Roof start (left)
		new Vec(w, roofStart), // Roof start (right)
		new Vec(w, h), // Bottom-right corner
		new Vec(0, h), // Bottom-left corner
		new Vec(0, roofStart), // Roof start (left)
		new Vec(halfW, 0), // Roof peak
		new Vec(w, roofStart), // Roof start (right)
	]
	const door = [
		new Vec(halfW - w / 10, h), // Bottom-left corner
		new Vec(halfW + w / 10, h), // Bottom-right corner
		new Vec(halfW + w / 10, h - h / 4), // Top-right corner
		new Vec(halfW - w / 10, h - h / 4), // Top-left corner
		new Vec(halfW - w / 10, h), // Bottom-left corner
	]
	return { house, door }
}

const shapeUtils = [HouseShapeUtil]

export default function ShapeWithGeometryExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					editor.createShape({
						type: 'house',
						x: 100,
						y: 100,
						props: {
							w: 100,
							h: 100,
						},
					})
				}}
				shapeUtils={shapeUtils}
			/>
		</div>
	)
}

/*
Introduction:
This file demonstrates how to create a shape with custom geometry in tldraw. The
shape we're creating is a simple house shape with a door. The HouseShapeUtil class
defines the behavior and appearance of our custom house shape.

[1]
The getGeometry method defines the geometric representation of our shape. This geometry
is used for hit-testing, intersection checking and other geometric calculations. We use
Polygon2d for the house body and Rectangle2d for the door. These are combined into a
Group2d to form the complete house geometry.

[2]
The component method determines how our shape is rendered. We create SVG paths for
both the house body and the door, combining them into a single path element. This
method is called when the shape needs to be drawn on the canvas. The tl-svg-container
class contains some helpful styles for rendering the svg correctly.

[3]
The indicator method renders the same path as a thin blue line when the shape is selected.

[4]
The getHouseVertices function calculates the vertices for both the house body and the door
based on the shape's dimensions. This is used by both the geometry and rendering methods
to ensure consistency in the shape's appearance.

*/
```

--------

# Custom shape migrations

Category: Shapes & tools

Keywords: version, update

Migrate your shapes and their data between versions

Sometimes you'll want to update the way a shape works in your application. When this happens there can be a risk of errors and bugs. For example, users with an old version of a shape in their documents might encounter errors when the editor tries to access a property that doesn't exist. This example shows how you can use our migrations system to preserve your users' data between versions. It uses a snapshot to load a document with a shape that is missing a "color" prop, and uses the migrations method of the shape util to update it.

## App.tsx

```tsx
import {
	BaseBoxShapeUtil,
	HTMLContainer,
	T,
	TLResizeInfo,
	TLShape,
	TLStoreSnapshot,
	Tldraw,
	createShapePropsMigrationIds,
	createShapePropsMigrationSequence,
	resizeBox,
} from 'tldraw'
import 'tldraw/tldraw.css'
import snapshot from './snapshot.json'

const MY_SHAPE_WITH_MIGRATIONS_TYPE = 'myshapewithmigrations' as const

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_SHAPE_WITH_MIGRATIONS_TYPE]: { w: number; h: number; color: string }
	}
}

// There's a guide at the bottom of this file!

export type IMyShape = TLShape<typeof MY_SHAPE_WITH_MIGRATIONS_TYPE>

// [1]
const versions = createShapePropsMigrationIds(
	// this must match the shape type in the shape definition
	MY_SHAPE_WITH_MIGRATIONS_TYPE,
	{
		AddColor: 1,
	}
)

// [2]
export const cardShapeMigrations = createShapePropsMigrationSequence({
	sequence: [
		{
			id: versions.AddColor,
			up(props) {
				// it is safe to mutate the props object here
				props.color = 'lightblue'
			},
			down(props) {
				delete props.color
			},
		},
	],
})

export class MigratedShapeUtil extends BaseBoxShapeUtil<IMyShape> {
	static override type = MY_SHAPE_WITH_MIGRATIONS_TYPE

static override props = {
		w: T.number,
		h: T.number,
		color: T.string,
	}

// [3]
	static override migrations = cardShapeMigrations

getDefaultProps(): IMyShape['props'] {
		return {
			w: 300,
			h: 300,
			color: 'lightblue',
		}
	}

component(shape: IMyShape) {
		return (
			<HTMLContainer
				id={shape.id}
				style={{
					backgroundColor: shape.props.color,
					boxShadow: '0 0 10px rgba(0,0,0,0.5)',
				}}
			></HTMLContainer>
		)
	}

indicator(shape: IMyShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}

override onResize(shape: IMyShape, info: TLResizeInfo<IMyShape>) {
		return resizeBox(shape, info)
	}
}

const customShapeUtils = [MigratedShapeUtil]

export default function ShapeWithMigrationsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// Pass in the array of custom shape classes
				shapeUtils={customShapeUtils}
				// Use a snapshot to load an old version of the shape
				snapshot={snapshot as TLStoreSnapshot}
			/>
		</div>
	)
}

/*
Introduction:

Sometimes you'll want to update the way a shape works in your application without breaking older
versions of the shape that a user may have stored or persisted in memory.

This example shows how you can use our migrations system to upgrade (or downgrade) user's data
between different versions. Most of the code above is general "custom shape" code—see our custom
shape example for more details.

[1] First, we need IDs for each migration. List each change with its version number. Once you've
added a migration, it should not change again.

[2] Next, we create a migration sequence. This is where we actually write our migration logic. Each
migration had three parts: an `id` (created in [1]), an `up` migration and `down` migration. In this
case, the `up` migration adds the `color` prop to the shape, and the `down` migration removes it.

In some cases (mainly in multiplayer sessions) a peer or server may need to take a later version of
a shape and migrate it down to an older version—in this case, it would run the down migrations in
order to get it to the needed version.

[3] Finally, we add our migrations to the ShapeUtil. This tells tldraw about the migrations so they
can be used with your shapes.

How it works:

Each time the editor's store creates a snapshot (`editor.store.createSnapshot`), it serializes all
of the records (the snapshot's `store`) as well as versions of each record that it contains (the
snapshot's `schema`). When the editor loads a snapshot, it compares its current schema with the
snapshot's schema to determine which migrations to apply to each record.

In this example, we have a snapshot (snapshot.json) that we created in version 0, however our shape
now has a 'color' prop that was added in version 1.

The snapshot looks something like this:

```json{
{
    "store": {
        "shape:BqG5uIAa9ig2-ukfnxwBX": {
            ...,
            "props": {
                "w": 300,
                "h": 300
            },
        },
	},
	"schema": {
		...,
		"sequences": {
			...,
			"com.tldraw.shape.arrow": 4,
			"com.tldraw.shape.myshape": 0
		}
	}
}
```

Note that the shape in the snapshot doesn't have a 'color' prop.

Note also that the schema's version for this shape is 0.

When the editor loads the snapshot, it will compare the serialized schema's version with its current
schema's version for the shape, which is 1 as defined in our shape's migrations. Since the
serialized version is older than its current version, it will use our migration to bring it up to
date: it will run the migration's `up` function, which will add the 'color' prop to the shape.
*/
```

--------

# Custom shape SVG export

Category: Shapes & tools

Keywords: basic, svg, custom, export, copy

Determine how your custom shapes look when copied/exported as an image.

The "export as SVG/PNG" and "copy as SVG/PNG" actions use the `toSvg` or `toBackgroundSvg` methods of a shape util. If a shape does not have a `toSvg` or `toBackgroundSvg` method defined, it will default to placing the shape's component inside a `<foreignObject>` element.

## App.tsx

```tsx
import { ReactElement } from 'react'
import {
	Geometry2d,
	HTMLContainer,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	SvgExportContext,
	T,
	Tldraw,
	TLShape,
} from 'tldraw'
import 'tldraw/tldraw.css'

const MY_CUSTOM_SHAPE_TO_SVG_TYPE = 'my-custom-shape-to-svg'

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

// There's a guide at the bottom of this file!

type ICustomShape = TLShape<typeof MY_CUSTOM_SHAPE_TO_SVG_TYPE>

const LIGHT_FILL = '#ff8888'
const DARK_FILL = '#ffcccc'

export class MyShapeUtil extends ShapeUtil<ICustomShape> {
	static override type = MY_CUSTOM_SHAPE_TO_SVG_TYPE
	static override props: RecordProps<ICustomShape> = {
		w: T.number,
		h: T.number,
	}

getDefaultProps(): ICustomShape['props'] {
		return {
			w: 200,
			h: 200,
		}
	}

override canEdit() {
		return false
	}
	override canResize() {
		return false
	}
	override isAspectRatioLocked() {
		return false
	}

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

component(_shape: ICustomShape) {
		const isDarkmode = this.editor.user.getIsDarkMode()
		return <HTMLContainer style={{ backgroundColor: isDarkmode ? DARK_FILL : LIGHT_FILL }} />
	}

indicator(shape: ICustomShape) {
		return this.getSvgRect(shape)
	}

// [1]
	override toSvg(
		shape: ICustomShape,
		ctx: SvgExportContext
	): ReactElement | null | Promise<ReactElement | null> {
		// ctx.addExportDef(getFontDef(shape))
		const isDarkmode = ctx.isDarkMode
		const fill = isDarkmode ? DARK_FILL : LIGHT_FILL
		return this.getSvgRect(shape, { fill })
	}

getSvgRect(shape: ICustomShape, props?: { fill: string }) {
		return <rect width={shape.props.w} height={shape.props.h} {...props} />
	}

// [2]

// override toBackgroundSvg(
	// 	shape: ICustomShape,
	// 	ctx: SvgExportContext
	// ): ReactElement | null | Promise<ReactElement | null> {
	// 	const isDarkmode = ctx.isDarkMode
	// 	const fill = isDarkmode ? '#333' : '#efefef'
	// 	return <rect width={shape.props.w} height={shape.props.h} fill={fill} />
	// }
}

// [3]

// function getFontDef(shape: ICustomShape): SvgExportDef {
// 	//
// 	return {
// 		some unique key,
// 		key: 'my-custom-shape-font',
// 		getElement: async () => {
// 			return <style></style> element
// 			check out the defaultStyleDefs.tsx file for an example of how
// 			we do this for tldraw fonts
// 		},
// 	}
// }

const customShape = [MyShapeUtil]
export default function CustomShapeToSvgExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShape}
				onMount={(editor) => {
					editor.createShape({ type: MY_CUSTOM_SHAPE_TO_SVG_TYPE, x: 100, y: 100 })
				}}
			/>
		</div>
	)
}
/*
 The "export as SVG/PNG" and "copy as SVG/PNG" actions use the `toSvg` or `toBackgroundSvg`
 methods of a shape util. If a shape does not have a `toSvg` or `toBackgroundSvg` method
 defined, it will default to an empty box.

For more information on creating a custom shape, check out the custom shape example.

[1]
    This method should return a React element that represents the shape as an SVG element.
    If your shape is HTML, then you will need to convert it to an SVG representation. In this
    example we've used a `rect` element to represent the shape. Other shapes may require more
    complex work to render them as SVGs, especially if they contain text. Check out [3] for more
	info.

[2]
    The `toBackgroundSvg` method is used to render a layer behind the shape when exporting as SVG.
    We use this in the tldraw codebase to make the highlighter shape. It's commented out here as
    we don't need it for this example.

[3]
	If your shape contains text, you may need to add a font definition to the SVG. This is done
	using the `addExportDef` method of the `SvgExportContext`. Your font def must contain a unique
	key and a function that returns a React element. Check out the `` function
	in the `defaultStyleDefs.tsx` file for an example of how this is done for tldraw fonts.

*/
```

--------

# Custom snapping

Category: Shapes & tools

Keywords: geometry, custom

Custom shapes with special bounds snapping behaviour.

This example shows how to create a shape with custom snapping geometry. When shapes are moved around in snap mode, they will snap to the bounds of other shapes by default. However, a shape can return custom snapping geometry to snap to instead.

In this case, we've created a custom playing card shape. The cards are designed to snap together so that the top-left icon remains visible when stacked, similar to a hand of cards in a game.

## App.tsx

```tsx
import { Editor, TLStoreSnapshot, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { PlayingCardTool } from './PlayingCardShape/playing-card-tool'
import { PlayingCardUtil } from './PlayingCardShape/playing-card-util'
import snapshot from './snapshot.json'
import { components, uiOverrides } from './ui-overrides'
// There's a guide at the bottom of this file!

// [1]
const customShapes = [PlayingCardUtil]
const customTools = [PlayingCardTool]

export default function BoundsSnappingShapeExample() {
	// [2]
	const handleMount = (editor: Editor) => {
		editor.user.updateUserPreferences({ isSnapMode: true })
	}
	// [3]
	return (
		<div className="tldraw__editor">
			<Tldraw
				//[a]
				shapeUtils={customShapes}
				tools={customTools}
				// [b]
				overrides={uiOverrides}
				components={components}
				// [c]
				onMount={handleMount}
				// [d]
				snapshot={snapshot as TLStoreSnapshot}
			/>
		</div>
	)
}

/*
Introduction:

This example shows how to create a shape with custom snapping geometry. When shapes are moved around
in snap mode, they will snap to the bounds of other shapes by default. A shape can return custom
snapping geometry to snap to instead. This example creates a playing card shape. The cards are
designed to snap together so that the top-left icon remains visible when stacked, similar to a hand
of cards in a game. The most relevant code for this customisation is in playing-card-util.tsx.

[1]
We define the custom shape and util arrays we'll pass to the Tldraw component. It's important to do
this outside of the component so that the arrays don't change on every render.

This is where we define the Tldraw component and pass in all our customisations.

[2]

We define a handleMount function that will be called when the editor mounts. We're using it to set
the snap mode to true in the user preferences. This is just to help demonstrate the custom snapping
geometry feature. Without snap mode being set in this way the user can still enter it by holding
cmd/ctrl while dragging.

[3]
This is where we're passing in all our customisations to the Tldraw component. Check out the
associated files for more information on what's being passed in.

[a] Firstly, our custom shape (playing-card-util.tsx) and tool (playing-card-tool.tsx)
        This tells the editor about our custom shape and tool.
    [b] Then our the uiOverrides and custom keyboard shortcuts component (ui-overrides.tsx),
        this makes sure that an icon for our tool appears in the toolbar and the shortcut
        for it appears in the dialog.
    [c] We pass in our handleMount function so that it's called when the editor mounts.

[d] Finally we pass in a snapshot so that the editor starts with some shapes in it.
        This isn't necessary, it just makes the example clearer on first glance.

*/
```

## ui-overrides.tsx

// There's a guide at the bottom of this file!

export const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		// Create a tool item in the ui's context.
		tools.PlayingCard = {
			id: 'PlayingCard',
			icon: <span style={{ fontSize: '2em' }}>🃏</span>,
			label: 'Playing Card',
			kbd: 'c',
			onSelect: () => {
				editor.setCurrentTool('PlayingCard')
			},
		}
		return tools
	},
}

export const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isCardSelected = useIsToolSelected(tools['PlayingCard'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['PlayingCard']} isSelected={isCardSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	KeyboardShortcutsDialog: (props) => {
		const tools = useTools()
		return (
			<DefaultKeyboardShortcutsDialog {...props}>
				<TldrawUiMenuItem {...tools['PlayingCard']} />
				<DefaultKeyboardShortcutsDialogContent />
			</DefaultKeyboardShortcutsDialog>
		)
	},
}

This file contains overrides for the Tldraw UI. These overrides are used to add your custom tools to
the toolbar and the keyboard shortcuts menu.

## playing-card-tool.tsx

```tsx
import { BaseBoxShapeTool } from 'tldraw'
export class PlayingCardTool extends BaseBoxShapeTool {
	static override id = 'PlayingCard'
	static override initial = 'idle'
	override shapeType = 'PlayingCard' as const
}

/*
This file contains our custom tool. The tool is a StateNode with the `id` "PlayingCard".

We get a lot of functionality for free by extending the BaseBoxShapeTool. but we can
handle events in our own way by overriding methods like onDoubleClick. For an example
of a tool with more custom functionality, check out the screenshot-tool example.

*/
```

## playing-card-util.tsx

```tsx
import {
	BaseBoxShapeUtil,
	BoundsSnapGeometry,
	HTMLContainer,
	RecordProps,
	Rectangle2d,
	T,
	TLShape,
} from 'tldraw'

// There's a guide at the bottom of this file!

const PLAYING_CARD_TYPE = 'PlayingCard'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[PLAYING_CARD_TYPE]: {
			w: number
			h: number
			suit: string
		}
	}
}

// [2]
export type IPlayingCard = TLShape<typeof PLAYING_CARD_TYPE>

export class PlayingCardUtil extends BaseBoxShapeUtil<IPlayingCard> {
	// [3]
	static override type = PLAYING_CARD_TYPE
	static override props: RecordProps<IPlayingCard> = {
		w: T.number,
		h: T.number,
		suit: T.string,
	}

// [4]
	override isAspectRatioLocked(_shape: IPlayingCard) {
		return true
	}

// [5]
	getDefaultProps(): IPlayingCard['props'] {
		const cardSuitsArray: string[] = ['♠️', '♣️', '♥️', '♦️']
		const randomSuit = cardSuitsArray[Math.floor(Math.random() * cardSuitsArray.length)]
		return {
			w: 270,
			h: 370,
			suit: randomSuit,
		}
	}

// [6]
	override getBoundsSnapGeometry(shape: IPlayingCard): BoundsSnapGeometry {
		return {
			points: new Rectangle2d({
				width: shape.props.h / 4.5,
				height: shape.props.h / 4.5,
				isFilled: true,
			}).bounds.cornersAndCenter,
		}
	}

// [7]
	component(shape: IPlayingCard) {
		return (
			<HTMLContainer
				style={{
					height: shape.props.h,
					width: shape.props.w,
					backgroundColor: 'white',
					boxShadow: '0 0 10px 0 rgba(0, 0, 0, 0.2)',
					position: 'relative',
					display: 'flex',
					justifyContent: 'center',
					alignItems: 'center',
					padding: 8,
				}}
				id={shape.id}
			>
				<span
					style={{
						position: 'absolute',
						top: 0,
						left: 0,
						display: 'flex',
						justifyContent: 'center',
						alignItems: 'center',
						height: shape.props.h / 4.5,
						width: shape.props.h / 4.5,
						fontSize: shape.props.h / 5,
					}}
				>
					{shape.props.suit}
				</span>
				<div style={{ fontSize: shape.props.h / 3 }}>{shape.props.suit}</div>
			</HTMLContainer>
		)
	}

// [8]
	indicator(shape: IPlayingCard) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

/*
This is a utility class for the PlayingCard shape. This is where you define the shape's behavior,
how it renders (its component and indicator), and how it handles different events. The most relevant
part of the code to custom snapping can be found in [7].

[2]
Define the shape type using TLShape with the shape's type as a type argument.

[3]
We define the shape's type and props for the editor. We can use tldraw's validator library to
make sure that the store always has shape data we can trust. In this case, we define the width
and height properties as numbers and assign a validator from tldraw's library to them.

[4]
We're going to lock the aspect ratio of this shape.

[5]
getDefaultProps determines what our shape looks like when click-creating one. In this case, we
want the shape to be 270x370 pixels and generate a suit for the card at random.

[6]
This is the important part for custom snapping. We define the getBoundsSnapGeometry method. This
method returns the geometry that the shape will snap to. In this case, we want the shape to snap
to a rectangle in the top left that contains the suit of the card. We can use the Rectangle2d helper
again here and set it to the same width and height as the span containing the suit which is defined
in [7].

[7]
We define the component method. This controls what the shape looks like and it returns JSX. It
generates a random suit for the card and returns a div with the suit in the center and a span with
the suit in the top left. The HTMLContainer component is a helpful wrapper that the tldraw library
exports, it's a div that comes with a css class.

[8]
The indicator is the blue box that appears around the shape when it's selected. We're just returning
a rectangle with the same width and height as the shape here.

*/
```

--------

# Custom validators for shape props

Category: Shapes & tools

Keywords: validation, validators, check, refine, constraints, props, custom, shape

Demonstrates using custom validators with `.check()` and `.refine()` methods to add validation constraints to shape props.

This example shows how to create custom validators for shape properties using `@tldraw/validate`. It demonstrates:

- Chaining `.check()` calls to add validation constraints without transforming values
- Using `.refine()` to validate and transform values

The example creates a custom shape with two validated properties:

1. **Percentage** - Chains multiple `.check()` calls to validate that the value is between 0 and 100. Invalid values throw an error.
2. **Rating** - Uses `.refine()` to clamp values to the 1-5 range. Invalid values are transformed rather than rejected.

When the example loads, it demonstrates both behaviors: attempting to create a shape with percentage=150 throws an error, while creating a shape with rating=10 succeeds but the value is clamped to 5.

## App.tsx

```tsx
import { HTMLContainer, RecordProps, Rectangle2d, ShapeUtil, T, TLShape, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		'validated-shape': {
			w: number
			h: number
			percentage: number
			rating: number
		}
	}
}

type ValidatedShape = TLShape<'validated-shape'>

// [2]
const validatedShapeProps: RecordProps<ValidatedShape> = {
	w: T.positiveNumber,
	h: T.positiveNumber,
	// [3]
	percentage: T.nonZeroFiniteNumber.check('max-value', (value) => {
		if (value > 100) throw new Error('Percentage cannot exceed 100')
	}),
	// [4]
	rating: T.integer.refine((value) => {
		return Math.max(1, Math.min(5, value))
	}),
}

class ValidatedShapeUtil extends ShapeUtil<ValidatedShape> {
	static override type = 'validated-shape' as const
	static override props = validatedShapeProps

getDefaultProps(): ValidatedShape['props'] {
		return { w: 300, h: 150, percentage: 50, rating: 3 }
	}

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

component(shape: ValidatedShape) {
		return (
			<HTMLContainer id={shape.id} style={{ padding: 16, pointerEvents: 'all' }}>
				<div>Percentage: {shape.props.percentage}%</div>
				<div>Rating: {shape.props.rating}/5</div>
			</HTMLContainer>
		)
	}

indicator(shape: ValidatedShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

// [5]
const customShapeUtils = [ValidatedShapeUtil]

export default function CustomValidatorsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				onMount={(editor) => {
					// [6]
					editor.createShape({ type: 'validated-shape', x: 100, y: 100 })

// [7]
					try {
						editor.createShape({
							type: 'validated-shape',
							x: 100,
							y: 300,
							props: { percentage: 150 },
						})
					} catch (error: any) {
						console.error('Validation failed:', error.message)
					}

// [8]
					editor.createShape({
						type: 'validated-shape',
						x: 450,
						y: 100,
						props: { rating: 10 }, // Will be clamped to 5
					})
				}}
			/>
		</div>
	)
}

/*
This example demonstrates custom validators using .check() and .refine() methods.

[1]
Extend TLGlobalShapePropsMap to register your custom shape's props with the type system.

[2]
Define validators for each prop. Each validator adds constraints beyond basic type checking.

[3]
Use .check() to add validation constraints. Each check validates without
transforming the value. The name (e.g. 'max-value') appears in error messages for debugging.

[4]
Use .refine() to transform values. Unlike .check(), refine() returns a (possibly modified)
value rather than just validating. Here it clamps the rating to 1-5 instead of throwing.

[5]
Create the shape utils array outside the component to prevent recreation on each render.

[6]
Create a valid shape on mount to show the default values.

[7]
Demonstrate .check() validation by attempting to create a shape with an invalid percentage.
Open your browser console to see the validation error.

[8]
Demonstrate .refine() transformation - this shape is created successfully with rating=10,
but the stored value is clamped to 5.
*/
```

--------

# Programmatic text shape creation

Category: Shapes & tools

Keywords: text, create, programmatic, autoSize, font, textAlign, richText, toRichText, bold, marks

Create and configure text shapes programmatically.

This example demonstrates how to create text shapes programmatically with various configuration options:

- **Auto-sized text** - Text shapes that automatically adjust width to fit content (`autoSize: true`)
- **Fixed-width text** - Text shapes with specified width that wrap content (`autoSize: false`, `w: number`)
- **Text alignment** - Horizontal alignment: `start` (left), `middle` (center), `end` (right)
- **Font styles** - Different fonts: `draw` (handdrawn), `sans`, `serif`, `mono`
- **Sizes** - Font sizes: `s`, `m`, `l`, `xl`
- **Rich text formatting** - Bold, italic, and other formatting using marks

Text shapes use rich text format internally. Use `toRichText('your text')` to convert plain text strings. For formatting like bold or italic, construct the rich text document with marks as shown in the example.

## App.tsx

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

export default function ProgrammaticTextShapeCreationAndConfigurationExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [1]
					editor.createShape({
						id: createShapeId(),
						type: 'text',
						x: 100,
						y: 100,
						props: {
							richText: toRichText('Auto-sized text'),
							size: 'l',
							color: 'blue',
							autoSize: true,
						},
					})

// [2]
					editor.createShape({
						id: createShapeId(),
						type: 'text',
						x: 100,
						y: 200,
						props: {
							richText: toRichText(
								'Fixed-width text that wraps when it reaches the specified width. This text will wrap to multiple lines.'
							),
							size: 'm',
							color: 'green',
							w: 300,
							autoSize: false,
						},
					})

// [3]
					editor.createShape({
						id: createShapeId(),
						type: 'text',
						x: 100,
						y: 400,
						props: {
							richText: toRichText('Center aligned'),
							size: 's',
							color: 'red',
							textAlign: 'middle',
							w: 200,
							autoSize: false,
						},
					})

// [4]
					editor.createShape({
						id: createShapeId(),
						type: 'text',
						x: 100,
						y: 500,
						props: {
							// Rich text with bold formatting using marks
							richText: {
								type: 'doc',
								content: [
									{
										type: 'paragraph',
										content: [{ type: 'text', text: 'Bold text', marks: [{ type: 'bold' }] }],
									},
								],
							},
							size: 'xl',
							color: 'orange',
							autoSize: true,
						},
					})

// [5]
					editor.createShape({
						id: createShapeId(),
						type: 'text',
						x: 100,
						y: 600,
						props: {
							richText: toRichText('Monospace font'),
							size: 'm',
							color: 'violet',
							font: 'mono',
							autoSize: true,
						},
					})

editor.zoomToFit({ animation: { duration: 0 } })
				}}
			/>
		</div>
	)
}

/*
[1]
Create an auto-sized text shape. When autoSize is true, the text shape automatically
adjusts its width to fit the content. This is the default behavior for text shapes.
Use toRichText() to convert plain text strings to the required rich text format.

[2]
Create a fixed-width text shape by setting autoSize to false and specifying a width.
The text will wrap when it reaches the specified width. This is useful for creating
text blocks with consistent formatting.

[3]
Create a text shape with center alignment. The textAlign property controls horizontal
text alignment within the shape: 'start' (left), 'middle' (center), or 'end' (right).

[4]
Create a text shape with bold formatting. To apply formatting like bold, italic, or
code, you need to construct the rich text document manually with marks. The marks array
on a text node specifies which formatting to apply. Available marks include 'bold',
'italic', 'code', 'link', and 'highlight'.

[5]
Create a text shape with a specific font. The font property supports 'draw' (handdrawn),
'sans' (sans-serif), 'serif' (serif), and 'mono' (monospace). The size property controls
the font size: 's', 'm', 'l', or 'xl'.

Note: The richText property requires a TLRichText object. Use toRichText('your text')
to convert plain text strings. For rich formatting with marks, construct the document
structure directly as shown in example [4].
*/
```

--------

# Data grid shape

Category: Shapes & tools

Keywords: data grid ag grid

A custom shape that renders AG Grid.

This example shows how to create a custom shape that renders AG Grid.

## App.tsx

```tsx
/* eslint-disable react-hooks/rules-of-hooks */
import { AgGridReact } from 'ag-grid-react'
import { BaseBoxShapeUtil, TLShape, Tldraw, createShapeId, useDelaySvgExport } from 'tldraw'

import 'ag-grid-community/styles/ag-grid.css'
import 'ag-grid-community/styles/ag-theme-quartz.css'
import 'tldraw/tldraw.css'

const AG_GRID_TYPE = 'ag-grid'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[AG_GRID_TYPE]: { w: number; h: number; rowData: any[]; columnDefs: any[] }
	}
}

type AgGridShape = TLShape<typeof AG_GRID_TYPE>

class AgGridShapeUtil extends BaseBoxShapeUtil<AgGridShape> {
	static override type = AG_GRID_TYPE

override canScroll(): boolean {
		return true
	}

override canEdit(): boolean {
		return true
	}

override getDefaultProps() {
		return {
			w: 300,
			h: 200,
			rowData: [],
			columnDefs: [],
		}
	}
	override component(shape: AgGridShape) {
		const isEditing = this.editor.getEditingShapeId() === shape.id
		const isReady = useDelaySvgExport()

return (
			<div
				style={{
					width: shape.props.w,
					height: shape.props.h,
					pointerEvents: isEditing ? 'all' : undefined,
				}}
				className="ag-theme-quartz"
			>
				<AgGridReact
					onGridReady={isReady}
					rowData={shape.props.rowData}
					columnDefs={shape.props.columnDefs}
					// autoSizeStrategy={{ type: 'f', width: shape.props.w }}
				/>
			</div>
		)
	}
	override indicator(shape: AgGridShape) {
		return <rect width={shape.props.w} height={shape.props.h} rx={8} ry={8} />
	}
}

export default function DataGridExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="ag-grid-example"
				shapeUtils={[AgGridShapeUtil]}
				onMount={(editor) => {
					const agGridShapeId = createShapeId('ag-grid')

if (!editor.getShape(agGridShapeId)) {
						editor.createShape({
							id: agGridShapeId,
							type: AG_GRID_TYPE,
							props: {
								w: 400,
								h: 300,
								rowData: [
									{ make: 'Tesla', model: 'Model Y', price: 64950, electric: true },
									{ make: 'Ford', model: 'F-Series', price: 33850, electric: false },
									{ make: 'Toyota', model: 'Corolla', price: 29600, electric: false },
								],
								columnDefs: [
									{ field: 'make', filter: true, floatingFilter: true, flex: 1 },
									{ field: 'model', flex: 1 },
									{ field: 'price', filter: true, floatingFilter: true, flex: 1 },
									{ field: 'electric', flex: 1 },
								],
							},
						})
						editor.select(agGridShapeId)
						editor.zoomToSelection()
					}
				}}
			/>
		</div>
	)
}
```

--------

# Drag and drop shape

Category: Shapes & tools

Keywords: reparent, shapes, grid, counter

Custom shapes that can be dragged and dropped onto each other.

This example shows how to create custom shapes that can be dragged and dropped onto each other.

## App.tsx

```tsx
import {
	Circle2d,
	Geometry2d,
	HTMLContainer,
	Rectangle2d,
	ShapeUtil,
	TLDragShapesOutInfo,
	TLShape,
	Tldraw,
} from 'tldraw'
import 'tldraw/tldraw.css'

const MY_GRID_SHAPE_TYPE = 'my-grid-shape'
const MY_COUNTER_SHAPE_TYPE = 'my-counter-shape'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_GRID_SHAPE_TYPE]: Record<string, never>
		[MY_COUNTER_SHAPE_TYPE]: Record<string, never>
	}
}

// [2]
type MyGridShape = TLShape<typeof MY_GRID_SHAPE_TYPE>
type MyCounterShape = TLShape<typeof MY_COUNTER_SHAPE_TYPE>

// [3]
const SLOT_SIZE = 100
class MyCounterShapeUtil extends ShapeUtil<MyCounterShape> {
	static override type = MY_COUNTER_SHAPE_TYPE

override canResize() {
		return false
	}
	override hideResizeHandles() {
		return true
	}

getDefaultProps(): MyCounterShape['props'] {
		return {}
	}

getGeometry(): Geometry2d {
		return new Circle2d({ radius: SLOT_SIZE / 2 - 10, isFilled: true })
	}

component() {
		return (
			<HTMLContainer
				style={{
					backgroundColor: '#e03131',
					border: '1px solid #ff8787',
					borderRadius: '50%',
				}}
			/>
		)
	}

indicator() {
		return <circle r={SLOT_SIZE / 2 - 10} cx={SLOT_SIZE / 2 - 10} cy={SLOT_SIZE / 2 - 10} />
	}
}

// [4]
class MyGridShapeUtil extends ShapeUtil<MyGridShape> {
	static override type = MY_GRID_SHAPE_TYPE

getDefaultProps(): MyGridShape['props'] {
		return {}
	}

getGeometry(): Geometry2d {
		return new Rectangle2d({
			width: SLOT_SIZE * 5,
			height: SLOT_SIZE * 2,
			isFilled: true,
		})
	}

override canResize() {
		return false
	}
	override hideResizeHandles() {
		return true
	}

// [5]
	override onDragShapesIn(shape: MyGridShape, draggingShapes: TLShape[]): void {
		const { editor } = this
		const reparentingShapes = draggingShapes.filter(
			(s) => s.parentId !== shape.id && s.type === 'my-counter-shape'
		)
		if (reparentingShapes.length === 0) return
		editor.reparentShapes(reparentingShapes, shape.id)
	}

// [6]
	override onDragShapesOut(
		shape: MyGridShape,
		draggingShapes: TLShape[],
		info: TLDragShapesOutInfo
	): void {
		const { editor } = this
		const reparentingShapes = draggingShapes.filter((s) => s.parentId !== shape.id)
		if (!info.nextDraggingOverShapeId) {
			editor.reparentShapes(reparentingShapes, editor.getCurrentPageId())
		}
	}

component() {
		return (
			<HTMLContainer
				style={{
					backgroundColor: '#efefef',
					borderRight: '1px solid #ccc',
					borderBottom: '1px solid #ccc',
					backgroundSize: `${SLOT_SIZE}px ${SLOT_SIZE}px`,
					backgroundImage: `
						linear-gradient(to right, #ccc 1px, transparent 1px),
						linear-gradient(to bottom, #ccc 1px, transparent 1px)
					`,
				}}
			/>
		)
	}

indicator() {
		return <rect width={SLOT_SIZE * 5} height={SLOT_SIZE * 2} />
	}
}

export default function DragAndDropExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={[MyGridShapeUtil, MyCounterShapeUtil]}
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size > 0) return
					editor.createShape({ type: 'my-grid-shape', x: 100, y: 100 })
					editor.createShape({ type: 'my-counter-shape', x: 700, y: 100 })
					editor.createShape({ type: 'my-counter-shape', x: 750, y: 200 })
					editor.createShape({ type: 'my-counter-shape', x: 770, y: 300 })
				}}
			/>
		</div>
	)
}

/*
[1]
First, we need to extend TLGlobalShapePropsMap to add our shape's props to the global type system.
This tells TypeScript about the shape's properties. Here we use Record<string, never> since our shapes
don't need any custom properties. These are very basic custom shapes: see the custom shape examples for
more complex examples.

[2]
Define the shape types using TLShape with each shape's type as a type argument.

[3]
Create a ShapeUtil for the counter shape. This defines how the shape behaves and renders. We disable resizing
and use Circle2d geometry for collision detection. The component renders as a red circle using HTMLContainer.

[4]
Create a ShapeUtil for the grid shape. This creates a rectangular grid that can accept dropped shapes. We use
Rectangle2d geometry and render it with CSS grid lines using background gradients.

[5]
Override onDragShapesIn to handle when shapes are dragged into the grid. We filter for counter shapes that
aren't already children of this grid, then reparent them to become children. This makes them move with the grid.

[6]
Override onDragShapesOut to handle when shapes are dragged out of the grid. If they're not being dragged to
another shape, we reparent them back to the page level, making them independent again.
*/
```

--------

# Attach shapes together (bindings)

Category: Shapes & tools

Keywords: attach

A sticker shape, using bindings to attach shapes to one and other

This example shows how to use bindings to attach shapes together. In this case, we've created a sticker that can be stuck onto other shapes.

## App.tsx

```tsx
import {
	BindingOnShapeChangeOptions,
	BindingOnShapeDeleteOptions,
	BindingUtil,
	Box,
	DefaultToolbar,
	DefaultToolbarContent,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	StateNode,
	TLBinding,
	TLPointerEventInfo,
	TLShape,
	TLUiComponents,
	TLUiOverrides,
	Tldraw,
	TldrawUiMenuItem,
	VecModel,
	createShapeId,
	invLerp,
	lerp,
	useIsToolSelected,
	useTools,
} from 'tldraw'
import 'tldraw/tldraw.css'

const STICKER_TYPE = 'sticker'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[STICKER_TYPE]: Record<string, never>
	}
}

type StickerShape = TLShape<typeof STICKER_TYPE>

const offsetX = -16
const offsetY = -26
class StickerShapeUtil extends ShapeUtil<StickerShape> {
	static override type = STICKER_TYPE
	static override props: RecordProps<StickerShape> = {}

override getDefaultProps() {
		return {}
	}

override canBind() {
		// stickers can bind to anything
		return true
	}
	override canEdit() {
		return false
	}
	override canResize() {
		return false
	}
	override canSnap() {
		return false
	}
	override hideRotateHandle() {
		return true
	}
	override isAspectRatioLocked() {
		return true
	}

override getGeometry() {
		return new Rectangle2d({
			width: 32,
			height: 32,
			x: offsetX,
			y: offsetY,
			isFilled: true,
		})
	}

override component() {
		return (
			<div
				style={{
					width: '100%',
					height: '100%',
					marginLeft: offsetX,
					marginTop: offsetY,
					fontSize: '26px',
					textAlign: 'center',
				}}
			>
				❤️
			</div>
		)
	}

override indicator() {
		return <rect width={32} height={32} x={offsetX} y={offsetY} />
	}

override onTranslateStart(shape: StickerShape) {
		const bindings = this.editor.getBindingsFromShape(shape, STICKER_TYPE)
		this.editor.deleteBindings(bindings)
	}

override onTranslateEnd(_initial: StickerShape, sticker: StickerShape) {
		const pageAnchor = this.editor.getShapePageTransform(sticker).applyToPoint({ x: 0, y: 0 })
		const target = this.editor.getShapeAtPoint(pageAnchor, {
			hitInside: true,
			filter: (shape) =>
				shape.id !== sticker.id &&
				this.editor.canBindShapes({ fromShape: sticker, toShape: shape, binding: STICKER_TYPE }),
		})

if (!target) return

const targetBounds = Box.ZeroFix(this.editor.getShapeGeometry(target)!.bounds)
		const pointInTargetSpace = this.editor.getPointInShapeSpace(target, pageAnchor)

const anchor = {
			x: invLerp(targetBounds.minX, targetBounds.maxX, pointInTargetSpace.x),
			y: invLerp(targetBounds.minY, targetBounds.maxY, pointInTargetSpace.y),
		}

this.editor.createBinding({
			type: STICKER_TYPE,
			fromId: sticker.id,
			toId: target.id,
			props: {
				anchor,
			},
		})
	}
}

declare module 'tldraw' {
	export interface TLGlobalBindingPropsMap {
		[STICKER_TYPE]: {
			anchor: VecModel
		}
	}
}

type StickerBinding = TLBinding<typeof STICKER_TYPE>

class StickerBindingUtil extends BindingUtil<StickerBinding> {
	static override type = STICKER_TYPE

override getDefaultProps() {
		return {
			anchor: { x: 0.5, y: 0.5 },
		}
	}

// when the shape we're stuck to changes, update the sticker's position
	override onAfterChangeToShape({
		binding,
		shapeAfter,
	}: BindingOnShapeChangeOptions<StickerBinding>): void {
		const sticker = this.editor.getShape<StickerShape>(binding.fromId)!

const shapeBounds = this.editor.getShapeGeometry(shapeAfter)!.bounds
		const shapeAnchor = {
			x: lerp(shapeBounds.minX, shapeBounds.maxX, binding.props.anchor.x),
			y: lerp(shapeBounds.minY, shapeBounds.maxY, binding.props.anchor.y),
		}
		const pageAnchor = this.editor.getShapePageTransform(shapeAfter).applyToPoint(shapeAnchor)

const stickerParentAnchor = this.editor
			.getShapeParentTransform(sticker)
			.invert()
			.applyToPoint(pageAnchor)

this.editor.updateShape({
			id: sticker.id,
			type: STICKER_TYPE,
			x: stickerParentAnchor.x,
			y: stickerParentAnchor.y,
		})
	}

// when the thing we're stuck to is deleted, delete the sticker too
	override onBeforeDeleteToShape({ binding }: BindingOnShapeDeleteOptions<StickerBinding>): void {
		this.editor.deleteShape(binding.fromId)
	}
}

class StickerTool extends StateNode {
	static override id = 'sticker'

override onEnter() {
		this.editor.setCursor({ type: 'cross', rotation: 0 })
	}

override onPointerDown(info: TLPointerEventInfo) {
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		const stickerId = createShapeId()
		this.editor.markHistoryStoppingPoint()
		this.editor.createShape({
			id: stickerId,
			type: STICKER_TYPE,
			x: currentPagePoint.x,
			y: currentPagePoint.y,
		})
		this.editor.setSelectedShapes([stickerId])
		this.editor.setCurrentTool('select.translating', {
			...info,
			target: 'shape',
			shape: this.editor.getShape(stickerId),
			isCreating: true,
			onInteractionEnd: 'sticker',
			onCreate: () => {
				this.editor.setCurrentTool('sticker')
			},
		})
	}
}

const overrides: TLUiOverrides = {
	tools(editor, schema) {
		schema['sticker'] = {
			id: 'sticker',
			label: 'Sticker',
			icon: 'heart-icon',
			kbd: 'p',
			onSelect: () => {
				editor.setCurrentTool('sticker')
			},
		}
		return schema
	},
}

const components: TLUiComponents = {
	Toolbar: (...props) => {
		const sticker = useTools().sticker
		const isStickerSelected = useIsToolSelected(sticker)
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...sticker} isSelected={isStickerSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
}

export default function StickerExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					;(window as any).editor = editor
				}}
				shapeUtils={[StickerShapeUtil]}
				bindingUtils={[StickerBindingUtil]}
				tools={[StickerTool]}
				overrides={overrides}
				components={components}
			/>
		</div>
	)
}
```

--------

# DOM-based shape size

Category: Shapes & tools

Keywords: dom, size, custom, dynamic, shape

A custom shape who's size is derived from it's rendered DOM.

## App.tsx

```tsx
/* eslint-disable react-hooks/rules-of-hooks */
import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
import {
	AtomMap,
	EditorAtom,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	T,
	Tldraw,
	TLShape,
	TLShapeId,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { contents } from './contents'

const DYNAMIC_SIZE_TYPE = 'dynamic-size'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[DYNAMIC_SIZE_TYPE]: { contents: string[] }
	}
}

// There's a guide at the bottom of this file!

const SHAPE_WIDTH_PX = 150

// [2]
type DynamicSizeShape = TLShape<typeof DYNAMIC_SIZE_TYPE>

// [3]
const ShapeSizes = new EditorAtom('shape sizes', (editor) => {
	const map = new AtomMap<TLShapeId, { width: number; height: number }>('shape sizes')

// [a] Clean up sizes when shapes are deleted
	editor.sideEffects.registerAfterDeleteHandler('shape', (shape) => {
		map.delete(shape.id)
	})

return map
})

// [4]
function useDynamicShapeSize(shape: DynamicSizeShape) {
	const ref = useRef<HTMLDivElement>(null)
	const editor = useEditor()

const updateShapeSize = useCallback(() => {
		if (!ref.current) return

// [a] Get actual DOM dimensions
		const width = ref.current.offsetWidth
		const height = ref.current.offsetHeight

// [b] Update the shape size in our global atom
		ShapeSizes.update(editor, (map) => {
			const existing = map.get(shape.id)
			if (existing && existing.width === width && existing.height === height) return map
			return map.set(shape.id, { width, height })
		})
	}, [editor, shape.id])

// [c] Update size immediately on render
	useLayoutEffect(() => {
		updateShapeSize()
	})

// [d] Watch for DOM size changes using ResizeObserver
	useLayoutEffect(() => {
		if (!ref.current) return
		const observer = new ResizeObserver(updateShapeSize)
		observer.observe(ref.current)
		return () => {
			observer.disconnect()
		}
	}, [updateShapeSize])

return ref
}

// [5]
export class DynamicSizeShapeUtil extends ShapeUtil<DynamicSizeShape> {
	// [a]
	static override type = DYNAMIC_SIZE_TYPE
	static override props: RecordProps<DynamicSizeShape> = {
		contents: T.arrayOf(T.string),
	}

// [b]
	getDefaultProps(): DynamicSizeShape['props'] {
		return {
			contents,
		}
	}

// [c]
	override canCull() {
		return false
	}

// [d]
	override canEdit() {
		return false
	}
	override canResize() {
		return false
	}
	override isAspectRatioLocked() {
		return true
	}

// [e]
	getGeometry(shape: DynamicSizeShape) {
		const size = ShapeSizes.get(this.editor).get(shape.id)
		return new Rectangle2d({
			width: SHAPE_WIDTH_PX,
			height: size?.height ?? 50,
			isFilled: true,
		})
	}

// [f]
	component(shape: DynamicSizeShape) {
		const ref = useDynamicShapeSize(shape)

const [contentsToShow, setContentsToShow] = useState<string>('')

// [i] Animate text content to demonstrate dynamic sizing
		useEffect(() => {
			const animationDuration = 6000
			const tick = (time: number) => {
				const progress = (time % animationDuration) / animationDuration
				const amountToShow = progress < 0.5 ? progress * 2 : 1 - (progress - 0.5) * 2

setContentsToShow(
					shape.props.contents
						.slice(0, Math.floor(amountToShow * shape.props.contents.length))
						.join(' ')
				)

frame = requestAnimationFrame(tick)
			}

let frame = requestAnimationFrame(tick)

return () => {
				cancelAnimationFrame(frame)
			}
		}, [shape.props.contents])

// [ii] Return DOM element that will be measured
		return (
			<div ref={ref} style={{ width: SHAPE_WIDTH_PX }}>
				{contentsToShow}
			</div>
		)
	}

// [g]
	indicator(shape: DynamicSizeShape) {
		const { width, height } = this.editor.getShapeGeometry(shape).bounds

return <rect width={width} height={height} />
	}
}

// [6]
const shapeUtils = [DynamicSizeShapeUtil]

export default function SizeFromDomExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				onMount={(editor) => {
					editor.selectAll()
					editor.deleteShapes(editor.getSelectedShapeIds())

editor.createShape({
						type: DYNAMIC_SIZE_TYPE,
						x: 100,
						y: 100,
					})

editor.selectAll().zoomToSelection()
				}}
			/>
		</div>
	)
}

/*
Introduction:

This example demonstrates how to create a shape whose size is determined by its DOM content rather than
shape props. It showcases two potentially reusable utilities: ShapeSizes and useDynamicShapeSize, which
can be adapted for other shapes that need DOM-driven sizing.

[1]
First, we need to extend TLGlobalShapePropsMap to add our shape's props to the global type system.
This tells TypeScript about the shape's properties.

[2]
Define the shape type. This shape only stores content data - its size is determined dynamically by
measuring the DOM element that renders the content.

[3]
ShapeSizes is a global EditorAtom that stores size information for shapes by their ID. This is the key
piece that makes DOM-driven sizing work:

[a] We register a cleanup handler to remove size data when shapes are deleted, preventing memory leaks.

[4]
useDynamicShapeSize is a reusable hook that measures DOM elements and updates the shape size data:

[a] We measure the actual DOM dimensions using offsetWidth/offsetHeight

[b] We store these dimensions in our global ShapeSizes atom. The atom will trigger re-renders of
	    components that depend on this data when the size changes.

[c] We measure immediately on every render to ensure we have current size data

[d] We use ResizeObserver to watch for size changes and update accordingly. This is what makes
	    the shape truly dynamic - it will update whenever the DOM content changes size.

[5]
The shape util defines how our dynamic-size shape behaves:

[a] Standard shape type and props definition. Note we only store content, not size.

[b] Default props with some sample content

[c] Prevent the shape from being culled when it's outside the viewport, which would break our measurements

[d] Shape behavior: not editable, not resizable (since size comes from DOM), aspect ratio locked

[e] getGeometry uses the size from our ShapeSizes atom. This is where the DOM-measured size gets
	    used by the editor for hit-testing, selection bounds, etc.

[f] The component renders the content and uses our hook to measure it:

[i] We animate the text content to demonstrate the dynamic sizing in action

[ii] The ref from useDynamicShapeSize is attached to the DOM element we want to measure

[g] Standard indicator for selection outline

[6]
Standard setup - pass our custom shape util to Tldraw and create an instance on mount.

Reusability:

The ShapeSizes atom and useDynamicShapeSize hook are designed to be reusable. To use them with other
shapes, you just need to:
1. Call useDynamicShapeSize(shape) in your component and attach the returned ref
2. Use ShapeSizes.get(editor).get(shapeId) in your getGeometry method
3. Ensure your shape doesn't have conflicting size props (or handle the conflict appropriately)

*/
```

## contents.ts

```ts
export const contents = `
Have five minutes? Let's try out the tldraw SDK in a React project. If you're new to React, we recommend using a Vite template as a starter. We'll assume your project is already running locally.

Prefer to jump straight to some code? Try this sandbox.

First, install the tldraw package from NPM:

npm install tldraw

Next, in your React project, import the Tldraw component and tldraw's CSS styles. Then render the Tldraw component inside a full screen container:

That's pretty much it! At this point, you should have a complete working single-user canvas. You can draw and write on the canvas, add images and video, zoom and pan, copy and paste, undo and redo, and do just about everything else you'd expect to do on a canvas.

You'll be starting from our default shapes, tools, and user interface, but you can customize all of these things for your project if you wish. For now, let's show off a few more features.
`
	.replace(/\n/g, '')
	.replace(/\s+/g, ' ')
	.split(' ')
```

--------

# Layout constraints (bindings)

Category: Shapes & tools

Keywords: constraints, group, shape, custom, bindings, drag, drop, position

How to constrain shapes to a layout using bindings.

You can use bindings to make shapes respond to changes to other shapes. This is useful for enforcing layout constraints

## App.tsx

```tsx
import {
	BindingOnChangeOptions,
	BindingOnCreateOptions,
	BindingOnDeleteOptions,
	BindingOnShapeChangeOptions,
	BindingUtil,
	HTMLContainer,
	IndexKey,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	T,
	TLBinding,
	TLShape,
	Tldraw,
	Vec,
	clamp,
	createBindingId,
	getIndexBetween,
} from 'tldraw'
import 'tldraw/tldraw.css'
import snapShot from './snapshot.json'

const CONTAINER_TYPE = 'container'
const ELEMENT_TYPE = 'element'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[CONTAINER_TYPE]: { height: number; width: number }
		[ELEMENT_TYPE]: { color: string }
	}
}

// The container shapes that can contain element shapes

const CONTAINER_PADDING = 24

type ContainerShape = TLShape<typeof CONTAINER_TYPE>

class ContainerShapeUtil extends ShapeUtil<ContainerShape> {
	static override type = CONTAINER_TYPE
	static override props: RecordProps<ContainerShape> = { height: T.number, width: T.number }

override getDefaultProps() {
		return {
			width: 100 + CONTAINER_PADDING * 2,
			height: 100 + CONTAINER_PADDING * 2,
		}
	}

override canBind({
		fromShapeType,
		toShapeType,
		bindingType,
	}: {
		fromShapeType: string
		toShapeType: string
		bindingType: string
	}) {
		return fromShapeType === 'container' && toShapeType === 'element' && bindingType === LAYOUT_TYPE
	}
	override canEdit() {
		return false
	}
	override canResize() {
		return false
	}
	override hideRotateHandle() {
		return true
	}
	override isAspectRatioLocked() {
		return true
	}

override getGeometry(shape: ContainerShape) {
		return new Rectangle2d({
			width: shape.props.width,
			height: shape.props.height,
			isFilled: true,
		})
	}

override component(shape: ContainerShape) {
		return (
			<HTMLContainer
				style={{
					backgroundColor: '#efefef',
					width: shape.props.width,
					height: shape.props.height,
				}}
			/>
		)
	}

override indicator(shape: ContainerShape) {
		return <rect width={shape.props.width} height={shape.props.height} />
	}
}

// The element shapes that can be placed inside the container shapes

type ElementShape = TLShape<typeof ELEMENT_TYPE>

class ElementShapeUtil extends ShapeUtil<ElementShape> {
	static override type = ELEMENT_TYPE
	static override props: RecordProps<ElementShape> = {
		color: T.string,
	}

override getDefaultProps() {
		return {
			color: '#AEC6CF',
		}
	}

override getGeometry() {
		return new Rectangle2d({
			width: 100,
			height: 100,
			isFilled: true,
		})
	}

override component(shape: ElementShape) {
		return <HTMLContainer style={{ backgroundColor: shape.props.color }}></HTMLContainer>
	}

override indicator() {
		return <rect width={100} height={100} />
	}

private getTargetContainer(shape: ElementShape, pageAnchor: Vec) {
		// Find the container shape that the element is being dropped on
		return this.editor.getShapeAtPoint(pageAnchor, {
			hitInside: true,
			filter: (otherShape) =>
				this.editor.canBindShapes({ fromShape: otherShape, toShape: shape, binding: LAYOUT_TYPE }),
		}) as ContainerShape | undefined
	}

getBindingIndexForPosition(shape: ElementShape, container: ContainerShape, pageAnchor: Vec) {
		// All the layout bindings from the container
		const allBindings = this.editor
			.getBindingsFromShape(container, LAYOUT_TYPE)
			.sort((a, b) => (a.props.index > b.props.index ? 1 : -1))

// Those bindings that don't involve the element
		const siblings = allBindings.filter((b) => b.toId !== shape.id)

// Get the relative x position of the element center in the container
		// Where should the element be placed? min index at left, max index + 1
		const order = clamp(
			Math.round((pageAnchor.x - container.x - CONTAINER_PADDING) / (100 + CONTAINER_PADDING)),
			0,
			siblings.length + 1
		)

// Get a fractional index between the two siblings
		const belowSib = allBindings[order - 1]
		const aboveSib = allBindings[order]
		let index: IndexKey

if (belowSib?.toId === shape.id) {
			index = belowSib.props.index
		} else if (aboveSib?.toId === shape.id) {
			index = aboveSib.props.index
		} else {
			index = getIndexBetween(belowSib?.props.index, aboveSib?.props.index)
		}

return index
	}

override onTranslateStart(shape: ElementShape) {
		// Update all the layout bindings for this shape to be placeholders
		this.editor.updateBindings(
			this.editor.getBindingsToShape(shape, LAYOUT_TYPE).map((binding) => ({
				...binding,
				props: { ...binding.props, placeholder: true },
			}))
		)
	}

override onTranslate(_: ElementShape, shape: ElementShape) {
		// Find the center of the element shape
		const pageAnchor = this.editor.getShapePageTransform(shape).applyToPoint({ x: 50, y: 50 })

// Find the container shape that the element is being dropped on
		const targetContainer = this.getTargetContainer(shape, pageAnchor)

if (!targetContainer) {
			// Delete all the bindings to the element
			const bindings = this.editor.getBindingsToShape(shape, LAYOUT_TYPE)
			this.editor.deleteBindings(bindings)
			return
		}

// Get the index for the new binding
		const index = this.getBindingIndexForPosition(shape, targetContainer, pageAnchor)

// Is there an existing binding already between the container and the shape?
		const existingBinding = this.editor
			.getBindingsFromShape(targetContainer, LAYOUT_TYPE)
			.find((b) => b.toId === shape.id)

if (existingBinding) {
			// If a binding already exists, update it
			if (existingBinding.props.index === index) return
			this.editor.updateBinding({
				...existingBinding,
				props: {
					...existingBinding.props,
					placeholder: true,
					index,
				},
			})
		} else {
			// ...otherwise, create a new one
			this.editor.createBinding({
				id: createBindingId(),
				type: LAYOUT_TYPE,
				fromId: targetContainer.id,
				toId: shape.id,
				props: {
					index,
					placeholder: true,
				},
			})
		}
	}

override onTranslateEnd(_: ElementShape, shape: ElementShape) {
		// Find the center of the element shape
		const pageAnchor = this.editor.getShapePageTransform(shape).applyToPoint({ x: 50, y: 50 })

// Find the container shape that the element is being dropped on
		const targetContainer = this.getTargetContainer(shape, pageAnchor)

// No target container? no problem
		if (!targetContainer) return

// get the index for the new binding
		const index = this.getBindingIndexForPosition(shape, targetContainer, pageAnchor)

// delete all the previous bindings for this shape
		this.editor.deleteBindings(this.editor.getBindingsToShape(shape, LAYOUT_TYPE))

// ...and then create a new one
		this.editor.createBinding({
			id: createBindingId(),
			type: LAYOUT_TYPE,
			fromId: targetContainer.id,
			toId: shape.id,
			props: {
				index,
				placeholder: false,
			},
		})
	}
}

// The binding between the element shapes and the container shapes

const LAYOUT_TYPE = 'layout'

declare module 'tldraw' {
	export interface TLGlobalBindingPropsMap {
		[LAYOUT_TYPE]: {
			index: IndexKey
			placeholder: boolean
		}
	}
}

type LayoutBinding = TLBinding<typeof LAYOUT_TYPE>

class LayoutBindingUtil extends BindingUtil<LayoutBinding> {
	static override type = LAYOUT_TYPE

override getDefaultProps() {
		return {
			index: 'a1' as IndexKey,
			placeholder: true,
		}
	}

override onAfterCreate({ binding }: BindingOnCreateOptions<LayoutBinding>): void {
		this.updateElementsForContainer(binding)
	}

override onAfterChange({ bindingAfter }: BindingOnChangeOptions<LayoutBinding>): void {
		this.updateElementsForContainer(bindingAfter)
	}

override onAfterChangeFromShape({ binding }: BindingOnShapeChangeOptions<LayoutBinding>): void {
		this.updateElementsForContainer(binding)
	}

override onAfterDelete({ binding }: BindingOnDeleteOptions<LayoutBinding>): void {
		this.updateElementsForContainer(binding)
	}

private updateElementsForContainer({
		props: { placeholder },
		fromId: containerId,
		toId,
	}: LayoutBinding) {
		// Get all of the bindings from the layout container
		const container = this.editor.getShape<ContainerShape>(containerId)
		if (!container) return

const bindings = this.editor
			.getBindingsFromShape(container, LAYOUT_TYPE)
			.sort((a, b) => (a.props.index > b.props.index ? 1 : -1))
		if (bindings.length === 0) return

for (let i = 0; i < bindings.length; i++) {
			const binding = bindings[i]

if (toId === binding.toId && placeholder) continue

const offset = new Vec(CONTAINER_PADDING + i * (100 + CONTAINER_PADDING), CONTAINER_PADDING)

const shape = this.editor.getShape<ElementShape>(binding.toId)
			if (!shape) continue

const point = this.editor.getPointInParentSpace(
				shape,
				this.editor.getShapePageTransform(container)!.applyToPoint(offset)
			)

if (shape.x !== point.x || shape.y !== point.y) {
				this.editor.updateShape({
					id: binding.toId,
					type: 'element',
					x: point.x,
					y: point.y,
				})
			}
		}

const width =
			CONTAINER_PADDING +
			(bindings.length * 100 + (bindings.length - 1) * CONTAINER_PADDING) +
			CONTAINER_PADDING

const height = CONTAINER_PADDING + 100 + CONTAINER_PADDING

if (width !== container.props.width || height !== container.props.height) {
			this.editor.updateShape({
				id: container.id,
				type: 'container',
				props: { width, height },
			})
		}
	}
}

export default function LayoutExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// @ts-ignore
				snapshot={snapShot}
				onMount={(editor) => {
					;(window as any).editor = editor
				}}
				shapeUtils={[ContainerShapeUtil, ElementShapeUtil]}
				bindingUtils={[LayoutBindingUtil]}
			/>
		</div>
	)
}
```

--------

# Pin (bindings)

Category: Shapes & tools

Keywords:

A pin, using bindings to pin together networks of shapes.

This example shows how to use bindings to connect a network of shapes together.

To try it out, select the pin tool, then click over two overlapping shapes to pin them together.

## App.tsx

```tsx
import {
	BindingOnShapeChangeOptions,
	BindingOnShapeDeleteOptions,
	BindingUtil,
	Box,
	DefaultFillStyle,
	DefaultToolbar,
	DefaultToolbarContent,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	StateNode,
	TLBinding,
	TLEditorComponents,
	TLPointerEventInfo,
	TLShape,
	TLShapeId,
	TLShapePartial,
	TLShapeUtilCanBindOpts,
	TLUiComponents,
	TLUiOverrides,
	Tldraw,
	TldrawUiMenuItem,
	Vec,
	VecModel,
	createShapeId,
	invLerp,
	lerp,
	useIsToolSelected,
	useTools,
} from 'tldraw'
import 'tldraw/tldraw.css'

const PIN_TYPE = 'pin'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[PIN_TYPE]: Record<string, never>
	}
}

type PinShape = TLShape<typeof PIN_TYPE>

const offsetX = -16
const offsetY = -26
class PinShapeUtil extends ShapeUtil<PinShape> {
	static override type = PIN_TYPE
	static override props: RecordProps<PinShape> = {}

override getDefaultProps() {
		return {}
	}

override canBind({ toShapeType, bindingType }: TLShapeUtilCanBindOpts<PinShape>) {
		if (bindingType === PIN_TYPE) {
			// pins cannot bind to other pins!
			return toShapeType !== PIN_TYPE
		}
		// Allow pins to participate in other bindings, e.g. arrows
		return true
	}
	override canEdit() {
		return false
	}
	override canResize() {
		return false
	}
	override hideRotateHandle() {
		return true
	}
	override isAspectRatioLocked() {
		return true
	}

override getGeometry() {
		return new Rectangle2d({
			width: 32,
			height: 32,
			x: offsetX,
			y: offsetY,
			isFilled: true,
		})
	}

override component() {
		return (
			<div
				style={{
					width: '100%',
					height: '100%',
					marginLeft: offsetX,
					marginTop: offsetY,
					fontSize: '26px',
					textAlign: 'center',
				}}
			>
				📍
			</div>
		)
	}

override indicator() {
		return <rect width={32} height={32} x={offsetX} y={offsetY} />
	}

override onTranslateStart(shape: PinShape) {
		const bindings = this.editor.getBindingsFromShape(shape, PIN_TYPE)
		this.editor.deleteBindings(bindings)
	}

override onTranslateEnd(_initial: PinShape, pin: PinShape) {
		const pageAnchor = this.editor.getShapePageTransform(pin).applyToPoint({ x: 0, y: 0 })

const targets = this.editor
			.getShapesAtPoint(pageAnchor, { hitInside: true })
			.filter(
				(shape) =>
					this.editor.canBindShapes({ fromShape: pin, toShape: shape, binding: PIN_TYPE }) &&
					shape.parentId === pin.parentId &&
					shape.index < pin.index
			)

for (const target of targets) {
			const targetBounds = Box.ZeroFix(this.editor.getShapeGeometry(target)!.bounds)
			const pointInTargetSpace = this.editor.getPointInShapeSpace(target, pageAnchor)

const anchor = {
				x: invLerp(targetBounds.minX, targetBounds.maxX, pointInTargetSpace.x),
				y: invLerp(targetBounds.minY, targetBounds.maxY, pointInTargetSpace.y),
			}

this.editor.createBinding({
				type: PIN_TYPE,
				fromId: pin.id,
				toId: target.id,
				props: {
					anchor,
				},
			})
		}
	}
}

declare module 'tldraw' {
	export interface TLGlobalBindingPropsMap {
		[PIN_TYPE]: {
			anchor: VecModel
		}
	}
}

type PinBinding = TLBinding<typeof PIN_TYPE>

class PinBindingUtil extends BindingUtil<PinBinding> {
	static override type = PIN_TYPE

override getDefaultProps() {
		return {
			anchor: { x: 0.5, y: 0.5 },
		}
	}

private changedToShapes = new Set<TLShapeId>()

override onOperationComplete(): void {
		if (this.changedToShapes.size === 0) return

const fixedShapes = this.changedToShapes
		const toCheck = [...this.changedToShapes]

const initialPositions = new Map<TLShapeId, VecModel>()
		const targetDeltas = new Map<TLShapeId, Map<TLShapeId, VecModel>>()

const addTargetDelta = (fromId: TLShapeId, toId: TLShapeId, delta: VecModel) => {
			if (!targetDeltas.has(fromId)) targetDeltas.set(fromId, new Map())
			targetDeltas.get(fromId)!.set(toId, delta)

if (!targetDeltas.has(toId)) targetDeltas.set(toId, new Map())
			targetDeltas.get(toId)!.set(fromId, { x: -delta.x, y: -delta.y })
		}

const allShapes = new Set<TLShapeId>()
		while (toCheck.length) {
			const shapeId = toCheck.pop()!

const shape = this.editor.getShape(shapeId)
			if (!shape) continue

if (allShapes.has(shapeId)) continue
			allShapes.add(shapeId)

const bindings = this.editor.getBindingsToShape(shape, PIN_TYPE)
			for (const binding of bindings) {
				if (allShapes.has(binding.fromId)) continue
				allShapes.add(binding.fromId)

const pin = this.editor.getShape<PinShape>(binding.fromId)
				if (!pin) continue

const pinPosition = this.editor.getShapePageTransform(pin).applyToPoint({ x: 0, y: 0 })
				initialPositions.set(pin.id, pinPosition)

for (const binding of this.editor.getBindingsFromShape(pin.id, PIN_TYPE)) {
					const shapeBounds = this.editor.getShapeGeometry(binding.toId)!.bounds
					const shapeAnchor = {
						x: lerp(shapeBounds.minX, shapeBounds.maxX, binding.props.anchor.x),
						y: lerp(shapeBounds.minY, shapeBounds.maxY, binding.props.anchor.y),
					}
					const currentPageAnchor = this.editor
						.getShapePageTransform(binding.toId)
						.applyToPoint(shapeAnchor)

const shapeOrigin = this.editor
						.getShapePageTransform(binding.toId)
						.applyToPoint({ x: 0, y: 0 })
					initialPositions.set(binding.toId, shapeOrigin)

addTargetDelta(pin.id, binding.toId, {
						x: currentPageAnchor.x - shapeOrigin.x,
						y: currentPageAnchor.y - shapeOrigin.y,
					})

if (!allShapes.has(binding.toId)) toCheck.push(binding.toId)
				}
			}
		}

const currentPositions = new Map(initialPositions)

const iterations = 30
		for (let i = 0; i < iterations; i++) {
			const movements = new Map<TLShapeId, VecModel[]>()
			for (const [aId, deltas] of targetDeltas) {
				if (fixedShapes.has(aId)) continue
				const aPosition = currentPositions.get(aId)!
				for (const [bId, targetDelta] of deltas) {
					const bPosition = currentPositions.get(bId)!

const adjustmentDelta = {
						x: targetDelta.x - (aPosition.x - bPosition.x),
						y: targetDelta.y - (aPosition.y - bPosition.y),
					}

if (!movements.has(aId)) movements.set(aId, [])
					movements.get(aId)!.push(adjustmentDelta)
				}
			}

for (const [shapeId, deltas] of movements) {
				const currentPosition = currentPositions.get(shapeId)!
				currentPositions.set(shapeId, Vec.Average(deltas).add(currentPosition))
			}
		}

const updates: TLShapePartial[] = []
		for (const [shapeId, position] of currentPositions) {
			const delta = Vec.Sub(position, initialPositions.get(shapeId)!)
			if (delta.len2() <= 0.01) continue

const newPosition = this.editor.getPointInParentSpace(shapeId, position)
			updates.push({
				...this.editor.getShape(shapeId)!,
				id: shapeId,
				x: newPosition.x,
				y: newPosition.y,
			})
		}

if (updates.length === 0) {
			this.changedToShapes.clear()
		} else {
			this.editor.updateShapes(updates)
		}
	}

// when the shape we're stuck to changes, update the pin's position
	override onAfterChangeToShape({
		binding,
		shapeAfter,
	}: BindingOnShapeChangeOptions<PinBinding>): void {
		this.changedToShapes.add(binding.toId)
		const pin = this.editor.getShape(binding.fromId)
		if (!pin) return

// If the bound shape changed parents, reparent the pin to follow
		if (pin.parentId !== shapeAfter.parentId) {
			this.editor.reparentShapes([pin.id], shapeAfter.parentId)
		}
	}

// when the thing we're stuck to is deleted, delete the pin too
	override onBeforeDeleteToShape({ binding }: BindingOnShapeDeleteOptions<PinBinding>): void {
		this.editor.deleteShape(binding.fromId)
	}
}

class PinTool extends StateNode {
	static override id = PIN_TYPE

override onEnter() {
		this.editor.setCursor({ type: 'cross', rotation: 0 })
	}

override onPointerDown(info: TLPointerEventInfo) {
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		const pinId = createShapeId()
		this.editor.markHistoryStoppingPoint()
		this.editor.createShape({
			id: pinId,
			type: PIN_TYPE,
			x: currentPagePoint.x,
			y: currentPagePoint.y,
		})
		this.editor.setSelectedShapes([pinId])
		this.editor.setCurrentTool('select.translating', {
			...info,
			target: 'shape',
			shape: this.editor.getShape(pinId),
			isCreating: true,
			onInteractionEnd: 'pin',
			onCreate: () => {
				this.editor.setCurrentTool('pin')
			},
		})
	}
}

const overrides: TLUiOverrides = {
	tools(editor, schema) {
		schema['pin'] = {
			id: 'pin',
			label: 'Pin',
			icon: 'heart-icon',
			kbd: 'p',
			onSelect: () => {
				editor.setCurrentTool('pin')
			},
		}
		return schema
	},
}

const components: TLUiComponents & TLEditorComponents = {
	Toolbar: (...props) => {
		const pin = useTools().pin
		const isPinSelected = useIsToolSelected(pin)
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...pin} isSelected={isPinSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
}

export default function PinExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="pin-example"
				onMount={(editor) => {
					;(window as any).editor = editor
					editor.setStyleForNextShapes(DefaultFillStyle, 'semi')
				}}
				shapeUtils={[PinShapeUtil]}
				bindingUtils={[PinBindingUtil]}
				tools={[PinTool]}
				overrides={overrides}
				components={components}
			/>
		</div>
	)
}
```

--------

# Rich text with custom extension and toolbar

Category: Shapes & tools

Keywords: text, tip, tap, extension, toolbar

Extend the TipTap text editor by adding a custom extension and toolbar.

This example shows how to add a custom extension and toolbar to the TipTap text editor by setting the `textOptions` prop.

## App.tsx

```tsx
import { Mark, mergeAttributes } from '@tiptap/core'
import { StarterKit } from '@tiptap/starter-kit'
import {
	DefaultRichTextToolbar,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	preventDefault,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './RichTextCustomExtension.css'

interface WavyExtensionOptions {
	HTMLAttributes: object
}

declare module '@tiptap/core' {
	interface Commands<ReturnType> {
		wavy: {
			setWavy(): ReturnType
			toggleWavy(): ReturnType
			unsetWavy(): ReturnType
		}
	}
}

const Wavy = Mark.create<WavyExtensionOptions>({
	name: 'wavy',

addOptions() {
		return {
			HTMLAttributes: {},
		}
	},

parseHTML() {
		return [
			{
				tag: 'span.wavy',
			},
		]
	},

renderHTML({ HTMLAttributes }) {
		return [
			'span',
			mergeAttributes(this.options.HTMLAttributes, { class: 'wavy' }, HTMLAttributes),
			0,
		]
	},

addCommands() {
		return {
			setWavy:
				() =>
				({ commands }) =>
					commands.setMark(this.name),
			toggleWavy:
				() =>
				({ commands }: any) =>
					commands.toggleMark(this.name),
			unsetWavy:
				() =>
				({ commands }) =>
					commands.unsetMark(this.name),
		}
	},
})

const components: TLComponents = {
	RichTextToolbar: () => {
		const editor = useEditor()
		const textEditor = useValue('textEditor', () => editor.getRichTextEditor(), [editor])

return (
			<DefaultRichTextToolbar>
				<TldrawUiButton
					type="icon"
					onClick={() => {
						textEditor?.chain().focus().toggleWavy().run()
					}}
					isActive={textEditor?.isActive('wavy')}
					onPointerDown={preventDefault}
				>
					〰️
				</TldrawUiButton>
				{/* Add the DefaultRichTextToolbarContent if you want to add more items. */}
				{/* <DefaultRichTextToolbarContent textEditor={textEditor} onEditLinkIntent={() => {}} /> */}
			</DefaultRichTextToolbar>
		)
	},
}

const textOptions = {
	tipTapConfig: {
		extensions: [StarterKit, Wavy],
	},
}

export default function RichTextCustomExtensionExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="rich-text-custom-extension"
				components={components}
				textOptions={textOptions}
			/>
		</div>
	)
}

/*
This example shows how to set custom properties on the TipTap editor.
*/
```

## RichTextCustomExtension.css

```css
.wavy {
	text-decoration: wavy underline hotpink;
}
```

--------

# Rich text with font options

Category: Shapes & tools

Keywords: text, tip, tap, extension, toolbar, font

Extend the TipTap text editor by adding font-family and font-size options.

This example shows how to add font-family and font-size options to the TipTap text editor by setting the `textOptions` prop.

## App.tsx

```tsx
import { EditorEvents as TextEditorEvents } from '@tiptap/core'
import { FontFamily } from '@tiptap/extension-font-family'
import { TextStyleKit } from '@tiptap/extension-text-style'
import { EditorState as TextEditorState } from '@tiptap/pm/state'
import { useEffect, useState } from 'react'
import {
	DefaultRichTextToolbar,
	DefaultRichTextToolbarContent,
	Editor,
	TLComponents,
	TLTextOptions,
	Tldraw,
	defaultAddFontsFromNode,
	tipTapDefaultExtensions,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { FontSize } from './FontSizeExtension'
import './RichTextFontExtension.css'
import { extensionFontFamilies } from './fonts'

const fontOptions = [
	{ label: 'Default', value: 'DEFAULT' },
	{ label: 'Inter', value: 'Inter' },
	{ label: 'Comic Sans MS', value: 'Comic Sans MS' },
	{ label: 'serif', value: 'serif' },
	{ label: 'monospace', value: 'monospace' },
	{ label: 'cursive', value: 'cursive' },
	{ label: 'Exo 2 (Google Font)', value: "'Exo 2'" },
]

const fontSizeOptions = [
	{ label: 'Small', value: '12px' },
	{ label: 'Normal', value: '16px' },
	{ label: 'Large', value: '20px' },
	{ label: 'X-Large', value: '24px' },
	{ label: 'XX-Large', value: '28px' },
	{ label: 'Huge', value: '32px' },
]

const components: TLComponents = {
	RichTextToolbar: () => {
		const editor = useEditor()
		const textEditor = useValue('textEditor', () => editor.getRichTextEditor(), [editor])
		const [_, setTextEditorState] = useState<TextEditorState | null>(textEditor?.state ?? null)

// Set up text editor transaction listener.
		useEffect(() => {
			if (!textEditor) {
				setTextEditorState(null)
				return
			}

const handleTransaction = ({ editor: textEditor }: TextEditorEvents['transaction']) => {
				setTextEditorState(textEditor.state)
			}

textEditor.on('transaction', handleTransaction)
			return () => {
				textEditor.off('transaction', handleTransaction)
				setTextEditorState(null)
			}
		}, [textEditor])

if (!textEditor) return null

const currentFontFamily = textEditor?.getAttributes('textStyle').fontFamily ?? 'DEFAULT'
		const currentFontSize = textEditor?.getAttributes('textStyle').fontSize

return (
			<DefaultRichTextToolbar>
				<select
					className="rich-text-font-extension-select"
					value={currentFontFamily}
					onPointerDown={editor.markEventAsHandled}
					onChange={(e) => {
						textEditor?.chain().focus().setFontFamily(e.target.value).run()
					}}
				>
					{fontOptions.map((option) => (
						<option key={option.value} value={option.value}>
							{option.label}
						</option>
					))}
				</select>
				<select
					className="rich-text-font-extension-select"
					value={currentFontSize}
					onPointerDown={editor.markEventAsHandled}
					onChange={(e) => {
						textEditor?.chain().focus().setFontSize(e.target.value).run()
					}}
				>
					{fontSizeOptions.map((option) => (
						<option key={option.value} value={option.value}>
							{option.label}
						</option>
					))}
				</select>
				{/* Add the DefaultRichTextToolbarContent if you want to add more items. */}
				<DefaultRichTextToolbarContent textEditor={textEditor} />
			</DefaultRichTextToolbar>
		)
	},
}

const textOptions: Partial<TLTextOptions> = {
	tipTapConfig: {
		extensions: [...tipTapDefaultExtensions, FontFamily, FontSize, TextStyleKit],
	},
	addFontsFromNode(node, state, addFont) {
		state = defaultAddFontsFromNode(node, state, addFont)

// if we have a font-family attribute, keep track of that in the state so it applies to children
		for (const mark of node.marks) {
			if (
				mark.type.name === 'textStyle' &&
				mark.attrs.fontFamily &&
				mark.attrs.fontFamily !== 'DEFAULT' &&
				mark.attrs.fontFamily !== state.family
			) {
				state = { ...state, family: mark.attrs.fontFamily }
			}
		}

// if one of our extension font families matches the current state, add that font to the document.
		const font = extensionFontFamilies[state.family]?.[state.style]?.[state.weight]
		if (font) addFont(font)

return state
	},
}

export default function RichTextFontExtensionExample() {
	const fontFaces = Object.values(extensionFontFamilies)
		.map((fontFamily) => Object.values(fontFamily))
		.flat()
		.map((fontStyle) => Object.values(fontStyle))
		.flat()

// We need to preload the fonts so that they are available when
	// making font changes. This is to avoid any FOUC as you change the
	// font families.
	const onMount = (editor: Editor) => {
		editor.fonts.requestFonts(fontFaces)
	}

const exoFont = extensionFontFamilies["'Exo 2'"].normal.normal.src.url

return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="rich-text-font-extension"
				components={components}
				textOptions={textOptions}
				// If you want to override one of the custom fonts,
				// you can do so by providing an assetUrls prop.
				assetUrls={{
					fonts: {
						tldraw_mono: exoFont,
					},
				}}
				onMount={onMount}
			/>
		</div>
	)
}

/*
This example shows how to set font family and font size properties on the TipTap editor.
*/
```

## FontSizeExtension.ts

```ts
import '@tiptap/extension-text-style'

import { Extension } from '@tiptap/core'

export interface FontSizeOptions {
	/**
	 * A list of node names where the font size can be applied.
	 * @default ['textStyle']
	 * @example ['heading', 'paragraph']
	 */
	types: string[]
}

declare module '@tiptap/core' {
	interface Commands<ReturnType> {
		fontSize: {
			/**
			 * Set the font size
			 * @param fontSize The font size
			 * @example editor.commands.setFontSize('32px')
			 */
			setFontSize(fontSize: string): ReturnType
			/**
			 * Unset the font size
			 * @example editor.commands.unsetFontSize()
			 */
			unsetFontSize(): ReturnType
		}
	}
}

/**
 * This extension allows you to set a font size for text.
 */
export const FontSize = Extension.create<FontSizeOptions>({
	name: 'fontSize',

addOptions() {
		return {
			types: ['textStyle'],
		}
	},

addGlobalAttributes() {
		return [
			{
				types: this.options.types,
				attributes: {
					fontSize: {
						default: null,
						parseHTML: (element) => element.style.fontSize,
						renderHTML: (attributes) => {
							if (!attributes.fontSize) {
								return {}
							}

return {
								style: `font-size: ${attributes.fontSize}`,
							}
						},
					},
				},
			},
		]
	},

addCommands() {
		return {
			setFontSize:
				(fontSize) =>
				({ chain }) => {
					return chain().setMark('textStyle', { fontSize }).run()
				},
			unsetFontSize:
				() =>
				({ chain }) => {
					return chain().setMark('textStyle', { fontSize: null }).removeEmptyTextStyle().run()
				},
		}
	},
})
```

## RichTextFontExtension.css

```css
.rich-text-font-extension-select {
	border: 0;
	background: transparent;
	margin: 0 8px;
}
```

## fonts.ts

```ts
import { TLDefaultFont, TLFontFace } from 'tldraw'

// NOTE: these fonts only support the latin character set. To support other languages, you'll add
// each one as a new font-family, similar to how you would with @font-face.
export const extensionFontFamilies: {
	[key: string]: { [key: string]: { [key: string]: TLFontFace } }
} = {
	Inter: {
		normal: {
			normal: {
				family: 'Inter',
				src: {
					url: 'https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fAZ9hiJ-Ek-_EeA.woff2',
					format: 'woff2',
				},
				weight: '500',
				style: 'normal',
			},
			bold: {
				family: 'Inter',
				src: {
					url: 'https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuFuYAZ9hiJ-Ek-_EeA.woff2',
					format: 'woff2',
				},
				weight: '700',
				style: 'normal',
			},
		},
		italic: {
			normal: {
				family: 'Inter',
				src: {
					url: 'https://fonts.gstatic.com/s/inter/v18/UcCM3FwrK3iLTcvneQg7Ca725JhhKnNqk4j1ebLhAm8SrXTc69tRipWFsevceSGM.woff2',
					format: 'woff2',
				},
				weight: '500',
				style: 'normal',
			},
			bold: {
				family: 'Inter',
				src: {
					url: 'https://fonts.gstatic.com/s/inter/v18/UcCM3FwrK3iLTcvneQg7Ca725JhhKnNqk4j1ebLhAm8SrXTcPtxRipWFsevceSGM.woff2',
					format: 'woff2',
				},
				weight: '700',
				style: 'normal',
			},
		},
	},
	"'Exo 2'": {
		normal: {
			normal: {
				family: 'Exo 2',
				src: {
					url: 'https://fonts.gstatic.com/s/exo2/v24/7cH1v4okm5zmbvwkAx_sfcEuiD8jjPKsOdC_jJ7bpAhL.woff2',
					format: 'woff2',
				},
				weight: '500',
				style: 'normal',
			},
			bold: {
				family: 'Exo 2',
				src: {
					url: 'https://fonts.gstatic.com/s/exo2/v24/7cH1v4okm5zmbvwkAx_sfcEuiD8jWfWsOdC_jJ7bpAhL.woff2',
					format: 'woff2',
				},
				weight: '700',
				style: 'normal',
			},
		},
		italic: {
			normal: {
				family: 'Exo 2',
				src: {
					url: 'https://fonts.gstatic.com/s/exo2/v24/7cH3v4okm5zmbtYtMeA0FKq0Jjg2drFGfeC9hp_5oBBKRrs.woff2',
					format: 'woff2',
				},
				weight: '500',
				style: 'normal',
			},
			bold: {
				family: 'Exo 2',
				src: {
					url: 'https://fonts.gstatic.com/s/exo2/v24/7cH3v4okm5zmbtYtMeA0FKq0Jjg2drGTeuC9hp_5oBBKRrs.woff2',
					format: 'woff2',
				},
				weight: '700',
				style: 'normal',
			},
		},
	},
} satisfies Record<string, TLDefaultFont>
```

--------

# Outlined text example

Category: Shapes & tools

Keywords: text, outline, stroke, extension, toolbar, styling

Add outlined text styling to the TipTap text editor with a custom extension.

This example shows how to add a text outline effect by creating a custom TipTap extension that applies CSS text-stroke styling to selected text. The example includes a custom toolbar button to toggle the outline effect on and off.

## App.tsx

interface OutlineExtensionOptions {
	HTMLAttributes: object
}

declare module '@tiptap/core' {
	interface Commands<ReturnType> {
		outline: {
			setOutline(): ReturnType
			toggleOutline(): ReturnType
			unsetOutline(): ReturnType
		}
	}
}

const Outline = Mark.create<OutlineExtensionOptions>({
	name: 'outline',

addOptions() {
		return {
			HTMLAttributes: {},
		}
	},

parseHTML() {
		return [
			{
				tag: 'span.outlined',
			},
		]
	},

renderHTML({ HTMLAttributes }) {
		return [
			'span',
			mergeAttributes(this.options.HTMLAttributes, { class: 'outlined filled' }, HTMLAttributes),
			0,
		]
	},

addCommands() {
		return {
			setOutline:
				() =>
				({ commands }) =>
					commands.setMark(this.name),
			toggleOutline:
				() =>
				({ commands }: any) =>
					commands.toggleMark(this.name),
			unsetOutline:
				() =>
				({ commands }) =>
					commands.unsetMark(this.name),
		}
	},

onCreate() {
		this.editor.commands.toggleMark('outline')
	},
})

const components: TLComponents = {
	RichTextToolbar: () => {
		const editor = useEditor()
		const textEditor = useValue('textEditor', () => editor.getRichTextEditor(), [editor])

return (
			<DefaultRichTextToolbar>
				<TldrawUiButton
					type="icon"
					onClick={() => {
						textEditor?.chain().focus().toggleOutline().run()
					}}
					isActive={textEditor?.isActive('outline')}
					onPointerDown={preventDefault}
					title="Toggle text outline"
				>
					⬜
				</TldrawUiButton>
			</DefaultRichTextToolbar>
		)
	},
}

const textOptions = {
	tipTapConfig: {
		extensions: [StarterKit, Outline],
	},
}

export default function OutlinedTextExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="outlined-text-example"
				components={components}
				textOptions={textOptions}
			/>
		</div>
	)
}

/*
This example shows how to add outlined text styling using a custom TipTap extension.
The outline effect is created using CSS text-stroke properties.
*/
```

## OutlinedTextExample.css

```css
.outlined {
	-webkit-text-stroke: 2px #000000;
	text-stroke: 2px #000000;
	color: transparent;
	font-weight: bold;
}

.outlined.filled {
	color: #ffffff;
}
```

--------

# Popup shape

Category: Shapes & tools

Keywords: dynamic shadows, css

Create a 3D illusion of depth with dynamic shadows and CSS transforms.

## App.tsx

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

const customShapeUtils = [PopupShapeUtil]

export default function PopupShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				onMount={(editor) => {
					for (let i = 0; i < 9; i++) {
						editor.createShape({
							type: 'my-popup-shape',
							x: (i % 3) * 220,
							y: Math.floor(i / 3) * 220,
						})
					}
					editor.zoomToBounds(editor.getCurrentPageBounds()!, { animation: { duration: 0 } })
				}}
			/>
		</div>
	)
}
```

## PopupShapeUtil.tsx

```tsx
/* eslint-disable react-hooks/rules-of-hooks */
import { useEffect, useRef, useState } from 'react'
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape } from 'tldraw'

const MY_POPUP_SHAPE_TYPE = 'my-popup-shape'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_POPUP_SHAPE_TYPE]: { w: number; h: number; animal: number }
	}
}

export type IMyPopupShape = TLShape<typeof MY_POPUP_SHAPE_TYPE>

export class PopupShapeUtil extends BaseBoxShapeUtil<IMyPopupShape> {
	static override type = MY_POPUP_SHAPE_TYPE
	static override props: RecordProps<IMyPopupShape> = {
		w: T.number,
		h: T.number,
		animal: T.number,
	}

getDefaultProps(): IMyPopupShape['props'] {
		return {
			w: 200,
			h: 200,
			animal: 0,
		}
	}

component(shape: IMyPopupShape) {
		const [popped, setPopped] = useState(false)

const ref = useRef<HTMLDivElement>(null)
		const ref2 = useRef<HTMLDivElement>(null)

useEffect(() => {
			const elm = ref.current
			if (!elm) return
			const elm2 = ref2.current
			if (!elm2) return
			if (popped) {
				// man
				// elm2.style.transform = `rotateX(0deg) translateY(0px) translateZ(0px)`
				// note
				elm.style.transform = `rotateX(0deg) translateY(0px) translateZ(0px)`
			} else {
				// man
				// elm.style.transform = `rotateX(-50deg) translateY(5px) translateZ(0px)`
				// elm2.style.transform = `scaleY(.8)`
				// note
				elm.style.transform = `rotateX(20deg)`
			}
		}, [popped])

const vpb = this.editor.getViewportPageBounds()
		const spb = this.editor.getShapePageBounds(shape)!
		const px = vpb.midX - spb.midX + spb.w / 2
		const py = vpb.midY - spb.midY + spb.h / 2

return (
			<HTMLContainer
				style={{
					pointerEvents: 'all',
					perspective: `${Math.max(vpb.w, vpb.h)}px`,
					perspectiveOrigin: `${px}px ${py}px`,
				}}
				onPointerDown={this.editor.markEventAsHandled}
				onDoubleClick={(e) => {
					setPopped((p) => !p)
					this.editor.markEventAsHandled(e)
				}}
			>
				<div
					ref={ref2}
					style={{
						position: 'absolute',
						top: 0,
						left: 0,
						width: '100%',
						height: '100%',
						transition: `all .5s`,
						backgroundSize: 'contain',
						backgroundRepeat: 'no-repeat',
						backgroundPosition: 'center',
						// man
						// transformOrigin: 'bottom center',
						// backgroundImage: `url(/shadow-man.png)`,
						// note
						backgroundColor: 'rgba(0,0,0,.5)',
					}}
				/>
				<div
					ref={ref}
					style={{
						position: 'absolute',
						top: 0,
						left: 0,
						width: '100%',
						height: '100%',
						transition: `all .5s`,
						display: 'flex',
						alignItems: 'center',
						justifyContent: 'center',
						padding: 16,
						overflow: 'hidden',
						fontFamily: 'tldraw_draw',
						color: '#333',
						fontSize: 24,
						backgroundSize: 'contain',
						backgroundRepeat: 'no-repeat',
						backgroundPosition: 'center',
						transformOrigin: 'top center',
						// man
						// backgroundImage: `url(/man.png)`,
						// transformOrigin: 'bottom center',
						// transform: `rotateX(20deg) translateY(5px) translateZ(40px)`,
						// note
						background: `gold`,
						border: '1px solid goldenrod',
					}}
				>
					{/* {shape.id.slice(-1).toUpperCase()} */}
				</div>
			</HTMLContainer>
		)
	}

indicator(shape: IMyPopupShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}
```

--------

# Multiplayer sync

Category: Collaboration

Keywords: basic, intro, simple, quick, start, multiplayer, sync, collaboration

Use tldraw sync for multiplayer collaboration.

The `useSyncDemo` hook can be used to quickly prototype multiplayer experiences in tldraw using a demo backend that we host. Data is wiped after one day.

## App.tsx

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

export default function SyncDemoExample({ roomId }: { roomId: string }) {
	const store = useSyncDemo({ roomId })
	return (
		<div className="tldraw__editor">
			<Tldraw store={store} deepLinks />
		</div>
	)
}
```

--------

# Multiplayer sync with a custom shape

Category: Collaboration

Keywords: basic, intro, simple, quick, start, multiplayer, sync, collaboration, custom shape

Use a custom shape in combination with tldraw sync.

This example shows a custom shape in combination with tldraw sync.

## App.tsx

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { CounterShapeTool, CounterShapeUtil } from './CounterShape'
import { components, uiOverrides } from './ui'

const customShapes = [CounterShapeUtil]
const customTools = [CounterShapeTool]

export default function SyncDemoShapeExample({ roomId }: { roomId: string }) {
	const store = useSyncDemo({ roomId, shapeUtils: customShapes })
	return (
		<div className="tldraw__editor">
			<Tldraw
				store={store}
				shapeUtils={customShapes}
				tools={customTools}
				overrides={uiOverrides}
				components={components}
				deepLinks
			/>
		</div>
	)
}
```

## CounterShape.tsx

```tsx
import { MouseEvent } from 'react'
import { BaseBoxShapeTool, BaseBoxShapeUtil, HTMLContainer, T, TLShape } from 'tldraw'

const COUNTER_TYPE = 'counter'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[COUNTER_TYPE]: { w: number; h: number; count: number }
	}
}

export type CounterShape = TLShape<typeof COUNTER_TYPE>

export class CounterShapeUtil extends BaseBoxShapeUtil<CounterShape> {
	static override type = COUNTER_TYPE
	static override props = {
		w: T.positiveNumber,
		h: T.positiveNumber,
		count: T.number,
	}

override getDefaultProps() {
		return {
			w: 200,
			h: 200,
			count: 0,
		}
	}

override component(shape: CounterShape) {
		const onClick = (event: MouseEvent, change: number) => {
			event.stopPropagation()
			this.editor.updateShape({
				id: shape.id,
				type: COUNTER_TYPE,
				props: { count: shape.props.count + change },
			})
		}

return (
			<HTMLContainer
				style={{
					pointerEvents: 'all',
					background: '#efefef',
					display: 'flex',
					alignItems: 'center',
					justifyContent: 'center',
					gap: 8,
				}}
			>
				<button onClick={(e) => onClick(e, -1)} onPointerDown={this.editor.markEventAsHandled}>
					-
				</button>
				<span>{shape.props.count}</span>
				<button onClick={(e) => onClick(e, 1)} onPointerDown={this.editor.markEventAsHandled}>
					+
				</button>
			</HTMLContainer>
		)
	}

override indicator(shape: CounterShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

export class CounterShapeTool extends BaseBoxShapeTool {
	static override id = 'counter'
	override shapeType = 'counter' as const
}
```

## ui.tsx

```tsx
import {
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TLUiOverrides,
	TldrawUiMenuItem,
	useIsToolSelected,
	useTools,
} from 'tldraw'

export const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		// Create a tool item in the ui's context.
		tools.counter = {
			id: 'counter',
			icon: 'color',
			label: 'counter',
			kbd: 'c',
			onSelect: () => {
				editor.setCurrentTool('counter')
			},
		}
		return tools
	},
}

export const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isCounterSelected = useIsToolSelected(tools['counter'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['counter']} isSelected={isCounterSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
}
```

--------

# Multiplayer sync with custom people menu

Category: Collaboration

Keywords: multiplayer, sync, collaboration, custom shape, presence, people, ui, facepile

A custom multiplayer people menu / facepile that displays connected collaborators.

This example demonstrates how to build a custom people menu (or facepile) that shows information about all users in a multiplayer session.

This is useful when you want to create a more detailed or custom-styled presence indicator than the default tldraw provides. This example shows user's names, ids, colors, and cursor position, all information provided in the `TLInstancePresence` returned by `editor.getCollaborators()`.

## App.tsx

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { Tldraw, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './sync-custom-people-menu.css'

// [1]
const components = {
	SharePanel: () => (
		<div className="tlui-share-zone" draggable={false}>
			<CustomPeopleMenu />
		</div>
	),
}

// [2]
export default function SyncCustomPeopleMenuExample({ roomId }: { roomId: string }) {
	const store = useSyncDemo({ roomId })
	return (
		<div className="tldraw__editor">
			<Tldraw store={store} deepLinks components={components} />
		</div>
	)
}

// [3]
function CustomPeopleMenu() {
	const editor = useEditor()

// [a]
	const myUserColor = useValue('user', () => editor.user.getColor(), [editor])
	const myUserName = useValue('user', () => editor.user.getName() || 'Guest', [editor])
	const myUserId = useValue('user', () => editor.user.getId(), [editor])

// [b]
	const allOtherPresences = useValue('presences', () => editor.getCollaborators(), [editor])

return (
		<div className="custom-people-menu">
			{/* [c] */}
			<div className="user-section">
				<h4 className="section-title">Me</h4>
				<div className="user-info">
					<div className="user-avatar" style={{ background: myUserColor }} />
					<span className="user-name" style={{ color: myUserColor }}>
						{myUserName}, ID: {myUserId}
					</span>
				</div>
			</div>

{/* [d] */}
			{allOtherPresences.length > 0 && (
				<div className="other-users-section">
					<h4 className="section-title">Other connected users:</h4>
					<div className="other-users-list">
						{allOtherPresences.map(({ userId, userName, color, cursor }) => (
							<div key={userId} className="other-user-item">
								<div className="other-user-avatar" style={{ background: color }} />
								<span className="other-user-name" style={{ color: color }}>
									{userName || `ID: ${userId}`}
								</span>
								<span className="cursor-info">
									Cursor
									<br />
									{cursor && Number.isFinite(cursor.x) && Number.isFinite(cursor.y)
										? `(${Math.round(cursor.x)}, ${Math.round(cursor.y)})`
										: 'cursor data unavailable'}
								</span>
							</div>
						))}
					</div>
				</div>
			)}
		</div>
	)
}

/*
[1]
We define custom components to override tldraw's default UI. Here we're replacing the SharePanel with our own CustomPeopleMenu component.

[2]
This is the main component that sets up a synced tldraw editor. It uses the useSyncDemo hook to create a multiplayer store and passes our custom components to replace the default UI elements.

[3]
The CustomPeopleMenu component displays information about all connected users. It uses tldraw's collaboration hooks to access real-time presence data. You can do whatever you like in here, see the TLInstancePresence interface to see what informatino you have access to.

[a]
	We use the useValue hook to reactively get the current user's information (color, name, and ID). These values will automatically update if the user changes their name or the system assigns a new color (note: the examlpe doesn't allow for name changing).

[b]
	We get the live presence of all other users information using the editor's getCollaborators() method. We need to call getCollaborators() in a useValue hook in order for the presence info to be reactive.

[c]
	Display the current user's information with their color indicator and name. We show both the display name and the internal user ID for debugging purposes.

[d]
	For each connected collaborator, we display their name (or ID if no name is set), their color indicator, and their current cursor position.
*/
```

## sync-custom-people-menu.css

```css
/* Custom People Menu Styles */
.custom-people-menu {
	background: #f5f5f5;
	padding: 4px;
	display: flex;
	flex-direction: column;
	gap: 12px;
	width: 320px;
}

.user-section {
	display: flex;
	flex-direction: column;
	gap: 8px;
}

.section-title {
	margin: 0;
}

.user-info {
	display: flex;
	align-items: center;
	padding: 8px 12px;
	gap: 8px;
}

.user-avatar {
	width: 16px;
	height: 16px;
	border-radius: 50%;
	margin-right: 8px;
}

.user-name {
	word-break: break-word;
}

.other-users-section {
	display: flex;
	flex-direction: column;
	gap: 8px;
}

.other-users-list {
	display: flex;
	flex-direction: column;
	gap: 6px;
}

.other-user-item {
	display: flex;
	align-items: start;
	padding: 6px 12px;
}

.other-user-avatar {
	width: 16px;
	height: 16px;
	border-radius: 50%;
	margin-right: 8px;
}

.other-user-name {
	word-break: break-word;
	width: 170px;
}

.cursor-info {
	width: 80px;
	color: #aaa;
	font-size: 12px;
	margin-left: 8px;
}
```

--------

# Multiplayer sync with custom presence

Category: Collaboration

Keywords: basic, intro, simple, quick, start, multiplayer, sync, collaboration, presence

Customize the presence data synced between different tldraw instances.

This example shows how to customize the presence data synced between different tldraw instances.

## App.tsx

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { useEffect } from 'react'
import { Tldraw, getDefaultUserPresence, useAtom } from 'tldraw'
import 'tldraw/tldraw.css'

export default function SyncCustomUserExample({ roomId }: { roomId: string }) {
	// [1]
	const timer = useAtom('timer', Date.now())
	useEffect(() => {
		const tick = () => {
			timer.set(Date.now())
			frame = requestAnimationFrame(tick)
		}
		let frame = requestAnimationFrame(tick)
		return () => cancelAnimationFrame(frame)
	}, [timer])

// [2]
	const store = useSyncDemo({
		roomId,
		getUserPresence(store, user) {
			// [2.1]
			const defaults = getDefaultUserPresence(store, user)
			if (!defaults) return null

return {
				...defaults,

// [2.2]
				camera: undefined,

// [2.3]
				cursor: {
					...defaults.cursor,
					x: (defaults.cursor.x ?? 0) + 20 * Math.sin(timer.get() / 200),
					y: (defaults.cursor.y ?? 0) + 20 * Math.cos(timer.get() / 200),
				},
			}
		},
	})

// [3]
	return (
		<div className="tldraw__editor">
			<Tldraw store={store} deepLinks />
		</div>
	)
}

/**
 * # Sync Custom User
 *
 * This example demonstrates how to use the sync demo server with custom presence state. The
 * presence state is synchronized to all other clients and used for multiplayer features like
 * cursors and viewport following. You can use custom presence state to change the data that's
 * synced to other clients, or remove parts you don't need for your app.
 *
 * 1. We create a timer that updates every frame. You don't need to do this in your app, it's just
 *    to power an animation. We store it in an `atom` so that changes to it will cause the presence
 *    info to update.
 *
 * 2. We create a multiplayer store using the userSyncDemo hook, and pass in a custom
 *    `getUserPresence` function to change the presence state that gets sent.
 *
 * 2.1. We get the default presence state using the `getDefaultUserPresence` function. If you wanted
 *    to send a very minimal set of presence data, you could avoid this part.
 *
 * 2.2. We remove the camera from the presence state. This means that the camera position won't be
 *    sent to other clients. Attempting to follow this users viewport will not work.
 *
 * 2.3. We update the cursor position and rotation based on the current time. This will make the
 *    cursor spin around in a circle.
 *
 * 3. We create a Tldraw component and pass in the multiplayer store. This will render the editor.
 */
```

--------

# Multiplayer sync with custom user data

Category: Collaboration

Keywords: basic, intro, simple, quick, start, multiplayer, sync, collaboration, custom shape

Integrate your own user data into tldraw sync.

This example shows how to integrate your own user data into tldraw sync.

## App.tsx

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { useState } from 'react'
import { TLUserPreferences, Tldraw, useTldrawUser } from 'tldraw'
import 'tldraw/tldraw.css'

export default function SyncCustomUserExample({ roomId }: { roomId: string }) {
	// [1]
	const [userPreferences, setUserPreferences] = useState<TLUserPreferences>({
		id: 'user-' + Math.random(),
		name: 'Jimmothy',
		color: 'palevioletred',
		colorScheme: 'dark',
	})

// [2]
	const store = useSyncDemo({ roomId, userInfo: userPreferences })

// [3]
	const user = useTldrawUser({ userPreferences, setUserPreferences })

// [4]
	return (
		<div className="tldraw__editor">
			<Tldraw store={store} user={user} deepLinks />
		</div>
	)
}

/**
 * # Sync Custom User
 *
 * This example demonstrates how to use the sync demo server with a custom user.
 *
 * You need access to two things to do this integration:
 *
 * - The user info
 * - A function to set the user info
 *
 * In this example we create an in-memory state for the user info, but in your system it's probably synchronized with a backend database somehow.
 *
 * 1. We get our user info and a function to set it from a `useState` hook. In your app this might come from a context provider or you might hook it up manually to your backend.
 * 2. We use the `useSyncDemo` hook to create the multiplayer store, and pass in the current user state as `userInfo`, which is a subset of the `userPreferences` type.
 * 3. We use the `useTLUser` hook to create a TLUser object, which allows the Editor to both read and update the user info and preferences.
 * 4. We render the `Tldraw` component with the multiplayer store and the user object.
 *
 * You can pass the same `user` object into the `useSync` hook if you're using your own server.
 */
```

--------

# Multiplayer sync with private content

Category: Collaboration

Keywords: basic, intro, simple, quick, start, multiplayer, sync, collaboration

Show and hide private content in a multiplayer session.

This is a simple example of how to show and hide private content in a multiplayer session based on a simple
data ownership model. Try it out by opening the example in two different tabs, toggling the private mode, and
drawing some shapes.

## App.tsx

```tsx
import { useSyncDemo } from '@tldraw/sync'
import React from 'react'
import {
	Atom,
	TLComponents,
	Tldraw,
	react,
	useAtom,
	useEditor,
	useIsToolSelected,
	useTools,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { VisibilityOff, VisibilityOn } from '../../icons/icons'
import { Toggle } from './Toggle'
import './style.css'

// There's a guide at the bottom of this file!

// [1]
const PrivateModeContext = React.createContext<null | Atom<boolean>>(null)

const components: TLComponents = {
	// [2]
	InFrontOfTheCanvas: () => {
		const editor = useEditor()
		const isInSelectTool = useIsToolSelected(useTools().select)
		const userId = useValue('userId', () => editor.user.getId(), [])
		const myPrivateSelectedShapes = useValue(
			'private shapes',
			() =>
				editor
					.getSelectedShapes()
					.filter((shape) => !!shape.meta.private && shape.meta.ownerId === userId),
			[editor, userId]
		)

// [3]
		const isPrivateMode$ = React.useContext(PrivateModeContext)!
		const isPrivateMode = useValue(isPrivateMode$)

return (
			<>
				{isInSelectTool && myPrivateSelectedShapes.length > 0 ? (
					<div className="toggle-panel">
						<div>
							Make {myPrivateSelectedShapes.length} selected shape
							{myPrivateSelectedShapes.length > 1 ? 's' : ''} public?{' '}
						</div>
						<button
							onClick={() => {
								editor.markHistoryStoppingPoint()
								// [7]
								const allAffectedShapes = [
									...editor.getShapeAndDescendantIds(myPrivateSelectedShapes.map((s) => s.id)),
								].map((id) => editor.getShape(id)!)
								editor.updateShapes(
									allAffectedShapes.map((shape) => ({
										...shape,
										meta: { ...shape.meta, private: false },
									}))
								)
							}}
						>
							Yes
						</button>
					</div>
				) : (
					<div className="toggle-panel pointer" onClick={() => isPrivateMode$.update((v) => !v)}>
						{isPrivateMode ? <VisibilityOff fill="#444" /> : <VisibilityOn fill="#444" />}
						<div>Private mode</div>
						<Toggle isChecked={isPrivateMode} />
					</div>
				)}
			</>
		)
	},
}
function App({ roomId }: { roomId: string }) {
	const store = useSyncDemo({ roomId })
	const isPrivateMode$ = React.useContext(PrivateModeContext)!
	return (
		<div className="tldraw__editor">
			<Tldraw
				store={store}
				deepLinks
				// [4]
				getShapeVisibility={(shape, editor) => {
					const userId = editor.user.getId()
					if (!!shape.meta.private && shape.meta.ownerId !== userId) {
						return 'hidden'
					}
					return 'inherit'
				}}
				onMount={(editor) => {
					// [5]
					editor.store.sideEffects.registerBeforeCreateHandler('shape', (shape) => {
						if ('private' in shape.meta) return shape
						return {
							...shape,
							meta: {
								...shape.meta,
								private: isPrivateMode$.get(),
								ownerId: editor.user.getId(),
							},
						}
					})

// [6]
					return react('clean up selection', () => {
						const selectedShapes = editor.getSelectedShapes()
						const filteredSelectedShapes = selectedShapes.filter((s) => !editor.isShapeHidden(s))
						if (filteredSelectedShapes.length !== selectedShapes.length) {
							editor.select(...filteredSelectedShapes)
						}
					})
				}}
				components={components}
			/>
		</div>
	)
}

export default function SyncPrivateContentExample({ roomId }: { roomId: string }) {
	return (
		<PrivateModeContext.Provider value={useAtom('isPrivateDrawingMode', false)}>
			<App roomId={roomId} />
		</PrivateModeContext.Provider>
	)
}

/**
 * This example demonstrates how to create a 'private' drawing mode where any shapes created by one person cannot be seen by another.
 * It sets up a simple ownership system where each shape created is tagged with the id of the user who created it.
 * It also adds a boolean flag to each shape called 'private' which is set to true if the shape is created in private mode.
 * If the user selects one or more private shapes, they will be given the option to make them public.
 *
 * 1. We create a context to store the atom that will hold the state of the private drawing mode. We are using signals here but you can use any state management library you like.
 * 2. We override the `InFrontOfTheCanvas` component to add a tool panel at the top of the screen that allows the user to toggle private drawing mode on and off, and to make private shapes public.
 * 3. We use the context to get the atom that holds the state of the private drawing mode. We then have to call 'useValue' on the atom to get the current value in a reactive way.
 * 4. We override the `getShapeVisibility` function to hide shapes that are private and not owned by the current user.
 * 5. We register a side effect that adds the 'private' and 'ownerId' meta fields to each shape created. We set the 'private' field to the current value of the private drawing mode atom.
 * 6. We register a side effect that cleans up the selection by removing any hidden shapes from the selection. This re-runs whenever the selection or the hidden state of a selected shape changes.
 * 7. Child shapes (e.g inside groups and frames) do not inherit the 'private' meta property from their parent. So when making a shape public, we decide to also make all descendant shapes public since this is most likely what the user intended.
 */
```

## Toggle.tsx

```tsx
export function Toggle({ isChecked }: { isChecked: boolean }) {
	const height = 20
	const width = 40
	const pillSize = height - 4
	return (
		<div
			style={{
				cursor: 'pointer',
				width,
				height,
				borderRadius: height / 2,
				backgroundColor: isChecked ? '#4bb05e' : '#999',
				display: 'flex',
				alignItems: 'center',
				justifyContent: isChecked ? 'flex-end' : 'flex-start',
				padding: 2,
			}}
		>
			{isChecked && (
				<div
					style={{ fontSize: 9, fontWeight: 600, color: 'white', position: 'relative', left: -3 }}
				>
					ON
				</div>
			)}
			<div
				style={{
					width: pillSize,
					height: pillSize,
					borderRadius: pillSize / 2,
					backgroundColor: 'white',
				}}
			/>
			{!isChecked && (
				<div
					style={{ fontSize: 9, fontWeight: 600, color: 'white', position: 'relative', right: -1 }}
				>
					OFF
				</div>
			)}
		</div>
	)
}
```

## style.css

```css
.toggle-panel {
	position: absolute;
	top: 10px;
	left: 50%;
	transform: translateX(-50%);
	border-radius: 8px;
	background: #efefef;
	box-shadow:
		0 0 0 1px rgba(0, 0, 0, 0.1),
		0 4px 8px rgba(0, 0, 0, 0.1);
	padding: 9px 10px 9px 15px;
	display: flex;
	align-items: center;
	gap: 10px;
}

.toggle-panel button {
	cursor: pointer;
}

.toggle-panel.pointer {
	cursor: pointer;
}
```

--------

# Manually update user presence

Category: Collaboration

Keywords: cursor

Manually show other users editing the same document.

Here, we add fake `InstancePresence` records to the store to simulate other users. If you have your own presence system, you could add real records to the store in the same way.

## App.tsx

```tsx
import { useRef } from 'react'
import { InstancePresenceRecordType, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

// [1]
const USER_NAME = 'huppy da arrow'
const MOVING_CURSOR_SPEED = 0.25 // 0 is stopped, 1 is full send
const MOVING_CURSOR_RADIUS = 100
const CURSOR_CHAT_MESSAGE = 'Hey, I think this is just great.'

// [2]
export default function UserPresenceExample() {
	const rRaf = useRef<any>(-1)
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="user-presence-example"
				onMount={(editor) => {
					// [a]
					const peerPresence = InstancePresenceRecordType.create({
						id: InstancePresenceRecordType.createId(editor.store.id),
						currentPageId: editor.getCurrentPageId(),
						userId: 'peer-1',
						userName: USER_NAME,
						cursor: { x: 0, y: 0, type: 'default', rotation: 0 },
						chatMessage: CURSOR_CHAT_MESSAGE,
					})

editor.store.mergeRemoteChanges(() => {
						editor.store.put([peerPresence])
					})

// [b]
					const raf = rRaf.current
					cancelAnimationFrame(raf)

if (MOVING_CURSOR_SPEED > 0 || CURSOR_CHAT_MESSAGE) {
						function loop() {
							let cursor = peerPresence.cursor
							if (!cursor) return
							let chatMessage = peerPresence.chatMessage

const now = Date.now()

if (MOVING_CURSOR_SPEED > 0) {
								const k = 1000 / MOVING_CURSOR_SPEED
								const t = (now % k) / k

cursor = {
									...cursor,
									x: 150 + Math.cos(t * Math.PI * 2) * MOVING_CURSOR_RADIUS,
									y: 150 + Math.sin(t * Math.PI * 2) * MOVING_CURSOR_RADIUS,
								}
							}

if (CURSOR_CHAT_MESSAGE) {
								const k = 1000
								const t = (now % (k * 3)) / k
								chatMessage =
									t < 1
										? ''
										: t > 2
											? CURSOR_CHAT_MESSAGE
											: CURSOR_CHAT_MESSAGE.slice(
													0,
													Math.ceil((t - 1) * CURSOR_CHAT_MESSAGE.length)
												)
							}

editor.store.mergeRemoteChanges(() => {
								editor.store.put([
									{
										...peerPresence,
										cursor,
										chatMessage,
										lastActivityTimestamp: now,
									},
								])
							})

rRaf.current = editor.timers.requestAnimationFrame(loop)
						}

rRaf.current = editor.timers.requestAnimationFrame(loop)
					} else {
						editor.store.mergeRemoteChanges(() => {
							editor.store.put([{ ...peerPresence, lastActivityTimestamp: Date.now() }])
						})
						rRaf.current = editor.timers.setInterval(() => {
							editor.store.mergeRemoteChanges(() => {
								editor.store.put([{ ...peerPresence, lastActivityTimestamp: Date.now() }])
							})
						}, 1000)
					}
				}}
			/>
		</div>
	)
}

/* 
This example shows how to add instance presence records to the store to show other users' cursors.
It is not an example of how to implement user presence, check out the collaboration examples for that:
https://tldraw.dev/examples/sync-demo

[1]
We're going to a fake a user's cursor and chat message, these are the values we'll use.

[2]
This is where we'll render the Tldraw component. We'll use the onMount callback to access the editor 
instance.
	[a] For every connected peer we need to add an instance presence record to the store. We can do
		this using the InstancePresenceRecordType.create function and add it to the store using the
		store.put method.
	[b] We'll use the requestAnimationFrame function to update the cursor position and chat message.
		This is just for demonstration purposes.
*/
```

--------

# Persist to storage

Category: Data & assets

Keywords: store, snapshot, debounce

Manually persist the contents of the editor to storage.

In this example, we load the contents of the editor from your browser's `localStorage`, and save it there when you make changes.

## App.tsx

```tsx
import { throttle } from 'lodash'
import { useLayoutEffect, useMemo, useState } from 'react'
import { DefaultSpinner, Tldraw, createTLStore, getSnapshot, loadSnapshot } from 'tldraw'
import 'tldraw/tldraw.css'

// There's a guide at the bottom of this file!

const PERSISTENCE_KEY = 'example-3'

export default function PersistenceExample() {
	//[1]
	const store = useMemo(() => createTLStore(), [])
	//[2]
	const [loadingState, setLoadingState] = useState<
		{ status: 'loading' } | { status: 'ready' } | { status: 'error'; error: string }
	>({
		status: 'loading',
	})
	//[3]
	useLayoutEffect(() => {
		setLoadingState({ status: 'loading' })

// Get persisted data from local storage
		const persistedSnapshot = localStorage.getItem(PERSISTENCE_KEY)

if (persistedSnapshot) {
			try {
				const snapshot = JSON.parse(persistedSnapshot)
				loadSnapshot(store, snapshot)
				setLoadingState({ status: 'ready' })
			} catch (error: any) {
				setLoadingState({ status: 'error', error: error.message }) // Something went wrong
			}
		} else {
			setLoadingState({ status: 'ready' }) // Nothing persisted, continue with the empty store
		}

// Each time the store changes, run the (debounced) persist function
		const cleanupFn = store.listen(
			throttle(() => {
				const snapshot = getSnapshot(store)
				localStorage.setItem(PERSISTENCE_KEY, JSON.stringify(snapshot))
			}, 500)
		)

return () => {
			cleanupFn()
		}
	}, [store])

// [4]
	if (loadingState.status === 'loading') {
		return (
			<div className="tldraw__editor">
				<h2>
					<DefaultSpinner />
				</h2>
			</div>
		)
	}

if (loadingState.status === 'error') {
		return (
			<div className="tldraw__editor">
				<h2>Error!</h2>
				<p>{loadingState.error}</p>
			</div>
		)
	}

return (
		<div className="tldraw__editor">
			<Tldraw store={store} />
		</div>
	)
}

/*
This example shows how to implement persistence in the Tldraw component. We do
this by saving the editor's state to local storage each time it changes. You 
should replace this in your app with some sort of backend storage solution. If 
you just want to save to local storage, you can use the `persistenceKey` prop
instead. Simply pass any string to this prop and the editor will automatically 
save to local storage.

[1]
We create a new store using the `createTLStore` helper function. We pass in the 
default shape utils so that the store knows how to handle the built-in shapes.

[2]
This is a cool pattern that uses Typescript to help keep track of our app's
loading state.

[3]
We use the `useLayoutEffect` hook to run our persistence code after the first
render. First we grab the persisted snapshot from local storage. If there is
one, we load it into the store and set the loading state to ready. If there
isn't one, we just set the loading state to ready.

Then we setup a listener on the store that will run our persistence code each
time the store changes. We use the `throttle` helper function to debounce the
listener so that it doesn't run too often. We also return a cleanup function
that will remove the listener when the component unmounts.

[4]
This is where we render our application depending on the loading state. If the
loading state is `loading`, we render a loading message. If the loading state
is `error`, we render an error message. If the loading state is `ready`, we
render the Tldraw component.
*/
```

--------

# Static assets

Category: Data & assets

Keywords: icons, fonts, pre-load

Use custom fonts, icons, and preload them using the `Tldraw` component.

The `Tldraw` component relies on static assets for fonts and icons. These must be pre-loaded in order that the component runs properly.

## App.tsx

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

// [1]
const assetUrls: TldrawProps['assetUrls'] = {
	fonts: {
		tldraw_draw: '/ComicMono.woff',
	},
	icons: {
		'tool-arrow': '/custom-arrow-icon.svg',
	},
}

export default function StaticAssetsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="static-assets" assetUrls={assetUrls} />
		</div>
	)
}

/**
[1]
By default, the Tldraw component will pull in assets from tldraw's asset CDN.
You can override this behavior by providing your own asset URLs. These URLs can
be relative or absolute URLs.

In this case, we are using a relative URL to a custom arrow icon and a custom font. 
Because this is a Vite project, these files are stored in this project's public folder.
Check your framework documentation for how to serve static assets.

Important! This object needs to be created outside of a React component, or else 
memoized using a useMemo hook, otherwise it will cause the Tldraw component to
receive a new `asserUrls` object every time the component re-renders.

```tsx

export default function StaticAssetsExample() {
	const assetUrls = useMemo<TldrawProps['assetUrls']>(() => ({
		fonts: {
			tldraw_draw: '/ComicMono.woff',
		},
		icons: {
			'tool-arrow': '/custom-arrow-icon.svg',
		},
	}, [])

return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="static-assets" assetUrls={assetUrls} />
		</div>
	)
}
```
*/
```

--------

# Export canvas as image

Category: Data & assets

Keywords: basic, assets, svg, png, blob

Export the entire canvas as an image file.

This example shows how you can use the `Editor.toImage()` function to create an image of all shapes on the canvas and then download it. The easiest way to download an image is to use the download attribute of a link element.

## App.tsx

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

function ExportCanvasButton() {
	const editor = useEditor()
	return (
		<button
			style={{ pointerEvents: 'all', fontSize: 18, backgroundColor: 'thistle' }}
			onClick={async () => {
				const shapeIds = editor.getCurrentPageShapeIds()
				if (shapeIds.size === 0) return alert('No shapes on the canvas')
				const { blob } = await editor.toImage([...shapeIds], { format: 'png', background: false })

const link = document.createElement('a')
				link.href = URL.createObjectURL(blob)
				link.download = 'every-shape-on-the-canvas.jpg'
				link.click()
				URL.revokeObjectURL(link.href)
			}}
		>
			Export canvas as image
		</button>
	)
}
const components: TLUiComponents = {
	SharePanel: ExportCanvasButton,
}
export default function ExportCanvasImageExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw components={components} />
		</div>
	)
}

/* 
This example shows how you can use the `Editor.toImage()` function to create an image with all the shapes 
on the canvas in it and then download it. The easiest way to download an image is to use the download 
attribute of a link element.

To learn more about overriding UI you can check out our various custom menu examples. For more on handling
assets, check out our Local/Hosted images examples.
*/
```

--------

# Export canvas as image (with settings)

Category: Data & assets

Keywords: basic, assets, svg, png, blob, image, settings

Export the entire canvas as an image file, with configurable settings.

This example shows how you can use the `Editor.toImage()` function to create an image of all shapes on the canvas and then download it. It also shows options for the different settings you can pass to the `toImage` function.

## App.tsx

```tsx
import { useState } from 'react'
import { Box, Tldraw, TLImageExportOptions, TLUiComponents, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'

const components: TLUiComponents = {
	SharePanel: ExportCanvasButton,
}

export default function ExportCanvasImageExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw components={components} />
		</div>
	)
}

function ExportCanvasButton() {
	const editor = useEditor()

// [1]
	const [opts, setOpts] = useState<TLImageExportOptions>({
		scale: 1,
		background: false,
		padding: editor.options.defaultSvgPadding,
	})

// [2]
	const [box, setBox] = useState({ x: 0, y: 0, w: 0, h: 0 })

return (
		<div
			style={{
				pointerEvents: 'all',
				border: '1px solid black',
				borderRadius: 5,
				padding: 12,
				position: 'absolute',
				display: 'flex',
				flexDirection: 'column',
				right: 164,
				top: 8,
			}}
		>
			<div
				style={{
					display: 'grid',
					gridTemplateColumns: '1fr auto',
					gridAutoFlow: 'row',
					rowGap: 4,
					columnGap: 16,
				}}
			>
				<Control
					type="checkbox"
					name="background"
					checked={opts.background}
					onChange={(e) => {
						setOpts({ ...opts, background: e.target.checked })
					}}
				/>
				<Control
					type="checkbox"
					name="darkmode"
					checked={opts.darkMode}
					onChange={(e) => {
						setOpts({ ...opts, darkMode: e.target.checked })
					}}
				/>
				<Control
					type="number"
					name="padding"
					value={opts.padding}
					onChange={(e) => {
						setOpts({ ...opts, padding: Math.ceil(Number(e.target.value)) })
					}}
				/>
				<Control
					type="number"
					name="scale"
					value={opts.scale}
					onChange={(e) => {
						setOpts({ ...opts, scale: Math.ceil(Number(e.target.value)) })
					}}
				/>
				<p style={{ gridColumn: '1 / span 2' }}>Box</p>
				{['x', 'y', 'w', 'h'].map((key) => (
					<div key={key} style={{ display: 'flex', gap: 4 }}>
						<Control
							type="number"
							name={key}
							value={box[key as keyof typeof box]}
							onChange={(event) => {
								setBox({
									...box,
									[key]: Math.ceil(Number(event.target.value)),
								})
							}}
						/>
					</div>
				))}
			</div>
			<button
				style={{ pointerEvents: 'all', marginTop: 16 }}
				onClick={async () => {
					const shapeIds = editor.getCurrentPageShapeIds()
					if (shapeIds.size === 0) return alert('No shapes on the canvas')

const { blob } = await editor.toImage([...shapeIds], {
						format: 'png',
						...opts,
						// If we have numbers for all of the box values, we can use them as bounds
						bounds: Object.values(box).every((b) => !Number.isNaN(b))
							? new Box(box.x, box.y, box.w, box.h)
							: undefined,
					})

const link = document.createElement('a')
					link.href = window.URL.createObjectURL(blob)
					link.download = 'every-shape-on-the-canvas.jpg'
					link.click()
				}}
			>
				Export canvas as image
			</button>
		</div>
	)
}

const Control = ({
	name,
	type,
	value,
	checked,
	onChange,
}: {
	name: string
	type?: React.HTMLInputTypeAttribute
	value?: string | number | readonly string[]
	checked?: boolean
	onChange?: React.ChangeEventHandler<HTMLInputElement>
}) => {
	return (
		<>
			<label htmlFor={`opt-${name}`} style={{ flexGrow: 2 }}>
				{name}
			</label>
			<input
				id={`opt-${name}`}
				name={name}
				type={type}
				style={{ maxWidth: 64, justifySelf: 'flex-end' }}
				value={value ?? ''}
				checked={!!checked}
				onChange={onChange}
			/>
		</>
	)
}

/* 
This example shows how you can use the image export settings in tldraw when generating an image.

1.
These are our defaults, though the rest of export / copy features use the user preferences,
e.g. editor.user.getIsDarkMode() for whether the user has enabled dark mode or not. But if
you're calling the image functions yourself, you can provide whatever options you wish.

2.
The bounding box is an optional argument that you can use to export a specific part of the canvas
or selection.
*/
```

--------

# Hosted images

Category: Data & assets

Keywords: assets, video, image, png, jpg, file

How to handle images uploaded by the user.

This example shows how to handle images uploaded by the user. To do this we'll need to
create a `TLAssetStore`, which tells the editor how to handle uploaded assets.

## App.tsx

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

// [1]
const UPLOAD_URL = '/SOME_ENDPOINT'

// [2]
const myAssetStore: TLAssetStore = {
	// [a]
	async upload(asset, file) {
		const id = uniqueId()

const objectName = `${id}-${file.name}`.replaceAll(/\W/g, '-')
		const url = `${UPLOAD_URL}/${objectName}`

await fetch(url, {
			method: 'POST',
			body: file,
		})

return { src: url }
	},

// [b]
	resolve(asset) {
		return asset.props.src
	},
}

// [3]
export default function HostedImagesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw assets={myAssetStore} />
		</div>
	)
}
/*

Introduction: This example shows how to handle images uploaded by the user. to do this we'll need to
create a TLAssetStore, which tells the editor how to handle uploaded assets.

[1] You'll want to have an endpoint on your server that accepts file uploads, and returns URLs.

[2] We define our asset store, which has two methods: upload for saving assets, and resolve for
retrieving them.

[a] The upload method is called when the user creates a file. It should take a `File` object,
    and return a URL that can be used to reference the file in the future.

[b] After the file has been uploaded, whenever we want to refer to it again the editor will
    call the `resolve` method with the asset. Here, we just do the default and return the `src`
    prop. If you wanted to, you could return a different URL - for example, to serve optimized
    images, or to add an authentication token. The implementation here is the default, and could 
	have been omitted.

[3] Finally, we have our actual instance. We pass our asset store to the `assets` prop of the
`Tldraw` component so it becomes part of the store.

*/
```

--------

# Custom paste behavior

Category: Data & assets

Keywords:

Change how pasting works by registering an external content handler.

This example adds a special rule for pasting single frame shapes, so they'll try to find an empty space instead of always pasting in the location they were copied from.

## App.tsx

```tsx
import {
	defaultHandleExternalTldrawContent,
	Editor,
	Tldraw,
	TLFrameShape,
	TLTldrawExternalContent,
} from 'tldraw'

// this example adds special behavior when pasting a single frame shape, matching the behavior of figma
export default function CustomPasteExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// on mount, override the default tldraw handler
					editor.registerExternalContentHandler('tldraw', (content) =>
						handleCustomTldrawPaste(editor, content)
					)
				}}
			/>
		</div>
	)
}

const SPACING_BETWEEN_FRAMES = 50

function handleCustomTldrawPaste(editor: Editor, { content, point }: TLTldrawExternalContent) {
	// find the only shape in the pasted content
	const onlyCopiedShape =
		content.rootShapeIds.length === 1
			? content.shapes.find((shape) => shape.id === content.rootShapeIds[0])
			: null

// make sure that the shape is a frame. if it is, retrieve the current version of that frame
	// from the document.
	const onlyCopiedFrame =
		onlyCopiedShape?.type === 'frame' ? (onlyCopiedShape as TLFrameShape) : null

// we only want to use our special behavior if the frame (current & pasted) will be a direct
	// descendant of the current page.
	const willPasteOnCurrentPage = onlyCopiedFrame
		? !editor.getShape(onlyCopiedFrame.parentId)
		: false

// if the paste is happening at a specific point, or we didn't copy a single frame that belongs
	// to this page, fall back to the default paste behavior
	if (point || !onlyCopiedFrame || !willPasteOnCurrentPage) {
		defaultHandleExternalTldrawContent(editor, { content, point })
		return
	}

// if we are pasting a single frame, and that frame is still in the document, we want to find a
	// free space to the right of the frame to put this one.
	editor.putContentOntoCurrentPage(content, { select: true })
	const newlyPastedFrame = editor.getOnlySelectedShape()
	if (!newlyPastedFrame || !editor.isShapeOfType(newlyPastedFrame, 'frame')) return

const siblingIds = editor.getSortedChildIdsForParent(newlyPastedFrame.parentId)
	const pastedBounds = editor.getShapePageBounds(newlyPastedFrame.id)!
	let targetPosition = pastedBounds.minX

const siblingBounds = siblingIds
		.map((id) => ({ id, bounds: editor.getShapePageBounds(id)! }))
		.sort((a, b) => a.bounds.minX - b.bounds.minX)

for (const sibling of siblingBounds) {
		if (sibling.id === newlyPastedFrame.id) continue

// if this sibling is above or below the copied frame, we don't need to take it into account
		if (sibling.bounds.minY > pastedBounds.maxY || sibling.bounds.maxY < pastedBounds.minY) continue

// if the sibling is to the left of the copied frame, we don't need to take it into account
		if (sibling.bounds.maxX < targetPosition) continue

// if the sibling is to the right of where the pasted frame would end up, we don't care about it
		if (sibling.bounds.minX > targetPosition + pastedBounds.w) continue

// otherwise, we need to shift our target right edge to the right of this sibling
		targetPosition = sibling.bounds.maxX + SPACING_BETWEEN_FRAMES
	}

// translate the pasted frame into position:
	editor.nudgeShapes([newlyPastedFrame.id], {
		x: targetPosition - pastedBounds.minX,
		y: 0,
	})
}
```

--------

# External content sources

Category: Data & assets

Keywords: copy, paste, html

Handle different types of content when pasting into tldraw.

In this example, we register a special handler for when the user pastes in `'text/html'` content. We add it to a special shape type that renders the HTML content directly. Try copying and pasting some code from a VSCode file.

## App.tsx

```tsx
import { useCallback } from 'react'
import {
	BaseBoxShapeUtil,
	defaultHandleExternalTextContent,
	Editor,
	HTMLContainer,
	Tldraw,
	TLShape,
} from 'tldraw'
import 'tldraw/tldraw.css'

const DANGEROUS_HTML_TYPE = 'dangerous-html'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[DANGEROUS_HTML_TYPE]: { w: number; h: number; html: string }
	}
}

// There's a guide at the bottom of this page!

// [1]
export type IDangerousHtmlShape = TLShape<typeof DANGEROUS_HTML_TYPE>

// [2]
class DangerousHtmlExample extends BaseBoxShapeUtil<IDangerousHtmlShape> {
	static override type = DANGEROUS_HTML_TYPE

override getDefaultProps() {
		return {
			w: 500,
			h: 300,
			html: '<div>hello</div>',
		}
	}

override component(shape: IDangerousHtmlShape) {
		return (
			<HTMLContainer style={{ overflow: 'auto' }}>
				<div dangerouslySetInnerHTML={{ __html: shape.props.html }}></div>
			</HTMLContainer>
		)
	}

override indicator(shape: IDangerousHtmlShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}

// [3]

export default function ExternalContentSourcesExample() {
	const handleMount = useCallback((editor: Editor) => {
		// We will register a new handler for text content. When a user pastes `text/html` content into the editor,
		// we will create a new shape with that html content.
		// To test this copy some html content from VS Code or some other text editor.
		editor.registerExternalContentHandler('text', async (content) => {
			const htmlSource = content.sources?.find((s) => s.type === 'text' && s.subtype === 'html')

if (htmlSource) {
				const center = content.point ?? editor.getViewportPageBounds().center

editor.createShape({
					type: 'dangerous-html',
					x: center.x - 250,
					y: center.y - 150,
					props: {
						html: htmlSource.data,
					},
				})
			} else {
				// otherwise, we'll fall back to the default handler
				await defaultHandleExternalTextContent(editor, content)
			}
		})
	}, [])

return (
		<div className="tldraw__editor">
			<Tldraw onMount={handleMount} shapeUtils={[DangerousHtmlExample]} />
		</div>
	)
}

/*
Introduction:
This example shows how to handle content pasted from external sources, this could be
embeds, files, svgs, text, images, or urls. In this case we will handle text/html content.

[1]
We want to render our html on the canvas, the best way to do that is to create a new shape util.
Here's where we define the type for our shape.

[2]
This is our shape util. It's a class that extends BaseBoxShapeUtil. For a more detailed
example of how to create a custom shape, see the custom config example.

[3]
We use the onMount prop to get access to the editor instance via
the handleMount callback (check out the API example for a more detailed look at this). Then we
call the registerExternalContentHandler method, we could choose to handle embeds, files, svgs,
text, images, or urls. For this example we will handle text/html content. The handler is called
with the point where the user pasted the content and an array of sources. We will find and
return the html source, then create a new shape with that html content.

*/
```

--------

# Meta migrations

Category: Data & assets

Keywords: records, snapshot, sequence

Create custom migrations for `meta` properties.

You can add arbitrary data migrations for tldraw snapshot data. This is mainly useful for updating the `meta` property of a record as your data types evolve.

## App.tsx

```tsx
import { Tldraw, createMigrationIds, createMigrationSequence } from 'tldraw'
import 'tldraw/tldraw.css'
import { snapshot } from './snapshot'
import { components } from './ui-overrides'

/**
 * This example demonstrates how to add custom migrations for `meta` properties, or any other
 * data in your store snapshots.
 *
 * If you have a custom shape type and you want to add migrations for its `props` object,
 * there is a simpler dedicated API for that. Check out [the docs](https://tldraw.dev/docs/persistence#Shape-props-migrations) for more info.
 */

/**
 * Let's say you added some page metadata, e.g. to allow setting the background color of a page independently.
 */
interface _PageMetaV1 {
	backgroundTheme?: 'red' | 'blue' | 'green' | 'purple'
}

/**
 * And then perhaps later on you decided to remove support for 'purple' because it's an ugly color.
 * So all purple pages will become blue.
 */
export interface PageMetaV2 {
	backgroundTheme?: 'red' | 'blue' | 'green'
}

/**
 * You would then create a migration to update the metadata from v1 to v2.
 */

// First pick a 'sequence id' that is unique to your app
const sequenceId = 'com.example.my-app'
// Then create a 'migration id' for each version of your metadata
const versions = createMigrationIds(sequenceId, {
	// the numbers must start at 1 and increment by 1
	RemovePurple: 1,
})
const migrations = createMigrationSequence({
	sequenceId,
	sequence: [
		{
			id: versions.RemovePurple,
			// `scope: 'record` tells the schema to call this migration on individual records.
			// `scope: 'storage'` would pass a storage object with get/set/delete methods, to allow for actions like deleting/creating records.
			scope: 'record',
			// When `scope` is 'record', you can specify a filter function to only apply the migration to records that match the filter.
			filter: (record) => record.typeName === 'page',
			// This up function will be called on all records that match the filter
			up(page: any) {
				if (page.meta.backgroundTheme === 'purple') {
					page.meta.backgroundTheme = 'blue'
					page.name += ' (was purple)'
				}
			},
		},
	],
})

export default function MetaMigrationsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// Pass in the custom migrations
				migrations={[migrations]}
				// When you load a snapshot from a previous version, the migrations will be applied automatically
				snapshot={snapshot}
				// This adds a dropdown to the canvas for changing the backgroundTheme property
				components={components}
			/>
		</div>
	)
}
```

## snapshot.ts

```ts
import { TLStoreSnapshot } from 'tldraw'

export const snapshot = {
	store: {
		'document:document': {
			gridSize: 10,
			name: '',
			meta: {},
			id: 'document:document',
			typeName: 'document',
		},
		'page:red': {
			meta: {
				backgroundTheme: 'red',
			},
			id: 'page:red',
			name: 'Red',
			index: 'a1',
			typeName: 'page',
		},
		'page:green': {
			meta: {
				backgroundTheme: 'green',
			},
			id: 'page:green',
			name: 'Green',
			index: 'a2',
			typeName: 'page',
		},
		'page:blue': {
			meta: {
				backgroundTheme: 'blue',
			},
			id: 'page:blue',
			name: 'Blue',
			index: 'a3',
			typeName: 'page',
		},
		'page:purple': {
			meta: {
				backgroundTheme: 'purple',
			},
			id: 'page:purple',
			name: 'Purple',
			index: 'a0',
			typeName: 'page',
		},
	},
	schema: {
		schemaVersion: 2,
		sequences: {
			'com.tldraw.store': 4,
			'com.tldraw.document': 2,
			'com.tldraw.page': 1,
		},
	},
} as TLStoreSnapshot
```

## ui-overrides.tsx

```tsx
import { useLayoutEffect } from 'react'
import { TLComponents, track, useEditor } from 'tldraw'
import { PageMetaV2 } from './MetaMigrations'

export const components: TLComponents = {
	TopPanel: track(() => {
		const editor = useEditor()
		const currentPage = editor.getCurrentPage()
		const meta: PageMetaV2 = currentPage.meta

useLayoutEffect(() => {
			const elem = document.querySelector('.tl-background') as HTMLElement
			if (!elem) return
			elem.style.backgroundColor = meta.backgroundTheme ?? 'unset'
		}, [meta.backgroundTheme])

return (
			<span style={{ pointerEvents: 'all', padding: '5px 15px', margin: 10, fontSize: 18 }}>
				bg:  
				<select
					value={meta.backgroundTheme ?? 'none'}
					onChange={(e) => {
						if (e.currentTarget.value === 'none') {
							editor.updatePage({ ...currentPage, meta: {} })
						} else {
							editor.updatePage({
								...currentPage,
								meta: { backgroundTheme: e.currentTarget.value },
							})
						}
					}}
				>
					<option value="none">None</option>
					<option value="red">Red</option>
					<option value="blue">Blue</option>
					<option value="green">Green</option>
				</select>
			</span>
		)
	}),
}
```

--------

# Slideshow (fixed camera)

Category: Use cases

Keywords: annotation, camera options, constraints, zoom, pan, camera bounds, pan speed, zoom speed, scroll, slides, presentation

A simple slideshow app with a fixed camera.

This example shows one way of making a simple slideshow app with a fixed camera, using camera options.

## App.tsx

```tsx
import { useEffect, useState } from 'react'
import { Editor, TLFrameShape, Tldraw, createShapeId, transact, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import { SLIDE_MARGIN, SLIDE_SIZE, SlidesProvider, useSlides } from './SlidesManager'

export default function SlideShowExample() {
	return (
		<div className="tldraw__editor">
			<SlidesProvider>
				<InsideSlidesContext />
			</SlidesProvider>
		</div>
	)
}

function InsideSlidesContext() {
	const [editor, setEditor] = useState<Editor | null>(null)
	const slides = useSlides()

const currentSlide = useValue('currentSlide', () => slides.getCurrentSlide(), [slides])

useEffect(() => {
		if (!editor) return

const nextBounds = {
			x: currentSlide.index * (SLIDE_SIZE.w + SLIDE_MARGIN),
			y: 0,
			w: SLIDE_SIZE.w,
			h: SLIDE_SIZE.h,
		}

editor.setCameraOptions({
			constraints: {
				bounds: nextBounds,
				behavior: 'contain',
				initialZoom: 'fit-max',
				baseZoom: 'fit-max',
				origin: { x: 0.5, y: 0.5 },
				padding: { x: 50, y: 50 },
			},
		})

editor.zoomToBounds(nextBounds, { force: true, animation: { duration: 500 } })
	}, [editor, currentSlide])

const currentSlides = useValue('slides', () => slides.getCurrentSlides(), [slides])

useEffect(() => {
		if (!editor) return

const ids = currentSlides.map((slide) => createShapeId(slide.id))

transact(() => {
			for (let i = 0; i < currentSlides.length; i++) {
				const shapeId = ids[i]
				const slide = currentSlides[i]
				const shape = editor.getShape(shapeId)
				if (shape) {
					if (shape.x === slide.index * (SLIDE_SIZE.w + SLIDE_MARGIN)) continue

// if name is still Slide and number, e.g Slide 1, update it. Use regex to test

const regex = /Slide \d+/
					let name = (shape as TLFrameShape).props.name
					if (regex.test((shape as TLFrameShape).props.name)) {
						name = `Slide ${slide.index + 1}`
					}

editor.updateShape({
						id: shapeId,
						type: 'frame',
						x: slide.index * (SLIDE_SIZE.w + SLIDE_MARGIN),
						props: {
							name,
						},
					})
				} else {
					editor.createShape({
						id: shapeId,
						parentId: editor.getCurrentPageId(),
						type: 'frame',
						x: slide.index * (SLIDE_SIZE.w + SLIDE_MARGIN),
						y: 0,
						props: {
							name: `Slide ${slide.index + 1}`,
							w: SLIDE_SIZE.w,
							h: SLIDE_SIZE.h,
						},
					})
				}
			}
		})

const unsubs: (() => void)[] = []

unsubs.push(
			editor.sideEffects.registerBeforeChangeHandler('shape', (prev, next) => {
				if (
					ids.includes(next.id) &&
					(next as TLFrameShape).props.name === (prev as TLFrameShape).props.name
				)
					return prev
				return next
			})
		)

unsubs.push(
			editor.sideEffects.registerBeforeChangeHandler('instance_page_state', (prev, next) => {
				next.selectedShapeIds = next.selectedShapeIds.filter((id) => !ids.includes(id))
				if (next.hoveredShapeId && ids.includes(next.hoveredShapeId)) next.hoveredShapeId = null
				return next
			})
		)

return () => {
			unsubs.forEach((fn) => fn())
		}
	}, [currentSlides, editor])

const handleMount = (editor: Editor) => {
		setEditor(editor)
	}

return <Tldraw onMount={handleMount} components={components} />
}

function Slides() {
	const editor = useEditor()
	const slides = useSlides()
	const currentSlides = useValue('slides', () => slides.getCurrentSlides(), [slides])
	const lowestIndex = currentSlides[0].index
	const highestIndex = currentSlides[currentSlides.length - 1].index

return (
		<>
			{/* {currentSlides.map((slide) => (
				<div
					key={slide.id}
					style={{
						position: 'absolute',
						top: 0,
						left: (SLIDE_SIZE.w + SLIDE_MARGIN) * slide.index,
						width: SLIDE_SIZE.w,
						height: SLIDE_SIZE.h,
						backgroundColor: 'white',
						border: '1px solid black',
						pointerEvents: 'all',
					}}
					onPointerDown={(e) => {
						if (slide.id !== slides.getCurrentSlideId()) {
							markEventAsHandled(e)
							slides.setCurrentSlide(slide.id)
						}
					}}
				/>
			))} */}
			{currentSlides.slice(0, -1).map((slide) => (
				<button
					key={slide.id + 'between'}
					style={{
						position: 'absolute',
						top: SLIDE_SIZE.h / 2,
						left: (slide.index + 1) * (SLIDE_SIZE.w + SLIDE_MARGIN) - (SLIDE_MARGIN + 40) / 2,
						width: 40,
						height: 40,
						pointerEvents: 'all',
					}}
					onPointerDown={editor.markEventAsHandled}
					onClick={() => {
						const newSlide = slides.newSlide(slide.index + 1)
						slides.setCurrentSlide(newSlide.id)
					}}
				>
					|
				</button>
			))}
			<button
				style={{
					position: 'absolute',
					top: SLIDE_SIZE.h / 2,
					left: lowestIndex * (SLIDE_SIZE.w + SLIDE_MARGIN) - (40 + SLIDE_MARGIN * 0.1),
					width: 40,
					height: 40,
					pointerEvents: 'all',
				}}
				onPointerDown={editor.markEventAsHandled}
				onClick={() => {
					const slide = slides.newSlide(lowestIndex - 1)
					slides.setCurrentSlide(slide.id)
				}}
			>
				{`+`}
			</button>
			<button
				style={{
					position: 'absolute',
					top: SLIDE_SIZE.h / 2,
					left: highestIndex * (SLIDE_SIZE.w + SLIDE_MARGIN) + (SLIDE_SIZE.w + SLIDE_MARGIN * 0.1),
					width: 40,
					height: 40,
					pointerEvents: 'all',
				}}
				onPointerDown={editor.markEventAsHandled}
				onClick={() => {
					const slide = slides.newSlide(highestIndex + 1)
					slides.setCurrentSlide(slide.id)
				}}
			>
				{`+`}
			</button>
		</>
	)
}

function SlideControls() {
	const slides = useSlides()
	const editor = useEditor()

return (
		<>
			<button
				style={{
					pointerEvents: 'all',
					position: 'absolute',
					top: '50%',
					left: 0,
					width: 50,
					height: 50,
				}}
				onPointerDown={editor.markEventAsHandled}
				onClick={() => slides.prevSlide()}
			>
				{`<`}
			</button>
			<button
				style={{
					pointerEvents: 'all',
					position: 'absolute',
					top: '50%',
					right: 0,
					width: 50,
					height: 50,
				}}
				onPointerDown={editor.markEventAsHandled}
				onClick={() => slides.nextSlide()}
			>
				{`>`}
			</button>
		</>
	)
}

const components = {
	OnTheCanvas: Slides,
	InFrontOfTheCanvas: SlideControls,
}
```

## SlidesManager.tsx

```tsx
import { createContext, ReactNode, useContext, useState } from 'react'
import { atom, computed, structuredClone, uniqueId } from 'tldraw'

export const SLIDE_SIZE = { x: 0, y: 0, w: 1600, h: 900 }
export const SLIDE_MARGIN = 100

interface Slide {
	id: string
	index: number
	name: string
}

class SlidesManager {
	private _slides = atom<Slide[]>('slide', [
		{
			id: '1',
			index: 0,
			name: 'Slide 1',
		},
		{
			id: '2',
			index: 1,
			name: 'Slide 2',
		},
		{
			id: '3',
			index: 2,
			name: 'Slide 3',
		},
	])

@computed getCurrentSlides() {
		return this._slides.get().sort((a, b) => (a.index < b.index ? -1 : 1))
	}

private _currentSlideId = atom('currentSlide', '1')

@computed getCurrentSlideId() {
		return this._currentSlideId.get()
	}

@computed getCurrentSlide() {
		return this._slides.get().find((slide) => slide.id === this.getCurrentSlideId())!
	}

setCurrentSlide(id: string) {
		this._currentSlideId.set(id)
	}

moveBy(delta: number) {
		const slides = this.getCurrentSlides()
		const currentIndex = slides.findIndex((slide) => slide.id === this.getCurrentSlideId())
		const next = slides[currentIndex + delta]
		if (!next) return
		this._currentSlideId.set(next.id)
	}

nextSlide() {
		this.moveBy(1)
	}

prevSlide() {
		this.moveBy(-1)
	}

newSlide(index: number) {
		const slides = structuredClone(this.getCurrentSlides())

let bumping = false
		for (const slide of slides) {
			if (slide.index === index) {
				bumping = true
			}
			if (bumping) {
				slide.index++
			}
		}

const newSlide = {
			id: uniqueId(),
			index,
			name: `Slide ${slides.length + 1}`,
		}

this._slides.set([...slides, newSlide])

return newSlide
	}
}

const slidesContext = createContext({} as SlidesManager)

export const SlidesProvider = ({ children }: { children: ReactNode }) => {
	const [slideManager] = useState(() => new SlidesManager())
	return <slidesContext.Provider value={slideManager}>{children}</slidesContext.Provider>
}

export function useSlides() {
	return useContext(slidesContext)
}
```

--------

# Slideshow (free camera)

Category: Use cases

Keywords: annotation, camera options, constraints, zoom, pan, camera bounds, pan speed, zoom speed, scroll, slides, presentation

A simple slideshow app with a moving camera.

This example shows one way of making a simple slideshow app with a moving camera.

## App.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TLUiOverrides,
	Tldraw,
	TldrawUiMenuItem,
	computed,
	createShapeId,
	track,
	useIsToolSelected,
	useTools,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { SlideShapeTool } from './SlideShapeTool'
import { SlideShapeUtil } from './SlideShapeUtil'
import { SlidesPanel } from './SlidesPanel'
import './slides.css'
import { $currentSlide, getSlides, moveToSlide } from './useSlides'

const components: TLComponents = {
	HelperButtons: SlidesPanel,
	Minimap: null,
	Toolbar: (props) => {
		const tools = useTools()
		const isSlideSelected = useIsToolSelected(tools['slide'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['slide']} isSelected={isSlideSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	KeyboardShortcutsDialog: (props) => {
		const tools = useTools()
		return (
			<DefaultKeyboardShortcutsDialog {...props}>
				<TldrawUiMenuItem {...tools['slide']} />
				<DefaultKeyboardShortcutsDialogContent />
			</DefaultKeyboardShortcutsDialog>
		)
	},
}

const overrides: TLUiOverrides = {
	actions(editor, actions) {
		const $slides = computed('slides', () => getSlides(editor))
		return {
			...actions,
			'next-slide': {
				id: 'next-slide',
				label: 'Next slide',
				kbd: 'right',
				onSelect() {
					const slides = $slides.get()
					const currentSlide = $currentSlide.get()
					const index = slides.findIndex((s) => s.id === currentSlide?.id)
					const nextSlide = slides[index + 1] ?? currentSlide ?? slides[0]
					if (nextSlide) {
						editor.stopCameraAnimation()
						moveToSlide(editor, nextSlide)
					}
				},
			},
			'previous-slide': {
				id: 'previous-slide',
				label: 'Previous slide',
				kbd: 'left',
				onSelect() {
					const slides = $slides.get()
					const currentSlide = $currentSlide.get()
					const index = slides.findIndex((s) => s.id === currentSlide?.id)
					const previousSlide = slides[index - 1] ?? currentSlide ?? slides[slides.length - 1]
					if (previousSlide) {
						editor.stopCameraAnimation()
						moveToSlide(editor, previousSlide)
					}
				},
			},
		}
	},
	tools(editor, tools) {
		tools.slide = {
			id: 'slide',
			icon: 'group',
			label: 'Slide',
			kbd: 's',
			onSelect: () => editor.setCurrentTool('slide'),
		}
		return tools
	},
}

const SlidesExample = track(() => {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="slideshow_example"
				shapeUtils={[SlideShapeUtil]}
				tools={[SlideShapeTool]}
				components={components}
				overrides={overrides}
				onMount={(editor) => {
					const existingSlides = getSlides(editor)
					if (existingSlides.length === 0) {
						editor.createShape({
							id: createShapeId(),
							type: 'slide',
							x: 100,
							y: 100,
							props: { w: 720, h: 480 },
						})
						editor.createShape({
							id: createShapeId(),
							type: 'slide',
							x: 900,
							y: 100,
							props: { w: 720, h: 480 },
						})
					}
				}}
			/>
		</div>
	)
})

export default SlidesExample
```

## SlideShapeTool.tsx

```tsx
import { BaseBoxShapeTool } from 'tldraw'

export class SlideShapeTool extends BaseBoxShapeTool {
	static override id = 'slide'
	static override initial = 'idle'
	override shapeType = 'slide' as const
}
```

## SlideShapeUtil.tsx

```tsx
import { useCallback } from 'react'
import {
	Geometry2d,
	RecordProps,
	Rectangle2d,
	SVGContainer,
	ShapeUtil,
	T,
	TLResizeInfo,
	TLShape,
	getPerfectDashProps,
	resizeBox,
	useValue,
} from 'tldraw'
import { moveToSlide, useSlides } from './useSlides'

const SLIDE_TYPE = 'slide'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[SLIDE_TYPE]: {
			w: number
			h: number
		}
	}
}

export type SlideShape = TLShape<typeof SLIDE_TYPE>

export class SlideShapeUtil extends ShapeUtil<SlideShape> {
	static override type = SLIDE_TYPE
	static override props: RecordProps<SlideShape> = {
		w: T.number,
		h: T.number,
	}

override canBind() {
		return false
	}
	override hideRotateHandle() {
		return true
	}

getDefaultProps(): SlideShape['props'] {
		return {
			w: 720,
			h: 480,
		}
	}

getGeometry(shape: SlideShape): Geometry2d {
		return new Rectangle2d({
			width: shape.props.w,
			height: shape.props.h,
			isFilled: false,
		})
	}

override onRotate(initial: SlideShape) {
		return initial
	}

override onResize(shape: SlideShape, info: TLResizeInfo<SlideShape>) {
		return resizeBox(shape, info)
	}

override onDoubleClick(shape: SlideShape) {
		moveToSlide(this.editor, shape)
		this.editor.selectNone()
	}

override onDoubleClickEdge(shape: SlideShape) {
		moveToSlide(this.editor, shape)
		this.editor.selectNone()
	}

component(shape: SlideShape) {
		const bounds = this.editor.getShapeGeometry(shape).bounds

// eslint-disable-next-line react-hooks/rules-of-hooks
		const zoomLevel = useValue('zoom level', () => this.editor.getZoomLevel(), [this.editor])

// eslint-disable-next-line react-hooks/rules-of-hooks
		const slides = useSlides()
		const index = slides.findIndex((s) => s.id === shape.id)

// eslint-disable-next-line react-hooks/rules-of-hooks
		const handleLabelPointerDown = useCallback(() => this.editor.select(shape.id), [shape.id])

if (!bounds) return null

return (
			<>
				<div onPointerDown={handleLabelPointerDown} className="slide-shape-label">
					{`Slide ${index + 1}`}
				</div>
				<SVGContainer>
					<g
						style={{
							stroke: 'var(--tl-color-text)',
							strokeWidth: 'calc(1px * var(--tl-scale))',
							opacity: 0.25,
						}}
						pointerEvents="none"
						strokeLinecap="round"
						strokeLinejoin="round"
					>
						{bounds.sides.map((side, i) => {
							const { strokeDasharray, strokeDashoffset } = getPerfectDashProps(
								side[0].dist(side[1]),
								1 / zoomLevel,
								{
									style: 'dashed',
									lengthRatio: 6,
									forceSolid: zoomLevel < 0.2,
								}
							)

return (
								<line
									key={i}
									x1={side[0].x}
									y1={side[0].y}
									x2={side[1].x}
									y2={side[1].y}
									strokeDasharray={strokeDasharray}
									strokeDashoffset={strokeDashoffset}
								/>
							)
						})}
					</g>
				</SVGContainer>
			</>
		)
	}

indicator(shape: SlideShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}
```

## SlidesPanel.tsx

```tsx
import { TldrawUiButton, track, useEditor, useValue } from 'tldraw'
import { moveToSlide, useCurrentSlide, useSlides } from './useSlides'

export const SlidesPanel = track(() => {
	const editor = useEditor()
	const slides = useSlides()
	const currentSlide = useCurrentSlide()
	const selectedShapes = useValue('selected shapes', () => editor.getSelectedShapes(), [editor])

if (slides.length === 0) return null
	return (
		<div className="slides-panel scroll-light" onPointerDown={editor.markEventAsHandled}>
			{slides.map((slide, i) => {
				const isSelected = selectedShapes.includes(slide)
				return (
					<TldrawUiButton
						key={'slides-panel-button:' + slide.id}
						type="normal"
						className="slides-panel-button"
						onClick={() => moveToSlide(editor, slide)}
						style={{
							background:
								currentSlide?.id === slide.id ? 'var(--tl-color-background)' : 'transparent',
							outline: isSelected ? 'var(--tl-color-selection-stroke) solid 1.5px' : 'none',
						}}
					>
						{`Slide ${i + 1}`}
					</TldrawUiButton>
				)
			})}
		</div>
	)
})
```

## slides.css

```css
.slides-panel {
	display: flex;
	flex-direction: column;
	gap: 4px;
	max-height: calc(100% - 110px);
	margin: 50px 0px;
	padding: 4px;
	background-color: var(--tl-color-low);
	pointer-events: all;
	border-top-right-radius: var(--tl-radius-4);
	border-bottom-right-radius: var(--tl-radius-4);
	overflow: auto;
	border-right: 2px solid var(--tl-color-background);
	border-bottom: 2px solid var(--tl-color-background);
	border-top: 2px solid var(--tl-color-background);
}

.slides-panel-button {
	border-radius: var(--tl-radius-4);
	outline-offset: -1px;
}

.slide-shape-label {
	pointer-events: all;
	position: absolute;
	background: var(--tl-color-low);
	padding: calc(12px * var(--tl-scale));
	border-bottom-right-radius: calc(var(--tl-radius-4) * var(--tl-scale));
	font-size: calc(12px * var(--tl-scale));
	color: var(--tl-color-text);
	white-space: nowrap;
}
```

## useSlides.tsx

```tsx
import { EASINGS, Editor, atom, useEditor, useValue } from 'tldraw'
import { SlideShape } from './SlideShapeUtil'

export const $currentSlide = atom<SlideShape | null>('current slide', null)

export function moveToSlide(editor: Editor, slide: SlideShape) {
	const bounds = editor.getShapePageBounds(slide.id)
	if (!bounds) return
	$currentSlide.set(slide)
	editor.selectNone()
	editor.zoomToBounds(bounds, {
		inset: 0,
		animation: { duration: 500, easing: EASINGS.easeInOutCubic },
	})
}

export function useSlides() {
	const editor = useEditor()
	return useValue<SlideShape[]>('slide shapes', () => getSlides(editor), [editor])
}

export function useCurrentSlide() {
	return useValue($currentSlide)
}

export function getSlides(editor: Editor) {
	return editor
		.getSortedChildIdsForParent(editor.getCurrentPageId())
		.map((id) => editor.getShape(id))
		.filter((s) => s?.type === 'slide') as SlideShape[]
}
```

--------

# Education canvas

Category: Use cases

Keywords: education, math, geometry, GCSE, teaching, learning, canvas, fixed camera

An educational application template with a math question on the left and a drawing canvas on the right.

This example demonstrates how to create an educational application using tldraw. It features:

- **Split Layout**: Question panel on the left, drawing canvas on the right
- **Fixed Camera**: Canvas has constrained bounds to keep students focused on the drawing area
- **GCSE Math Question**: A geometry problem suitable for GCSE-level mathematics
- **Grid Background**: Coordinate grid to help with plotting points and shapes
- **Educational Styling**: Clean, professional styling suitable for educational environments

Perfect for creating interactive math worksheets, geometry exercises, or any educational content that requires visual problem-solving.

## App.tsx

```tsx
import { memo, useCallback, useEffect, useRef, useState } from 'react'
import { Box, Editor, TLCameraOptions, TLComponents, Tldraw, track, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './education-canvas.css'

// Fixed camera options to prevent zooming/panning
const CAMERA_OPTIONS: Partial<TLCameraOptions> = {
	isLocked: false,
	constraints: {
		initialZoom: 'fit-max',
		baseZoom: 'fit-max',
		bounds: {
			x: 0,
			y: 0,
			w: 600,
			h: 600,
		},
		behavior: { x: 'contain', y: 'contain' },
		padding: { x: 100, y: 100 },
		origin: { x: 0.5, y: 0.5 },
	},
}

const CameraSetup = track(() => {
	const editor = useEditor()

useEffect(() => {
		if (!editor) return
		editor.run(() => {
			editor.zoomToBounds(new Box(0, 0, 600, 600), {
				inset: 150,
			})
			editor.setCameraOptions(CAMERA_OPTIONS)
			editor.setCamera(editor.getCamera(), {
				immediate: true,
			})
			// editor.updateInstanceState({
			// 	isGridMode: true,
			// })
		})
	}, [editor])

return null
})

const TICKS = 8

const CartesianGrid = memo(function CartesianGrid() {
	return (
		<svg
			className="cartesian-grid"
			width="600"
			height="600"
			viewBox="0 0 600 600"
			stroke="#aaa"
			color="#aaa"
		>
			{Array.from({ length: TICKS * 2 + 1 }).map((_, i) => {
				const step = 600 / (TICKS * 2)
				const opacity = i === TICKS ? 1 : 0.16
				return (
					<g key={i + '_line'}>
						<line x1={0} y1={i * step} x2={600} y2={i * step} strokeWidth="1" opacity={opacity} />
						<line x1={i * step} y1={0} x2={i * step} y2={600} strokeWidth="1" opacity={opacity} />
					</g>
				)
			})}
			<g>
				{Array.from({ length: TICKS * 2 + 1 }).map((_, i) => {
					const index = i
					if (i - TICKS === 0) return null
					const y = 600 - index * (600 / (TICKS * 2))
					return (
						<g key={i + '_textx'}>
							<text
								key={index}
								x={312}
								y={y}
								dy="0.3em"
								fontFamily="Arial"
								textAnchor="start"
								letterSpacing=".25em"
								stroke="none"
								fill="#aaa"
								fontWeight="bold"
							>
								{-TICKS + index}
							</text>
							<line x1={295} y1={y} x2={305} y2={y} strokeWidth="2" />
						</g>
					)
				})}
				{Array.from({ length: TICKS * 2 + 1 }).map((_, i) => {
					const index = i
					if (i - TICKS === 0) return null
					const x = index * (600 / (TICKS * 2))
					return (
						<g key={i + '_texty'}>
							<text
								key={index}
								x={x}
								y={320}
								dy="0.3em"
								fontFamily="Arial"
								textAnchor="middle"
								stroke="none"
								fill="#aaa"
								fontWeight="bold"
							>
								{-TICKS + index}
							</text>
							<line x1={x} y1={295} x2={x} y2={305} strokeWidth="2" strokeLinecap="round" />
						</g>
					)
				})}
			</g>
		</svg>
	)
})

const components: TLComponents = {
	OnTheCanvas: CartesianGrid,
}

export default function EducationCanvasExample() {
	const [answers, setAnswers] = useState({
		partB: '',
		partC: '',
	})

const handleAnswerChange = (part: keyof typeof answers, value: string) => {
		setAnswers((prev) => ({ ...prev, [part]: value }))
	}

const rEditor = useRef<Editor | null>(null)
	const handleMount = useCallback((editor: Editor) => {
		rEditor.current = editor
	}, [])

const handleSubmit = useCallback(async () => {
		// Normalize answers for comparison
		const normalizeAnswer = (answer: string) => {
			return answer.toLowerCase().replace(/[^a-z0-9(),.-]/g, '')
		}

// Check Part B - Area (accept 8, 8 square units, 8 units², etc.)
		const normalizedB = normalizeAnswer(answers.partB)
		const isPartBCorrect =
			normalizedB.includes('8') &&
			(normalizedB.includes('square') || normalizedB.includes('unit') || normalizedB === '8')

// Check Part C - Coordinates (accept (0,7), (0, 7), 0,7, etc.)
		const normalizedC = normalizeAnswer(answers.partC)
		const isPartCCorrect =
			normalizedC.includes('0') &&
			normalizedC.includes('7') &&
			(normalizedC.includes('(0,7)') ||
				normalizedC.includes('0,7') ||
				normalizedC.match(/0.*7/) ||
				normalizedC.match(/7.*0/))

if (isPartBCorrect && isPartCCorrect) {
			alert('Good job! Both answers are correct!')
		} else if (isPartBCorrect || isPartCCorrect) {
			let message = 'Good progress! '
			if (isPartBCorrect) message += 'Part B is correct. '
			if (isPartCCorrect) message += 'Part C is correct. '
			if (!isPartBCorrect) message += 'Check your area calculation for Part B.'
			if (!isPartCCorrect) message += 'Check your coordinates for Part C.'
			alert(message)
		} else {
			alert('Please check your answers and try again.')
		}

// Do something with the answers
		const editor = rEditor.current
		if (editor) {
			// For example, get the canvas content and the answers and send it to the server.
			// const result = {
			// 	answers: {
			// 		partA: await editor.toImage(editor.getCurrentPageShapes()),
			// 		partB: answers.partB,
			// 		partC: answers.partC,
			// 	},
			// }
			// console.log(result)
		}
	}, [answers])

return (
		<div className="education-container">
			{/* Question Panel - Left Half */}
			<div className="question-panel">
				<div className="question-content">
					<h1 className="main-title">Mathematics - Geometry</h1>

<div className="question-card">
						<h2 className="question-title">Question 1</h2>
						<p className="question-text">
							A triangle ABC has vertices at A(2, 3), B(6, 3), and C(4, 7).
						</p>

<div className="question-part">
							<p className="question-text">
								<strong>Part A:</strong> Draw triangle ABC on the coordinate grid.
							</p>
						</div>

<div className="question-part">
							<p className="question-text">
								<strong>Part B:</strong> Calculate the area of triangle ABC.
							</p>
							<div className="answer-input-group">
								<label className="answer-label">
									<strong>Answer:</strong>
								</label>
								<input
									type="text"
									className="answer-input"
									placeholder="Enter the area"
									value={answers.partB}
									onChange={(e) => handleAnswerChange('partB', e.target.value)}
								/>
							</div>
						</div>

<div className="question-part">
							<p className="question-text">
								<strong>Part C:</strong> Find the coordinates of point D such that ABCD forms a
								parallelogram.
							</p>
							<div className="answer-input-group">
								<label className="answer-label">
									<strong>Answer:</strong>
								</label>
								<input
									type="text"
									className="answer-input"
									placeholder="Enter coordinates as (x, y)"
									value={answers.partC}
									onChange={(e) => handleAnswerChange('partC', e.target.value)}
								/>
							</div>
						</div>

<button className="submit-button" onClick={handleSubmit}>
							Submit Answers
						</button>
					</div>

<div className="instructions-card">
						<h3 className="instructions-title">Instructions:</h3>
						<ul className="instructions-list">
							<li>Use the drawing canvas on the right to sketch your solution</li>
							<li>
								You can use the draw tool <kbd>D</kbd> to draw points and the line tool <kbd>L</kbd>{' '}
								to draw lines
							</li>
							<li>
								Use the text tool <kbd>T</kbd> to label points and write calculations
							</li>
							<li>Show all your working clearly</li>
							<li>Enter your final answers in the answer boxes above</li>
						</ul>
					</div>
				</div>
			</div>

{/* Canvas Panel - Right Half */}
			<div className="canvas-panel">
				<div className="canvas-container">
					<Tldraw
						options={{ maxPages: 1 }}
						persistenceKey="education-canvas"
						components={components}
						onMount={handleMount}
						overrides={{
							tools: (_editor, tools) => {
								// These are the tool ids that are allowed to be used in the education canvas...
								const allowedTools = ['select', 'hand', 'draw', 'eraser', 'line', 'text']
								// Tools are keyed by their id, so we can delete off all the tools that are not in the allowedTools array
								for (const key in tools) {
									if (!allowedTools.includes(key)) {
										delete tools[key]
									}
								}
								// Return the mutated tools
								return tools
							},
						}}
					>
						<CameraSetup />
					</Tldraw>
				</div>
			</div>
		</div>
	)
}
```

## education-canvas.css

```css
/* Education Canvas Example Styles */

.education-container {
	display: flex;
	min-height: 100vh;
	font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
	gap: 40px;
}

.question-panel {
	width: 100%;
	max-width: 500px;
	flex-shrink: 0;
	padding: 2rem;
	background-color: #f8fafc;
	border-right: 2px solid #e2e8f0;
	display: flex;
	flex-direction: column;
	justify-content: flex-start;
	overflow: auto;
}

.question-content {
	max-width: 500px;
}

.main-title {
	font-size: 1.5rem;
	font-weight: bold;
	margin-bottom: 1.5rem;
	color: #1e293b;
}

.question-card {
	background-color: white;
	padding: 1.5rem;
	border-radius: 8px;
	border: 1px solid #e2e8f0;
	margin-bottom: 1.5rem;
}

.question-title {
	font-size: 1.2rem;
	font-weight: 600;
	margin-bottom: 1rem;
	color: #374151;
}

.question-text {
	line-height: 1.6;
	margin-bottom: 1rem;
	color: #4b5563;
}

.question-text:last-child {
	margin-bottom: 0;
}

.instructions-card {
	background-color: #e0f2fe;
	padding: 1rem;
	border-radius: 6px;
	border: 1px solid #0284c7;
}

.instructions-title {
	margin: 0;
	font-size: 1rem;
	font-weight: 600;
	margin-bottom: 0.5rem;
	color: #0c4a6e;
}

.instructions-list {
	margin: 0;
	padding-left: 1.2rem;
	color: #0c4a6e;
}

.hint-card {
	background-color: #fef3c7;
	padding: 1rem;
	border-radius: 6px;
	border: 1px solid #f59e0b;
	margin-top: 1rem;
}

.hint-text {
	margin: 0;
	font-size: 0.9rem;
	color: #92400e;
}

.canvas-panel {
	flex: 1;
	position: relative;
	background-color: #ffffff;
	min-width: 0; /* Allows flex item to shrink below content size */
}

.canvas-container {
	position: absolute;
	top: 1rem;
	left: 1rem;
	right: 1rem;
	bottom: 1rem;
	border: 2px solid #e2e8f0;
	border-radius: 8px;
	overflow: hidden;
}

.cartesian-grid {
	position: absolute;
	top: 0px;
	left: 0px;
	right: 0;
	bottom: 0;
	width: 600px;
	height: 600px;
	overflow: visible;
}

.mask-fg {
	position: absolute;
	inset: 0px;
	background-color: black;
	opacity: 0.5;
	pointer-events: none;
}

/* Answer Section Styles */
.answer-section {
	padding: 1rem;
	background-color: #f8fafc;
	border-top: 2px solid #e2e8f0;
	max-height: 300px;
	overflow-y: auto;
}

.answer-title {
	font-size: 1.1rem;
	font-weight: 600;
	margin-bottom: 1rem;
	color: #374151;
}

.answer-input-group {
	margin-bottom: 1rem;
}

.answer-input-group:last-child {
	margin-bottom: 0;
}

.answer-label {
	display: block;
	font-size: 0.9rem;
	font-weight: 500;
	margin-bottom: 0.5rem;
	color: #4b5563;
}

.answer-input {
	width: 100%;
	padding: 0.5rem;
	border: 1px solid #d1d5db;
	border-radius: 4px;
	font-size: 0.9rem;
	color: #374151;
	background-color: white;
	box-sizing: border-box;
}

.answer-input:focus {
	outline: none;
	border-color: #3b82f6;
	box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
}

.answer-input::placeholder {
	color: #9ca3af;
}

.submit-button {
	width: 100%;
	padding: 0.75rem;
	margin-top: 1rem;
	background-color: #3b82f6;
	color: white;
	border: none;
	border-radius: 6px;
	font-size: 1rem;
	font-weight: 600;
	cursor: pointer;
	transition: background-color 0.2s ease;
}

.submit-button:hover {
	background-color: #2563eb;
}

.submit-button:active {
	background-color: #1d4ed8;
}

/* Question Part Styles */
.question-part {
	margin-bottom: 1.5rem;
}

.question-part:last-of-type {
	margin-bottom: 1rem;
}

/* Answer input styles within question card */
.question-card .answer-input-group {
	margin-top: 0.75rem;
	margin-bottom: 0;
}

.question-card .answer-input {
	width: 100%;
	padding: 0.5rem;
	border: 1px solid #d1d5db;
	border-radius: 4px;
	font-size: 0.9rem;
	color: #374151;
	background-color: white;
	box-sizing: border-box;
}

.question-card .answer-input:focus {
	outline: none;
	border-color: #3b82f6;
	box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
}

.question-card .answer-input::placeholder {
	color: #9ca3af;
}

.question-card .submit-button {
	width: 100%;
	padding: 0.75rem;
	margin-top: 1rem;
	background-color: #3b82f6;
	color: white;
	border: none;
	border-radius: 6px;
	font-size: 1rem;
	font-weight: 600;
	cursor: pointer;
	transition: background-color 0.2s ease;
}

.question-card .submit-button:hover {
	background-color: #2563eb;
}

.question-card .submit-button:active {
	background-color: #1d4ed8;
}

/* Mobile responsiveness */
@media (max-width: 1000px) {
	.education-container {
		flex-direction: column;
		gap: 0;
		min-height: auto;
	}

.question-panel {
		max-width: none;
		border-right: none;
		border-bottom: 2px solid #e2e8f0;
	}

.canvas-panel {
		min-height: 60vh;
	}

.canvas-container {
		overflow: hidden;
		position: relative !important;
		top: auto !important;
		left: auto !important;
		right: auto !important;
		bottom: auto !important;
		height: 60vh;
		margin: 1rem;
	}
}
```

--------

# Image annotator

Category: Use cases

Keywords: annotation, camera options, constraints, zoom, pan, camera bounds, pan speed, zoom speed

An image annotator built with tldraw.

This example shows how you might want to configure `cameraOptions` to make an image annotation app.

## App.tsx

```tsx
import { useState } from 'react'
import 'tldraw/tldraw.css'
import { ImageAnnotationEditor } from './ImageAnnotationEditor'
import { ImageExport } from './ImageExport'
import { ImagePicker } from './ImagePicker'
import './image-annotator.css'
import { AnnotatorImage } from './types'

type State =
	| {
			phase: 'pick'
	  }
	| {
			phase: 'annotate'
			id: string
			image: AnnotatorImage
	  }
	| {
			phase: 'export'
			result: Blob
	  }

export default function ImageAnnotatorWrapper() {
	const [state, setState] = useState<State>({ phase: 'pick' })

switch (state.phase) {
		case 'pick':
			return (
				<div className="ImageAnnotator">
					<ImagePicker
						onChooseImage={(image) =>
							setState({ phase: 'annotate', image, id: Math.random().toString(36) })
						}
					/>
				</div>
			)
		case 'annotate':
			return (
				<div className="ImageAnnotator">
					<ImageAnnotationEditor
						// remount tldraw if the image/id changes:
						key={state.id}
						image={state.image}
						onDone={(result) => setState({ phase: 'export', result })}
					/>
				</div>
			)
		case 'export':
			return (
				<div className="ImageAnnotator">
					<ImageExport result={state.result} onStartAgain={() => setState({ phase: 'pick' })} />
				</div>
			)
	}
}
```

## ImageAnnotationEditor.tsx

```tsx
import { useCallback, useEffect, useState } from 'react'
import {
	AssetRecordType,
	Editor,
	SVGContainer,
	TLImageShape,
	TLShapeId,
	Tldraw,
	createShapeId,
	track,
	useEditor,
} from 'tldraw'
import { AnnotatorImage } from './types'

// TODO:
// - prevent changing pages (create page, change page, move shapes to new page)
// - prevent locked shape context menu
// - inertial scrolling for constrained camera
export function ImageAnnotationEditor({
	image,
	onDone,
}: {
	image: AnnotatorImage
	onDone(result: Blob): void
}) {
	const [imageShapeId, setImageShapeId] = useState<TLShapeId | null>(null)
	const [editor, setEditor] = useState(null as Editor | null)

function onMount(editor: Editor) {
		setEditor(editor)
	}

useEffect(() => {
		if (!editor) return

// Create the asset and image shape
		const assetId = AssetRecordType.createId()
		editor.createAssets([
			{
				id: assetId,
				typeName: 'asset',
				type: 'image',
				meta: {},
				props: {
					w: image.width,
					h: image.height,
					mimeType: image.type,
					src: image.src,
					name: 'image',
					isAnimated: false,
				},
			},
		])
		const shapeId = createShapeId()
		editor.createShape({
			id: shapeId,
			type: 'image',
			x: 0,
			y: 0,
			isLocked: true,
			props: {
				w: image.width,
				h: image.height,
				assetId,
			},
		})

// Make sure the shape is at the bottom of the page
		function makeSureShapeIsAtBottom() {
			if (!editor) return

const shape = editor.getShape(shapeId)
			if (!shape) return

const pageId = editor.getCurrentPageId()

// The shape should always be the child of the current page
			if (shape.parentId !== pageId) {
				editor.moveShapesToPage([shape], pageId)
			}

// The shape should always be at the bottom of the page's children
			const siblings = editor.getSortedChildIdsForParent(pageId)
			const currentBottomShape = editor.getShape(siblings[0])!
			if (currentBottomShape.id !== shapeId) {
				editor.sendToBack([shape])
			}
		}

makeSureShapeIsAtBottom()

const removeOnCreate = editor.sideEffects.registerAfterCreateHandler(
			'shape',
			makeSureShapeIsAtBottom
		)

const removeOnChange = editor.sideEffects.registerAfterChangeHandler(
			'shape',
			makeSureShapeIsAtBottom
		)

// The shape should always be locked
		const cleanupKeepShapeLocked = editor.sideEffects.registerBeforeChangeHandler(
			'shape',
			(prev, next) => {
				if (next.id !== shapeId) return next
				if (next.isLocked) return next
				return { ...prev, isLocked: true }
			}
		)

// Reset the history
		editor.clearHistory()
		setImageShapeId(shapeId)

return () => {
			removeOnChange()
			removeOnCreate()
			cleanupKeepShapeLocked()
		}
	}, [image, editor])

useEffect(() => {
		if (!editor) return
		if (!imageShapeId) return

/**
		 * We don't want the user to be able to scroll away from the image, or zoom it all the way out. This
		 * component hooks into camera updates to keep the camera constrained - try uploading a very long,
		 * thin image and seeing how the camera behaves.
		 */
		editor.setCameraOptions({
			constraints: {
				initialZoom: 'default',
				baseZoom: 'fit-min-100',
				bounds: { w: image.width, h: image.height, x: 0, y: 0 },
				padding: { x: 32, y: 64 },
				origin: { x: 0.5, y: 0.5 },
				behavior: 'contain',
			},
		})
		editor.setCamera(editor.getCamera(), { reset: true })
	}, [editor, imageShapeId, image])

return (
		<Tldraw
			onMount={onMount}
			components={{
				// we don't need pages for this use-case
				PageMenu: null,
				// grey-out the area outside of the image
				InFrontOfTheCanvas: useCallback(() => {
					if (!imageShapeId) return null
					return <ImageBoundsOverlay imageShapeId={imageShapeId} />
				}, [imageShapeId]),
				// add a "done" button in the top right for when the user is ready to export
				SharePanel: useCallback(() => {
					if (!imageShapeId) return null
					return <DoneButton imageShapeId={imageShapeId} onClick={onDone} />
				}, [imageShapeId, onDone]),
			}}
		/>
	)
}

/**
 * When we export, we'll only include the bounds of the image itself, so show an overlay on top of
 * the canvas to make it clear what will/won't be included. Check `image-annotator.css` for more on
 * how this works.
 */
const ImageBoundsOverlay = track(function ImageBoundsOverlay({
	imageShapeId,
}: {
	imageShapeId: TLShapeId
}) {
	const editor = useEditor()
	const image = editor.getShape(imageShapeId) as TLImageShape
	if (!image) return null

const imagePageBounds = editor.getShapePageBounds(imageShapeId)!
	const viewport = editor.getViewportScreenBounds()
	const topLeft = editor.pageToViewport(imagePageBounds)
	const bottomRight = editor.pageToViewport({ x: imagePageBounds.maxX, y: imagePageBounds.maxY })

const path = [
		// start by tracing around the viewport itself:
		`M ${-10} ${-10}`,
		`L ${viewport.maxX + 10} ${-10}`,
		`L ${viewport.maxX + 10} ${viewport.maxY + 10}`,
		`L ${-10} ${viewport.maxY + 10}`,
		`Z`,

// then cut out a hole for the image:
		`M ${topLeft.x} ${topLeft.y}`,
		`L ${bottomRight.x} ${topLeft.y}`,
		`L ${bottomRight.x} ${bottomRight.y}`,
		`L ${topLeft.x} ${bottomRight.y}`,
		`Z`,
	].join(' ')

return (
		<SVGContainer className="ImageOverlayScreen">
			<path d={path} fillRule="evenodd" />
		</SVGContainer>
	)
})

function DoneButton({
	imageShapeId,
	onClick,
}: {
	imageShapeId: TLShapeId
	onClick(result: Blob): void
}) {
	const editor = useEditor()
	return (
		<button
			className="DoneButton"
			onClick={async () => {
				const { blob } = await editor.toImage([...editor.getCurrentPageShapeIds()], {
					format: 'png',
					background: true,
					bounds: editor.getShapePageBounds(imageShapeId)!,
					padding: 0,
					scale: 1,
				})

onClick(blob)
			}}
		>
			Done
		</button>
	)
}
```

## ImageExport.tsx

```tsx
import { useEffect, useLayoutEffect, useState } from 'react'

export function ImageExport({ result, onStartAgain }: { result: Blob; onStartAgain(): void }) {
	const [src, setSrc] = useState<string | null>(null)
	useLayoutEffect(() => {
		const url = URL.createObjectURL(result)
		setSrc(url)
		return () => URL.revokeObjectURL(url)
	}, [result])

function onDownload() {
		if (!src) return

const a = document.createElement('a')
		a.href = src
		a.download = 'annotated-image.png'
		a.click()
	}

const [didCopy, setDidCopy] = useState(false)
	function onCopy() {
		navigator.clipboard.write([new ClipboardItem({ [result.type]: result })])
		setDidCopy(true)
	}
	useEffect(() => {
		if (!didCopy) return
		const t = setTimeout(() => setDidCopy(false), 2000)
		return () => clearTimeout(t)
	}, [didCopy])

return (
		<div className="ImageExport">
			{src && <img src={src} />}
			<div className="ImageExport-buttons">
				<button onClick={onCopy}>{didCopy ? 'Copied!' : 'Copy'}</button>
				<button onClick={onDownload}>Download</button>
			</div>
			<button onClick={onStartAgain}>Start Again</button>
		</div>
	)
}
```

## ImagePicker.tsx

```tsx
import { useState } from 'react'
import { DEFAULT_SUPPORTED_MEDIA_TYPE_LIST, FileHelpers, MediaHelpers } from 'tldraw'
import anakin from './assets/anakin.jpeg'
import distractedBf from './assets/distracted-bf.jpeg'
import expandingBrain from './assets/expanding-brain.png'

export function ImagePicker({
	onChooseImage,
}: {
	onChooseImage(image: { src: string; width: number; height: number; type: string }): void
}) {
	const [isLoading, setIsLoading] = useState(false)
	function onClickChooseImage() {
		const input = window.document.createElement('input')
		input.type = 'file'
		input.accept = DEFAULT_SUPPORTED_MEDIA_TYPE_LIST
		input.addEventListener('change', async (e) => {
			const fileList = (e.target as HTMLInputElement).files
			if (!fileList || fileList.length === 0) return
			const file = fileList[0]

setIsLoading(true)
			try {
				const dataUrl = await FileHelpers.blobToDataUrl(file)
				const { w, h } = await MediaHelpers.getImageSize(file)
				onChooseImage({ src: dataUrl, width: w, height: h, type: file.type })
			} finally {
				setIsLoading(false)
			}
		})
		input.click()
	}

async function onChooseExample(src: string) {
		setIsLoading(true)
		try {
			const image = await fetch(src)
			const blob = await image.blob()
			const { w, h } = await MediaHelpers.getImageSize(blob)
			onChooseImage({ src, width: w, height: h, type: blob.type })
		} finally {
			setIsLoading(false)
		}
	}

if (isLoading) {
		return <div className="ImagePicker">Loading...</div>
	}

return (
		<div className="ImagePicker">
			<button onClick={onClickChooseImage}>Choose an image</button>
			<div className="ImagePicker-exampleLabel">or use an example:</div>
			<div className="ImagePicker-examples">
				<img src={anakin} alt="anakin" onClick={() => onChooseExample(anakin)} />
				<img
					src={distractedBf}
					alt="distracted boyfriend"
					onClick={() => onChooseExample(distractedBf)}
				/>
				<img
					src={expandingBrain}
					alt="expanding brain"
					onClick={() => onChooseExample(expandingBrain)}
				/>
			</div>
		</div>
	)
}
```

## image-annotator.css

```css
.ImageAnnotator {
	position: absolute;
	inset: 0;
}

.ImageAnnotator .ImagePicker {
	position: absolute;
	inset: 1rem;
	display: flex;
	align-items: center;
	justify-content: center;
	text-align: center;
	flex-direction: column;
	gap: 1rem;
}
.ImageAnnotator .ImagePicker button {
	padding: 0.5rem 1rem;
	border: none;
	background: #eee;
	cursor: pointer;
	font: inherit;
}
.ImageAnnotator .ImagePicker button:hover {
	opacity: 0.9;
}
.ImageAnnotator .ImagePicker-exampleLabel {
	padding-top: 1rem;
	opacity: 0.7;
	font-size: 14px;
}
.ImageAnnotator .ImagePicker-examples {
	display: grid;
	grid-template-columns: repeat(3, 1fr);
	width: 100%;
	max-width: 780px;
	gap: 1rem;
}
.ImageAnnotator .ImagePicker-examples img {
	width: 100%;
	height: auto;
	object-fit: contain;
	aspect-ratio: 1;
	cursor: pointer;
}
.ImageAnnotator .ImagePicker-examples img:hover {
	opacity: 0.9;
}

.ImageAnnotator .ImageOverlayScreen {
	pointer-events: none;
	fill: var(--tl-color-background);
	fill-opacity: 0.8;
	stroke: none;
}

.ImageAnnotator .DoneButton {
	font: inherit;
	background: var(--tl-color-primary);
	border: none;
	color: var(--tl-color-selected-contrast);
	font-size: 1rem;
	padding: 0.5rem 1rem;
	border-radius: 6px;
	margin: 6px;
	pointer-events: all;
	z-index: var(--tl-layer-panels);
	border: 2px solid var(--tl-color-background);
	cursor: pointer;
}
.ImageAnnotator .DoneButton:hover {
	filter: brightness(1.1);
}

.ImageAnnotator .ImageExport {
	padding: 1rem;
	display: flex;
	flex-direction: column;
	gap: 1rem;
	align-items: center;
	height: 100%;
}
.ImageAnnotator .ImageExport img {
	width: 100%;
	max-height: 50vh;
	object-fit: contain;
}
.ImageAnnotator .ImageExport button {
	padding: 0.5rem 1rem;
	border: none;
	background: #eee;
	cursor: pointer;
	font: inherit;
}
.ImageAnnotator .ImageExport button:hover {
	opacity: 0.9;
}
.ImageAnnotator .ImageExport-buttons {
	display: flex;
	gap: 1rem;
	align-items: center;
	justify-content: center;
	margin-bottom: auto;
}
.ImageAnnotator .ImageExport-buttons button {
	background-color: hsl(214, 84%, 56%);
	color: white;
}
```

## types.tsx

```tsx
export interface AnnotatorImage {
	src: string
	width: number
	height: number
	type: string
}
```

--------

# PDF editor

Category: Use cases

Keywords: annotation, camera options, constraints, zoom, pan, camera bounds, pan speed, zoom speed, scroll

A very basic PDF editor built with tldraw.

This example shows how you might want to configure `cameraOptions` to make a PDF editor.

## App.tsx

```tsx
import { useState } from 'react'
import 'tldraw/tldraw.css'
import { PdfEditor } from './PdfEditor'
import { Pdf, PdfPicker } from './PdfPicker'
import './pdf-editor.css'

type State =
	| {
			phase: 'pick'
	  }
	| {
			phase: 'edit'
			pdf: Pdf
	  }

export default function PdfEditorWrapper() {
	const [state, setState] = useState<State>({ phase: 'pick' })

switch (state.phase) {
		case 'pick':
			return (
				<div className="PdfEditor">
					<PdfPicker onOpenPdf={(pdf) => setState({ phase: 'edit', pdf })} />
				</div>
			)
		case 'edit':
			return (
				<div className="PdfEditor">
					<PdfEditor pdf={state.pdf} />
				</div>
			)
	}
}
```

## ExportPdfButton.tsx

```tsx
import { PDFDocument } from 'pdf-lib'
import { useState } from 'react'
import { Editor, useEditor } from 'tldraw'
import { Pdf } from './PdfPicker'

export function ExportPdfButton({ pdf }: { pdf: Pdf }) {
	const [exportProgress, setExportProgress] = useState<number | null>(null)
	const editor = useEditor()

return (
		<button
			className="ExportPdfButton"
			onClick={async () => {
				setExportProgress(0)
				try {
					await exportPdf(editor, pdf, setExportProgress)
				} finally {
					setExportProgress(null)
				}
			}}
		>
			{exportProgress ? `Exporting... ${Math.round(exportProgress * 100)}%` : 'Export PDF'}
		</button>
	)
}

async function exportPdf(
	editor: Editor,
	{ name, source, pages }: Pdf,
	onProgress: (progress: number) => void
) {
	const totalThings = pages.length * 2 + 2
	let progressCount = 0
	const tickProgress = () => {
		progressCount++
		onProgress(progressCount / totalThings)
	}

const pdf = await PDFDocument.load(source)
	tickProgress()

const pdfPages = pdf.getPages()
	if (pdfPages.length !== pages.length) {
		throw new Error('PDF page count mismatch')
	}

const pageShapeIds = new Set(pages.map((page) => page.shapeId))
	const allIds = Array.from(editor.getCurrentPageShapeIds()).filter((id) => !pageShapeIds.has(id))

for (let i = 0; i < pages.length; i++) {
		const page = pages[i]
		const pdfPage = pdfPages[i]

const bounds = page.bounds
		const shapesInBounds = allIds.filter((id) => {
			const shapePageBounds = editor.getShapePageBounds(id)
			if (!shapePageBounds) return false
			return shapePageBounds.collides(bounds)
		})

if (shapesInBounds.length === 0) {
			tickProgress()
			tickProgress()
			continue
		}

const exportedPng = await editor.toImage(allIds, {
			format: 'png',
			background: false,
			bounds: page.bounds,
			padding: 0,
			scale: 1,
		})
		tickProgress()

pdfPage.drawImage(await pdf.embedPng(await exportedPng.blob.arrayBuffer()), {
			x: 0,
			y: 0,
			width: pdfPage.getWidth(),
			height: pdfPage.getHeight(),
		})
		tickProgress()
	}

const url = URL.createObjectURL(new Blob([await pdf.save()], { type: 'application/pdf' }))
	tickProgress()
	const a = document.createElement('a')
	a.href = url
	a.download = name
	a.click()
	URL.revokeObjectURL(url)
}
```

## PdfEditor.tsx

```tsx
import { useMemo } from 'react'
import {
	Box,
	SVGContainer,
	TLComponents,
	TLImageShape,
	TLShapePartial,
	Tldraw,
	getIndicesBetween,
	react,
	sortByIndex,
	track,
	useEditor,
} from 'tldraw'
import { ExportPdfButton } from './ExportPdfButton'
import { Pdf } from './PdfPicker'

// TODO:
// - prevent changing pages (create page, change page, move shapes to new page)
// - prevent locked shape context menu
// - inertial scrolling for constrained camera
// - render pages on-demand instead of all at once.
export function PdfEditor({ pdf }: { pdf: Pdf }) {
	const components = useMemo<TLComponents>(
		() => ({
			PageMenu: null,
			Overlays: () => <PageOverlayScreen pdf={pdf} />,
			SharePanel: () => <ExportPdfButton pdf={pdf} />,
		}),
		[pdf]
	)

return (
		<Tldraw
			onMount={(editor) => {
				editor.createAssets(
					pdf.pages.map((page) => ({
						id: page.assetId,
						typeName: 'asset',
						type: 'image',
						meta: {},
						props: {
							w: page.bounds.w,
							h: page.bounds.h,
							mimeType: 'image/png',
							src: page.src,
							name: 'page',
							isAnimated: false,
						},
					}))
				)
				editor.createShapes(
					pdf.pages.map(
						(page): TLShapePartial<TLImageShape> => ({
							id: page.shapeId,
							type: 'image',
							x: page.bounds.x,
							y: page.bounds.y,
							isLocked: true,
							props: {
								assetId: page.assetId,
								w: page.bounds.w,
								h: page.bounds.h,
							},
						})
					)
				)

const shapeIds = pdf.pages.map((page) => page.shapeId)
				const shapeIdSet = new Set(shapeIds)

// Don't let the user unlock the pages
				editor.sideEffects.registerBeforeChangeHandler('shape', (prev, next) => {
					if (!shapeIdSet.has(next.id)) return next
					if (next.isLocked) return next
					return { ...prev, isLocked: true }
				})

// Make sure the shapes are below any of the other shapes
				function makeSureShapesAreAtBottom() {
					const shapes = shapeIds.map((id) => editor.getShape(id)!).sort(sortByIndex)
					const pageId = editor.getCurrentPageId()

const siblings = editor.getSortedChildIdsForParent(pageId)
					const currentBottomShapes = siblings
						.slice(0, shapes.length)
						.map((id) => editor.getShape(id)!)

if (currentBottomShapes.every((shape, i) => shape.id === shapes[i].id)) return

const otherSiblings = siblings.filter((id) => !shapeIdSet.has(id))
					const bottomSibling = otherSiblings[0]
					const lowestIndex = editor.getShape(bottomSibling)!.index

const indexes = getIndicesBetween(undefined, lowestIndex, shapes.length)
					editor.updateShapes(
						shapes.map((shape, i) => ({
							...shape,
							id: shape.id,
							isLocked: shape.isLocked,
							index: indexes[i],
						}))
					)
				}

makeSureShapesAreAtBottom()
				editor.sideEffects.registerAfterCreateHandler('shape', makeSureShapesAreAtBottom)
				editor.sideEffects.registerAfterChangeHandler('shape', makeSureShapesAreAtBottom)

// Constrain the camera to the bounds of the pages
				const targetBounds = pdf.pages.reduce(
					(acc, page) => acc.union(page.bounds),
					pdf.pages[0].bounds.clone()
				)

function updateCameraBounds(isMobile: boolean) {
					editor.setCameraOptions({
						constraints: {
							bounds: targetBounds,
							padding: { x: isMobile ? 16 : 164, y: 64 },
							origin: { x: 0.5, y: 0 },
							initialZoom: 'fit-x-100',
							baseZoom: 'default',
							behavior: 'contain',
						},
					})
					editor.setCamera(editor.getCamera(), { reset: true })
				}

let isMobile = editor.getViewportScreenBounds().width < 840

react('update camera', () => {
					const isMobileNow = editor.getViewportScreenBounds().width < 840
					if (isMobileNow === isMobile) return
					isMobile = isMobileNow
					updateCameraBounds(isMobile)
				})

updateCameraBounds(isMobile)
			}}
			components={components}
		/>
	)
}

const PageOverlayScreen = track(function PageOverlayScreen({ pdf }: { pdf: Pdf }) {
	const editor = useEditor()

const viewportPageBounds = editor.getViewportPageBounds()

const relevantPageBounds = pdf.pages
		.map((page) => {
			if (!viewportPageBounds.collides(page.bounds)) return null
			return page.bounds
		})
		.filter((bounds): bounds is Box => bounds !== null)

function pathForPageBounds(bounds: Box) {
		return `M ${bounds.x} ${bounds.y} L ${bounds.maxX} ${bounds.y} L ${bounds.maxX} ${bounds.maxY} L ${bounds.x} ${bounds.maxY} Z`
	}

const viewportPath = `M ${viewportPageBounds.x} ${viewportPageBounds.y} L ${viewportPageBounds.maxX} ${viewportPageBounds.y} L ${viewportPageBounds.maxX} ${viewportPageBounds.maxY} L ${viewportPageBounds.x} ${viewportPageBounds.maxY} Z`

return (
		<>
			<SVGContainer className="PageOverlayScreen-screen">
				<path
					d={`${viewportPath} ${relevantPageBounds.map(pathForPageBounds).join(' ')}`}
					fillRule="evenodd"
				/>
			</SVGContainer>
			{relevantPageBounds.map((bounds, i) => (
				<div
					key={i}
					className="PageOverlayScreen-outline"
					style={{
						width: bounds.w,
						height: bounds.h,
						transform: `translate(${bounds.x}px, ${bounds.y}px)`,
					}}
				/>
			))}
		</>
	)
})
```

## PdfPicker.tsx

```tsx
import PdfJSWorkerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url'

import { useState } from 'react'
import { AssetRecordType, Box, TLAssetId, TLShapeId, createShapeId } from 'tldraw'
import tldrawPdf from './assets/tldraw.pdf'

export interface PdfPage {
	src: string
	bounds: Box
	assetId: TLAssetId
	shapeId: TLShapeId
}

export interface Pdf {
	name: string
	pages: PdfPage[]
	source: string | ArrayBuffer
}

const pageSpacing = 32

export function PdfPicker({ onOpenPdf }: { onOpenPdf(pdf: Pdf): void }) {
	const [isLoading, setIsLoading] = useState(false)

async function loadPdf(name: string, source: ArrayBuffer): Promise<Pdf> {
		const PdfJS = await import('pdfjs-dist')
		PdfJS.GlobalWorkerOptions.workerSrc = PdfJSWorkerSrc

const pdf = await PdfJS.getDocument(source.slice(0)).promise
		const pages: PdfPage[] = []

const canvas = window.document.createElement('canvas')
		const context = canvas.getContext('2d')
		if (!context) throw new Error('Failed to create canvas context')

const visualScale = 1.5
		const scale = window.devicePixelRatio

let top = 0
		let widest = 0
		for (let i = 1; i <= pdf.numPages; i++) {
			const page = await pdf.getPage(i)
			const viewport = page.getViewport({ scale: scale * visualScale })
			canvas.width = viewport.width
			canvas.height = viewport.height
			const renderContext = {
				canvasContext: context,
				viewport,
			}
			await page.render(renderContext).promise

const width = viewport.width / scale
			const height = viewport.height / scale
			pages.push({
				src: canvas.toDataURL(),
				bounds: new Box(0, top, width, height),
				assetId: AssetRecordType.createId(),
				shapeId: createShapeId(),
			})
			top += height + pageSpacing
			widest = Math.max(widest, width)
		}
		canvas.width = 0
		canvas.height = 0

for (const page of pages) {
			page.bounds.x = (widest - page.bounds.width) / 2
		}

return {
			name,
			pages,
			source,
		}
	}

function onClickOpenPdf() {
		const input = window.document.createElement('input')
		input.type = 'file'
		input.accept = 'application/pdf'
		input.addEventListener('change', async (e) => {
			const fileList = (e.target as HTMLInputElement).files
			if (!fileList || fileList.length === 0) return
			const file = fileList[0]

setIsLoading(true)
			try {
				const pdf = await loadPdf(file.name, await file.arrayBuffer())
				onOpenPdf(pdf)
			} finally {
				setIsLoading(false)
			}
		})
		input.click()
	}

async function onClickUseExample() {
		setIsLoading(true)
		try {
			const result = await fetch(tldrawPdf)
			const pdf = await loadPdf('tldraw.pdf', await result.arrayBuffer())
			onOpenPdf(pdf)
		} finally {
			setIsLoading(false)
		}
	}

if (isLoading) {
		return <div className="PdfPicker">Loading...</div>
	}

return (
		<div className="PdfPicker">
			<button onClick={onClickOpenPdf}>Open PDF</button>
			<div>or</div>
			<button onClick={onClickUseExample}>Use an example</button>
		</div>
	)
}
```

## pdf-editor.css

```css
.PdfEditor {
	position: absolute;
	inset: 0;
}

.PdfEditor .PdfPicker {
	position: absolute;
	inset: 1rem;
	display: flex;
	align-items: center;
	justify-content: center;
	text-align: center;
	flex-direction: column;
	gap: 1rem;
}
.PdfEditor .PdfPicker button {
	padding: 0.5rem 1rem;
	border: none;
	background: #eee;
	cursor: pointer;
	font: inherit;
}
.PdfEditor .PdfPicker button:hover {
	opacity: 0.9;
}

.PdfEditor .PdfBgRenderer {
	position: absolute;
	pointer-events: none;
}
.PdfEditor .PdfBgRenderer img {
	position: absolute;
}

.PdfEditor .PageOverlayScreen-screen {
	pointer-events: none;
	fill: var(--tl-color-background);
	fill-opacity: 0.8;
	stroke: none;
}
.PdfEditor .PageOverlayScreen-outline {
	position: absolute;
	pointer-events: none;
	box-shadow: var(--tl-shadow-2);
}
.PdfEditor .ExportPdfButton {
	font: inherit;
	background: var(--tl-color-primary);
	border: none;
	color: var(--tl-color-selected-contrast);
	font-size: 1rem;
	padding: 0.5rem 1rem;
	border-radius: 6px;
	margin: 6px;
	margin-bottom: 0;
	pointer-events: all;
	z-index: var(--tl-layer-panels);
	border: 2px solid var(--tl-color-background);
	cursor: pointer;
}
.PdfEditor .ExportPdfButton:hover {
	filter: brightness(1.1);
}
```

--------

# Canvas mask

Category: Use cases

Keywords: mask, window, clip

This example shows how you can mask the canvas.

The canvas has a white overlay. When you have a shape selected, the shape's bounds will be used as a mask through the overlay.

## App.tsx

```tsx
import { useEffect, useRef } from 'react'
import { TLComponents, TLShape, Tldraw, createShapeId, useEditor, useQuickReactor } from 'tldraw'
import 'tldraw/tldraw.css'
import './mask-window.css'

function MaskWindow() {
	const editor = useEditor()
	const ref = useRef<HTMLDivElement>(null)

useQuickReactor(
		'clip',
		() => {
			const elm = ref.current
			if (!elm) return

const rotation = editor.getSelectionRotation()
			const box = editor.getSelectionRotatedScreenBounds()

if (!box) {
				// If there's nothing selected, clear the clip path
				elm.style.clipPath = ''
				return
			}

const vsb = editor.getViewportScreenBounds()

// Expand the box, offset it by the viewport screen bounds, and get the corners
			const { corners } = box.clone().translate(vsb.point.clone().neg()).expandBy(20)

// Account for rotation by rotating the points of the rectangle
			const [tl, tr, br, bl] = corners.map((p) => p.rotWith(box.point, rotation))

// Since there's no reliable "reverse clip path", we wind around the corners in order to turn our clip into a mask
			elm.style.clipPath = `polygon(0% 0%, ${tl.x}px 0%, ${tl.x}px ${tl.y}px, ${bl.x}px ${bl.y}px, ${br.x}px ${br.y}px, ${tr.x}px ${tr.y}px, ${tl.x}px ${tl.y}px, ${tl.x}px 0%, 100% 0%, 100% 100%, 0% 100%)`
		},
		[editor]
	)

useExtraBonusStuff()

return <div ref={ref} className="mask-fg" />
}

const components: TLComponents = {
	InFrontOfTheCanvas: () => {
		return <MaskWindow />
	},
}

export default function MaskWindowExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="mask" components={components} />
		</div>
	)
}

// Some extra stuff that isnt necessary but good for this demo
function useExtraBonusStuff() {
	const editor = useEditor()

useEffect(() => {
		if (editor.getCurrentPageShapeIds().size === 0) {
			const vpb = editor.getViewportPageBounds()

// if the canvas is empty, create some shapes for the demo
			for (let i = 0; i < 50; i++) {
				const x = vpb.x + Math.random() * vpb.w
				const y = vpb.y + Math.random() * vpb.h
				editor.createShape({ type: 'geo', x, y })
			}

const id = createShapeId()
			const { center } = editor.getViewportPageBounds()
			editor.createShape({
				id,
				type: 'geo',
				x: center.x - 100,
				y: center.y - 100,
				props: {
					w: 200,
					h: 200,
				},
			})
			editor.select(id)
		}

// As a (fragile) treat, press J to save positions for the selected shape, then press Ctrl+J to animate between positions
		const positions: TLShape[] = []

const handleKeydown = (e: any) => {
			if (e.key === 'j') {
				e.preventDefault()
				e.stopPropagation()
				if (e.metaKey || e.ctrlKey) {
					const shape = positions.shift()
					if (!shape) return
					editor.animateShape(shape, { animation: { duration: 1000 } })
				} else {
					const shape = editor.getOnlySelectedShape()
					if (!shape) return
					positions.push(shape)
				}
			}
		}
		document.addEventListener('keydown', handleKeydown)
		return () => {
			document.removeEventListener('keydown', handleKeydown)
		}
	}, [editor])
}
```

## mask-window.css

```css
.mask-svg {
	position: absolute;
	top: 0px;
	left: 0px;
}

.mask-fg {
	position: absolute;
	top: 0px;
	left: 0px;
	width: 100%;
	height: 100%;
	pointer-events: none;
	background-color: rgba(255, 255, 255, 0.9);
	/* -webkit-mask:
		url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" preserveAspectRatio="none"><rect x="100" y="100" width="20" height="20"/></svg>')
			0/100% 100%,
		linear-gradient(#fff, #fff);
	-webkit-mask-composite: destination-out;
	mask-composite: exclude; */
}
```

--------

# Fog of war

Category: Use cases

Keywords: ui, fog, overlay

Create a fog of war effect by keeping an HTML canvas in sync with canvas content.

This example shows how you might keep an HTML canvas in sync with canvas content. It implements a simple "fog of war" effect, where the canvas is covered by a black overlay that can be cleared by drawing shapes on the canvas.

## App.tsx

```tsx
import { useEffect, useRef } from 'react'
import { Box, TLComponents, Tldraw, Vec, useEditor, useReactor } from 'tldraw'
import 'tldraw/tldraw.css'

const CELL_SIZE = 32
const COUNT = 100

const boxes: Box[][] = []
const cells: boolean[][] = []
for (let i = 0; i < COUNT; i++) {
	cells[i] = []
	boxes[i] = []
	for (let j = 0; j < COUNT; j++) {
		cells[i].push(false)
		boxes[i].push(
			new Box((i - COUNT / 2) * CELL_SIZE, (j - COUNT / 2) * CELL_SIZE, CELL_SIZE, CELL_SIZE)
		)
	}
}

export function Fog() {
	const rCanvas = useRef<HTMLCanvasElement>(null)
	const rVisibility = useRef<boolean[][]>(cells)
	const editor = useEditor()

useEffect(() => {
		const cvs = rCanvas.current!
		const rect = cvs.getBoundingClientRect()
		cvs.width = rect.width
		cvs.height = rect.height
	}, [editor])

useReactor(
		'update fog',
		() => {
			const cells = rVisibility.current
			const shapes = editor.getCurrentPageShapes()
			for (const shape of shapes) {
				const point = editor.getShapePageBounds(shape)!.point
				const geometry = editor.getShapeGeometry(shape)
				const adjustedPoint = Vec.Sub(point, geometry.bounds.point)
				for (let i = 0; i < boxes.length; i++) {
					for (let j = 0; j < boxes[i].length; j++) {
						const box = boxes[i][j]
						box.translate(Vec.Neg(adjustedPoint))
						if (geometry.bounds.collides(box)) {
							cells[i][j] = true
						}
						box.translate(adjustedPoint)
					}
				}
			}
			const cvs = rCanvas.current!
			const ctx = cvs.getContext('2d')!

cvs.style.filter = `blur(${editor.getCamera().z * 15}px)`

ctx.resetTransform()
			const camera = editor.getCamera()

ctx.clearRect(0, 0, cvs.width, cvs.height)
			ctx.fillStyle = 'rgba(0,0,0,0.9)'
			ctx.fillRect(0, 0, cvs.width, cvs.height)

ctx.translate(100, 100)
			ctx.scale(camera.z, camera.z)
			ctx.translate(camera.x, camera.y)

for (let i = 0; i < boxes.length; i++) {
				for (let j = 0; j < boxes[i].length; j++) {
					if (!cells[i][j]) continue
					const box = boxes[i][j]
					ctx.clearRect(box.x, box.y, box.width, box.height)
				}
			}
		},
		[editor]
	)

return (
		<canvas
			ref={rCanvas}
			style={{
				position: 'absolute',
				top: -100,
				left: -100,
				width: 'calc(100% + 200px)',
				height: 'calc(100% + 200px)',
				WebkitFilter: 'blur(15px)',
				filter: 'blur(15px)',
				pointerEvents: 'none',
			}}
		/>
	)
}

const components: TLComponents = {
	InFrontOfTheCanvas: Fog,
}

export default function BasicExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="example" components={components} />
		</div>
	)
}
```

--------

# Mark exams

Category: Use cases

Keywords: education, pdf, annotation, toolbar, util, ui overrides

A tool for marking exams. It includes common pdf annotation tools, as well as a built in tool for marking individual questions and tallying the total score of the exam.

This example, built on top of the [pdf-editor](https://examples.tldraw.com/pdf-editor) example, shows how you might take a more tailored approach to building a pdf editor experience. It includes:

- A custom shape called `exam-mark` that allows you to add marks on a per question basis.
- A custom tool to place the `exam-mark` shape.
- A widget that shows the total exam score (the sum of all `exam-mark` scores in the document), useful if you wanted to export it the total score to a database.

## App.tsx

```tsx
import { useState } from 'react'
import 'tldraw/tldraw.css'
import './pdf-editor/pdf-editor.css'
import { PdfEditor } from './pdf-editor/PdfEditor'
import { Pdf, PdfPicker } from './pdf-editor/PdfPicker'

type State =
	| {
			phase: 'pick'
	  }
	| {
			phase: 'edit'
			pdf: Pdf
	  }

export default function ExamMarkingExample() {
	const [state, setState] = useState<State>({ phase: 'pick' })

/*
Introduction:

This example of an exam marking tool is built on top of the `pdf-editor` example. The files specific to the pdf-editor live in the `pdf-editor` folder in this directory.
What this adds on top of the pdf editor is a custom shape that allows you mark individual questions and have their score tallied, and a custom tool that allows you create that shape.

File structure:
`add-mark-util.tsx` is a shape utility that defines the exam mark shape.
`add-mark-tool.tsx` is a custom tool that allows you to add the exam mark shape to the page.
`ExamScoreLabel.tsx` is a widget that shows the total exam score.
`ui-overrides.tsx` is a file that overrides the default toolbar and keyboard shortcuts menu to add the exam mark tool.

*/
```

## ExamScoreLabel.tsx

```tsx
import { useEditor, useValue } from 'tldraw'

// [1]
export function ExamScoreLabel() {
	const editor = useEditor()

const score = useValue(
		'score',
		() => {
			let score = 0
			for (const shape of editor.getCurrentPageShapes()) {
				if (!editor.isShapeOfType(shape, 'exam-mark')) continue
				score += shape.props.score
			}
			return score
		},
		[editor]
	)

return (
		<div
			style={{
				background: 'var(--tl-color-panel)',

display: 'flex',
				alignItems: 'center',
				justifyContent: 'center',
				padding: '0.5rem 1rem',
				borderRadius: '6px',
				margin: '6px 0px 0px 0px',
				borderWidth: '2px',
				borderStyle: 'solid',
				borderColor: 'var(--tl-color-background-contrast)',
				zIndex: 'var(--tl-layer-panels)',
			}}
		>
			<p style={{ fontSize: '1.25em', margin: 0 }}>Total exam score: {score}</p>
		</div>
	)
}

[1]
This is a simple widget that shows the total exam score. It's an example of how to use the editor instance to compute a value that depends on the shapes on the page.

[a]
We listen for changes to the document using the editor.store.listen method inside of a useEffect hook.

[b]
We define a function that calculates the score based on the shapes on the page. We filter all shapes on the current page to only include `exam-mark` shapes, and then access the score prop of each shape and add them all to get the total score.

*/
```

## add-mark-tool.tsx

```tsx
import { StateNode } from 'tldraw'
import { EXAM_MARK_HEIGHT, EXAM_MARK_WIDTH } from './add-mark-util'

// Check out the custom tool example for a more detailed explanation of the StateNode class.

export class MarkingTool extends StateNode {
	static override id = 'mark'

override onEnter() {
		this.editor.setCursor({ type: 'cross', rotation: 0 })
	}

override onPointerUp() {
		const pagePoint = this.editor.inputs.getCurrentPagePoint()
		this.editor.createShape({
			type: 'exam-mark',
			x: pagePoint.x - EXAM_MARK_WIDTH / 2,
			y: pagePoint.y - EXAM_MARK_HEIGHT / 2,
		})

if (!this.editor.getInstanceState().isToolLocked) {
			this.editor.setCurrentTool('select')
		}
	}
}
```

## add-mark-util.tsx

```tsx
import { useEffect, useRef, useState } from 'react'
import { HTMLContainer, RecordProps, Rectangle2d, ShapeUtil, T, TLShape } from 'tldraw'

export const EXAM_MARK_WIDTH = 80
export const EXAM_MARK_HEIGHT = 40

const EXAM_MARK_TYPE = 'exam-mark'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[EXAM_MARK_TYPE]: {
			score: number
		}
	}
}

export type IExamMarkShape = TLShape<typeof EXAM_MARK_TYPE>

export const examMarkShapeDefaultProps: IExamMarkShape['props'] = {
	score: 0,
}

export class ExamMarkUtil extends ShapeUtil<IExamMarkShape> {
	static override type = EXAM_MARK_TYPE
	static override props: RecordProps<IExamMarkShape> = {
		score: T.number,
	}

override getDefaultProps(): IExamMarkShape['props'] {
		return examMarkShapeDefaultProps
	}

// [1]
	override canEdit(_shape: IExamMarkShape): boolean {
		return true
	}

// [2]
	override component(shape: IExamMarkShape) {
		// [a]
		const isEditing = this.editor.getEditingShapeId() === shape.id

// [b]
		/* eslint-disable react-hooks/rules-of-hooks */
		const [score, setScore] = useState<number | string>(shape.props.score)

const inputRef = useRef<HTMLInputElement>(null)

// [c]
		useEffect(() => {
			this.editor.setEditingShape(shape.id)
		}, [shape.id])

// [d]
		useEffect(() => {
			if (isEditing && inputRef.current) {
				inputRef.current.focus()
				inputRef.current.select()
			}
		}, [isEditing])
		/* eslint-enable react-hooks/rules-of-hooks */

// [e]
		const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
			const value = e.target.value
			setScore(value)
			const num = Number(value)
			if (!isNaN(num)) {
				this.editor.updateShape({
					id: shape.id,
					type: EXAM_MARK_TYPE,
					props: {
						score: num,
					},
				})
			}
		}

return (
			<HTMLContainer id={shape.id}>
				<div
					style={{
						height: '100%',
						fontSize: '1.5em',
						display: 'flex',
						alignItems: 'center',
					}}
				>
					<input
						ref={inputRef}
						type="number"
						value={score}
						style={{
							width: '100%',
							fontSize: '1.25em',
							padding: '6px 10px',
							borderRadius: 4,
							border: '1px solid blue',
							opacity: 0.7,
							pointerEvents: isEditing ? 'all' : 'none',
						}}
						onChange={handleChange}
						onBlur={() => {
							this.editor.setEditingShape(null)
						}}
						onPointerDown={isEditing ? this.editor.markEventAsHandled : undefined}
						onPointerUp={isEditing ? this.editor.markEventAsHandled : undefined}
						onPointerMove={isEditing ? this.editor.markEventAsHandled : undefined}
					/>
				</div>
			</HTMLContainer>
		)
	}

override indicator() {
		return <rect width={EXAM_MARK_WIDTH} height={EXAM_MARK_HEIGHT} rx={4} />
	}

getGeometry() {
		return new Rectangle2d({
			width: EXAM_MARK_WIDTH,
			height: EXAM_MARK_HEIGHT,
			isFilled: true,
		})
	}

override hideSelectionBoundsBg() {
		return true
	}
	override hideSelectionBoundsFg() {
		return true
	}

override canResize(_shape: IExamMarkShape): boolean {
		return false
	}
}

/*
A utility class for the exam mark shape. This is where you define the shape's behavior, how it renders (its component and indicator), and how it handles different events. For more details on how to create a custom shape utility, check out the `custom-config` example.

[1] We allow this component to be editable. This gives us some behavior for free, namely double clicking the shape will start editing the shape, which we can access using `editor.getEditingShapeId()`. With this, we can focus the input when the shape is double clicked. See [1][a] and [1][c] for more details.

[2] Render method — the React component that will be rendered for the shape. It takes the shape as an argument. HTMLContainer is just a div that's being used to wrap the input.

- [a] To control behavior, we need to know if the shape is being edited. We can access this using `editor.getEditingShapeId()`.

- [b] The important part of this shape utility is how it handles the score input. We know we want the ExamScoreLabel component to be able to access the score of the shape, so we want the score to be a prop for the shape.
 Annoying: eslint sometimes thinks this is a class component, but it's not.

- [c] When the shape is mounted, we set it to be in editing mode.

- [d] Focus the input when the the shape is being edited, i.e. when it's double clicked or when it's mounted. This means that when a shape is created, the text is immediately focused and selected.

- [e] We want to be able to edit the score of the shape, so we need to be able to update the shape's props. We do this by using the editor.updateShape method when we detect that the score is a number.

For notes on the other parts of this shape utility, check out the `custom-config` example.
*/
```

## ui-overrides.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TldrawUiMenuItem,
	TLUiOverrides,
	useIsToolSelected,
	useTools,
} from 'tldraw'

// There's a guide at the bottom of this file!

// [1]
export const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		// Create a tool item in the ui's context.
		tools.mark = {
			id: 'mark',
			icon: <span style={{ fontSize: '2em' }}>📝</span>,
			label: 'Mark Exam',
			kbd: 'm',
			onSelect: () => {
				editor.setCurrentTool('mark')
			},
		}
		return tools
	},
}

// [2]
export const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isMarkingToolSelected = useIsToolSelected(tools['mark'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['mark']} isSelected={isMarkingToolSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	KeyboardShortcutsDialog: (props) => {
		const tools = useTools()
		return (
			<DefaultKeyboardShortcutsDialog {...props}>
				<TldrawUiMenuItem {...tools['mark']} />
				<DefaultKeyboardShortcutsDialogContent />
			</DefaultKeyboardShortcutsDialog>
		)
	},
}

This file contains overrides for the Tldraw UI. These overrides are used to add your custom tools to
the toolbar and the keyboard shortcuts menu.

[1]
First we have to add our new tool to the tools object in the tools override. This is where we define
all the basic information about our new tool - its icon, label, keyboard shortcut, what happens when
we select it, etc.

[2]
Then, we replace the UI components for the toolbar and keyboard shortcut dialog with our own, that
add our new tool to the existing default content. Ideally, we'd interleave our new tool into the
ideal place among the default tools, but for now we're just adding it at the start to keep things
simple.
*/
```

## ExportPdfButton.tsx

```tsx
import { PDFDocument } from 'pdf-lib'
import { useState } from 'react'
import { Editor, useEditor } from 'tldraw'
import { Pdf } from './PdfPicker'

export function ExportPdfButton({ pdf }: { pdf: Pdf }) {
	const [exportProgress, setExportProgress] = useState<number | null>(null)
	const editor = useEditor()

return (
		<button
			style={{
				font: 'inherit',
				background: 'var(--tl-color-primary)',
				border: 'none',
				color: 'var(--tl-color-selected-contrast)',
				fontSize: '1rem',
				padding: '0.5rem 1rem',
				borderRadius: '6px',
				margin: '6px 0px',
				marginBottom: 0,
				pointerEvents: 'all',
				zIndex: 'var(--tl-layer-panels)',
				borderWidth: '2px',
				borderStyle: 'solid',
				borderColor: 'var(--tl-color-background)',
				cursor: 'pointer',
			}}
			onClick={async () => {
				setExportProgress(0)
				try {
					await exportPdf(editor, pdf, setExportProgress)
				} finally {
					setExportProgress(null)
				}
			}}
		>
			{exportProgress ? `Exporting... ${Math.round(exportProgress * 100)}%` : 'Export PDF'}
		</button>
	)
}

const pdf = await PDFDocument.load(source)
	tickProgress()

const pdfPages = pdf.getPages()
	if (pdfPages.length !== pages.length) {
		throw new Error('PDF page count mismatch')
	}

const pageShapeIds = new Set(pages.map((page) => page.shapeId))
	const allIds = Array.from(editor.getCurrentPageShapeIds()).filter((id) => !pageShapeIds.has(id))

for (let i = 0; i < pages.length; i++) {
		const page = pages[i]
		const pdfPage = pdfPages[i]

if (shapesInBounds.length === 0) {
			tickProgress()
			tickProgress()
			continue
		}

const exportedPng = await editor.toImage(shapesInBounds, {
			format: 'png',
			background: false,
			bounds: page.bounds,
			padding: 0,
			scale: 1,
		})
		tickProgress()

pdfPage.drawImage(await pdf.embedPng(await exportedPng.blob.arrayBuffer()), {
			x: 0,
			y: 0,
			width: pdfPage.getWidth(),
			height: pdfPage.getHeight(),
		})
		tickProgress()
	}

## PdfEditor.tsx

```tsx
import { useMemo } from 'react'
import {
	Box,
	SVGContainer,
	StateNode,
	TLClickEventInfo,
	TLComponents,
	TLImageShape,
	TLShapePartial,
	Tldraw,
	getIndicesBetween,
	react,
	sortByIndex,
	track,
	useEditor,
} from 'tldraw'
import { MarkingTool } from '../add-mark-tool'
import { EXAM_MARK_HEIGHT, EXAM_MARK_WIDTH, ExamMarkUtil } from '../add-mark-util'
import { ExamScoreLabel } from '../ExamScoreLabel'
import { components, uiOverrides } from '../ui-overrides'
import { ExportPdfButton } from './ExportPdfButton'
import { Pdf } from './PdfPicker'

const customShapeUtils = [ExamMarkUtil]
const customTools = [MarkingTool]

export function PdfEditor({ pdf }: { pdf: Pdf }) {
	const pdfEditorComponents = useMemo<TLComponents>(
		() => ({
			PageMenu: null,
			Overlays: () => <PageOverlayScreen pdf={pdf} />,
			SharePanel: () => (
				<div
					style={{
						display: 'flex',
						flexDirection: 'row',
						alignItems: 'center',
						gap: 8,
						justifyContent: 'normal',
						padding: '0px 6px',
					}}
				>
					<ExamScoreLabel />
					<ExportPdfButton pdf={pdf} />
				</div>
			),
			...components,
		}),
		[pdf]
	)

return (
		<Tldraw
			onMount={(editor) => {
				// See the custom-double-click-behavior example for more details on this
				type IdleStateNode = StateNode & {
					handleDoubleClickOnCanvas(info: TLClickEventInfo): void
				}

const selectIdleState = editor.getStateDescendant<IdleStateNode>('select.idle')
				if (!selectIdleState) throw Error('SelectTool Idle state not found')

function customDoubleClickOnCanvasHandler(_info: TLClickEventInfo) {
					const pagePoint = editor.inputs.getCurrentPagePoint()
					editor.createShape({
						type: 'exam-mark',
						x: pagePoint.x - EXAM_MARK_WIDTH / 2,
						y: pagePoint.y - EXAM_MARK_HEIGHT / 2,
					})
				}

selectIdleState.handleDoubleClickOnCanvas =
					customDoubleClickOnCanvasHandler.bind(selectIdleState)

editor.createAssets(
					pdf.pages.map((page) => ({
						id: page.assetId,
						typeName: 'asset',
						type: 'image',
						meta: {},
						props: {
							w: page.bounds.w,
							h: page.bounds.h,
							mimeType: 'image/png',
							src: page.src,
							name: 'page',
							isAnimated: false,
						},
					}))
				)
				editor.createShapes(
					pdf.pages.map(
						(page): TLShapePartial<TLImageShape> => ({
							id: page.shapeId,
							type: 'image',
							x: page.bounds.x,
							y: page.bounds.y,
							isLocked: true,
							props: {
								assetId: page.assetId,
								w: page.bounds.w,
								h: page.bounds.h,
							},
						})
					)
				)

const shapeIds = pdf.pages.map((page) => page.shapeId)
				const shapeIdSet = new Set(shapeIds)

const siblings = editor.getSortedChildIdsForParent(pageId)
					const currentBottomShapes = siblings
						.slice(0, shapes.length)
						.map((id) => editor.getShape(id)!)

if (currentBottomShapes.every((shape, i) => shape.id === shapes[i].id)) return

const otherSiblings = siblings.filter((id) => !shapeIdSet.has(id))
					const bottomSibling = otherSiblings[0]
					const lowestIndex = editor.getShape(bottomSibling)!.index

makeSureShapesAreAtBottom()
				editor.sideEffects.registerAfterCreateHandler('shape', makeSureShapesAreAtBottom)
				editor.sideEffects.registerAfterChangeHandler('shape', makeSureShapesAreAtBottom)

// Constrain the camera to the bounds of the pages
				const targetBounds = pdf.pages.reduce(
					(acc, page) => acc.union(page.bounds),
					pdf.pages[0].bounds.clone()
				)

let isMobile = editor.getViewportScreenBounds().width < 840

updateCameraBounds(isMobile)
			}}
			components={pdfEditorComponents}
			tools={customTools}
			initialState="mark" // set the initial tool to the exam marking tool
			shapeUtils={customShapeUtils}
			overrides={uiOverrides}
		/>
	)
}

const PageOverlayScreen = track(function PageOverlayScreen({ pdf }: { pdf: Pdf }) {
	const editor = useEditor()

const viewportPageBounds = editor.getViewportPageBounds()

const relevantPageBounds = pdf.pages
		.map((page) => {
			if (!viewportPageBounds.collides(page.bounds)) return null
			return page.bounds
		})
		.filter((bounds): bounds is Box => bounds !== null)

function pathForPageBounds(bounds: Box) {
		return `M ${bounds.x} ${bounds.y} L ${bounds.maxX} ${bounds.y} L ${bounds.maxX} ${bounds.maxY} L ${bounds.x} ${bounds.maxY} Z`
	}

## PdfPicker.tsx

```tsx
import PdfJSWorkerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url'
import { useState } from 'react'
import { AssetRecordType, Box, TLAssetId, TLShapeId, createShapeId } from 'tldraw'
import examPdf from '../assets/biologyExamExample.pdf'

export interface PdfPage {
	src: string
	bounds: Box
	assetId: TLAssetId
	shapeId: TLShapeId
}

export interface Pdf {
	name: string
	pages: PdfPage[]
	source: string | ArrayBuffer
}

const pageSpacing = 32

export function PdfPicker({ onOpenPdf }: { onOpenPdf(pdf: Pdf): void }) {
	const [isLoading, setIsLoading] = useState(false)

async function loadPdf(name: string, source: ArrayBuffer): Promise<Pdf> {
		const PdfJS = await import('pdfjs-dist')
		PdfJS.GlobalWorkerOptions.workerSrc = PdfJSWorkerSrc
		const pdf = await PdfJS.getDocument(source.slice(0)).promise
		const pages: PdfPage[] = []

const canvas = window.document.createElement('canvas')
		const context = canvas.getContext('2d')
		if (!context) throw new Error('Failed to create canvas context')

const visualScale = 1.5
		const scale = window.devicePixelRatio

for (const page of pages) {
			page.bounds.x = (widest - page.bounds.width) / 2
		}

return {
			name,
			pages,
			source,
		}
	}

setIsLoading(true)
			try {
				const pdf = await loadPdf(file.name, await file.arrayBuffer())
				onOpenPdf(pdf)
			} finally {
				setIsLoading(false)
			}
		})
		input.click()
	}

async function onClickUseExample() {
		setIsLoading(true)
		try {
			const result = await fetch(examPdf)
			const pdf = await loadPdf('biologyExamExample.pdf', await result.arrayBuffer())
			onOpenPdf(pdf)
		} finally {
			setIsLoading(false)
		}
	}

if (isLoading) {
		return <div className="PdfPicker">Loading...</div>
	}

return (
		<div className="PdfPicker">
			<button onClick={onClickOpenPdf}>Open PDF</button>
			<div>or</div>
			<button onClick={onClickUseExample}>Use an example</button>
		</div>
	)
}
```

## pdf-editor.css

```css
.PdfEditor {
	position: absolute;
	inset: 0;
}

.PdfEditor .PdfBgRenderer {
	position: absolute;
	pointer-events: none;
}
.PdfEditor .PdfBgRenderer img {
	position: absolute;
}

--------

# Snowstorm

Category: Use cases

Keywords: snowstorm, front

Show a visual effect in front of the canvas.

This example shows how you can display a visual effect (a snowstorm) in front of the canvas.

## App.tsx

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

export default function BasicExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="example">
				<SnowStorm />
			</Tldraw>
		</div>
	)
}
```

## SnowStorm.tsx

```tsx
import { useEffect, useRef } from 'react'
import { Vec, useEditor, usePrefersReducedMotion } from 'tldraw'

const MAX_GUST_SPEED = 2
const GUST_ROTATION_DURATION = 30_000

const MAX_PIXELS_SCROLL_EFFECT = 18
const MAX_SCROLL_SPEED = 2

const MIN_POINTER_DISTANCE_SQUARED = 10_000
const SNOWFLAKE_VELOCITY_DECAY = 0.82

interface Snowflake {
	element: HTMLElement
	x: number
	y: number
	vx: number
	vy: number
	pvx: number
	pvy: number
	size: number
}

function rnd(min: number, max: number): number {
	return Math.random() * (max - min) + min
}

class Snowstorm {
	private flakes: Snowflake[] = []
	private active: boolean = false
	private container: HTMLElement
	private width: number
	private height: number

windX = 0
	windY = 0

baseWindX = 0

// Configuration options
	private readonly config = {
		flakesMax: 128,
		flakeSizeMin: 2,
		flakeSizeMax: 5,
		flakeSpeedMinY: 1,
		flakeSpeedMaxY: 3,
		flakeSpeedX: 2,
	}

constructor(container: HTMLElement = document.body) {
		this.container = container
		this.width = container.clientWidth
		this.height = container.clientHeight
	}

private createSnowflake(): Snowflake {
		const element = document.createElement('div')
		element.classList.add('snowflake')
		this.container.appendChild(element)

return {
			element,
			x: 0,
			y: 0,
			vx: 0,
			vy: 0,
			pvx: 0,
			pvy: 0,
			size: 1,
		}
	}

configureSnowflake(flake: Snowflake) {
		const size = rnd(this.config.flakeSizeMin, this.config.flakeSizeMax)
		flake.x = rnd(0, this.width)
		flake.y = rnd(-this.height, 0)
		flake.vx = rnd(-this.config.flakeSpeedX, this.config.flakeSpeedX)
		flake.vy = rnd(this.config.flakeSpeedMinY, this.config.flakeSpeedMaxY)
		flake.element.style.width = `${size}px`
		flake.element.style.height = `${size}px`
		flake.element.style.opacity = rnd(0.5, 1).toString()
	}

// Main render loop
	render(screenPoint: Vec, pointerVelocity: Vec, time: number) {
		if (!this.active) return

const q = Math.sin(time / GUST_ROTATION_DURATION)

// make wind gradually cycle between 0 and 10, maybe a bit randomly, like gusts of wind
		this.baseWindX = q * MAX_GUST_SPEED

const pointerLen = pointerVelocity.len2()

for (const flake of this.flakes) {
			const dist2 = Vec.Dist2(screenPoint, new Vec(flake.x, flake.y))

// if the pointer is moving quickly, give nearby snowflakes a little boost based on the pointer velocity
			if (dist2 < MIN_POINTER_DISTANCE_SQUARED) {
				if (pointerLen > 1) {
					flake.pvx = pointerVelocity.x
					flake.pvy = pointerVelocity.y < 0 ? pointerVelocity.y / 2 : pointerVelocity.y // don't push up as easily
				}
			} else {
				// otherwise, declay down other snowflakes that have been boosted
				if (flake.pvx !== 0) {
					flake.pvx *= SNOWFLAKE_VELOCITY_DECAY
					if (Math.abs(flake.pvx) < 0.01) {
						flake.pvx = 0
					}

if (flake.pvy !== 0) {
						flake.pvy *= SNOWFLAKE_VELOCITY_DECAY
						if (Math.abs(flake.pvy) < 0.01) {
							flake.pvy = 0
						}
					}
				}
			}

// Move the flake based on the wind, the base wind, the pointer velocity, and some random wobble
			flake.x += flake.vx + this.windX + this.baseWindX + flake.pvx
			flake.y += flake.vy + this.windY + flake.pvy

// Wrap the snowflakes around the screen horizontally
			if (flake.x < 0) {
				flake.x += this.width
				flake.pvx = 0
			} else if (flake.x > this.width) {
				flake.x -= this.width
				flake.pvx = 0
			}

// Wrap the snowflakes around the screen vertically
			if (flake.y < 0) {
				flake.y += this.height
				flake.pvy = 0
			} else if (flake.y > this.height) {
				flake.y -= this.height
				flake.pvy = 0
			}

flake.element.style.transform = `translate(${flake.x}px, ${flake.y}px)`
		}
	}

resize() {
		this.width = this.container.clientWidth
		this.height = this.container.clientHeight
	}

start() {
		this.active = true
		while (this.flakes.length < this.config.flakesMax) {
			const flake = this.createSnowflake()
			this.configureSnowflake(flake)
			this.flakes.push(flake)
		}
		window.addEventListener('resize', this.resize)
	}

stop() {
		this.active = false
		for (const flake of this.flakes) {
			this.container.removeChild(flake.element)
		}
		this.flakes = []
	}

dispose() {
		this.stop()
		window.removeEventListener('resize', this.resize)
	}
}

export function SnowStorm() {
	const editor = useEditor()
	const rElm = useRef<HTMLDivElement>(null)
	const prefersReducedMotion = usePrefersReducedMotion()

useEffect(() => {
		if (prefersReducedMotion) return
		if (!rElm.current) return
		const snowstorm = new Snowstorm(rElm.current)
		const velocity = new Vec(0, 0)
		const camera = Vec.From(editor.getCamera())

const start = Date.now()

function updateOnTick() {
			const time = Date.now() - start

const newCamera = editor.getCamera()

// Apply camera movement effect only when zoom isn't changing
			if (newCamera.z === camera.z) {
				const dx = (newCamera.x - camera.x) * camera.z
				const dy = (newCamera.y - camera.y) * camera.z

// add the camera movement to the velocity
				velocity.addXY(
					Math.min(dx / MAX_PIXELS_SCROLL_EFFECT, MAX_SCROLL_SPEED),
					Math.min(dy / MAX_PIXELS_SCROLL_EFFECT, MAX_SCROLL_SPEED)
				)

// decay velocity
				velocity.mul(SNOWFLAKE_VELOCITY_DECAY)

// stop the snowflakes from moving if the camera is not moving
				if (velocity.len2() < 1) {
					velocity.x = 0
					velocity.y = 0
				}

snowstorm.windX = velocity.x
				snowstorm.windY = velocity.y
			}

camera.setTo(newCamera)
			snowstorm.render(
				editor.inputs.getCurrentScreenPoint(),
				editor.inputs.getPointerVelocity(),
				time
			)
		}

snowstorm.start()
		editor.on('tick', updateOnTick)

return () => {
			editor.off('tick', updateOnTick)
			snowstorm.dispose()
		}
	}, [editor, prefersReducedMotion])

return <div ref={rElm} className="snowstorm" />
}
```

## snowstorm.css

```css
.snowflake {
	position: absolute;
	background-color: #ccc;
	border-radius: 100%;
	pointer-events: none;
}

.snowstorm {
	position: absolute;
	width: 100%;
	height: 100%;
	pointer-events: none;
}
```

--------

# Timeline scrubber

Category: Use cases

Keywords: timeline, history, undo, redo, time travel, scrubber

A timeline scrubber that records document changes and allows time travel through editor history.

This example demonstrates how to create a timeline scrubber that records all document changes using `store.listen` and enables time travel through the editing history. Users can scrub backwards and forwards through time using a slider control at the bottom of the editor. If changes are made while scrubbed back in time, a new timeline branch is created from that point.

## App.tsx

```tsx
import { useCallback, useEffect, useState } from 'react'
import {
	RecordsDiff,
	reverseRecordsDiff,
	squashRecordDiffs,
	Tldraw,
	TldrawUiSlider,
	track,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './timeline-scrubber.css'

interface TimelineEntry {
	timestamp: number
	diff: RecordsDiff<any>
}

interface TimelineState {
	entries: TimelineEntry[]
	currentIndex: number
}

export default function TimelineScrubberExample() {
	return (
		<div className="timeline-scrubber-example">
			<Tldraw>
				<TimelineScrubber />
			</Tldraw>
		</div>
	)
}

const TimelineScrubber = track(() => {
	const editor = useEditor()

const [timeline, setTimeline] = useState<TimelineState>({
		entries: [],
		currentIndex: 0,
	})

// [1]
	const recordChange = useCallback((diff: RecordsDiff<any>) => {
		const newEntry: TimelineEntry = {
			timestamp: Date.now(),
			diff,
		}

setTimeline((prev) => {
			// [2]
			if (prev.currentIndex < prev.entries.length) {
				// We're scrubbed back in time, create new timeline branch
				const newEntries = prev.entries.slice(0, prev.currentIndex)
				newEntries.push(newEntry)
				return {
					entries: newEntries,
					currentIndex: newEntries.length,
				}
			} else {
				// Normal forward progression
				const newEntries = [...prev.entries, newEntry]
				return {
					entries: newEntries,
					currentIndex: newEntries.length,
				}
			}
		})
	}, [])

// [3]
	useEffect(() => {
		if (!editor) return

const cleanupFn = editor.store.listen(
			({ changes }) => {
				recordChange(changes)
			},
			{ scope: 'document', source: 'user' }
		)

return cleanupFn
	}, [editor, recordChange])

// [4]
	const navigateToIndex = useCallback(
		(targetIndex: number) => {
			if (!editor || targetIndex === timeline.currentIndex) return

const { entries, currentIndex } = timeline

const isForward = targetIndex > currentIndex
			const diffsToApply = entries
				.slice(Math.min(currentIndex, targetIndex), Math.max(currentIndex, targetIndex))
				.map((entry) => entry.diff)

if (diffsToApply.length > 0) {
				if (!isForward) diffsToApply.reverse()

let diffToApply =
					diffsToApply.length === 1 ? diffsToApply[0] : squashRecordDiffs(diffsToApply)

if (!isForward) {
					diffToApply = reverseRecordsDiff(diffToApply)
				}

editor.store.mergeRemoteChanges(() => {
					editor.store.applyDiff(diffToApply)
				})
			}

setTimeline((prev) => ({ ...prev, currentIndex: targetIndex }))
		},
		[timeline, editor]
	)

const handleSliderChange = useCallback(
		(newIndex: number) => {
			navigateToIndex(newIndex)
		},
		[navigateToIndex]
	)

const isEmpty = timeline.entries.length === 0

const length = Math.max(3, String(timeline.entries.length).length)

return (
		<div className="timeline-scrubber-controls">
			<div className="timeline-scrubber-info">
				{isEmpty
					? '000 / 000'
					: `${timeline.currentIndex.toString().padStart(length, '0')} / ${timeline.entries.length.toString().padStart(length, '0')}`}
			</div>
			<TldrawUiSlider
				steps={timeline.entries.length}
				value={isEmpty ? 1 : timeline.currentIndex}
				label="History"
				title={
					timeline.currentIndex === 0
						? 'Empty canvas'
						: new Date(
								timeline.entries[timeline.currentIndex - 1]?.timestamp ?? Date.now()
							).toLocaleString()
				}
				onValueChange={handleSliderChange}
			/>
		</div>
	)
})

/*
[1]
The recordChange function handles new changes from the store. It creates a new timeline entry
and manages timeline branching logic.

[2]
If we're not at the latest point in time (currentIndex < entries.length), it means the user
made a change while scrubbed back. We truncate the future timeline and create a new branch.
Timeline indexing: 0 = empty canvas, 1 = first change applied, 2 = second change, etc.

[3] 
We listen to document changes from user actions only, filtering out changes we make during
navigation to avoid recording our own time travel operations.

[4]
Navigation collects the required diffs, squashes them into a single optimized diff, then
applies it (reversing first if going backward). Uses mergeRemoteChanges to ensure changes
are treated as remote and don't trigger our listener.
*/
```

## timeline-scrubber.css

```css
.timeline-scrubber-example {
	height: 100vh;
	width: 100%;
}

.timeline-scrubber-controls {
	position: absolute;
	top: 0;
	left: 0;
	right: 0;
	display: flex;
	align-items: center;
	gap: 12px;
	padding: 0 16px;
	background: var(--color-panel);
	border-top: 1px solid var(--color-muted-1);
	font-size: 12px;
	color: var(--color-text-1);
}

.timeline-scrubber-info {
	flex-shrink: 0;
	font-variant: tabular-nums;
}

.timeline-scrubber-controls .tlui-slider__container {
	flex: 1;
}

.timeline-scrubber-example .tl-canvas {
	top: 44px;
}
.timeline-scrubber-example .tlui-layout {
	top: 44px;
	height: calc(100% - 44px);
}
```

Oops!

Something went wrong

{title}

Focusing: {focusName}