# tldraw SDK features

--------

# Accessibility

Tldraw includes accessibility features for keyboards and assistive technologies. The SDK announces shape selections to screen readers, supports keyboard navigation between shapes, respects reduced motion preferences, and provides hooks for custom shapes to supply descriptive text.

## Screen reader announcements

When users select shapes, tldraw announces the selection to screen readers through a live region. The announcement includes the shape type, any descriptive text, and the shape's position in reading order.

For a single shape selection, the announcement follows this pattern: "[description], [shape type]. [position] of [total]". For example, selecting an image with alt text might announce "A team photo, image. 3 of 7". Multiple selections announce the count: "4 shapes selected".

The announcement system uses the [`DefaultA11yAnnouncer`](/reference/tldraw/DefaultA11yAnnouncer) component, which renders a visually hidden live region that screen readers monitor for changes. The [`useA11y`](/reference/tldraw/useA11y) hook provides programmatic access to announce custom messages:

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

function CustomAnnouncement() {
	const a11y = useA11y()

	const handleCustomAction = () => {
		a11y.announce({ msg: 'Custom action completed', priority: 'polite' })
	}

	return <button onClick={handleCustomAction}>Do action</button>
}

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

The `priority` option accepts `'polite'` or `'assertive'` and defaults to `'assertive'`. Polite announcements wait for a pause in speech, while assertive announcements interrupt immediately. See [`TLUiA11y`](/reference/tldraw/TLUiA11y) for the message type.

> See the [screen reader accessibility example](/examples/ui/screen-reader-accessibility) for custom shape descriptions and announcements.

## Keyboard navigation

Users can navigate between shapes using the keyboard. With a shape selected, Tab moves selection to the next shape in reading order and Shift+Tab moves to the previous shape. Arrow keys with Ctrl/Cmd move selection to the nearest shape in that direction, and Ctrl/Cmd+Shift+Down or Up select a group's first child or its parent. [`Editor.selectAdjacentShape`](/reference/editor/Editor#selectAdjacentShape) is the programmatic equivalent.

Tldraw determines reading order by analyzing shape positions on the canvas. Shapes are grouped into rows based on their vertical position, then sorted left-to-right within each row. This creates a natural top-to-bottom, left-to-right reading order similar to text. You can access this order programmatically with [`Editor.getCurrentPageShapesInReadingOrder`](/reference/editor/Editor#getCurrentPageShapesInReadingOrder).

A "Skip to main content" link appears when users Tab into the editor. It selects the first shape on the canvas and zooms to it.

### Excluding shapes from keyboard navigation

Exclude custom shapes from keyboard navigation by overriding [`ShapeUtil.canTabTo`](/reference/editor/ShapeUtil#canTabTo):

```tsx
class DecorativeShapeUtil extends ShapeUtil<DecorativeShape> {
	// Decorative shapes don't receive keyboard focus
	canTabTo() {
		return false
	}

	// ...
}
```

Shapes that return `false` from `canTabTo()` are skipped during Tab navigation and excluded from reading order calculations.

## Shape descriptions for screen readers

When a shape is selected, the announcement includes descriptive text from two sources: the shape's text content and its ARIA descriptor. [`ShapeUtil.getText`](/reference/editor/ShapeUtil#getText) returns the shape's primary text content, while [`ShapeUtil.getAriaDescriptor`](/reference/editor/ShapeUtil#getAriaDescriptor) provides alternative text specifically for accessibility purposes.

For most shapes, `getText()` is sufficient. The default implementation returns `undefined`, which produces announcements with just the shape type and position.

### Providing alt text for media shapes

Image and video shapes support an `altText` property that `getAriaDescriptor()` returns. Users can set alt text through the media toolbar when an image or video is selected:

```tsx
// Setting alt text programmatically
editor.updateShapes([
	{
		id: imageShape.id,
		type: 'image',
		props: { altText: 'A diagram showing the system architecture' },
	},
])
```

### Custom shape descriptions

Give custom shapes screen reader descriptions by overriding [`ShapeUtil.getAriaDescriptor`](/reference/editor/ShapeUtil#getAriaDescriptor):

```tsx
class CardShapeUtil extends ShapeUtil<CardShape> {
	getAriaDescriptor(shape: CardShape) {
		// Return a description that makes sense when read aloud
		return `${shape.props.title}: ${shape.props.summary}`
	}

	// ...
}
```

If your shape has visible text, override [`ShapeUtil.getText`](/reference/editor/ShapeUtil#getText) instead. The announcement system checks `getAriaDescriptor()` first, then falls back to `getText()`:

```tsx
class CardShapeUtil extends ShapeUtil<CardShape> {
	getText(shape: CardShape) {
		return shape.props.title
	}

	// ...
}
```

## Reduced motion

The SDK respects user motion preferences through the `animationSpeed` user preference. When set to 0, animations are disabled. By default, this value matches the operating system's `prefers-reduced-motion` setting.

Use [`usePrefersReducedMotion`](/reference/tldraw/usePrefersReducedMotion) in custom shape components to check whether to show animations:

```tsx
import { usePrefersReducedMotion } from 'tldraw'

function AnimatedIndicator() {
	const prefersReducedMotion = usePrefersReducedMotion()

	if (prefersReducedMotion) {
		return <StaticIndicator />
	}

	return <PulsingIndicator />
}
```

The hook returns `true` when:

- The `animationSpeed` preference is 0 (the default when the OS prefers reduced motion)
- When used outside an editor context, the operating system's reduced motion preference is enabled

Users can toggle reduced motion through the accessibility menu, found under Preferences in the main menu.

> See the [reduced motion example](/examples/configuration/reduced-motion) for a custom shape that respects motion preferences.

## Enhanced accessibility mode

The `enhancedA11yMode` user preference adds visible labels to UI elements that normally rely on icons alone. When enabled, the style panel shows text labels for each section like "Color", "Opacity", and "Align". This helps users who need more context than an icon provides.

Toggle this setting programmatically:

```tsx
editor.user.updateUserPreferences({
	enhancedA11yMode: true,
})
```

## Disabling keyboard shortcuts

Assistive technologies often have their own keyboard commands that conflict with tldraw's shortcuts. The `areKeyboardShortcutsEnabled` preference lets users turn tldraw's shortcuts off:

```tsx
editor.user.updateUserPreferences({
	areKeyboardShortcutsEnabled: false,
})
```

When disabled, tldraw's keyboard shortcuts don't interfere with assistive technology shortcuts. Basic navigation with Tab and arrow keys still works for shape selection.

## Accessibility menu

The default UI includes an accessibility submenu under Preferences in the main menu, with toggles for:

| Setting                     | Effect                                        |
| --------------------------- | --------------------------------------------- |
| Reduce motion               | Disables animations                           |
| Keyboard shortcuts          | Enables or disables tldraw keyboard shortcuts |
| Enhanced accessibility mode | Shows visible labels on UI elements           |

You can use these components individually to build custom accessibility controls:

```tsx
import {
	ToggleReduceMotionItem,
	ToggleKeyboardShortcutsItem,
	ToggleEnhancedA11yModeItem,
} from 'tldraw'
```

See [`AccessibilityMenu`](/reference/tldraw/AccessibilityMenu) for the default implementation.

## Best practices for custom shapes

Override `getAriaDescriptor()` or `getText()` to give screen reader users context about what the shape contains. A shape announced as "card" is less useful than "Meeting notes: Q4 planning session".

The shape's `component()` renders inside an HTML container, so the usual web accessibility rules apply: use semantic elements rather than styled divs, make interactive elements focusable and operable with the keyboard, and check `usePrefersReducedMotion()` before showing animations.

For more on creating custom shapes, see [Custom shapes](/docs/shapes).

## Debugging accessibility

Enable the `a11y` debug flag to log accessibility announcements to the console:

```tsx
import { debugFlags } from 'tldraw'

debugFlags.a11y.set(true)
```

With this flag enabled, the console shows each announcement and logs the accessible name of elements as they receive keyboard focus. This is useful for verifying that your custom shapes provide appropriate descriptions.

--------

# Actions

Actions are named operations that users trigger from menus, keyboard shortcuts, or custom UI. Each action bundles an identifier, display metadata (label, icon, keyboard shortcut), and a handler function. Actions let you define operations like "undo", "group", or "export as PNG" once and invoke them from multiple places with consistent behavior.

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

const overrides: TLUiOverrides = {
	actions(editor, actions, helpers) {
		// Add a custom action
		actions['show-selection-count'] = {
			id: 'show-selection-count',
			label: 'action.show-selection-count',
			kbd: 'shift+c',
			onSelect(source) {
				const count = editor.getSelectedShapeIds().length
				helpers.addToast({ title: `${count} shapes selected` })
			},
		}
		return actions
	},
}

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

The `tldraw` package includes nearly 100 default actions covering editing, arrangement, export, zoom, and preferences. You can override any of these or add your own through the `overrides` prop, typed as [`TLUiOverrides`](/reference/tldraw/TLUiOverrides).

## How actions work

Actions live in a React context inside the tldraw UI. When the UI mounts, it registers all default actions, applies any overrides you've provided, and makes them available through the [`useActions`](/reference/tldraw/useActions) hook. Menus and toolbars look up actions by ID and render them with their labels, icons, and keyboard shortcuts.

Each action has an `onSelect` handler that receives a source parameter indicating where it was triggered:

```tsx
const actions = useActions()
const duplicateAction = actions['duplicate']

// Trigger programmatically
duplicateAction.onSelect('toolbar')
```

Keyboard shortcuts are bound automatically. The [`useKeyboardShortcuts`](/reference/tldraw/useKeyboardShortcuts) hook parses each action's `kbd` property and registers hotkey handlers. When a shortcut fires, it calls the action's `onSelect` with `'kbd'` as the source.

## Action structure

The [`TLUiActionItem`](/reference/tldraw/TLUiActionItem) interface defines what an action contains:

| Property               | Description                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | Unique identifier for the action (e.g., `'duplicate'`, `'zoom-in'`)                                                                                           |
| `label`                | Translation key for display text. Can be a string or an object mapping contexts to different keys (see [Context-sensitive labels](#context-sensitive-labels)) |
| `icon`                 | Icon name from tldraw's icon set, or a custom React element                                                                                                   |
| `kbd`                  | Keyboard shortcut string. Use commas to bind several combinations, e.g. `'cmd+g,ctrl+g'` (see [Keyboard shortcuts](#keyboard-shortcuts))                      |
| `readonlyOk`           | When `true`, the action works in readonly mode. Defaults to `false`                                                                                           |
| `checkbox`             | When `true`, renders as a toggle with a checkmark indicator in menus                                                                                          |
| `isRequiredA11yAction` | When `true`, the keyboard shortcut works even when shortcuts are normally disabled (e.g., while editing a shape). Used for accessibility actions              |
| `onSelect`             | Handler called when the action is triggered. Receives a [`TLUiEventSource`](/reference/tldraw/TLUiEventSource) indicating the trigger origin (`'kbd'`, `'menu'`, `'toolbar'`, etc.)             |

## Accessing actions

Use the [`useActions`](/reference/tldraw/useActions) hook to get all registered actions:

```typescript
import { useActions } from 'tldraw'

function MyComponent() {
	const actions = useActions()

	return (
		<button onClick={() => actions['undo'].onSelect('toolbar')}>
			Undo
		</button>
	)
}
```

The hook returns a record mapping action IDs to action objects. You can iterate over it to build custom menus or filter actions by property.

## Default actions

The default actions cover most editing operations you'd expect in a canvas application. Some common ones, by category:

| Category    | Action ids                                                                                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editing     | `undo`, `redo`, `duplicate`, `delete`, `copy`, `cut`, `paste`                                                                                                              |
| Grouping    | `group`, `ungroup`                                                                                                                                                         |
| Arrangement | `bring-to-front`, `bring-forward`, `send-backward`, `send-to-back`, `align-left`, `align-center-horizontal`, `align-right`, `distribute-horizontal`, `distribute-vertical` |
| Export      | `export-as-svg`, `export-as-png`, `copy-as-svg`, `copy-as-png`                                                                                                             |
| Zoom        | `zoom-in`, `zoom-out`, `zoom-to-100`, `zoom-to-fit`, `zoom-to-selection`, `select-zoom-tool`                                                                               |
| Preferences | `toggle-dark-mode`, `toggle-snap-mode`, `toggle-grid`, `toggle-focus-mode`                                                                                                 |

The full list is in the [default actions source](https://github.com/tldraw/tldraw/blob/main/packages/tldraw/src/lib/ui/context/actions.tsx). Most actions guard themselves inside their handlers. For example, `group` and the arrangement actions do nothing unless shapes are selected and the select tool is active.

## Overriding actions

Pass an `overrides` prop to customize actions. The override function receives the editor, the default actions, and helper utilities:

```typescript
import { Tldraw, TLUiOverrides } from 'tldraw'

const overrides: TLUiOverrides = {
	actions(editor, actions, helpers) {
		// Modify existing action
		actions['duplicate'].kbd = 'cmd+shift+d,ctrl+shift+d'

		// Disable an action by removing it
		delete actions['print']

		return actions
	},
}

function App() {
	return <Tldraw overrides={overrides} />
}
```

The `copy`, `cut`, and `paste` shortcuts are handled by native clipboard events rather than the `kbd` system, so changing their `kbd` has no effect.

### Modifying behavior

To change what an action does, replace its `onSelect` handler:

```typescript
const overrides: TLUiOverrides = {
	actions(editor, actions, helpers) {
		const originalDuplicate = actions['duplicate'].onSelect

		actions['duplicate'].onSelect = async (source) => {
			console.log('Duplicating shapes...')
			await originalDuplicate(source)
			console.log('Done!')
		}

		return actions
	},
}
```

You can call the original handler before or after your custom logic, or replace it entirely.

### Adding custom actions

Add new actions by inserting them into the actions record:

```typescript
const overrides: TLUiOverrides = {
	actions(editor, actions, helpers) {
		actions['my-custom-action'] = {
			id: 'my-custom-action',
			label: 'action.my-custom-action',
			kbd: 'cmd+shift+k,ctrl+shift+k',
			icon: 'external-link',
			onSelect(source) {
				const shapes = editor.getSelectedShapes()
				console.log('Custom action on', shapes.length, 'shapes')
			},
		}

		return actions
	},
}
```

Custom actions integrate with the keyboard shortcut system automatically. To add them to menus, override the menu components; see [Actions in menus](#actions-in-menus) and the [custom menus example](/examples/ui/custom-menus).

### Using helper utilities

The override function receives a `helpers` object ([`TLUiOverrideHelpers`](/reference/tldraw/TLUiOverrideHelpers), the return value of [`useDefaultHelpers`](/reference/tldraw/useDefaultHelpers)):

```typescript
const overrides: TLUiOverrides = {
	actions(editor, actions, helpers) {
		actions['show-toast'] = {
			id: 'show-toast',
			label: 'action.show-toast',
			onSelect(source) {
				helpers.addToast({
					title: 'Hello!',
					description: 'This is a custom action.',
				})
			},
		}

		return actions
	},
}
```

Available helpers:

| Helper                  | Description                          |
| ----------------------- | ------------------------------------ |
| `addToast`              | Show a toast notification            |
| `removeToast`           | Remove a specific toast              |
| `clearToasts`           | Remove all toasts                    |
| `addDialog`             | Open a dialog                        |
| `removeDialog`          | Close a specific dialog              |
| `clearDialogs`          | Close all dialogs                    |
| `msg`                   | Get a translated string by key       |
| `isMobile`              | Boolean indicating mobile breakpoint |
| `insertMedia`           | Open file picker and insert media    |
| `replaceImage`          | Replace selected image with new file |
| `replaceVideo`          | Replace selected video with new file |
| `printSelectionOrPages` | Print selection or all pages         |
| `cut`                   | Cut selected shapes to clipboard     |
| `copy`                  | Copy selected shapes to clipboard    |
| `paste`                 | Paste from clipboard                 |
| `copyAs`                | Copy shapes as SVG or PNG            |
| `exportAs`              | Export shapes as SVG, PNG, or JSON   |
| `getEmbedDefinition`    | Get embed info for a URL             |

## Keyboard shortcuts

Shortcuts use a simple string format with modifier keys separated by `+`. Use commas to bind several combinations to the same action. Every combination is active on every platform; the conventional `cmd+…,ctrl+…` pair covers Mac and everything else, and only the shortcut hint shown in menus ([`TldrawUiKbd`](/reference/tldraw/TldrawUiKbd)) is platform-specific:

```typescript
kbd: 'cmd+g,ctrl+g' // Cmd+G or Ctrl+G
kbd: 'shift+1' // Shift+1
kbd: 'cmd+shift+s,ctrl+shift+s' // Cmd+Shift+S or Ctrl+Shift+S
```

Modifiers are `cmd` (alias `meta`), `ctrl`, `shift`, and `alt` (alias `option`). Special keys include `del`, `backspace`, `enter`, `escape`, `space`, and the arrow keys (`left`, `right`, `up`, `down`).

Shortcuts only fire while the editor is focused and the key event does not target a text input. They are also disabled when a menu is open, a shape is being edited, the editor has a crashing error, or the user has disabled keyboard shortcuts in preferences. In readonly mode, only actions with `readonlyOk` are bound. Actions marked with `isRequiredA11yAction: true` bypass the disabled check for accessibility purposes.

## Actions in menus

The default UI uses [`TldrawUiMenuActionItem`](/reference/tldraw/TldrawUiMenuActionItem) to render actions in menus:

```typescript
import { TldrawUiMenuActionItem, TldrawUiMenuGroup } from 'tldraw'

function CustomMenu() {
	return (
		<TldrawUiMenuGroup id="edit">
			<TldrawUiMenuActionItem actionId="undo" />
			<TldrawUiMenuActionItem actionId="redo" />
			<TldrawUiMenuActionItem actionId="duplicate" />
		</TldrawUiMenuGroup>
	)
}
```

This component looks up the action by ID and renders it with the correct label, icon, and shortcut hint. Pass `disabled` yourself if the item should be disabled. For toggle actions, use [`TldrawUiMenuActionCheckboxItem`](/reference/tldraw/TldrawUiMenuActionCheckboxItem) with a `checked` prop.

## Context-sensitive labels

Some actions show different labels depending on where they appear. The `label` property can be an object mapping menu context types ([`TLUiMenuContextType`](/reference/tldraw/TLUiMenuContextType), plus `default`) to translation keys:

```typescript
actions['export-as-svg'] = {
	id: 'export-as-svg',
	label: {
		default: 'action.export-as-svg',
		menu: 'action.export-as-svg.short',
		'context-menu': 'action.export-as-svg.short',
	},
	// ...
}
```

The menu component uses the appropriate label based on its context. If no specific label exists for a context, it falls back to `default`.

## Tracking action usage

The `source` parameter tells you where the action was triggered. Use this for analytics:

```tsx
actions['custom-action'] = {
	id: 'custom-action',
	label: 'action.custom',
	kbd: 'cmd+k,ctrl+k',
	onSelect(source) {
		trackEvent('custom-action', { source })
		// source: 'kbd', 'menu', 'context-menu', 'toolbar', 'quick-actions', 'zoom-menu', etc.
	},
}
```

## Related examples

- [Action overrides](/examples/ui/action-overrides) - Add custom actions and modify existing action shortcuts using the overrides prop.
- [Keyboard shortcuts](/examples/ui/keyboard-shortcuts) - Change keyboard shortcuts for tools and actions.
- [Custom menus](/examples/ui/custom-menus) - Build custom menus that use actions with proper labels and shortcuts.

--------

# Animation

The animation system drives smooth transitions for shapes and for the camera. Shape animations interpolate a shape's position, rotation, opacity, and props. Camera animations move the viewport for pans and zooms.

## How it works

Animations run on the editor's [tick system](/sdk-features/ticks). When you call [`Editor.animateShape`](/reference/editor/Editor#animateShape) or a camera method with an `animation` option, the editor subscribes to `tick` events, applies the easing function to the elapsed time, and interpolates between the start and end values until the animation completes.

Camera animations respect the user's animation speed preference; shape animations don't. See [User preferences](#user-preferences) below.

## Shape animations

Use [`Editor.animateShape`](/reference/editor/Editor#animateShape) to animate a single shape or [`Editor.animateShapes`](/reference/editor/Editor#animateShapes) to animate several at once. The editor tracks each animating shape independently, so multiple animations can run at the same time:

```typescript
import { createShapeId, EASINGS } from 'tldraw'

const shapeId = createShapeId('myshape')

editor.animateShape(
	{ id: shapeId, type: 'geo', x: 200, y: 100 },
	{ animation: { duration: 500, easing: EASINGS.easeOutCubic } }
)
```

### Animated properties

The editor linearly interpolates the properties common to every shape: `x`, `y`, `rotation` (in radians), and `opacity` (0 to 1).

For shape-specific props like width and height, the shape util implements [`ShapeUtil.getInterpolatedProps`](/reference/editor/ShapeUtil#getInterpolatedProps). If a util doesn't implement it, the props jump to their end values on the first frame. This is how [`BaseBoxShapeUtil`](/reference/editor/BaseBoxShapeUtil) interpolates its dimensions (`lerp` is exported from `tldraw`):

```typescript
getInterpolatedProps(startShape: Shape, endShape: Shape, t: number) {
	return {
		...endShape.props,
		w: lerp(startShape.props.w, endShape.props.w, t),
		h: lerp(startShape.props.h, endShape.props.h, t),
	}
}
```

### Animation lifecycle

Shape animations default to a duration of 500 ms and `linear` easing. Intermediate frames don't create history entries; when the animation finishes the editor calls `updateShapes()` with the final values, so a single undo restores the starting state.

You can interrupt an animation in two ways. Calling `updateShapes()` on an animating shape cancels its animation and applies the new values immediately. Starting a new animation for a shape cancels the existing one.

User interaction wins over ongoing animations. If you drag a shape that's animating, the animation stops and the shape follows your pointer.

## Camera animations

The camera-move methods ([`Editor.setCamera`](/reference/editor/Editor#setCamera), [`Editor.zoomToBounds`](/reference/editor/Editor#zoomToBounds), [`Editor.zoomToFit`](/reference/editor/Editor#zoomToFit), and the rest) accept an `animation` option in [`TLCameraMoveOptions`](/reference/editor/TLCameraMoveOptions). Without it, or with a `duration` of `0`, the camera jumps straight to the target. See [Camera](/sdk-features/camera) for the full set of methods.

```typescript
editor.setCamera(
	{ x: 0, y: 0, z: 1 },
	{ animation: { duration: 320, easing: EASINGS.easeInOutCubic } }
)
```

Camera animations default to `easeInOutCubic` easing. They stop as soon as the user pans, zooms, or pinches, and you can stop them yourself with [`Editor.stopCameraAnimation`](/reference/editor/Editor#stopCameraAnimation). If the camera is locked, camera methods do nothing unless you pass `force: true`.

### Zooming to bounds

Use `zoomToBounds()` to animate the camera so a specific area fills the viewport, for example to focus on shapes or build slideshow-style transitions. You can also cap the zoom with `targetZoom` and add screen-space padding with `inset`:

```typescript
const bounds = { x: 0, y: 0, w: 800, h: 600 }
editor.zoomToBounds(bounds, {
	animation: { duration: 500 },
	targetZoom: 1, // zoom to 100%
	inset: 50, // padding around the bounds in pixels
})
```

`zoomToFit()` is a convenience wrapper that zooms to fit all shapes on the current page:

```typescript
editor.zoomToFit({ animation: { duration: 200 } })
```

### Camera slide

[`Editor.slideCamera`](/reference/editor/Editor#slideCamera) creates momentum-based camera movement that decelerates under friction:

```typescript
editor.slideCamera({
	speed: 1,
	direction: { x: 1, y: 0 },
	friction: 0.1,
})
```

## Easing functions

Easing functions control the rate of change during an animation. Use an `easeOut` curve when responding to user actions (fast start, gentle settle), `easeIn` for exits (gentle start, quick finish), and `easeInOut` for autonomous moves like camera transitions.

[`EASINGS`](/reference/editor/EASINGS) provides `linear` plus the standard `easeIn`, `easeOut`, and `easeInOut` variants of `Quad`, `Cubic`, `Quart`, `Quint`, `Sine`, and `Expo`, for example `EASINGS.easeOutCubic` or `EASINGS.easeInOutSine`.

## User preferences

Camera animations check `editor.user.getAnimationSpeed()` before running. This value is a speed multiplier: the editor divides animation durations by it, so users can speed up, slow down, or disable animations entirely. It defaults to `0` when the operating system reports `prefers-reduced-motion`.

When animation speed is zero, `setCamera()`, `zoomToBounds()`, `zoomToFit()`, and the other camera-move methods jump straight to the target, and `slideCamera()` does nothing. `animateShape()` and `animateShapes()` do not check this preference. If you need reduced motion support for shape animations, check the animation speed yourself:

```typescript
if (editor.user.getAnimationSpeed() > 0) {
	editor.animateShape(
		{ id: shapeId, type: 'geo', x: 200, y: 100 },
		{ animation: { duration: 500 } }
	)
} else {
	editor.updateShape({ id: shapeId, type: 'geo', x: 200, y: 100 })
}
```

## Related examples

- [Shape animation](/examples/editor-api/shape-animation) - Animate shapes with `animateShape` and easing functions.
- [Slideshow](/examples/use-cases/slideshow) - Transition between slides with `zoomToBounds` and animation options.
- [Reduced motion](/examples/configuration/reduced-motion) - Respect the user's animation speed preference and `prefers-reduced-motion`.

--------

# Assets

Assets are external resources like images, videos, and bookmarks that shapes display on the canvas. They're stored as separate records in the store and referenced by ID from shapes. This lets you reuse the same image across multiple shapes without duplicating data, and swap out storage backends without touching your shapes.

The SDK includes three asset types: image, video, and bookmark. Each asset record holds metadata (dimensions, MIME type, source URL) while the actual file lives wherever you want to put it. You provide upload and resolve handlers that tell tldraw how to store files and fetch them for rendering.

## How it works

### Asset records and the store

Assets live in the store alongside shapes and pages. Each asset record contains metadata (dimensions, MIME type, name) but not the actual file bytes—those live in your storage backend.

When someone drops an image onto the canvas, tldraw creates two records: an asset record with dimensions and metadata, and a shape record with position and size. The shape references the asset through its `assetId` property. Multiple shapes can reference the same asset. Deleting a shape never deletes its asset: call [`Editor.deleteAssets`](/reference/editor/Editor#deleteAssets) yourself when you know an asset is no longer referenced.

Asset records have a `props` object for type-specific properties and a `meta` object for your custom data. The `src` property in props holds the URL returned by your upload handler. This can be an HTTP URL, a data URL, or any string your resolve handler understands.

### Asset types

The SDK defines three built-in asset types.

**Image assets** store raster images like PNG, JPEG, or GIF. They track width, height, MIME type, animation status, file size, and an optional `pixelRatio` for @2x images. The `isAnimated` flag is true for animated GIF, WebP, AVIF, and APNG files.

```typescript
const imageAsset: TLImageAsset = {
	id: 'asset:image123' as TLAssetId,
	typeName: 'asset',
	type: 'image',
	props: {
		w: 1920,
		h: 1080,
		name: 'photo.jpg',
		isAnimated: false,
		mimeType: 'image/jpeg', // can be null if unknown
		src: 'https://storage.example.com/uploads/photo.jpg', // can be null before upload
		fileSize: 245000, // optional
		pixelRatio: 2, // optional
	},
	meta: {},
}
```

**Video assets** store video files like MP4 or WebM. They have the same structure as image assets: dimensions, MIME type, source URL, and `isAnimated` (which is typically true for videos).

```typescript
const videoAsset: TLVideoAsset = {
	id: 'asset:video456' as TLAssetId,
	typeName: 'asset',
	type: 'video',
	props: {
		w: 1920,
		h: 1080,
		name: 'clip.mp4',
		isAnimated: true,
		mimeType: 'video/mp4',
		src: 'https://storage.example.com/uploads/clip.mp4',
		fileSize: 5242880,
	},
	meta: {},
}
```

**Bookmark assets** store web page previews. When someone pastes a URL, tldraw fetches metadata from the page and creates a bookmark that renders as a preview card.

```typescript
const bookmarkAsset: TLBookmarkAsset = {
	id: 'asset:bookmark1' as TLAssetId,
	typeName: 'asset',
	type: 'bookmark',
	props: {
		title: 'Example Website',
		description: 'A great example of web design',
		image: 'https://example.com/preview.jpg',
		favicon: 'https://example.com/favicon.ico',
		src: 'https://example.com',
	},
	meta: {},
}
```

### The TLAssetStore interface

[`TLAssetStore`](/reference/tlschema/TLAssetStore) defines how tldraw talks to your storage backend. You provide an implementation when creating the editor, and tldraw calls your handlers whenever someone adds or accesses assets.

The default behavior depends on your store setup. With an in-memory store (the default), [`inlineBase64AssetStore`](/reference/editor/inlineBase64AssetStore) converts every uploaded file to a data URL: quick for prototyping, but nothing persists across sessions. With a [`persistenceKey`](/sdk-features/persistence#The-persistenceKey-prop), assets are stored in the browser's [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) alongside the document. With a [sync server](/docs/sync), implement `TLAssetStore` yourself to upload files to S3, Google Cloud Storage, or your own API.

The interface has three methods:

| Method    | Purpose                                                                           |
| --------- | --------------------------------------------------------------------------------- |
| `upload`  | Store a file and return its URL                                                   |
| `resolve` | Return the URL to use when rendering an asset (optional, defaults to `props.src`) |
| `remove`  | Clean up files when assets are deleted (optional)                                 |

The **upload** method receives an asset record (with metadata already populated) and the File to store. Return an object with `src` (the URL) and optionally `meta` (custom metadata to merge into the asset record). You also get an AbortSignal for cancellation.

```typescript
async upload(asset: TLAsset, file: File, abortSignal?: AbortSignal): Promise<{ src: string; meta?: JsonObject }>
```

The **resolve** method receives an asset and a [`TLAssetContext`](/reference/tlschema/TLAssetContext) describing how the asset is being displayed. It can be sync or async. Return the URL to use for rendering, or `null` if the asset is unavailable (shapes then render a broken-asset placeholder). This is where you can get clever: return optimized thumbnails when zoomed out, high-resolution images for export, or add authentication tokens.

```typescript
resolve(asset: TLAsset, ctx: TLAssetContext): Promise<string | null> | string | null
```

The **remove** method receives asset IDs that are no longer needed. Clean up the stored files to free space. This method is optional.

```typescript
async remove(assetIds: TLAssetId[]): Promise<void>
```

Here's a minimal implementation that converts files to data URLs (good for prototyping, not so great for production):

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

const assetStore: TLAssetStore = {
	async upload(asset, file) {
		const dataUrl = await new Promise<string>((resolve) => {
			const reader = new FileReader()
			reader.onload = () => resolve(reader.result as string)
			reader.readAsDataURL(file)
		})
		return { src: dataUrl }
	},

	resolve(asset, ctx) {
		return asset.props.src
	},
}

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

### The TLAssetContext

When resolving assets, tldraw gives you a [`TLAssetContext`](/reference/tlschema/TLAssetContext) with information about the current render environment. Use this to optimize asset delivery.

| Property                  | Type             | Description                                                                                                       |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `screenScale`             | `number`         | How much the asset is scaled relative to native dimensions. A 1000px image rendered at 500px has screenScale 0.5. |
| `steppedScreenScale`      | `number`         | screenScale rounded up to the next power of 2, useful for tiered caching.                                         |
| `dpr`                     | `number`         | Device pixel ratio. Retina displays are 2 or 3.                                                                   |
| `networkEffectiveType`    | `string \| null` | Browser's connection type: 'slow-2g', '2g', '3g', or '4g'.                                                        |
| `shouldResolveToOriginal` | `boolean`        | True for copy/paste and for SVG exports without an explicit `pixelRatio`. Return full quality.                    |

Here's a resolve handler that serves optimized images based on network conditions and zoom level:

```typescript
resolve(asset, ctx) {
	const baseUrl = asset.props.src
	if (!baseUrl) return null

	// For exports, always return original
	if (ctx.shouldResolveToOriginal) {
		return baseUrl
	}

	// On slow connections, serve lower quality
	if (ctx.networkEffectiveType === 'slow-2g' || ctx.networkEffectiveType === '2g') {
		return `${baseUrl}?quality=low`
	}

	// Serve resolution appropriate for current zoom
	const targetWidth = Math.ceil(asset.props.w * ctx.steppedScreenScale * ctx.dpr)
	return `${baseUrl}?w=${targetWidth}`
}
```

## Key components

### Editor asset methods

The [`Editor`](/reference/editor/Editor) class provides methods for managing assets:

| Method                      | Description                               |
| --------------------------- | ----------------------------------------- |
| [`Editor.createAssets`](/reference/editor/Editor#createAssets)    | Add asset records to the store            |
| [`Editor.updateAssets`](/reference/editor/Editor#updateAssets)    | Update existing assets                    |
| [`Editor.deleteAssets`](/reference/editor/Editor#deleteAssets)    | Remove assets and call the remove handler |
| [`Editor.getAsset`](/reference/editor/Editor#getAsset)        | Get an asset by ID                        |
| [`Editor.getAssets`](/reference/editor/Editor#getAssets)       | Get all assets in the store               |
| [`Editor.resolveAssetUrl`](/reference/editor/Editor#resolveAssetUrl) | Resolve an asset ID to a renderable URL   |

Asset operations happen outside the undo/redo history since they're typically part of larger operations like pasting images. You don't want "undo" to magically un-upload a file.

```typescript
// Create an asset
editor.createAssets([imageAsset])

// Update an asset. updateAssets shallow-merges the record, so spread the existing props
editor.updateAssets([
	{
		...imageAsset,
		props: { ...imageAsset.props, name: 'new-name.jpg' },
	},
])

// Get an asset with type safety
const asset = editor.getAsset<TLImageAsset>(imageAsset.id)

// Resolve to a URL for rendering
const url = await editor.resolveAssetUrl(imageAsset.id, { screenScale: 0.5 })

// Delete assets
editor.deleteAssets([imageAsset.id])
```

### Shape and asset relationships

Shapes reference assets through an `assetId` property in their props. Image shapes, video shapes, and bookmark shapes all follow this pattern. The shape stores position, size, rotation, and crop settings while the asset stores the media metadata and source URL.

This separation pays off:

- Update an asset's `src` and every shape referencing it updates immediately
- Duplicate a shape without duplicating storage
- Implement lazy loading where assets only load when shapes become visible

When you delete an asset, shapes referencing it render a broken-asset placeholder.

## Extension points

### Custom storage backends

Implement [`TLAssetStore`](/reference/tlschema/TLAssetStore) to integrate with any storage backend. For local development, convert files to data URLs. For production, upload to S3, Google Cloud Storage, or your own API.

Here's an example that uploads to a custom API:

```typescript
const assetStore: TLAssetStore = {
	async upload(asset, file, abortSignal) {
		const formData = new FormData()
		formData.append('file', file)
		formData.append('assetId', asset.id)

		const response = await fetch('/api/upload', {
			method: 'POST',
			body: formData,
			signal: abortSignal,
		})

		const { url, uploadedAt } = await response.json()
		return {
			src: url,
			meta: { uploadedAt }, // Custom metadata gets merged into the asset
		}
	},

	resolve(asset, ctx) {
		// Add auth token for private content
		const token = getAuthToken()
		return `${asset.props.src}?token=${token}`
	},

	async remove(assetIds) {
		await fetch('/api/assets', {
			method: 'DELETE',
			body: JSON.stringify({ ids: assetIds }),
		})
	},
}
```

### Custom asset types

[`AssetUtil`](/reference/editor/AssetUtil) is the asset-side counterpart to `ShapeUtil`. Each asset type has one, and it defines which MIME types the type accepts, how to derive an asset record from a dropped file, and what default props new instances start with. The built-in `ImageAssetUtil`, `VideoAssetUtil`, and `BookmarkAssetUtil` live in `defaultAssetUtils`.

To add your own type, register its props on `TLGlobalAssetPropsMap` via TypeScript module augmentation, then implement an `AssetUtil` for it. Set `static props` so the store validates and migrates your records:

```typescript
import { AssetUtil, T, TLAsset, TLAssetId } from 'tldraw'

const AUDIO_TYPE = 'audio'

declare module 'tldraw' {
	export interface TLGlobalAssetPropsMap {
		[AUDIO_TYPE]: {
			src: string | null
			mimeType: string | null
			name: string
		}
	}
}

type TLAudioAsset = TLAsset<typeof AUDIO_TYPE>

class AudioAssetUtil extends AssetUtil<TLAudioAsset> {
	static override type = AUDIO_TYPE
	static override props = {
		src: T.string.nullable(),
		mimeType: T.string.nullable(),
		name: T.string,
	}

	override getDefaultProps(): TLAudioAsset['props'] {
		return { src: null, mimeType: null, name: '' }
	}

	override getSupportedMimeTypes() {
		return ['audio/mpeg', 'audio/wav', 'audio/ogg']
	}

	override async getAssetFromFile(file: File, assetId: TLAssetId): Promise<TLAudioAsset | null> {
		return {
			id: assetId,
			typeName: 'asset',
			type: AUDIO_TYPE,
			props: {
				src: null, // populated by the asset store after upload
				mimeType: file.type,
				name: file.name,
			},
			meta: {},
		}
	}
}
```

Pass the util to the `<Tldraw>` component. The default asset utils are always included; a custom util with the same `type` replaces the built-in one:

```tsx
import { Tldraw } from 'tldraw'

const assetUtils = [AudioAssetUtil]

export default function App() {
	return <Tldraw assetUtils={assetUtils} />
}
```

When a file is dropped or pasted, the editor checks it against `maxAssetSize`, then finds the first registered util whose `acceptsMimeType()` returns true for the file's MIME type and calls its `getAssetFromFile()`. The returned asset record then flows through your `TLAssetStore.upload` handler, which assigns the final `src`. To place the asset on the canvas, a shape util must declare the asset type in `static handledAssetTypes` and implement `createShapeForAsset()`; that shape reads the resolved URL through `editor.resolveAssetUrl()` like the built-in shapes do. See the [custom asset type example](/examples/data/assets/custom-asset-type) for the full pattern.

### Configuring built-in asset utils

The simplest way to configure the built-in utils is through the `<Tldraw>` props `maxAssetSize`, `maxImageDimension`, `acceptedImageMimeTypes`, and `acceptedVideoMimeTypes`. For anything else, use [`AssetUtil.configure`](/reference/editor/AssetUtil#configure) to tweak options on a built-in util without subclassing it. For example, lock image uploads down to PNG:

```tsx
import { ImageAssetUtil, defaultAssetUtils, Tldraw } from 'tldraw'

const PngOnlyImageAssetUtil = ImageAssetUtil.configure({
	supportedMimeTypes: ['image/png'],
})

const assetUtils = defaultAssetUtils.map((util) =>
	util === ImageAssetUtil ? PngOnlyImageAssetUtil : util
)

<Tldraw assetUtils={assetUtils} />
```

`ImageAssetUtil` exposes `maxDimension` and `supportedMimeTypes` options. `VideoAssetUtil` exposes `supportedMimeTypes`. If you also pass the matching `<Tldraw>` props, those win.

### Asset validation and migrations

Asset records use the migration system to evolve their schema. Each asset type has its own migration sequence that handles adding properties, renaming fields, and validating data. When you load a document with old asset records, migrations transform them to the current schema automatically.

Validators ensure asset data matches the expected structure at runtime. Setting `static props` on your `AssetUtil` is enough for the store to validate it. If you need a standalone validator, [`createAssetValidator`](/reference/tlschema/createAssetValidator) builds one for a single asset type (id, `typeName`, `type` literal, props, and meta). Add migration sequences via `static migrations` to handle schema changes over time.

## Security

### SVG sanitization

SVG files can contain scripts, event handlers, and external resource references that execute during rendering. tldraw automatically sanitizes all SVGs on paste and file drop using an allowlist-based sanitizer that:

- Strips `<script>`, `<iframe>`, `<object>`, `<embed>`, and other dangerous elements
- Removes all `on*` event handler attributes (`onerror`, `onload`, etc.)
- Allows only `http:`, `https:`, and `mailto:` links
- Restricts `<image>` and `<feImage>` hrefs to `data:` URIs only
- Restricts `<use>` hrefs to fragment references (`#id`) only
- Sanitizes CSS to remove `@import`, `expression()`, and external `url()` references
- Preserves `<foreignObject>` content (needed for text rendering) with a separate HTML allowlist
- Preserves `<style>` elements with `data:` font URLs (needed for embedded fonts)

For stronger guarantees, we recommend [DOMPurify](https://github.com/cure53/DOMPurify), a widely used and audited sanitizer. We don't bundle it (it's a ~17KB dependency), but if your app already uses it you can wire it into your external content handlers. Note that DOMPurify's default SVG profile strips `<foreignObject>` and `<style>` elements, which tldraw uses for text rendering and embedded fonts. Configure it to preserve those so tldraw's SVG output round-trips correctly.

If you're implementing custom external content handlers, you can also import our built-in sanitizer directly:

```typescript
import { sanitizeSvg } from 'tldraw'

const sanitized = sanitizeSvg(svgText)
if (!sanitized) {
	// SVG contained no safe content
}
```

### Recommended CSP policy

For defense in depth, we recommend deploying a Content Security Policy. This protects against attack vectors that sanitization alone cannot cover:

```
Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: blob: https://your-asset-domain.com;
  font-src 'self' data:;
  connect-src 'self' https://your-api.com;
  object-src 'none';
  base-uri 'self';
```

- **`script-src 'self'`** prevents inline scripts in SVGs from executing
- **`style-src 'self' 'unsafe-inline'`** allows tldraw's runtime inline styles while blocking external stylesheets
- **`img-src 'self' data: blob:`** allows data URLs for embedded images and blob URLs for asset previews, while blocking loads to arbitrary external origins
- **`object-src 'none'`** blocks `<object>` and `<embed>` elements entirely
- **`base-uri 'self'`** prevents `<base>` tag injection that could redirect relative URLs

### Hosting assets on a separate domain

We recommend serving user-uploaded assets from a completely separate domain (e.g. `example-assets.com` rather than a subdomain like `assets.example.com`). This provides an extra layer of protection: if a malicious file somehow bypasses sanitization, browser same-origin policies prevent it from accessing cookies, storage, or APIs on your main domain.

## Related examples

- [Hosted images](/examples/data/assets/hosted-images) - Implement a TLAssetStore that uploads images to a server
- [Local images](/examples/editor-api/local-images) - Create image shapes from local asset records
- [Local videos](/examples/editor-api/local-videos) - Create video shapes from local asset records
- [Asset options](/examples/configuration/asset-props) - Control allowed asset types, max size, and dimensions
- [Custom asset type](/examples/data/assets/custom-asset-type) - Register a custom AssetUtil and a shape that renders it
- [Static assets](/examples/data/assets/static-assets) - Pre-load custom fonts and icons

--------

# Attribution

The attribution system lets you track which users create or edit shapes. Connect tldraw to your auth system through a [`TLUserStore`](/reference/tlschema/TLUserStore) to resolve display names, render attribution labels, and persist user records alongside your document data. The built-in note shape uses attribution to show who last edited a note's text, and you can add similar tracking to custom shapes.

## User store

A `TLUserStore` provides a reactive `currentUser` signal for the active user and an optional `resolve` method for looking up other users by ID. Pass it as the `users` prop on the [`Tldraw`](/reference/tldraw/Tldraw) component or the [`useSync`](/reference/sync/useSync) hook:

```tsx
import { computed, createUserId, Tldraw, TLUserStore, UserRecordType } from 'tldraw'
import 'tldraw/tldraw.css'

const currentUser = computed('currentUser', () =>
	UserRecordType.create({
		id: createUserId('user-123'),
		name: 'Alice',
		color: '#e03131',
	})
)

const users: TLUserStore = {
	currentUser,
}

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

When no `users` prop is provided, the editor derives the current user from [user preferences](/sdk-features/user-preferences). With `useSync`, other users are resolved from collaborator presence.

### Resolving other users

The optional `resolve` method looks up users by their raw ID string. The editor calls it first whenever it needs a display name or user record for an ID:

```tsx
import {
	computed,
	createCachedUserResolve,
	createUserId,
	TLUserStore,
	UserRecordType,
} from 'tldraw'

const users: TLUserStore = {
	currentUser: computed('currentUser', () =>
		UserRecordType.create({
			id: createUserId('user-123'),
			name: 'Alice',
			color: '#e03131',
		})
	),
	resolve: createCachedUserResolve((userId) => {
		// Look up the user from your auth system
		return myUserCache.get(userId) ?? null
	}),
}
```

The [`createCachedUserResolve`](/reference/tlschema/createCachedUserResolve) helper wraps a lookup function so that each user ID gets a single stable reactive signal. If you write your own `resolve`, return the same signal for repeated calls with the same ID.

## How attribution works

Attribution is opt-in per shape type. Each shape util decides what to track and when to stamp a user ID. When you stamp a user ID with [`Editor.getAttributionUserId`](/reference/editor/Editor#getAttributionUserId), the editor also writes a corresponding `user:` record to the store so that display names survive across sessions, clipboard paste, and `.tldr` file exports.

### Note shape attribution

The built-in note shape tracks who last edited its text. Whenever a note's rich text changes and is non-empty, [`NoteShapeUtil`](/reference/tldraw/NoteShapeUtil) sets the `textLastEditedBy` prop to the current user's ID via `editor.getAttributionUserId()`. Clearing the text resets it to `null`, and duplicating or pasting a note with text re-stamps the copy to the current user. The note renders the last editor's first name as a small label in the corner.

## Reading attribution

The [`Editor`](/reference/editor/Editor) provides three methods for working with attribution. [`Editor.getAttributionUserId`](/reference/editor/Editor#getAttributionUserId) returns the current user's raw ID string (without the `user:` prefix). [`Editor.getAttributionDisplayName`](/reference/editor/Editor#getAttributionDisplayName) and [`Editor.getAttributionUser`](/reference/editor/Editor#getAttributionUser) check the `TLUserStore` first, then fall back to `user:` records in the store:

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

function AttributionLabel({ userId }: { userId: string }) {
	const editor = useEditor()

	const name = useValue('attribution-name', () => editor.getAttributionDisplayName(userId), [
		editor,
		userId,
	])

	if (!name) return null
	return <span>{name}</span>
}
```

## Custom shape attribution

Add attribution tracking to your own shapes by storing a user ID in your shape's props and overriding [`ShapeUtil.getReferencedUserIds`](/reference/editor/ShapeUtil#getReferencedUserIds):

```tsx
import { ShapeUtil, T, TLBaseShape } from 'tldraw'

type MyShape = TLBaseShape<
	'my-shape',
	{
		createdBy: string | null
	}
>

class MyShapeUtil extends ShapeUtil<MyShape> {
	static override type = 'my-shape' as const
	static override props = {
		createdBy: T.string.nullable(),
	}

	override getReferencedUserIds(shape: MyShape) {
		return shape.props.createdBy ? [shape.props.createdBy] : []
	}

	// ... other ShapeUtil methods
}
```

When shapes are copied to the clipboard or exported, the editor includes the `user:` records returned by `getReferencedUserIds`. Display names then remain available on the other side.

To stamp the current user when creating shapes:

```tsx
const userId = editor.getAttributionUserId()

editor.createShape({
	type: 'my-shape',
	props: {
		createdBy: userId,
	},
})
```

## Extensible user records

Extend user records with custom metadata by passing validators to [`createTLSchema`](/reference/tlschema/createTLSchema):

```tsx
import { createTLSchema, T } from 'tldraw'

const schema = createTLSchema({
	user: {
		meta: {
			department: T.string,
			isAdmin: T.boolean,
		},
	},
})
```

Custom metadata is validated and persisted alongside the standard user fields. Access it through the `meta` property on [`TLUser`](/reference/tlschema/TLUser) records.

## API reference

| Symbol                                | Description                                                             |
| ------------------------------------- | ----------------------------------------------------------------------- |
| [`Editor.getAttributionUserId`](/reference/editor/Editor#getAttributionUserId)      | Get the current user's ID for stamping shapes. Returns `string \| null` |
| [`Editor.getAttributionDisplayName`](/reference/editor/Editor#getAttributionDisplayName) | Resolve a display name from a user ID. Returns `string \| null`         |
| [`Editor.getAttributionUser`](/reference/editor/Editor#getAttributionUser)        | Resolve a full [`TLUser`](/reference/tlschema/TLUser) record from a user ID                        |
| [`TLUserStore`](/reference/tlschema/TLUserStore)                      | Interface for connecting to your auth/user system                       |
| [`TLUser`](/reference/tlschema/TLUser)                           | A user record in the store                                              |
| [`UserRecordType`](/reference/tlschema/UserRecordType)                   | The default user record type                                            |
| [`createUserId`](/reference/tlschema/createUserId)                     | Create a typed user ID                                                  |
| [`createCachedUserResolve`](/reference/tlschema/createCachedUserResolve)          | Create a cached resolve function for `TLUserStore`                      |
| [`createUserRecordType`](/reference/tlschema/createUserRecordType)             | Build a user record type with custom meta validators                    |

For setting up user identity in multiplayer, see the [Collaboration](/sdk-features/collaboration#user-identity) page.

## Related examples

- [Attribution](/examples/users/attribution): basic attribution with a user switcher and attribution inspector
- [Attribution timeline](/examples/users/attribution-timeline): timeline scrubber with per-user filtering

--------

# Bindings

Bindings create persistent relationships between shapes. When you draw an arrow to a rectangle, a binding stores that connection so the arrow stays attached when you move the rectangle. Bindings power features like arrows that follow shapes, stickers that stick to other shapes, and layout constraints that keep shapes aligned.

The SDK handles bookkeeping for you: when you delete a shape, its bindings are cleaned up automatically, and lifecycle hooks on the binding's [`BindingUtil`](/reference/editor/BindingUtil) let you react to changes.

## How it works

When you create a binding, the editor stores it as a record with `fromId` and `toId` fields pointing to shape IDs. The editor maintains an index of all bindings touching each shape. When either shape changes position, transforms, or gets deleted, the binding's [`BindingUtil`](/reference/editor/BindingUtil) receives callbacks that can update the bound shapes accordingly.

The system handles several scenarios automatically:

- When a shape is deleted, all its bindings are removed and their binding utils receive isolation and deletion callbacks
- When shapes are copied, only bindings between copied shapes are duplicated
- When shapes are moved to different pages, cross-page bindings are automatically removed
- When both bound shapes are copied or duplicated together, the binding is copied with them

The bindings index is a computed value that updates incrementally as bindings change. Lookups are fast and never scan all records.

## Key concepts

### Directional relationships

Every binding has direction. The `fromId` points to the source shape, and the `toId` points to the target shape. For arrows, the arrow is always the "from" shape and the shape it points to is the "to" shape. This directionality determines which lifecycle hooks fire and lets the system know which shape "owns" the relationship.

The distinction matters when shapes change. If you move a rectangle that an arrow points to, the arrow binding's `onAfterChangeToShape` hook fires. If you move the arrow itself, `onAfterChangeFromShape` fires instead.

### Binding records

A binding record ([`TLBaseBinding`](/reference/tlschema/TLBaseBinding)) contains just enough information to identify the relationship and store relationship-specific data:

```typescript
interface TLBaseBinding<Type, Props> {
	id: TLBindingId
	typeName: 'binding'
	type: Type
	fromId: TLShapeId
	toId: TLShapeId
	props: Props
	meta: JsonObject
}
```

The `props` field holds binding-specific data. Arrow bindings store the normalized anchor point on the target shape and whether the attachment is "precise" or should snap to the shape's edge. Custom bindings can store any data appropriate to the relationship type.

### BindingUtil lifecycle

Each binding type implements a [`BindingUtil`](/reference/editor/BindingUtil) class that responds to events throughout the binding's lifetime:

| Hooks                                                                | When they fire                                                                                                                                                                         |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onBeforeCreate`, `onAfterCreate`, `onBeforeChange`, `onAfterChange` | The binding record itself is created or modified. The `onBefore*` hooks can return a replacement binding record.                                                                       |
| `onAfterChangeFromShape`, `onAfterChangeToShape`                     | A bound shape changes. These are the most common hooks for keeping shapes synchronized. Arrow bindings use them to update the arrow's position and parent when the target shape moves. |
| `onBeforeDelete`, `onAfterDelete`                                    | The binding record is removed.                                                                                                                                                         |
| `onBeforeDeleteFromShape`, `onBeforeDeleteToShape`                   | A bound shape is about to be deleted.                                                                                                                                                  |
| `onBeforeIsolateFromShape`, `onBeforeIsolateToShape`                 | The bound shapes are about to be separated (one is deleted, copied, or duplicated without the other). Use these to "bake in" the binding's current state before it disappears.         |
| `onOperationComplete`                                                | All binding operations in a transaction have finished. Use it to compute aggregate updates across many related bindings.                                                               |

### Isolation vs deletion

Isolation callbacks handle a specific problem: when an arrow's target shape is deleted, the arrow shouldn't suddenly point to empty space. The `onBeforeIsolateFromShape` hook receives the binding and the `removedShape`, and lets the arrow update its terminal position to match the current attachment point before the binding is removed. The arrow then appears to "let go" of the shape naturally.

Isolation also occurs during copy and duplicate operations. If you copy an arrow but not its target, the copied arrow needs to convert its binding into a fixed position. The isolation callback handles this transformation.

Use isolation callbacks for consistency updates that should happen whenever shapes separate. Use `onBeforeDeleteFromShape` and `onBeforeDeleteToShape` for actions specific to deletion, like removing a sticker when its parent shape is deleted.

## API patterns

### Creating bindings

Create bindings using [`Editor.createBinding`](/reference/editor/Editor#createBinding) or [`Editor.createBindings`](/reference/editor/Editor#createBindings). You must provide the binding type, `fromId`, and `toId`. The BindingUtil supplies default props for anything you leave out. The editor checks both shapes' `canBind()` first and skips the binding if either refuses.

```typescript
editor.createBinding({
	type: 'arrow',
	fromId: arrowShape.id,
	toId: targetShape.id,
	props: {
		terminal: 'end',
		normalizedAnchor: { x: 0.5, y: 0.5 },
		isPrecise: false,
		isExact: false,
		snap: 'none',
	},
})
```

### Querying bindings

The editor provides several methods for finding bindings: [`Editor.getBinding`](/reference/editor/Editor#getBinding), [`Editor.getBindingsFromShape`](/reference/editor/Editor#getBindingsFromShape), [`Editor.getBindingsToShape`](/reference/editor/Editor#getBindingsToShape), and [`Editor.getBindingsInvolvingShape`](/reference/editor/Editor#getBindingsInvolvingShape).

```typescript
// Get a specific binding by ID
const binding = editor.getBinding(bindingId)

// Get all bindings where this shape is the source
const outgoing = editor.getBindingsFromShape(shape.id, 'arrow')

// Get all bindings where this shape is the target
const incoming = editor.getBindingsToShape(shape.id, 'arrow')

// Get all bindings involving this shape (either direction)
const all = editor.getBindingsInvolvingShape(shape.id, 'arrow')
```

### Updating and deleting bindings

Update bindings with [`Editor.updateBinding`](/reference/editor/Editor#updateBinding), passing a partial with the binding's `id` and `type`:

```typescript
editor.updateBinding({
	id: binding.id,
	type: 'arrow',
	props: { normalizedAnchor: { x: 0.8, y: 0.2 } },
})
```

Delete bindings with [`Editor.deleteBinding`](/reference/editor/Editor#deleteBinding), or let the system remove them automatically when shapes are deleted. Pass `isolateShapes: true` to trigger isolation callbacks:

```typescript
editor.deleteBinding(binding.id, { isolateShapes: true })
```

### Controlling which shapes can bind

Shapes control whether they accept bindings by implementing [`ShapeUtil.canBind`](/reference/editor/ShapeUtil#canBind):

```typescript
class MyShapeUtil extends ShapeUtil<MyShape> {
	static override type = 'my-shape' as const

	override canBind({ toShape, bindingType }: TLShapeUtilCanBindOpts) {
		// Only allow arrow bindings where this shape is the target
		return bindingType === 'arrow' && toShape.type === 'my-shape'
	}
}
```

The editor calls both shapes' `canBind()` methods before creating or updating a binding. If either returns false, the binding is skipped. Use [`Editor.canBindShapes`](/reference/editor/Editor#canBindShapes) to run the same check yourself.

## Extension points

Custom binding types let you create new kinds of relationships between shapes.

### Defining the binding type

First, extend the type system to include your binding's props. Use TypeScript's module augmentation to add your binding type to [`TLGlobalBindingPropsMap`](/reference/tlschema/TLGlobalBindingPropsMap), then derive the binding type from [`TLBinding`](/reference/tlschema/TLBinding):

```typescript
import { TLBinding, VecModel } from 'tldraw'

declare module 'tldraw' {
	export interface TLGlobalBindingPropsMap {
		myBinding: {
			anchor: VecModel
			strength: number
		}
	}
}

type MyBinding = TLBinding<'myBinding'>
```

### Implementing BindingUtil

Create a class extending [`BindingUtil`](/reference/editor/BindingUtil) with your binding type. At minimum, implement `getDefaultProps()`. Add lifecycle hooks based on what behavior you need:

```typescript
import {
	BindingOnShapeChangeOptions,
	BindingOnShapeIsolateOptions,
	BindingUtil,
	RecordProps,
	T,
	vecModelValidator,
} from 'tldraw'

class MyBindingUtil extends BindingUtil<MyBinding> {
	static override type = 'myBinding' as const
	static override props: RecordProps<MyBinding> = {
		anchor: vecModelValidator,
		strength: T.number,
	}

	override getDefaultProps() {
		return { anchor: { x: 0.5, y: 0.5 }, strength: 1 }
	}

	override onAfterChangeToShape({ binding, shapeAfter }: BindingOnShapeChangeOptions<MyBinding>) {
		// Update the "from" shape when the "to" shape moves
	}

	override onBeforeIsolateFromShape({
		binding,
		removedShape,
	}: BindingOnShapeIsolateOptions<MyBinding>) {
		// Bake in current state before the binding is removed
	}
}
```

### Registering the binding

Pass your BindingUtil to the editor via the `bindingUtils` prop:

```tsx
<Tldraw bindingUtils={[MyBindingUtil]} />
```

## Related examples

The examples app includes several binding implementations that demonstrate different use cases:

- [Sticker bindings](/examples/shapes/tools/sticker-bindings) - Shapes that stick to other shapes and follow them when moved. Demonstrates `onAfterChangeToShape` for position updates and `onBeforeDeleteToShape` for cascading deletion.
- [Pin bindings](/examples/shapes/tools/pin-bindings) - Pins that connect networks of shapes together, moving them as a group. Demonstrates `onOperationComplete` for computing aggregate updates across multiple related bindings.
- [Layout bindings](/examples/shapes/tools/layout-bindings) - Constraining shapes to layout positions. Demonstrates using bindings to enforce spatial relationships between shapes.
- [Arrow binding options](/examples/shapes/tools/arrow-binding-options) - Configuring how the built-in arrow binding attaches to shapes.

--------

# Camera system

The camera controls which part of the infinite canvas is visible. It holds the viewport's position and zoom, converts between screen space and page space, and responds to user input like wheel, trackpad, keyboard, and touch. You can constrain it to a bounded area, move it programmatically with animation, and follow other users' viewports in collaborative sessions.

## How it works

The camera represents the viewport's position and zoom using three values: `x` and `y` for position in page space, and `z` for zoom level. A zoom of `1` means 100%, `0.5` is 50%, and `2` is 200%. The camera's `x` and `y` are the page-space offset of the viewport: the page point at the viewport's top-left corner is `(-x, -y)`.

The camera converts between screen space (browser pixels) and page space (the canvas). Use [`Editor.screenToPage`](/reference/editor/Editor#screenToPage) to turn a mouse position into a canvas point and [`Editor.pageToScreen`](/reference/editor/Editor#pageToScreen) to go the other way. See [Coordinates](/sdk-features/coordinates) for the full set of conversions.

```typescript
const pagePoint = editor.screenToPage({ x: event.clientX, y: event.clientY })
const screenPoint = editor.pageToScreen({ x: shape.x, y: shape.y })
```

Read the camera with [`Editor.getCamera`](/reference/editor/Editor#getCamera) or [`Editor.getZoomLevel`](/reference/editor/Editor#getZoomLevel), and read the visible page area with [`Editor.getViewportPageBounds`](/reference/editor/Editor#getViewportPageBounds). All of these are reactive, so you can use them in `track` components or `useValue`.

## Camera options

Configure the camera with [`TLCameraOptions`](/reference/editor/TLCameraOptions). Pass the initial options through the `options.camera` prop, or change them at runtime with [`Editor.setCameraOptions`](/reference/editor/Editor#setCameraOptions), which re-applies the constraints to the current camera immediately:

```tsx
<Tldraw options={{ camera: { wheelBehavior: 'zoom' } }} />
```

```typescript
editor.setCameraOptions({
	isLocked: false,
	wheelBehavior: 'pan',
	panSpeed: 1,
	zoomSpeed: 1,
	zoomSteps: [0.1, 0.25, 0.5, 1, 2, 4, 8],
})
```

Set `isLocked` to freeze the camera for fixed-viewport apps. Camera methods then do nothing unless you pass `force: true`.

`wheelBehavior` decides what the mouse wheel or trackpad scroll does: `'pan'`, `'zoom'`, or `'none'`. If the user has set an input mode in their preferences, that preference wins: `'trackpad'` pans and `'mouse'` zooms.

`panSpeed` and `zoomSpeed` are multipliers on input sensitivity. Values below 1 slow movement down, values above 1 speed it up.

`zoomSteps` lists the discrete zoom levels used by zoom in and zoom out. The first value is the minimum zoom and the last is the maximum; the camera clamps to this range even without constraints.

## Camera constraints

Camera constraints limit where users can navigate. Use them for presentations, guided experiences, or applications with fixed content areas:

```typescript
editor.setCameraOptions({
	constraints: {
		bounds: { x: 0, y: 0, w: 1920, h: 1080 },
		padding: { x: 50, y: 50 },
		origin: { x: 0.5, y: 0.5 },
		initialZoom: 'fit-min',
		baseZoom: 'default',
		behavior: 'inside',
	},
})
```

The `bounds` define the constrained area in page space. The camera restricts panning outside this rectangle based on the `behavior` setting.

The `padding` adds a screen-space margin inside the viewport so content doesn't touch the edges.

The `origin` positions the bounds within the viewport when an axis uses `'fixed'` behavior, when `'contain'` is zoomed out below the fit zoom, and when the camera resets. `{ x: 0.5, y: 0.5 }` centers the bounds; `{ x: 0, y: 0 }` aligns them top-left.

### Zoom fitting

`initialZoom` is the zoom the camera starts at and returns to on reset. `baseZoom` is the zoom that `zoomSteps` are multiplied by, so a step of `1` means "the base zoom" rather than 100%. Both accept the same values:

| Value           | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `'default'`     | 100% zoom                                                               |
| `'fit-x'`       | The bounds' width fills the viewport width                              |
| `'fit-y'`       | The bounds' height fills the viewport height                            |
| `'fit-min'`     | The smaller axis fills the viewport; the larger axis may extend past it |
| `'fit-max'`     | The larger axis fills the viewport, so the full bounds stay visible     |
| `'fit-x-100'`   | `fit-x` or 100%, whichever is smaller                                   |
| `'fit-y-100'`   | `fit-y` or 100%, whichever is smaller                                   |
| `'fit-min-100'` | `fit-min` or 100%, whichever is smaller                                 |
| `'fit-max-100'` | `fit-max` or 100%, whichever is smaller                                 |

### Constraint behaviors

The `behavior` option controls how the bounds constrain camera movement:

| Value       | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `'free'`    | The bounds are ignored                                                          |
| `'fixed'`   | The bounds are pinned at the origin; the user can't pan                         |
| `'inside'`  | The bounds stay completely within the viewport                                  |
| `'outside'` | The bounds stay touching the viewport                                           |
| `'contain'` | `'fixed'` when zoomed out below the fit zoom, `'inside'` when zoomed in past it |

Set behavior per axis for asymmetric constraints:

```typescript
behavior: {
  x: 'free',    // Horizontal panning unrestricted
  y: 'inside',  // Vertical panning keeps bounds visible
}
```

## Camera methods

The camera-move methods below ([`Editor.setCamera`](/reference/editor/Editor#setCamera), [`Editor.centerOnPoint`](/reference/editor/Editor#centerOnPoint), [`Editor.zoomIn`](/reference/editor/Editor#zoomIn), [`Editor.zoomOut`](/reference/editor/Editor#zoomOut), [`Editor.zoomToFit`](/reference/editor/Editor#zoomToFit), [`Editor.zoomToSelection`](/reference/editor/Editor#zoomToSelection), [`Editor.zoomToBounds`](/reference/editor/Editor#zoomToBounds), and [`Editor.resetZoom`](/reference/editor/Editor#resetZoom)) accept optional [`TLCameraMoveOptions`](/reference/editor/TLCameraMoveOptions):

- `animation` - animate the move with `duration` and `easing`
- `immediate` - move the camera immediately rather than on the next tick
- `force` - move the camera even when `isLocked` is true
- `reset` - reset the camera to the constraints' initial zoom and origin

### Basic navigation

Move the camera to a specific position and zoom:

```typescript
editor.setCamera({ x: -500, y: -300, z: 1.5 })
```

Center the viewport on a point:

```typescript
editor.centerOnPoint({ x: 1000, y: 500 })
```

Zoom in or out. Both methods accept an optional screen point to zoom toward:

```typescript
editor.zoomIn()
editor.zoomOut()
editor.zoomIn(editor.inputs.getCurrentScreenPoint(), { animation: { duration: 200 } })
```

### Zoom to content

Focus the camera on shapes or bounds:

```typescript
// Fit all shapes on the current page
editor.zoomToFit()

// Fit the current selection
editor.zoomToSelection()

// Reset zoom to 100%. With constraints, toggles between the initial zoom and 100%
editor.resetZoom()

// Fit specific bounds with padding
const bounds = { x: 0, y: 0, w: 1000, h: 800 }
editor.zoomToBounds(bounds, { inset: 100 })
```

`zoomToBounds` accepts `inset` to add screen-space padding around the bounds and `targetZoom` to cap the zoom level.

### Animated movement

Add smooth transitions with the `animation` option. The [`EASINGS`](/reference/editor/EASINGS) object provides common easing functions:

```typescript
import { EASINGS } from 'tldraw'

editor.setCamera(
	{ x: 0, y: 0, z: 1 },
	{
		animation: {
			duration: 500,
			easing: EASINGS.easeInOutCubic,
		},
	}
)
```

Camera animations stop automatically when the user pans or zooms: user input takes precedence over programmatic movement. You can also stop them at any time with [`Editor.stopCameraAnimation`](/reference/editor/Editor#stopCameraAnimation). See [Animation](/sdk-features/animation) for more on animation options and user preferences.

### Momentum scrolling

Use [`Editor.slideCamera`](/reference/editor/Editor#slideCamera) for kinetic scrolling, for example to keep the camera moving after a gesture ends:

```typescript
editor.slideCamera({
	speed: 1,
	direction: { x: 1, y: 0 },
	friction: 0.1,
	speedThreshold: 0.01,
})
```

`speed` is clamped to a maximum of `1` and `direction` sets the initial velocity. A `z` component on `direction` slides the zoom as well. `friction` controls how fast the camera decelerates (higher stops sooner) and defaults to `editor.options.cameraSlideFriction`. The slide ends once the speed drops below `speedThreshold`.

### Quick zoom navigation

The default tldraw UI has a quick zoom mode. Press `z` to select the zoom tool, then hold Shift. The camera zooms out to show your current viewport plus everything on the page, and a brush marks where you'll land. Move the cursor to place the brush and release Shift to zoom there. Press Escape to cancel and return to the original view.

## Collaboration features

Call [`Editor.startFollowingUser`](/reference/editor/Editor#startFollowingUser) to track another user's viewport, or [`Editor.zoomToUser`](/reference/editor/Editor#zoomToUser) to jump to their cursor once. While following, the camera fits the other user's viewport inside yours: if the aspect ratios differ, the zoom adjusts so their whole viewport stays visible.

See [User following](/sdk-features/user-following) for details.

## Related examples

- [Camera options](/examples/configuration/camera-options) - Configure the camera's options and constraints, including zoom behavior, pan speed, and camera bounds.
- [Image annotator](/examples/use-cases/image-annotator) - Configure camera options for a fixed-viewport annotation app.
- [Slideshow (fixed camera)](/examples/use-cases/slideshow) - A slideshow with a fixed camera using camera constraints.
- [Lock camera zoom](/examples/editor-api/lock-camera-zoom) - Lock the camera at a specific zoom level.
- [Zoom to bounds](/examples/editor-api/zoom-to-bounds) - Zoom the camera to specific bounds with `zoomToBounds`.
- [Scrollable container](/examples/layout/scroll) - Use the editor inside a scrollable container with mousewheel handling.

--------

# Click detection

In tldraw, the click detection system turns a pair of nearby clicks into a `double_click` event. The [`ClickManager`](/reference/editor/ClickManager) tracks consecutive pointer downs with a small state machine and emits `double_click` when the timing and distance thresholds are met.

After a double-click, extra nearby clicks are treated as overflow. Overflow clicks do not dispatch additional click events; they suppress the sequence long enough to prevent a rapid double-double-click from becoming two double-clicks.

## How it works

When a pointer down event occurs, the manager either starts a new sequence, detects a double-click, or moves the sequence into overflow. Each state has a timeout that determines how long to wait before returning to idle.

Two timeout durations control the detection speed. The first click uses `doubleClickDurationMs` (450ms by default), which is how long the user has to make the second click. After a double-click, `multiClickDurationMs` (200ms by default) controls both the settle delay and the overflow suppression window. The option name is historical; it now controls only the post-double-click window.

### State transitions

The click state machine progresses through these states:

| State             | Description                                   |
| ----------------- | --------------------------------------------- |
| `idle`            | No active click sequence                      |
| `pendingDouble`   | First click registered, waiting for second    |
| `pendingOverflow` | Double-click registered, waiting for overflow |
| `overflow`        | Extra clicks detected after the double-click  |

The second pointer down still reaches the state chart as a `pointer_down`, followed immediately by a `double_click` event, and the manager starts waiting for overflow. If the timeout expires before another click, the manager dispatches a double-click settle event and returns to idle. If another pointer down arrives first, the sequence moves to overflow and no further click events are dispatched until the overflow timeout expires.

### Distance validation

Consecutive clicks must occur within a maximum distance of 40 pixels (screen space). If pointer down events are farther apart, the new pointer down starts a fresh click sequence instead.

### Click event phases

Each click event carries a `phase` that says when in the sequence it fired:

| Phase         | When it fires                                                       |
| ------------- | ------------------------------------------------------------------- |
| `down`        | On the second pointer down, when the double-click is detected       |
| `up`          | On the matching pointer up while the double-click is still pending  |
| `settle-down` | When the timeout expires without overflow while the pointer is down |
| `settle-up`   | When the timeout expires without overflow after the pointer is up   |

The phase system lets tools respond at different points in the click sequence. Most default selection and cropping behavior responds on the `down` phase, so it starts on the second pointer down. The hand tool's double-click zoom responds on `settle-up`, so an overflow click can still cancel the pending zoom.

### Movement cancellation

If the pointer moves too far during a pending click sequence, the system cancels the sequence and returns to idle. This prevents double-click detection during click-drag operations. The movement threshold is `dragDistanceSquared` for fine pointers (mouse, stylus) and `coarseDragDistanceSquared` for coarse pointers (touchscreens), both editor [options](/sdk-features/options).

The manager only sees pointer events that match the current pen mode: in pen mode, finger taps don't produce double-clicks, and outside pen mode, pen taps don't.

## Handling click events

Tools receive click events through handler methods defined in the [`TLEventHandlers`](/reference/editor/TLEventHandlers) interface. Here's a complete example of a custom tool that zooms in as soon as a double-click is detected:

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

class ZoomTool extends StateNode {
	static override id = 'zoom'

	override onDoubleClick(info: TLClickEventInfo) {
		if (info.phase !== 'down') return
		// info.point is in client space; zoomIn wants a point relative to the viewport
		const screenPoint = this.editor.inputs.getCurrentScreenPoint()
		this.editor.zoomIn(screenPoint, { animation: { duration: 200 } })
	}
}

const customTools = [ZoomTool]

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				tools={customTools}
				onMount={(editor) => {
					editor.setCurrentTool('zoom')
				}}
			/>
		</div>
	)
}
```

Use `phase: 'down'` for behavior that should start on the second pointer down, or a settle phase for behavior that should wait until the overflow window has passed.

The select tool routes shape double-clicks to [`ShapeUtil.onDoubleClick`](/reference/editor/ShapeUtil#onDoubleClick), and double-clicks on handles, edges, and corners to [`ShapeUtil.onDoubleClickHandle`](/reference/editor/ShapeUtil#onDoubleClickHandle), [`ShapeUtil.onDoubleClickEdge`](/reference/editor/ShapeUtil#onDoubleClickEdge), and [`ShapeUtil.onDoubleClickCorner`](/reference/editor/ShapeUtil#onDoubleClickCorner). Return a partial shape object to apply changes:

```tsx
override onDoubleClick(shape: MyShape) {
	return {
		id: shape.id,
		type: shape.type,
		props: { expanded: !shape.props.expanded },
	}
}
```

The [`TLClickEventInfo`](/reference/editor/TLClickEventInfo) type includes these properties:

| Property    | Type                                                          | Description                                            |
| ----------- | ------------------------------------------------------------- | ------------------------------------------------------ |
| `type`      | `'click'`                                                     | Event type identifier                                  |
| `name`      | `'double_click'`                                              | Which click event this is                              |
| `point`     | `VecLike`                                                     | Pointer position in client space                       |
| `pointerId` | `number`                                                      | Unique identifier for the pointer                      |
| `button`    | `number`                                                      | Mouse button (0 = left, 1 = middle, 2 = right)         |
| `phase`     | `'down' \| 'up' \| 'settle-down' \| 'settle-up'`              | When in the click sequence this fired                  |
| `target`    | `'canvas' \| 'selection' \| 'shape' \| 'handle' \| 'overlay'` | What was clicked                                       |
| `shape`     | `TLShape \| undefined`                                        | The shape, when target is `'shape'` or `'handle'`      |
| `handle`    | `TLHandle \| TLSelectionHandle \| undefined`                  | The handle, when target is `'handle'` or `'selection'` |
| `overlay`   | `TLOverlay \| undefined`                                      | The overlay, when target is `'overlay'`                |
| `shiftKey`  | `boolean`                                                     | Whether Shift was held                                 |
| `altKey`    | `boolean`                                                     | Whether Alt/Option was held                            |
| `ctrlKey`   | `boolean`                                                     | Whether Control (or Command) was held                  |
| `metaKey`   | `boolean`                                                     | Whether Meta/Command was held                          |
| `accelKey`  | `boolean`                                                     | Platform accelerator key (Cmd on Mac, Ctrl on Windows) |

## Timing configuration

Click timing is configured through the editor's [options](/sdk-features/options):

| Option                  | Default | Description                                               |
| ----------------------- | ------- | --------------------------------------------------------- |
| `doubleClickDurationMs` | 450ms   | Time window for the first click to become a double-click  |
| `multiClickDurationMs`  | 200ms   | Double-click settle delay and overflow suppression window |

## Related examples

- [Canvas events](/examples/events/canvas-events) — logs pointer events including click sequences to understand the event flow
- [Custom double-click behavior](/examples/events/custom-double-click-behavior) — overrides the default double-click handler in the SelectTool
- [Shape with onDoubleClickEdge](/examples/shapes/tools/shape-with-onDoubleClickEdge) — implements `onDoubleClickEdge` in a custom shape

--------

# Clipboard

The clipboard lets you copy, cut, and paste shapes within a single editor or between different editor instances. When you copy shapes, the editor serializes them along with their bindings and assets into a [`TLContent`](/reference/editor/TLContent) object. This format preserves document structure and relationships so shapes paste correctly elsewhere.

## How clipboard operations work

Clipboard operations have two flows: extracting content (copy/cut) and placing content (paste).

### Extracting content

When you copy or cut shapes, the editor calls [`Editor.getContentFromCurrentPage`](/reference/editor/Editor#getContentFromCurrentPage) to serialize them into a [`TLContent`](/reference/editor/TLContent) object (or `undefined` if the selection is empty):

```ts
const content = editor.getContentFromCurrentPage(editor.getSelectedShapeIds())
// content contains shapes, bindings, assets, and schema
```

This method collects the selected shapes and their descendants, gathers bindings between them, and includes any referenced assets. Root shapes (those whose parents aren't in the selection) get transformed to page coordinates so they paste at the correct position.

The method keeps only bindings where both the `fromId` and `toId` shapes are in the copied set. This prevents dangling references to shapes that won't exist in the pasted content.

### Placing content

[`Editor.putContentOntoCurrentPage`](/reference/editor/Editor#putContentOntoCurrentPage) handles paste operations. It takes [`TLContent`](/reference/editor/TLContent) and reconstructs shapes on the current page:

```ts
// Paste at a specific point
editor.putContentOntoCurrentPage(content, {
	point: { x: 100, y: 100 },
	select: true,
})

// Paste and preserve original positions
editor.putContentOntoCurrentPage(content, {
	preservePosition: true,
})
```

The method migrates the content through the store's schema system to handle version differences (it throws if `content.schema` is missing), remaps shape and binding IDs to prevent collisions, and finds an appropriate parent for the pasted shapes.

Parent selection depends on how you paste. With a `point`, the editor uses the deepest shape under that point that can receive every pasted root shape (via `ShapeUtil#canReceiveNewChildrenOfType`). Without a point, it looks at the current selection: for each selected shape it takes the nearest container that accepts the content (the shape itself, an accepting ancestor, or its parent), and if the selection spans several containers it uses their deepest common accepting ancestor. A shape is never pasted into itself. Shapes that land on the page are then reparented into any frame that contains their center.

### Browser clipboard integration

The editor writes clipboard data in multiple formats. For HTML-aware applications, it embeds serialized [`TLContent`](/reference/editor/TLContent) in a `<div data-tldraw>` element. For plain text, it extracts the text of the copied shapes.

The clipboard uses a versioned format with compression. Version 3 (the current format) stores assets as plain JSON and compresses other data using LZ compression. This keeps the payload small while asset information stays quickly accessible. Older version 1 and 2 payloads are still read on paste.

When pasting, the editor tries the browser's Clipboard API first because it preserves metadata that the clipboard event API strips out. If that fails, it falls back to reading from the paste event's clipboard data, and it prefers the event's files when the API only returned file names. The editor handles images, files, URLs, HTML, and plain text, routing each through the appropriate handler. To copy shapes as an image instead, use [`copyAs`](/reference/tldraw/copyAs), which shares the same pipeline.

Three hooks on [`TldrawOptions`](/reference/editor/TldrawOptions) let you intercept these flows. `onClipboardPasteRaw` fires before tldraw parses the clipboard, so you can read the raw `ClipboardEvent` yourself; return `false` to short-circuit the default pipeline. `onBeforePasteFromClipboard` receives the parsed external content and can transform it or return `false` to cancel. `onBeforeCopyToClipboard` receives the [`TLContent`](/reference/editor/TLContent) about to be written and can transform it or return `false` to cancel the copy (for a cut, nothing is deleted).

### Asset resolution

Before writing to the clipboard, the editor calls [`Editor.resolveAssetsInContent`](/reference/editor/Editor#resolveAssetsInContent). Image and video assets whose `src` isn't already a data or http URL (for example, assets stored in IndexedDB) are resolved and inlined as data URLs; hosted URLs are copied unchanged:

```ts
const content = editor.getContentFromCurrentPage(editor.getSelectedShapeIds())
const resolved = await editor.resolveAssetsInContent(content)
// local assets in resolved.assets now have data URLs for src
```

This makes the content portable across editor instances without relying on URLs that only work in the source app.

### Cut operations

Cut combines copy and delete. The editor first copies the selected shapes to the clipboard, then deletes the originals, so a failed copy leaves your shapes intact.

### Plain text paste

`Cmd+Shift+V` (or `Ctrl+Shift+V` on Windows and Linux) pastes the clipboard as plain text. HTML and rich formatting are stripped. This is the standard "paste without formatting" shortcut. It's handy when styled text from a browser or word processor would otherwise bring its fonts and colors onto the canvas with it. If the clipboard has no plain text (a copied PNG, say), the shortcut falls through to the normal paste.

## Content structure

The [`TLContent`](/reference/editor/TLContent) type defines the clipboard payload:

```ts
interface TLContent {
	shapes: TLShape[]
	bindings: TLBinding[] | undefined
	rootShapeIds: TLShapeId[]
	assets: TLAsset[]
	schema: SerializedSchema
	users?: TLUser[]
}
```

- `shapes` contains all copied shapes in serialized form
- `rootShapeIds` identifies which shapes have no parent in the copied set, distinguishing top-level shapes from nested children
- `bindings` holds relationships between shapes, like arrows connected to boxes
- `assets` includes images, videos, and other external resources
- `schema` preserves the store schema version, so content from a different editor version can be migrated on paste
- `users` carries any user records referenced by the copied shapes, so [attribution](/sdk-features/attribution) display names survive the paste; on paste, only users not already in the store are created

## Position handling

[`Editor.putContentOntoCurrentPage`](/reference/editor/Editor#putContentOntoCurrentPage) offers flexible positioning:

- By default, shapes paste in place if any of them is on screen; otherwise the group is centered in the viewport
- When pasting into a selected container, shapes are centered in that container
- With the `point` option, shapes are centered on that point. The UI passes the cursor position when the paste-at-cursor preference is on, when you paste from the context menu, or when you press `Cmd+Option+V` (`Ctrl+Alt+V`), which inverts the preference for one paste
- The `preservePosition` option places shapes at their exact stored coordinates

The editor uses `preservePosition` internally when moving shapes between pages, where position preservation matters.

## ID remapping

Shape and binding IDs get remapped during paste to prevent collisions with existing shapes. The editor creates a mapping from old IDs to new IDs, then updates parent-child relationships and binding endpoints to match. Asset IDs are not remapped: assets already in the store are reused, and new ones are created under their original IDs.

The `preserveIds` option disables remapping. The editor uses it when moving shapes between pages, where the shapes should keep their existing IDs.

## External content handling

For non-tldraw content (images, URLs, plain text), use [`Editor.putExternalContent`](/reference/editor/Editor#putExternalContent) to route it through registered handlers:

```ts
// Paste files at a specific point
await editor.putExternalContent({
	type: 'files',
	files: droppedFiles,
	point: { x: 100, y: 200 },
})

// Paste a URL
await editor.putExternalContent({
	type: 'url',
	url: 'https://example.com/image.png',
	point: editor.inputs.getCurrentPagePoint(),
})

// Paste text
await editor.putExternalContent({
	type: 'text',
	text: 'Hello world',
	point: { x: 100, y: 100 },
})
```

Serialized tldraw content goes through the same route: `editor.putExternalContent({ type: 'tldraw', content })` marks a history stopping point, pastes with [`Editor.putContentOntoCurrentPage`](/reference/editor/Editor#putContentOntoCurrentPage), and selects the result. Register custom handlers with [`Editor.registerExternalContentHandler`](/reference/editor/Editor#registerExternalContentHandler) to customize how different content types are processed. See [External content](/sdk-features/external-content) for details on the handler system.

## Related examples

- [Custom paste behavior](/examples/data/assets/custom-paste) shows how to customize paste by registering an external content handler that changes where pasted shapes are positioned.
- [External content sources](/examples/data/assets/external-content-sources) shows how to handle different content types when pasting into tldraw, including custom handling for HTML content.

--------

# Collaboration

The `@tldraw/sync` package provides real-time multiplayer collaboration for tldraw. Multiple users can edit the same document simultaneously, see each other's cursors, and follow each other's viewports. The sync system handles connection management, conflict resolution, and presence.

Collaboration requires a server component to coordinate changes between clients. Use tldraw's demo server for prototyping, or run your own server for production.

## Quick start with the demo server

The fastest way to add multiplayer is with [`useSyncDemo`](/reference/sync/useSyncDemo). This hook connects to a hosted demo server that handles synchronization:

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

export default function App() {
	const store = useSyncDemo({ roomId: 'my-room-id' })

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw store={store} />
		</div>
	)
}
```

Anyone who opens the app with the same `roomId` will see the same document and each other's cursors. The demo server is great for prototyping, but data is deleted after a day and rooms are publicly accessible by ID. Don't use it in production.

## Production setup with useSync

For production, use the [`useSync`](/reference/sync/useSync) hook with your own server:

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

export default function Room({ roomId }: { roomId: string }) {
	const store = useSync({
		uri: `wss://your-server.com/sync/${roomId}`,
		assets: myAssetStore,
	})

	if (store.status === 'loading') {
		return <div>Connecting...</div>
	}

	if (store.status === 'error') {
		return <div>Connection error: {store.error.message}</div>
	}

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw store={store.store} />
		</div>
	)
}
```

The `useSync` hook returns a [`RemoteTLStoreWithStatus`](/reference/sync/RemoteTLStoreWithStatus) object with three possible states:

| Status          | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `loading`       | Establishing connection and performing initial sync            |
| `synced-remote` | Connected and syncing. Includes `store` and `connectionStatus` |
| `error`         | Connection failed. Includes `error` with details               |

### Asset storage

Production setups require a [`TLAssetStore`](/reference/tlschema/TLAssetStore) for handling images, videos, and other files:

```tsx
const myAssetStore: TLAssetStore = {
	upload: async (asset, file) => {
		const response = await fetch('/api/upload', {
			method: 'POST',
			body: file,
		})
		const { url } = await response.json()
		return { src: url }
	},
	resolve: (asset, context) => {
		// context includes dpr, networkEffectiveType, and shouldResolveToOriginal
		return asset.props.src
	},
}

const store = useSync({
	uri: `wss://your-server.com/sync/${roomId}`,
	assets: myAssetStore,
})
```

See the [Assets](/docs/assets) documentation for more on implementing asset stores.

## User identity

By default, users get a default name and a random color, stored in localStorage. To customize this, pass a [`TLUserStore`](/reference/tlschema/TLUserStore) as `users`, whose methods return reactive `Signal` values:

```tsx
import { computed, UserRecordType, createUserId } from 'tldraw'

const currentUser = computed('currentUser', () =>
	UserRecordType.create({
		id: createUserId('user-123'),
		name: 'Alice',
		color: '#ff0000',
	})
)

const store = useSyncDemo({
	roomId: 'my-room',
	users: {
		currentUser,
	},
})
```

The `users` store is also used for shape attribution — the same `currentUser` signal stamps shapes with user IDs. See the [Attribution](/sdk-features/attribution) page for details on tracking which users create or edit shapes. Provide a `resolve` method to look up other users by ID:

```tsx
const users: TLUserStore = {
	currentUser: myAuth.currentUser$,
	resolve: (userId) => myUserCache.getSignal(userId),
}
```

### Integrating with useTldrawCurrentUser

If you need to let users edit their preferences through tldraw's UI, use [`useTldrawCurrentUser`](/reference/editor/useTldrawCurrentUser):

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { useEffect, useMemo, useRef, useState } from 'react'
import {
	atom,
	computed,
	createUserId,
	TLUserPreferences,
	TLUserStore,
	Tldraw,
	UserRecordType,
	useTldrawCurrentUser,
} from 'tldraw'

export default function App({ roomId }: { roomId: string }) {
	const [userPreferences, setUserPreferences] = useState<TLUserPreferences>({
		id: 'user-123',
		name: 'Alice',
		color: 'coral',
		colorScheme: 'dark',
	})

	const userPrefsAtom = useRef(atom('userPrefs', userPreferences)).current
	useEffect(() => {
		userPrefsAtom.set(userPreferences)
	}, [userPreferences, userPrefsAtom])

	const users: TLUserStore = useMemo(() => {
		const currentUser = computed('currentUser', () => {
			const p = userPrefsAtom.get()
			return UserRecordType.create({
				id: createUserId(p.id),
				name: p.name ?? '',
				color: p.color ?? '',
			})
		})
		return { currentUser }
	}, [userPrefsAtom])

	const store = useSyncDemo({ roomId, users })
	const user = useTldrawCurrentUser({ userPreferences, setUserPreferences })

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw store={store} user={user} />
		</div>
	)
}
```

## Connection status

When using `useSync`, the store object includes connection status information:

```tsx
const store = useSync({ uri, assets })

if (store.status === 'synced-remote') {
	// store.connectionStatus is 'online' or 'offline'
	console.log('Connection:', store.connectionStatus)
}
```

The connection status reflects the WebSocket connection state. When offline, changes are queued locally and sync when the connection resumes.

## Custom presence

The presence system controls what information is shared with other users. By default, it includes cursor position, selected shapes, and viewport bounds. You can customize this with `getUserPresence`, starting from [`getDefaultUserPresence`](/reference/tlschema/getDefaultUserPresence):

```tsx
import { getDefaultUserPresence } from 'tldraw'

const store = useSyncDemo({
	roomId: 'my-room',
	getUserPresence(store, user) {
		const defaults = getDefaultUserPresence(store, user)
		if (!defaults) return null

		return {
			...defaults,
			// Remove camera/viewport to disable follow functionality
			camera: undefined,
		}
	},
})
```

Return `null` from `getUserPresence` to hide this user's presence entirely. This is useful for spectator modes where you want a user to observe without appearing in the room.

## Authentication

To add authentication, generate the WebSocket URI dynamically:

```tsx
const store = useSync({
	uri: async () => {
		const token = await getAuthToken()
		return `wss://your-server.com/sync/${roomId}?token=${token}`
	},
	assets: myAssetStore,
})
```

The `uri` option accepts a function that returns a string or Promise. This runs when establishing the connection and on reconnection, so tokens can refresh automatically.

## Running your own server

For production, you'll need to run a sync server. The `@tldraw/sync-core` package provides [`TLSocketRoom`](/reference/sync-core/TLSocketRoom) for server-side room management.

Our [Cloudflare Workers template](https://github.com/tldraw/tldraw/tree/main/templates/sync-cloudflare) is the same setup that runs tldraw.com. It includes:

- WebSocket sync via Durable Objects (one per room)
- Asset storage with R2
- Bookmark unfurling for URL previews

Get started with the template:

```bash
npm create tldraw@latest -- --template multiplayer
```

Or copy the relevant pieces into your existing infrastructure. See [Sync](/docs/sync) for other server setups.

### Server architecture

The sync server uses a room-based model:

1. Each document has a unique room ID
2. Clients connect via WebSocket to their room
3. The server maintains one `TLSocketRoom` per active room
4. Changes broadcast to all connected clients in real-time
5. The server is authoritative for conflict resolution

```
┌─────────┐     ┌─────────────────┐     ┌─────────┐
│ Client  │────▶│   TLSocketRoom  │◀────│ Client  │
└─────────┘     │   (per room)    │     └─────────┘
                └────────┬────────┘
                         │
                    ┌────▼────┐
                    │ Storage │
                    └─────────┘
```

## Custom shapes and bindings

If you use custom shapes or bindings, register them with the sync hooks using schema options:

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { Tldraw } from 'tldraw'
import { MyCustomShapeUtil } from './MyCustomShape'
import { MyCustomBindingUtil } from './MyCustomBinding'

const customShapes = [MyCustomShapeUtil]
const customBindings = [MyCustomBindingUtil]

export default function App({ roomId }: { roomId: string }) {
	const store = useSyncDemo({
		roomId,
		shapeUtils: customShapes,
		bindingUtils: customBindings,
	})

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw store={store} shapeUtils={customShapes} bindingUtils={customBindings} />
		</div>
	)
}
```

Pass the shape and binding utilities to both the sync hook (for schema registration) and the Tldraw component (for rendering). If they don't match, shapes may fail to sync or render correctly.

`useSyncDemo` adds tldraw's default utilities for you. `useSync` doesn't: when you pass `shapeUtils` or `bindingUtils` to `useSync`, include the defaults yourself, for example `shapeUtils: [...defaultShapeUtils, MyCustomShapeUtil]`.

## Comments

Comment threads sync the same way, through record types you opt into with the `records` option:

```tsx
import { useSync } from '@tldraw/sync'
import { commentSchemaRecords } from 'tldraw'

const store = useSync({
	uri: `wss://your-server.com/sync/${roomId}`,
	assets: myAssetStore,
	records: commentSchemaRecords,
})
```

Your server's schema needs the same registration. On the server you can also serve comments through the room's object-store lane, which gates them by their own per-session permission. A viewer who can't edit the document can still comment. See [Commenting](/sdk-features/commenting) for the tool, the canvas layer, and the server setup.

## Building custom sync

The `@tldraw/sync` package handles connection management, reconnection, conflict resolution, and protocol versioning. For most applications, it's the right choice. You might need custom sync when integrating with existing infrastructure, using a different transport (like WebRTC), or implementing specialized conflict resolution.

tldraw's store provides the primitives you need to build your own sync layer.

### Listening to changes

The store's [`Store.listen`](/reference/store/Store#listen) method notifies you when records change:

```tsx
const unsubscribe = editor.store.listen(
	(entry) => {
		// entry.changes contains all modifications
		// entry.source is 'user' (local) or 'remote'
		console.log('Changes:', entry.changes)
	},
	{ source: 'user', scope: 'document' }
)

// Later: stop listening
unsubscribe()
```

Filter options narrow what changes you receive:

| Filter   | Values                                           | Description               |
| -------- | ------------------------------------------------ | ------------------------- |
| `source` | `'user'`, `'remote'`, `'all'`                    | Who made the change       |
| `scope`  | `'document'`, `'session'`, `'presence'`, `'all'` | What type of data changed |

For sync, you typically want `source: 'user'` (only local changes) and `scope: 'document'` (only persistent data).

### Change structure

Changes arrive as a [`RecordsDiff`](/reference/store/RecordsDiff) object with three categories:

```tsx
interface RecordsDiff<R> {
	added: Record<string, R> // New records
	updated: Record<string, [from: R, to: R]> // Changed records (before/after)
	removed: Record<string, R> // Deleted records
}
```

Each entry is keyed by record ID. For updates, you get both the previous and current state, which is useful for conflict detection or generating patches.

### Applying remote changes

When you receive changes from other clients, wrap them in [`Store.mergeRemoteChanges`](/reference/store/Store#mergeRemoteChanges):

```tsx
function applyRemoteChanges(records: TLRecord[], deletedIds: TLRecord['id'][]) {
	editor.store.mergeRemoteChanges(() => {
		if (records.length > 0) {
			editor.store.put(records)
		}
		if (deletedIds.length > 0) {
			editor.store.remove(deletedIds)
		}
	})
}
```

This marks the changes as `'remote'` source, so your own listener won't echo them back to the server. It also batches the operations into a single transaction, and remote changes never enter the undo/redo history.

### Snapshots and serialization

For initial sync or persistence, serialize the entire store:

```tsx
// Get all document records as a plain object
const data = editor.store.serialize('document')
// Returns: { 'shape:abc': {...}, 'page:xyz': {...}, ... }

// Get a snapshot with schema information (recommended for persistence)
const snapshot = editor.store.getStoreSnapshot('document')
// Returns: { store: {...}, schema: {...} }

// Restore from snapshot (handles migrations automatically)
editor.store.loadStoreSnapshot(snapshot)
```

The snapshot format includes schema information, so tldraw can automatically migrate old data when your schema evolves.

### Presence records

User presence (cursors, selections, viewports) uses [`InstancePresenceRecordType`](/reference/tlschema/InstancePresenceRecordType) records. Only `userId`, `userName`, and `currentPageId` are required; everything else has a default:

```tsx
import { createUserId, InstancePresenceRecordType } from 'tldraw'

// Create a presence record for a remote user, keyed by that client's session id
const presence = InstancePresenceRecordType.create({
	id: InstancePresenceRecordType.createId(remoteSessionId),
	userId: createUserId('user-123'),
	userName: 'Alice',
	color: '#ff6b6b',
	currentPageId: editor.getCurrentPageId(),
	cursor: { x: 100, y: 200, type: 'default', rotation: 0 },
	lastActivityTimestamp: Date.now(),
})

// Add to store
editor.store.put([presence])

// Update cursor position
editor.store.update(presence.id, (record) => ({
	...record,
	cursor: { x: 150, y: 250, type: 'default', rotation: 0 },
}))

// Remove when user disconnects
editor.store.remove([presence.id])
```

Listen for presence changes separately from document changes:

```tsx
editor.store.listen(
	(entry) => {
		// Broadcast presence to other clients
		sendPresence(entry.changes)
	},
	{ source: 'user', scope: 'presence' }
)
```

### Example: simple broadcast sync

Here's a minimal example using a WebSocket for broadcast sync (no conflict resolution):

```tsx
import { useEffect, useRef, useState } from 'react'
import { Tldraw, createTLStore, defaultBindingUtils, defaultShapeUtils } from 'tldraw'

function App() {
	const [store] = useState(() =>
		createTLStore({ shapeUtils: defaultShapeUtils, bindingUtils: defaultBindingUtils })
	)
	const wsRef = useRef<WebSocket | null>(null)

	useEffect(() => {
		const ws = new WebSocket('wss://your-server.com/room/123')
		wsRef.current = ws

		// Send local changes to server
		const unsubscribe = store.listen(
			(entry) => {
				ws.send(
					JSON.stringify({
						type: 'changes',
						added: Object.values(entry.changes.added),
						updated: Object.values(entry.changes.updated).map(([, to]) => to),
						removed: Object.keys(entry.changes.removed),
					})
				)
			},
			{ source: 'user', scope: 'document' }
		)

		// Apply remote changes
		ws.onmessage = (event) => {
			const msg = JSON.parse(event.data)
			if (msg.type === 'changes') {
				store.mergeRemoteChanges(() => {
					if (msg.added.length || msg.updated.length) {
						store.put([...msg.added, ...msg.updated])
					}
					if (msg.removed.length) {
						store.remove(msg.removed)
					}
				})
			}
		}

		return () => {
			unsubscribe()
			ws.close()
		}
	}, [store])

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

This example omits initial state sync, reconnection handling, and conflict resolution. For production, start with `@tldraw/sync` and customize it, or study its implementation for how it handles these cases.

## Related examples

- [Multiplayer sync](/examples/collaboration/sync-demo) — Basic multiplayer setup with the demo server
- [Custom user](/examples/users/sync-custom-user) — Setting custom user identity for multiplayer
- [Custom presence](/examples/collaboration/sync-custom-presence) — Customizing presence data sent to collaborators
- [Custom shapes](/examples/collaboration/sync-custom-shape) — Syncing custom shapes with multiplayer
- [User presence](/examples/collaboration/user-presence) — Manually creating and updating presence records

--------

# Commenting

In tldraw, a comment is a message pinned to a place on the canvas. Comments group into threads, one conversation per pin. Every comment records who wrote it and comments can mention other people.

The `@tldraw/commenting` package works at two levels. `CanvasComments` is a comments layer you render in front of the canvas: it draws the pins, opens the threads, and reads and writes the records itself. The parts it's built from are exported too, so you can replace any of them or assemble your own layer from the pieces.

Commenting is a licensed feature. It runs in development without a key. In production it needs a tldraw license that includes commenting.

## Setup

There are three pieces: register the comment record types with your store, register the comment tool, and render the comments layer.

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

// In production, a tldraw license key that includes commenting. Not needed in development.
const YOUR_LICENSE_KEY = undefined

// Your app's user directory. Any id you can't resolve renders as an anonymous user.
const AUTHORS: Record<string, CommentAuthor> = {
	me: { name: 'You', color: '#EC5E41' },
	ada: { name: 'Ada Lovelace', color: '#0E9F6E' },
}
const resolveAuthor = (id: string) => AUTHORS[id]

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

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

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

Comments are records in the editor's store, exactly like shapes. [`commentSchemaRecords`](/reference/tlschema/commentSchemaRecords) registers the `comment-thread`, `comment`, and `comment-reaction` types, which aren't in the default schema. Once they're registered, comments persist and sync however your document already does: add a `persistenceKey` or a sync backend and they come along with it.

`CanvasComments` needs two things, and both are about identity. `currentUserId` is the id of the person commenting, or `null` for a viewer who can read comments but not post them. `resolveAuthor` maps an author id to a `CommentAuthor`: a `name`, an optional `color` for their avatar and pin, and an optional `image`. Return `undefined` for an id you can't resolve and the layer falls back to an anonymous user.

These two props, plus the read-status and mention callbacks below, make up the `CommentingContext`. The sidebar takes the same context, so a host mounting both surfaces builds one object and spreads it into each.

Mount the layer through the `InFrontOfTheCanvas` component slot so it sits above the canvas but below the UI, and import `commenting.css` alongside `tldraw.css`.

<Callout type="warning">
	Without a license key that includes commenting, every commenting component renders nothing in
	production. The feature is fully enabled in development, so a missing key shows up as a blank
	canvas after you deploy. See [License key](/sdk-features/license-key).
</Callout>

## Placing comments

`commentToolOverrides` puts the comment tool in Quick Actions with the `C` shortcut. With the tool active, clicking empty canvas starts a thread anchored to that point, and clicking a shape anchors a comment to the shape. You can also turn on region comments, where dragging the tool out covers an area. Either way the click only opens a composer: nothing is written to the store until the comment is posted.

Once a comment thread exists, its pin is the handle for everything else.

| Input       | Result                                                               |
| ----------- | -------------------------------------------------------------------- |
| Click a pin | Opens the thread, with its replies and a reply composer.             |
| Drag a pin  | Re-anchors the thread. Drop it on a shape to attach it to the shape. |
| `Escape`    | Closes the open thread.                                              |
| `Shift+C`   | Hides and shows the pins on the canvas.                              |

In the built-in layer, resolve and delete-thread sit in the thread's header, and the edit and delete controls for a single comment appear only on the author's own comments by default. [`canModifyComment`](#who-can-edit-and-delete) changes who gets those controls, and [Syncing comments](#syncing-comments) covers enforcing the same rules on the server.

To put the show and hide toggle in a menu of your own, use `CommentsMenuItem`. It's a checkbox item wired to the same state as the `Shift+C` shortcut.

```tsx
import { CommentsMenuItem } from '@tldraw/commenting'
import { DefaultMainMenu, TldrawUiMenuGroup } from 'tldraw'

function MainMenu() {
	return (
		<DefaultMainMenu>
			<TldrawUiMenuGroup id="comments">
				<CommentsMenuItem />
			</TldrawUiMenuGroup>
		</DefaultMainMenu>
	)
}
```

## Configuring the tool

Commenting options live on the comment tool. Set them with `CommentTool.configure()`, which mirrors `ShapeUtil.configure` and returns a configured subclass to register:

```tsx
import { CommentTool, commentToolOverrides } from '@tldraw/commenting'
import { Tldraw } from 'tldraw'

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

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

Options are fixed once the tool is registered, so this is static configuration only. Live values, like the current user and the author resolver, are the `CommentingContext` instead, passed as props to each surface. Calls to `configure` can be chained, and each one layers over the last.

The sections below introduce the relevant comment options, and [All options](#all-options) lists every one together.

## Anchors

A thread's `anchor` says where it lives. It's a discriminated union, so new anchor kinds can arrive without breaking existing threads.

| Anchor   | Description                                                                                                              |
| -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `point`  | A fixed page point. What a click on empty canvas produces.                                                               |
| `shape`  | A shape, with `x`/`y` as a normalized (0–1) offset in its bounds. The pin keeps its spot as the shape moves and resizes. |
| `region` | A rectangular area of the page, with the pin on one corner.                                                              |
| `page`   | The page itself, with no spatial anchor. These threads have no pin and surface in a list instead.                        |

Shape-anchored threads outlive their shape. Delete the shape and the thread converts to a `point` anchor where its pin last sat, so the conversation doesn't vanish with the thing it was about. Bring the shape back, whether by undoing the delete or by a page move that re-creates it, and the shape anchor is restored. The exception is a pin someone moved by hand in the meantime: a manual placement wins over the restore.

Threads follow their shape across pages too. Move the shape to another page and the thread's `pageId`, along with the denormalized `pageId` on each of its comments, updates to match. Comments do not move when you cut or copy a shape.

### Shape anchor precision

A comment that lands on a shape anchors in one of two ways. A **precise** anchor pins to the exact clicked spot. An **imprecise** one addresses the shape as a whole and renders its pin at a spot you choose, the `impreciseShapeAnchor`, which is the shape's top-right corner by default. Both track the shape as it moves and resizes, and both store the clicked `x`/`y`, so precision governs rendering rather than data.

Shape comments are precise by default. `shouldBePrecise` makes the call, and it receives the gesture: the target shape, the release point, and whether Alt was held.

```tsx
// Precise on notes, shape-level everywhere else
const tools = [
	CommentTool.configure({
		shouldBePrecise: (editor, { shapeId }) => editor.getShape(shapeId)?.type === 'note',
	}),
]
```

Return `() => false` for shape-level anchoring throughout, or `(editor, { altKey }) => altKey` to make precision a per-placement choice the user holds Alt for. The predicate governs new placements only. Anchors already stored render the way they were made.

## Comments and undo

Comment writes are not undoable by default. The `history` option governs all of them, including posting, replying, editing and resolving, and it defaults to `'ignore'`. It covers your own writes too: a record you write with `putCommentRecords` lands on the undo stack, or doesn't, exactly like one the built-in UI writes.

In a shared document an undoable delete resurrects a thread a collaborator already removed, and an undoable resolve reverts their newer state. `'record'` is safe in a single-player app, or when the comment store isn't synced.

Deleting is the one write `history` doesn't reach. It's never undoable, because of how deletes work: see [Deleting is a soft delete](#deleting-is-a-soft-delete).

Pin drags are the exception worth configuring separately. Re-anchoring a comment is a spatial edit that may reasonably undo alongside the shape move that prompted it, so `dragHistory` overrides `history` for drags alone:

```tsx
CommentTool.configure({ dragHistory: 'record' })
```

The [comments and undo example](/examples/collaboration/comment-history) lets you feel the difference: post a comment, press undo, and watch whether the thread count moves.

## Who can comment

Left unset, `canComment` allows participation whenever `currentUserId` is set. Participation covers composing threads and replies, editing and deleting your own comments, resolving threads, and moving pins. Pass a callback to decide for yourself:

```tsx
CommentTool.configure({
	canComment: ({ currentUserId }) => currentUserId !== null && getRole() !== 'viewer',
	components: {
		ComposerFallback: ({ context }) => (context === 'thread' ? <SignInPrompt /> : null),
	},
})
```

When `canComment` returns false, composers give way to the `ComposerFallback` slot and the action affordances hide. That slot's `context` says which surface is asking: the bottom of an open thread (`'thread'`), or the placement popover the tool opens (`'pending'`). Leave the slot unset and those surfaces render nothing.

`canComment` is read during render through `useCanComment`, so a callback that reads signals re-evaluates when they change.

## Who can edit and delete

`canComment` is about the viewer; `canModifyComment` is about the viewer and one particular record. It's asked for three writes: editing a comment, deleting a comment, and deleting a thread. Where it returns false, that affordance isn't rendered.

By default, only a comment's author can edit or delete it, and only a thread's creator can delete the thread. Pass a callback to widen that, composing with `defaultCanModifyComment` so the owner keeps what they already had:

```tsx
import { CommentTool, defaultCanModifyComment } from '@tldraw/commenting'

CommentTool.configure({
	canModifyComment: (ctx) =>
		// Moderators may remove anything. Editing stays the author's, whoever you are.
		(ctx.action !== 'edit-comment' && isModerator(ctx.currentUserId)) ||
		defaultCanModifyComment(ctx),
})
```

The `ctx` carries the editor, the viewer's `currentUserId`, and the write itself as a discriminated union: `{ action: 'edit-comment' | 'delete-comment', comment }` or `{ action: 'delete-thread', thread }`. Narrowing works too — return false to close edits after an hour, or on a resolved thread.

Resolving, reopening, reacting, and moving a pin aren't asked about: none of them is anyone's in particular, so `canComment` is the only gate on them. `canModifyComment` is checked after `canComment`, so a viewer who may not participate gets no action affordances whatever it returns. Like `canComment`, it's read during render (through `useCanModifyComment`), so a callback that reads signals re-evaluates when they change.

Enforce the same rule on the server: `createCommentAuthorizers` takes a `canModifyComment` of its own, and that one is authoritative. See [Syncing comments](#syncing-comments).

<Callout type="warning">
	`canComment` and `canModifyComment` hide UI. They don't enforce anything. Comment records carry a
	client-supplied `createdBy` and `authorId`, and a client can write whatever your sync server
	accepts. Enforce permissions in your server's record authorization, and verify author ids against
	the session's authenticated identity. See [Syncing comments](#syncing-comments).
</Callout>

## Mentions

Composers support `@`-mentions. Supply the roster with `getMentionSuggestions`, which can be synchronous or async:

```tsx
import { CanvasComments, filterMentionMembers, MentionMember } from '@tldraw/commenting'

const MEMBERS: MentionMember[] = [
	{ id: 'me', name: 'You', color: '#EC5E41', you: true },
	{ id: 'ada', name: 'Ada Lovelace', color: '#0E9F6E' },
	{ id: 'grace', name: 'Grace Hopper', color: '#4465E9', secondary: 'grace@example.com' },
]

function Comments() {
	return (
		<CanvasComments
			currentUserId="me"
			resolveAuthor={resolveAuthor}
			getMentionSuggestions={(query) => filterMentionMembers(MEMBERS, query)}
		/>
	)
}
```

A `MentionMember` is a `CommentAuthor` plus an `id`, an optional `secondary` line for the picker, and `you` to mark the current user. `filterMentionMembers` does the matching; supply your own filter to query a server instead. To change how a row looks, pass `renderMentionSuggestion`.

A mention is a node in the body rather than text in it, so you can't find one by searching the string. To detect a mention, look for `{ type: 'mention', attrs: { id } }` in the body's `content` tree.

The mention components come from `@tldraw/mentions` and are re-exported here. That package also powers mentions in shape rich text. See [Rich text](/sdk-features/rich-text).

## Reactions

Hover a comment and open the picker to react with an emoji. A pill appears with a live count, and hovering it names who reacted.

Each reaction is its own `comment-reaction` record, one per (comment, user, emoji), rather than a field on the comment. Two people reacting at once therefore write different records and neither can clobber the other. The record id is derived from the triple, so re-picking an emoji toggles it. Registering `commentSchemaRecords` registers the reaction type along with the rest.

Reactions are multi-select by default, where each emoji toggles independently. Set `allowMultipleReactions: false` for single-select, where a new emoji replaces your existing one.

The palette is pluggable. A reaction's emoji is treated as an opaque token: the layer stores it, syncs it, and hands it to a renderer, and never assumes it's a glyph. So you can swap in tokens of your own.

```tsx
CommentTool.configure({
	components: {
		ReactionContent: MyTokenRenderer, // how a token is drawn
		ReactionPalette: MyPalette, // what the add-reaction button opens
	},
	isAllowedReaction: (token) => isMyToken(token) || isAllowedReactionEmoji(token),
})
```

`isAllowedReaction` is enforced client-side. If arbitrary tokens would be a problem for you, validate them on your server too.

## Region comments

A region thread covers a rectangular area rather than a point. Regions are off by default, so the tool stays click-only until you turn them on:

```tsx
CommentTool.configure({ enableRegions: true })
```

That's the whole configuration. A region reveals its dashed box and resize handles while the pointer is inside it, moves by its pin, and resizes from its corners. The pin sits on whichever corner the creating drag was released on, which the anchor remembers.

## The sidebar

`CanvasCommentsSidebar` lists comment threads in a panel beside the canvas. Clicking a row brings that thread's pin into view and opens it.

Its open state is a signal you drive, so the toggle lives wherever your app wants it. `useCommentsSidebarOpen` reads it and `toggleCommentsSidebar` flips it; the underlying `commentsSidebarOpen` atom is exported too, for code that has an editor but no React context:

```tsx
import {
	CanvasComments,
	CanvasCommentsSidebar,
	CommentingContext,
	toggleCommentsSidebar,
	useCommentsSidebarOpen,
} from '@tldraw/commenting'
import { TldrawUiButton, TldrawUiButtonLabel, useEditor } from 'tldraw'

function SidebarToggle() {
	const editor = useEditor()
	const open = useCommentsSidebarOpen()
	return (
		<TldrawUiButton type="normal" onClick={() => toggleCommentsSidebar(editor)}>
			<TldrawUiButtonLabel>{open ? 'Hide comments' : 'Comments'}</TldrawUiButtonLabel>
		</TldrawUiButton>
	)
}

// Both surfaces read the same context, so build it once and spread it into each.
const commenting: CommentingContext = { currentUserId: 'me', resolveAuthor }

const components: TLComponents = {
	InFrontOfTheCanvas: () => (
		<>
			<CanvasComments {...commenting} />
			<CanvasCommentsSidebar {...commenting} />
		</>
	),
	SharePanel: SidebarToggle,
}
```

The sidebar's filters cover resolved threads, only comments you made, only unread comments, and only the current page. They're held per editor, so a user's choices survive the panel closing. Pass `header` and `empty` to replace the chrome around the list.

## Unread state

The layer doesn't track who has read what. That data lives in your app. Supply it as two callbacks. `isCommentUnread` reports whether a comment is unread, and `onCommentsRead` fires once per report with every unread comment the user actually sees in an open thread, so you can record read receipts in one write.

```tsx
<CanvasComments
	currentUserId="me"
	resolveAuthor={resolveAuthor}
	isCommentUnread={(commentId) => !readReceipts.has(commentId)}
	onCommentsRead={(commentIds) => markCommentsRead(commentIds)}
	onPostComment={(comment) => notifyMentionedUsers(comment)}
/>
```

Unread state drives the sidebar's unread filter and the receipts reported through `onCommentsRead`. Without `isCommentUnread`, the filter is hidden and nothing is reported. `onPostComment` fires when this user posts a comment through one of the built-in composers, whether a new thread or a reply. This is where notifications and mention emails belong. It does not fire for comments arriving over sync, so the sender is the one who notifies. See the [comment notifications example](/examples/collaboration/comment-notifications).

## Custom components

Every visible piece of the layer is a slot. Set them through the `components` option, and leave a slot unset to keep its default.

| Slot               | Replaces                                                               |
| ------------------ | ---------------------------------------------------------------------- |
| `CommentBody`      | A comment's body, normally the rich-text renderer.                     |
| `PinContent`       | A pin's inner content, normally the author's initial.                  |
| `ThreadPreview`    | A sidebar row's preview, normally the body as plain text.              |
| `ThreadRow`        | A whole sidebar row, normally `CommentListItem`.                       |
| `ThreadActions`    | Adds controls to an open thread's header. Additive, not a replacement. |
| `ComposerFallback` | What shows where a composer would sit when the viewer can't comment.   |
| `ReactionContent`  | How a reaction token is drawn.                                         |
| `ReactionPalette`  | What the add-reaction button opens.                                    |
| `ReactionTooltip`  | The list of who reacted, shown on a reaction pill.                     |

```tsx
import { CommentTool, richTextToPlaintext } from '@tldraw/commenting'
import { TLComment } from 'tldraw'

function PriorityBody({ comment }: { comment: TLComment }) {
	const urgent = comment.meta.priority === 'urgent'
	return (
		<div className={urgent ? 'urgent-comment' : 'comment'}>{richTextToPlaintext(comment.body)}</div>
	)
}

const tools = [CommentTool.configure({ components: { CommentBody: PriorityBody } })]
```

Every comment record type carries a `meta` field the layer never reads. Use it for priorities, categories, external ticket ids, or anything else your app tracks alongside a comment.

`ThreadRow` and `ThreadActions` are the two slots that add to a surface rather than replace a piece of it, so they get the records behind what's on screen.

`ThreadRow` receives the summarized row along with the thread record, and the default row is exported. A row that only adds something can spread the props into `CommentListItem` rather than start over:

```tsx
import { CommentListItem, CommentListItemRenderProps, CommentTool } from '@tldraw/commenting'
import { TLCommentThread } from 'tldraw'

function StatusRow({ thread, ...row }: CommentListItemRenderProps & { thread: TLCommentThread }) {
	return (
		<div className="status-row">
			<CommentListItem {...row} />
			{thread.meta.status === 'blocked' && <span className="blocked">Blocked</span>}
		</div>
	)
}

const tools = [CommentTool.configure({ components: { ThreadRow: StatusRow } })]
```

`ThreadActions` adds controls to an open thread's header, ahead of the built-in resolve and dismiss buttons. This is where host verbs go: assign a thread, link it to a ticket, mark it as a to-do. It adds alongside the built-in actions rather than replacing them, so a thread never loses the ability to be resolved.

```tsx
import { CommentTool } from '@tldraw/commenting'
import { TLCommentThread } from 'tldraw'

function AssignAction({ thread }: { thread: TLCommentThread }) {
	return (
		<button type="button" className="tlui-cmt-thread__action" onClick={() => assign(thread.id)}>
			Assign
		</button>
	)
}

const tools = [CommentTool.configure({ components: { ThreadActions: AssignAction } })]
```

A link affordance doesn't need this slot: see [Linking to a thread](#linking-to-a-thread).

## Working with comment records

Comment records aren't part of the `TLRecord` union, so `editor.store` doesn't know their types statically. These helpers own that reinterpretation and keep your call sites typed.

| Helper                  | Description                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `getLiveCommentThreads` | The threads that render.                                                             |
| `getLiveComments`       | The comments that render.                                                            |
| `getCommentThreads`     | Every thread in the store, including deleted ones.                                   |
| `getComments`           | Every comment in the store, including deleted ones.                                  |
| `getCommentRecord`      | One record by id, or `undefined`.                                                    |
| `putCommentRecords`     | Write threads and comments.                                                          |
| `removeCommentRecords`  | Remove them by id. Rarely what you want — see [Writing comments](#writing-comments). |

Prefer the live reads. Deleting a comment doesn't remove its record: it flags it and lets the server prune it, as [Writing comments](#writing-comments) explains. So the unfiltered reads include records that nothing renders. `getLiveCommentThreads` also drops threads whose comments have all gone, which have no surface left.

Those reads are non-reactive. In React use the hooks instead, which read the live set: `useCommentThreads`, `useComments`, and `useThreadComments` for one thread's replies, oldest first.

```tsx
import { useCommentThreads } from '@tldraw/commenting'
import { useEditor } from 'tldraw'

function OpenThreadCount() {
	const editor = useEditor()
	const threads = useCommentThreads(editor)
	const open = threads.filter((thread) => !thread.resolved)
	return <div>{open.length} open threads</div>
}
```

## Writing comments

To post a thread yourself, whether you're seeding a document with review notes or importing comments from another system, build the records and write them:

```tsx
import { putCommentRecords } from '@tldraw/commenting'
import { createComment, createCommentThread, toRichText } from 'tldraw'

const thread = createCommentThread({
	pageId: editor.getCurrentPageId(),
	anchor: { type: 'point', x: 120, y: 240 },
	createdBy: 'ada',
})

const comment = createComment({
	threadId: thread.id,
	pageId: thread.pageId,
	authorId: 'ada',
	body: toRichText('Can we make this arrow dashed?'),
})

putCommentRecords(editor, [thread, comment])
```

The other writes each have a rule attached (a timestamp to stamp, or the delete protocol below), so they come as functions. The built-in thread view calls exactly these, so a UI of your own behaves like the one in the box.

| Helper                          | Description                                            |
| ------------------------------- | ------------------------------------------------------ |
| `editComment`                   | Replace a comment's body and mark it edited.           |
| `resolveThread`, `reopenThread` | Resolve a thread, stamping who and when, or reopen it. |
| `deleteComment`                 | Delete a comment.                                      |
| `deleteThread`                  | Delete a thread and its whole conversation.            |

```tsx
import { deleteComment, resolveThread } from '@tldraw/commenting'

resolveThread(editor, thread, currentUserId)
deleteComment(editor, comment)
```

The record you pass says which comment or thread to act on; the change itself lands on the version currently in the store. So a record you took a copy of earlier is safe to pass. It won't put back a field that has moved since, such as a thread's anchor after its pinned shape moved, or a comment's body after its author edited it elsewhere. And it won't re-create a record that has already been deleted, which a plain `putCommentRecords` of a stale copy would. If the record is gone, the call does nothing.

### Deleting is a soft delete

`deleteComment` and `deleteThread` don't remove records. They set an `isDeleted` flag and leave the pruning to the server, which then removes the thread, its comments, and their reactions.

That indirection is what makes deleting safe in a shared document. A reaction belongs to whoever left it, not to whoever is deleting the comment underneath it, so no client should be removing it. And a server enforcing per-record permissions gets a write it can check against the session's identity rather than a deletion it can only refuse. `removeCommentRecords` is a hard delete, and such a server rejects it. Reach for it on a local, unsynced comment store.

The flag is write-once server-side, so deletes are never undoable, whatever `history` says: an undo clearing the flag would be vetoed and rebased rather than bring the comment back.

Deleting a thread's last comment leaves the thread with nothing to render. The record stays for the server to prune, since whoever deleted the comment may not be the thread's creator.

## Revealing a thread

To open a thread from outside the canvas, whether from a notification, a shared link, or a list of your own, call `revealThread` with a thread or comment id. `CanvasComments` serves the request: it waits for the records to arrive, switches pages if it needs to, zooms in if the pin is inside a cluster, then opens the thread.

```tsx
import { revealThread } from '@tldraw/commenting'

// e.g. from a ?comment=<id> search param
revealThread(editor, commentId)
```

An unserved request is inert, so it's safe to call before the records have synced in. `useRevealThreadPending` returns the id of a request that hasn't been served yet, which is how you notice a deep link to a comment that no longer exists. Give it a grace period first, since a request also sits there while its records are still arriving. When the grace period elapses, re-check with `getRevealThreadPending(editor)` so you don't act on a request that cleared inside it.

For a thread you already hold, `focusThread(editor, thread)` centers and opens it directly.

## Linking to a thread

The other half of a deep link is producing one. Give the commenting context a `getThreadHref` and every surface that can link to a thread does:

```tsx
<CanvasComments
	currentUserId="me"
	resolveAuthor={resolveAuthor}
	getThreadHref={(threadId) => `/file/${fileId}?comment=${encodeURIComponent(threadId)}`}
/>
```

Sidebar rows become anchors, so ctrl/cmd-click and middle-click open a thread in a new tab, and an open thread's header menu offers **Copy link**. A relative href is resolved against the current document before it reaches the clipboard, so what gets pasted is a whole URL.

Without `getThreadHref`, neither appears.

## Pin clustering

Zoom out far enough and pins pile on top of each other. Clustering folds nearby pins into a count badge as you zoom out, then splits them apart as you zoom back in. Splits happen at a wider spacing than merges, so pins don't flicker at the boundary. Clicking a badge zooms to just past the point where that cluster breaks up.

Clustering is on by default. Turn it off with `enableClustering: false`.

The work is precomputed once per comment add, remove, or move, so per-frame camera changes cost a single walk over a sorted event table. See the [comment clustering example](/examples/collaboration/comment-clustering).

## Syncing comments

Comment records don't ship in the default schema, so both ends of the connection have to register them, and they have to match. A client with the types talking to a server without them will fail schema validation.

On the client, pass `records` to the sync hook:

```tsx
const store = useSync({
	uri: `wss://your-server.com/sync/${roomId}`,
	assets: myAssetStore,
	records: commentSchemaRecords,
})
```

On the server, pass the same map to [`createTLSchema`](/reference/tlschema/createTLSchema):

```ts
import { TLSocketRoom } from '@tldraw/sync-core'
import { commentSchemaRecords, createTLSchema } from '@tldraw/tlschema'

const schema = createTLSchema({ records: commentSchemaRecords })

const room = new TLSocketRoom({
	schema,
	// Serve comments through the object-store lane rather than the document
	objectTypes: ['comment', 'comment-thread', 'comment-reaction'],
})
```

`objectTypes` moves those record types onto a separate lane. Lane records are stored apart from the document and left out of document snapshots. More usefully, they're gated by their own per-session permission rather than by `isReadonly`, so a session can be allowed to comment without being allowed to edit:

```ts
room.handleSocketConnect({
	sessionId,
	socket,
	isReadonly: true, // can't touch the document
	objectAccess: 'write', // but can still comment
})
```

`objectAccess` is `'read'` or `'write'` and defaults to `'write'`. To persist the lane separately, read it with [`TLSocketRoom.getCurrentObjectsSnapshot`](/reference/sync-core/TLSocketRoom#getCurrentObjectsSnapshot). To mirror comments into your own database as they commit, use the room's `onCommittedChanges` callback:

```ts
const room = new TLSocketRoom({
	schema,
	objectTypes: ['comment', 'comment-thread', 'comment-reaction'],
	onCommittedChanges({ diff }) {
		// Project comment records into Postgres for notifications and search
		projectComments(diff)
	},
})
```

`onCommittedChanges` only fires for client pushes. Server-initiated writes don't trigger it, including `updateStore`, `loadSnapshot`, and writing to storage directly, so anything mirroring room state has to handle those paths itself.

This is also where per-record permissions belong. The lane's write access is all or nothing, so rules like "only the author may edit a comment" or "only the thread's creator may delete it" are enforced as your server validates each incoming record against the session's identity. `createCommentAuthorizers` is that validation, ready-made — pass it to the room's `authorizeRecord`:

```ts
import { createCommentAuthorizers } from '@tldraw/sync-collaboration'

const room = new TLSocketRoom({
	schema,
	objectTypes: ['comment', 'comment-thread', 'comment-reaction'],
	authorizeRecord: {
		...createCommentAuthorizers<SessionMeta>({
			getUserId: (session) => session.meta.userId,
			// Moderators may take anything down. Editing stays the author's, whoever you are.
			canModifyComment: (ctx) =>
				(ctx.action !== 'edit-comment' && isModerator(ctx.session.meta)) ||
				ctx.userId === ctx.ownerId,
		}),
	},
})
```

It stamps authorship from the session so nothing can be posted or resolved in someone else's name, keeps `isDeleted` write-once, and, through `canModifyComment`, decides who may edit a comment, delete a comment, or delete a thread. Left unset, `canModifyComment` defaults to the record's owner, matching the client. It's asked after the structural rules, so widening it grants those three writes and nothing else: attribution stays immutable, a soft delete stays write-once, and clients still can't hard-delete a record.

This is the same question the client's [`canModifyComment`](#who-can-edit-and-delete) answers, and the server's answer is the one that counts: the client's only decides which affordances the UI offers. Widen the two together. A moderator offered a delete the server then rejects sees the comment disappear and come back, with nothing to explain it.

`createCommentAuthorizers` also takes a `canComment` callback, checked before every comment write. It defaults to `({ isReadonly }) => !isReadonly`, so a read-only session can't post even with `objectAccess: 'write'`. To let read-only viewers comment, as in the `handleSocketConnect` example above, pass `canComment: () => true` (or a rule based on the session's `meta`).

## Building your own comments UI

`CanvasComments` is one way to assemble the parts, and every part it uses is exported. You can rebuild it, or build something quite different, from the same pieces.

| Export                                   | Description                                                 |
| ---------------------------------------- | ----------------------------------------------------------- |
| `CommentTool`, `commentToolOverrides`    | Placement: the tool state machine and its toolbar entry.    |
| `CommentPin`, `CountBadge`               | The pin marker and the clustered-count badge.               |
| `CommentThread`, `CommentCard`, `Byline` | A thread and its comments.                                  |
| `CommentComposer`, `SendButton`          | The composer and its send control.                          |
| `CommentsList`, `CommentListItem`        | A list of threads and one row of it.                        |
| `EmptyState`, `sortSidebarRows`          | The list's empty state, and the sidebar's ordering.         |
| `Avatar`, `Mention`, `MentionList`       | Author avatars and the mention picker.                      |
| `Reaction`, `Reactions`                  | A reaction pill and a comment's row of them.                |
| `anchorPagePoint`, `shapeAnchorAt`       | Anchor math: page position from an anchor, and the reverse. |
| `editComment`, `deleteComment`           | The write verbs. See [Writing comments](#writing-comments). |
| `registerCommentAnchorLifecycle`         | Keeps shape-anchored threads alive across shape deletion.   |

The presentational components take plain props and know nothing about the editor. The canvas layer, the tool, and the hooks build on them. `CanvasComments` registers the anchor lifecycle for you, so call `registerCommentAnchorLifecycle` yourself only if you're replacing the layer wholesale.

## All options

Every option below is set with `CommentTool.configure()`. Anything you leave unset falls back to `defaultCommentingOptions`.

### History

| Option        | Default     | Description                                                             |
| ------------- | ----------- | ----------------------------------------------------------------------- |
| `history`     | `'ignore'`  | How comment writes interact with the undo stack.                        |
| `dragHistory` | `undefined` | History mode for pin drags specifically. Unset, drags follow `history`. |

### Anchoring

| Option                 | Default        | Description                                               |
| ---------------------- | -------------- | --------------------------------------------------------- |
| `shouldBePrecise`      | `() => true`   | Whether a shape placement anchors precisely.              |
| `impreciseShapeAnchor` | `{x: 1, y: 0}` | Where imprecise shape pins sit within the shape's bounds. |

### Permissions

| Option             | Default     | Description                                                                         |
| ------------------ | ----------- | ----------------------------------------------------------------------------------- |
| `canComment`       | `undefined` | Whether the viewer may participate. Unset, allowed whenever `currentUserId` is set. |
| `canModifyComment` | `undefined` | Whether the viewer may edit or delete a record. Unset, each is its owner's to make. |

### Reactions

| Option                   | Default       | Description                                                  |
| ------------------------ | ------------- | ------------------------------------------------------------ |
| `allowMultipleReactions` | `true`        | Whether a user can hold more than one reaction on a comment. |
| `isAllowedReaction`      | emoji palette | Which reaction tokens may be written.                        |

### Regions

| Option          | Default | Description                                                |
| --------------- | ------- | ---------------------------------------------------------- |
| `enableRegions` | `false` | Whether dragging the comment tool creates a region anchor. |

### Clustering

| Option             | Default | Description                                                 |
| ------------------ | ------- | ----------------------------------------------------------- |
| `enableClustering` | `true`  | Fold nearby pins into count badges as the camera zooms out. |

### Components

| Option       | Default | Description                                                       |
| ------------ | ------- | ----------------------------------------------------------------- |
| `components` | `{}`    | Component overrides. See [Custom components](#custom-components). |

## Related articles

- [Commenting](/docs/commenting) — A shorter introduction to the feature
- [Collaboration](/sdk-features/collaboration) — Presence, sync hooks, and custom sync
- [tldraw sync](/docs/sync) — Running a sync server
- [Rich text](/sdk-features/rich-text) — The `TLRichText` format comment bodies use
- [License key](/sdk-features/license-key) — Enabling licensed features in production

## Related examples

- [Commenting](/examples/collaboration/commenting) — The full flow: tool, pins, threads, mentions
- [Commenting sidebar](/examples/collaboration/commenting-sidebar) — A thread list panel beside the canvas
- [Comment clustering](/examples/collaboration/comment-clustering) — Merging pins into count badges as you zoom out
- [Comment anchors](/examples/collaboration/comment-anchors) — The ways a comment can attach to the canvas
- [Shape comment precision](/examples/collaboration/comment-shape-precision) — Precise, shape-level, and Alt-gated anchoring
- [Comments and undo](/examples/collaboration/comment-history) — How comment writes interact with the undo stack
- [Region comments](/examples/collaboration/comment-regions) — Commenting on an area, and tuning the interaction

--------

# Coordinates

The editor uses three coordinate systems: screen space, viewport space, and page space. When you move the mouse over the canvas, the browser gives you screen coordinates. To create a shape at that location, you need to convert those coordinates to page space.

The editor provides methods to convert between these coordinate systems. You'll use these when building custom tools, positioning DOM overlays, or responding to pointer events. The [Camera](/sdk-features/camera) article explains the camera values these conversions depend on.

| Method                     | Description                                                         |
| -------------------------- | ------------------------------------------------------------------- |
| [`Editor.screenToPage`](/reference/editor/Editor#screenToPage)   | Convert a screen point to page space.                               |
| [`Editor.pageToScreen`](/reference/editor/Editor#pageToScreen)   | Convert a page point to screen space.                               |
| [`Editor.pageToViewport`](/reference/editor/Editor#pageToViewport) | Convert a page point to viewport space (relative to the container). |

## The three coordinate systems

### Screen space

Screen space uses pixel coordinates from the browser window's top-left corner. These are the values you get from `MouseEvent.clientX` and `MouseEvent.clientY`. Screen coordinates include any space outside the editor container, like browser chrome or other page content.

### Viewport space

Viewport space uses pixel coordinates from the editor container's top-left corner. This accounts for where the editor sits on the page. If the editor is embedded in a scrollable element or positioned away from the browser's origin, viewport coordinates differ from screen coordinates by that offset.

The editor tracks the container's position in [`Editor.getViewportScreenBounds`](/reference/editor/Editor#getViewportScreenBounds).

### Page space

Page space is the infinite canvas itself. A shape at `x: 100, y: 200` stays at those coordinates regardless of how the user pans or zooms. Top-level shapes store their position in page space; children of frames and groups store it relative to their parent. See [Parenting](/sdk-features/parenting) for the helpers that convert between shape space and page space.

The camera determines which part of page space is visible. When you zoom in, the same page-space region takes up more screen pixels. When you pan, different page-space coordinates come into view.

## Coordinate transformations

### Screen to page space

Use [`Editor.screenToPage`](/reference/editor/Editor#screenToPage) to convert screen coordinates to page coordinates. This is the most common transformation. It accounts for the editor container's position, the camera position, and the zoom level:

```typescript
// Convert mouse event coordinates to page space
const pagePoint = editor.screenToPage({ x: event.clientX, y: event.clientY })

// Create a shape at the clicked location
editor.createShape({
	type: 'geo',
	x: pagePoint.x,
	y: pagePoint.y,
	props: { w: 100, h: 100, geo: 'rectangle' },
})
```

### Page to screen space

Use [`Editor.pageToScreen`](/reference/editor/Editor#pageToScreen) to convert page coordinates to screen coordinates, for example to position a DOM element that lives outside the editor container:

```typescript
// Convert shape position to screen coordinates
const shape = editor.getShape(shapeId)
if (!shape) return
const screenPoint = editor.pageToScreen({ x: shape.x, y: shape.y })

// Position a DOM element at the shape's screen location
element.style.left = `${screenPoint.x}px`
element.style.top = `${screenPoint.y}px`
```

### Page to viewport space

Use [`Editor.pageToViewport`](/reference/editor/Editor#pageToViewport) to convert page coordinates to viewport coordinates. This is `pageToScreen()` without the container offset, so use it for canvas rendering or for positioning elements inside the editor container:

```typescript
// Get viewport coordinates for a page point
const viewportPoint = editor.pageToViewport({ x: 500, y: 300 })

// Check if a point is visible in the viewport
const viewportBounds = editor.getViewportScreenBounds()
const isVisible =
	viewportPoint.x >= 0 &&
	viewportPoint.x <= viewportBounds.w &&
	viewportPoint.y >= 0 &&
	viewportPoint.y <= viewportBounds.h
```

## Viewport bounds

Use [`Editor.getViewportScreenBounds`](/reference/editor/Editor#getViewportScreenBounds) to get the editor container's position and size in screen space:

```typescript
const screenBounds = editor.getViewportScreenBounds()
// screenBounds.x, screenBounds.y - container position in screen space
// screenBounds.w, screenBounds.h - container dimensions in pixels
```

Use [`Editor.getViewportPageBounds`](/reference/editor/Editor#getViewportPageBounds) to get the visible area in page space:

```typescript
const pageBounds = editor.getViewportPageBounds()
// pageBounds.x, pageBounds.y - top-left corner of visible area in page space
// pageBounds.w, pageBounds.h - visible area dimensions in page units
```

Both are reactive, so you can read them inside `track` components or `useValue` and re-render when the user pans or zooms. At higher zoom levels, the visible page-space area is smaller.

## Using the inputs manager

The editor's inputs manager tracks the current pointer position, so you can read it from anywhere in your code:

```typescript
// Get the current pointer position
const screenPoint = editor.inputs.getCurrentScreenPoint()
const pagePoint = editor.inputs.getCurrentPagePoint()

// Get the position where the current drag started
const originScreenPoint = editor.inputs.getOriginScreenPoint()
const originPagePoint = editor.inputs.getOriginPagePoint()
```

Despite the name, the inputs manager's "screen point" is relative to the editor container, which this article calls viewport space. Don't pass it to `screenToPage()` and don't subtract `getViewportScreenBounds()` from it.

Pointer event info is different: its `point` property holds `clientX`/`clientY`, so it is in screen space and converts with `screenToPage()`:

```typescript
editor.on('event', (event) => {
	if (event.type === 'pointer' && event.name === 'pointer_down') {
		const pagePoint = editor.screenToPage(event.point)
		// Use pagePoint for shape manipulation
	}
})
```

## Related examples

- [Reactive inputs](/examples/editor-api/reactive-inputs) - Display page and screen coordinates reactively as the pointer moves.
- [Selection UI](/examples/ui/selection-ui) - Use selection bounds in screen space to position custom UI around shapes.

--------

# Culling

The culling system optimizes rendering performance by hiding shapes that are outside the viewport.

Culled shapes stay in the DOM with `display: none`, so they cost nothing to render, and they stay in the store, so they can still be selected, hit-tested, and exported. The culling set is an incremental derivation that updates as the camera moves or shapes change. See [Performance](/sdk-features/performance) for how culling fits with the other rendering optimizations.

## Using the culling APIs

The editor exposes two sets of shape IDs. [`Editor.getNotVisibleShapes`](/reference/editor/Editor#getNotVisibleShapes) returns the shapes whose page bounds don't intersect the viewport and whose shape util allows culling. [`Editor.getCulledShapes`](/reference/editor/Editor#getCulledShapes) removes the selected shapes and the shape being edited from that set, so users can always see what they're working with. Both are reactive, and `getCulledShapes()` returns the same `Set` instance while its contents are unchanged, so it's cheap to read in `track` components or `useValue`.

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

export default function CullingExample() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					// Get the IDs of shapes outside the viewport (before selection filtering)
					const notVisible = editor.getNotVisibleShapes()

					// Get the IDs of shapes that should not render (excludes selected/editing shapes)
					const culled = editor.getCulledShapes()

					console.log('Not visible:', notVisible.size)
					console.log('Actually culled:', culled.size)
				}}
			/>
		</div>
	)
}
```

## How it works

The first layer queries the editor's spatial index for shapes whose page bounds intersect the viewport and marks everything else as not visible, skipping shapes whose util's `canCull` returns `false`. The second layer removes the selected shapes and the editing shape, so a user can scroll a shape partly or fully out of view while still seeing and interacting with it.

## Shape-level control

A shape type opts out of culling by overriding [`ShapeUtil.canCull`](/reference/editor/ShapeUtil#canCull). The default returns `true`. When your override returns `false`, the shape never enters the not-visible set, so it never gets `display: none`:

```tsx
import { ShapeUtil, TLBaseShape, RecordProps, T, Rectangle2d } from 'tldraw'

type MyShape = TLBaseShape<'my-shape', { w: number; h: number; hasGlow: boolean }>

class MyShapeUtil extends ShapeUtil<MyShape> {
	static override type = 'my-shape' as const
	static override props: RecordProps<MyShape> = {
		w: T.number,
		h: T.number,
		hasGlow: T.boolean,
	}

	getDefaultProps(): MyShape['props'] {
		return { w: 100, h: 100, hasGlow: false }
	}

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

	override canCull(shape: MyShape): boolean {
		// Shapes with glow effects shouldn't be culled because
		// the glow might be visible even when the shape bounds aren't
		if (shape.props.hasGlow) {
			return false
		}
		return true
	}

	component(shape: MyShape) {
		return <div style={{ width: shape.props.w, height: shape.props.h }} />
	}

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

Shapes whose util overrides `canCull` are subscribed to individually inside the culling derivation, so a `canCull` that reads many props re-runs the derivation more often. Shapes using the default fast path don't pay this cost. Disable culling only for shapes that need it: visual effects that extend past the bounds, shapes that measure their DOM, or animations that should keep running off-screen. See [Performance](/sdk-features/performance#disable-culling-only-when-necessary) for guidance.

## Related examples

- [Size from DOM](/examples/shapes/tools/size-from-dom) - A shape that disables culling because it measures its DOM element to determine size.

--------

# Cursor chat

Cursor chat lets users send short messages that appear as bubbles near their cursor. It's designed for quick, ephemeral communication during collaborative sessions: a fast "look here" or "nice work" that doesn't interrupt the canvas workflow.

Cursor chat only appears when collaboration UI is enabled, which means the store has to be collaborative. The simplest way to get one is [`useSyncDemo`](/reference/sync/useSyncDemo):

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

export default function App() {
	const store = useSyncDemo({ roomId: 'my-cursor-chat-room' })

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				store={store}
				onMount={(editor) => {
					// Show a message bubble at the cursor
					editor.updateInstanceState({ chatMessage: 'Hello from the canvas!' })
				}}
			/>
		</div>
	)
}
```

On desktop, users press `/` to open the chat input, type their message (up to 64 characters), and press Enter to send. The message follows their cursor. Once the input closes, the message stays visible for two seconds and then clears.

## Chat state

Chat state lives in instance state with two properties:

| Property      | Type      | Description                             |
| ------------- | --------- | --------------------------------------- |
| `isChatting`  | `boolean` | Whether the user is actively typing     |
| `chatMessage` | `string`  | The current message (max 64 characters) |

Read the current state with [`Editor.getInstanceState`](/reference/editor/Editor#getInstanceState):

```tsx
const { isChatting, chatMessage } = editor.getInstanceState()
```

Update it with [`Editor.updateInstanceState`](/reference/editor/Editor#updateInstanceState):

```tsx
// Start chatting
editor.updateInstanceState({ isChatting: true })

// Update the message
editor.updateInstanceState({ chatMessage: 'Looking at this shape' })

// Stop chatting and clear the message
editor.updateInstanceState({ isChatting: false, chatMessage: '' })
```

Both properties are ephemeral—they don't persist to storage or survive page reloads.

## How it works

When a user starts chatting:

1. The `CursorChatBubble` component renders an input field at the cursor position
2. The input tracks the cursor via `pointermove` events
3. As the user types, `chatMessage` updates in instance state
4. When they press Enter with text in the input, the input clears and the message becomes its placeholder; the input stays open for another message
5. When they press Escape, press Enter with an empty input, or the input loses focus, `isChatting` becomes `false`
6. The message stays visible for 2 seconds, then clears automatically

While the input is open, chat times out after 5 seconds of inactivity.

## Keyboard shortcuts

The default keyboard action for cursor chat is `/`. You can find it under the action ID `open-cursor-chat`. The action is only registered when collaboration UI is enabled, and the default context menu shows it as [`CursorChatItem`](/reference/tldraw/CursorChatItem):

```tsx
import { Tldraw, useActions } from 'tldraw'

function ChatButton() {
	const actions = useActions()

	return (
		<button onClick={() => actions['open-cursor-chat'].onSelect('menu')}>Open cursor chat</button>
	)
}
```

Inside the chat input:

| Key      | Action                                                                 |
| -------- | ---------------------------------------------------------------------- |
| `Enter`  | Send the message (if content exists) or stop chatting (if input empty) |
| `Escape` | Stop chatting                                                          |

## Presence synchronization

In multiplayer sessions, chat messages synchronize automatically through presence records. The `chatMessage` field in [`TLInstancePresence`](/reference/tlschema/TLInstancePresence) contains the message other users see:

```tsx
import { createUserId, InstancePresenceRecordType } from 'tldraw'

// Inside onMount: create a remote user's presence with a chat message
const peerPresence = InstancePresenceRecordType.create({
	id: InstancePresenceRecordType.createId(editor.store.id),
	currentPageId: editor.getCurrentPageId(),
	userId: createUserId('peer-1'),
	userName: 'Alice',
	cursor: { x: 100, y: 200, type: 'default', rotation: 0 },
	chatMessage: 'Check out this arrow!',
})

editor.store.mergeRemoteChanges(() => {
	editor.store.put([peerPresence])
})
```

The presence derivation includes the local user's `chatMessage` from instance state, so changes broadcast to other users without any extra work.

## Customizing the chat bubble

You can replace the default chat bubble by providing a custom `CursorChatBubble` component through [`TLUiComponents`](/reference/tldraw/TLUiComponents). The slot is only rendered when collaboration UI is enabled, so this example needs a collaborative store too:

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { Tldraw, TLUiComponents, useEditor, track } from 'tldraw'
import 'tldraw/tldraw.css'

const CustomCursorChat = track(function CustomCursorChat() {
	const editor = useEditor()
	const { isChatting, chatMessage } = editor.getInstanceState()

	if (!isChatting && !chatMessage) return null

	return (
		<div
			style={{
				position: 'fixed',
				bottom: 20,
				left: '50%',
				transform: 'translateX(-50%)',
				padding: '8px 16px',
				background: editor.user.getColor(),
				borderRadius: 8,
				color: 'white',
			}}
		>
			{isChatting ? 'Typing...' : chatMessage}
		</div>
	)
})

const components: TLUiComponents = {
	CursorChatBubble: CustomCursorChat,
}

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

Remote users' chat messages render as part of the collaborator cursor, in the DOM cursor layer. To customize how they appear, replace the `CollaboratorCursor` component. See [Cursors](/sdk-features/cursors#rendering-collaborator-cursors) for details.

## Availability

Cursor chat requires:

- Collaboration enabled (`editor.store.props.collaboration !== undefined`)
- A non-touch device (disabled on mobile/tablet)

Setting `isChatting` isn't gated, but the bubble won't render without both, so check availability before triggering chat programmatically:

```tsx
const hasCollaboration = editor.store.props.collaboration !== undefined
const isTouchDevice = editor.getInstanceState().isCoarsePointer

if (hasCollaboration && !isTouchDevice) {
	editor.updateInstanceState({ isChatting: true })
}
```

## Related articles

- [Cursors](/sdk-features/cursors) — Cursor types, colors, and collaborator cursor customization
- [Collaboration](/sdk-features/collaboration) — Presence synchronization and multiplayer setup
- [User preferences](/sdk-features/user-preferences) — User colors and identity

## Related examples

- [User presence](/examples/collaboration/user-presence) — Display collaborator cursors and chat messages

--------

# Cursors

The cursor system controls what cursor users see when interacting with the canvas. The current cursor is stored in instance state and changes automatically as users hover over different elements or use different tools. You can also set the cursor manually for custom tools.

## Cursor state

The cursor state is a [`TLCursor`](/reference/tlschema/TLCursor): a [`TLCursorType`](/reference/tlschema/TLCursorType) and a rotation angle. Access it through [`Editor.getInstanceState`](/reference/editor/Editor#getInstanceState):

```typescript
const { type, rotation } = editor.getInstanceState().cursor
```

The `type` determines the visual appearance—like `'default'`, `'grab'`, or `'nwse-resize'`. The `rotation` is an angle in radians that rotates the cursor icon. Rotation is mainly used for resize and rotate cursors so they align with the shape being manipulated.

## Cursor types

tldraw supports these cursor types:

| Type          | Description                                    |
| ------------- | ---------------------------------------------- |
| `default`     | Standard pointer arrow                         |
| `pointer`     | Hand indicating clickable element              |
| `cross`       | Crosshair for precise positioning              |
| `comment`     | Speech bubble for placing comments             |
| `grab`        | Open hand for draggable content                |
| `grabbing`    | Closed hand while dragging                     |
| `text`        | I-beam for text editing                        |
| `move`        | Four-way arrow for moving elements             |
| `zoom-in`     | Magnifying glass with plus                     |
| `zoom-out`    | Magnifying glass with minus                    |
| `ew-resize`   | Horizontal resize (east-west)                  |
| `ns-resize`   | Vertical resize (north-south)                  |
| `nesw-resize` | Diagonal resize (northeast-southwest)          |
| `nwse-resize` | Diagonal resize (northwest-southeast)          |
| `nesw-rotate` | Rotation handle (northeast-southwest position) |
| `nwse-rotate` | Rotation handle (northwest-southeast position) |
| `senw-rotate` | Rotation handle (southeast-northwest position) |
| `swne-rotate` | Rotation handle (southwest-northeast position) |
| `none`        | Hidden cursor                                  |

Static cursors like `default`, `pointer`, and `grab` are prerendered SVG cursors defined as CSS custom properties in tldraw's stylesheet (`--tl-cursor-default`, `--tl-cursor-grab`, and so on). Dynamic cursors like the resize and rotate types are generated at runtime as SVGs with the current rotation applied. The canvas reads the result from the `--tl-cursor` variable.

> `TLCursorType` also includes `resize-edge`, `resize-corner`, and `rotate` for schema compatibility. The default cursor rendering doesn't support them, so don't pass them to `setCursor`.

## Setting the cursor

Use [`Editor.setCursor`](/reference/editor/Editor#setCursor) to change the cursor:

```typescript
editor.setCursor({ type: 'cross', rotation: 0 })
```

You can update just the type or just the rotation—the other property keeps its current value:

```typescript
// Change only the type
editor.setCursor({ type: 'grab' })

// Change only the rotation
editor.setCursor({ rotation: Math.PI / 4 })
```

### Cursor rotation

Rotation is specified in radians. When users resize or rotate shapes that are themselves rotated, the cursor rotates to match:

```typescript
// Get the selection's rotation and apply it to a resize cursor
const selectionRotation = editor.getSelectionRotation()
editor.setCursor({
	type: 'nwse-resize',
	rotation: selectionRotation,
})
```

This keeps the cursor aligned with the shape's edges rather than the screen axes. The default tools handle cursor rotation automatically. You only need to set it manually for custom tools.

## Cursors in custom tools

Custom tools typically set the cursor when entering a state and reset it when exiting:

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

export class MyCustomTool extends StateNode {
	static override id = 'my-tool'

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

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

For tools with child states, each state can set its own cursor. A drawing state might use `'cross'`, while a dragging state uses `'grabbing'`.

## Cursor colors

Dynamic cursors (resize and rotate types) receive the active [theme](/sdk-features/themes)'s `cursor` color for the current color mode: black in the default light theme, white in the default dark theme. The built-in SVGs use fixed black and white fills for contrast, so this color only shows in custom cursor SVGs.

## Collaborator cursors

In multiplayer sessions, each user's cursor appears on other users' canvases. These remote cursors use the user's presence color—a randomly assigned color from the user color palette.

### User color palette

When a user first loads tldraw, they're assigned a random color from the built-in `USER_COLORS` palette:

```typescript
const USER_COLORS = [
	'#FF802B',
	'#EC5E41',
	'#F2555A',
	'#F04F88',
	'#E34BA9',
	'#BD54C6',
	'#9D5BD2',
	'#7B66DC',
	'#02B1CC',
	'#11B3A3',
	'#39B178',
	'#55B467',
]
```

You can read or change a user's color through user preferences:

```typescript
// Get the user's color
const color = editor.user.getColor()

// Set a specific color
editor.user.updateUserPreferences({ color: '#FF802B' })
```

### Rendering collaborator cursors

Remote cursors render as DOM elements in a dedicated layer stacked above the canvas and below the UI panels. Each visible collaborator gets a cursor showing:

- The cursor arrow in the user's color
- The user's name as a label next to the cursor
- Any active chat message in a bubble

A collaborator whose cursor is outside your viewport shows as a small hint arrow clamped to the viewport edge, pointing toward them. [`CollaboratorHintOverlayUtil`](/reference/tldraw/CollaboratorHintOverlayUtil) draws the hints on the overlay canvas rather than as DOM elements.

To customize the cursor, pass your own component via the `components` prop's `CollaboratorCursor` slot (see [`DefaultCursor`](/reference/editor/DefaultCursor) and [`TLCursorProps`](/reference/editor/TLCursorProps)):

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

function CustomCollaboratorCursor({ point, color, name, zoom }: TLCursorProps) {
	if (!point) return null
	return (
		<div
			style={{
				position: 'absolute',
				// The layer is scaled by the camera, so counter-scale by 1 / zoom to keep the
				// cursor a constant on-screen size (the default components do the same).
				transform: `translate(${point.x}px, ${point.y}px) scale(${1 / zoom})`,
				transformOrigin: 'top left',
				pointerEvents: 'none',
			}}
		>
			{/* A dot instead of the default arrow */}
			<div style={{ width: 16, height: 16, borderRadius: '50%', backgroundColor: color }} />
			{name && <div style={{ color }}>{name}</div>}
		</div>
	)
}

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

### Cursor position in presence

Collaborator cursor positions are stored in presence records ([`TLInstancePresence`](/reference/tlschema/TLInstancePresence)). The cursor field includes position, type, and rotation:

```typescript
{
  cursor: {
    x: number
    y: number
    type: TLCursorType
    rotation: number
  } | null
}
```

The editor automatically broadcasts cursor position updates to other users in the same room. `cursor` is `null` only when presence hasn't been populated yet or a custom presence derivation omits it. The editor hides a collaborator's cursor when it's outside your viewport or the user has been inactive.

## Related articles

- [Cursor chat](/sdk-features/cursor-chat) - Send ephemeral chat messages at the cursor position
- [Tools](/sdk-features/tools) - Learn how tools handle input and set cursors
- [Collaboration](/sdk-features/collaboration) - User presence and multiplayer features
- [User preferences](/sdk-features/user-preferences) - Manage user colors and other preferences
- [Overlay utils](/sdk-features/overlay-utils) - Canvas overlays, including the collaborator cursor hint overlay

## Related examples

- [Custom tool](/examples/shapes/tools/custom-tool) - Build a custom tool with cursor handling
- [User presence](/examples/collaboration/user-presence) - Display collaborator cursors and presence

--------

# Deep links

Deep links serialize editor state into URL-safe strings. They let users share links that open the editor at specific locations: individual shapes, viewport positions, or entire pages.

The simplest way to enable deep links is with the `deepLinks` option:

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw persistenceKey="example" options={{ deepLinks: true }} />
		</div>
	)
}
```

With `deepLinks` enabled, the editor reads the `d` query parameter on mount and navigates to it, then keeps the URL up to date as users navigate. Anyone opening the URL sees the same page and viewport position.

For more control, use the editor methods directly. [`Editor.createDeepLink`](/reference/editor/Editor#createDeepLink) generates URLs with encoded state, [`Editor.navigateToDeepLink`](/reference/editor/Editor#navigateToDeepLink) moves the editor to a specified location, and [`Editor.registerDeepLinkListener`](/reference/editor/Editor#registerDeepLinkListener) updates URLs automatically as users navigate.

## Deep link types

A [`TLDeepLink`](/reference/editor/TLDeepLink) is one of three types:

| Type       | Purpose                                             | Encoded prefix |
| ---------- | --------------------------------------------------- | -------------- |
| `shapes`   | Links to specific shapes, zooming to fit them       | `s`            |
| `viewport` | Links to a bounding box view, with an optional page | `v`            |
| `page`     | Links to a specific page, zoomed to fit its content | `p`            |

## How it works

Deep links are encoded as compact strings with a single-character prefix identifying the type:

- Shape links (`s`) encode shape IDs separated by dots: `s<id1>.<id2>.<id3>`
- Viewport links (`v`) encode rounded bounding box coordinates: `v<x>.<y>.<w>.<h>` with optional page ID
- Page links (`p`) encode a page ID: `p<pageId>`

All IDs are URL-encoded to handle special characters. The default query parameter is `d`, but you can customize this with the `param` option. When navigating to a shapes deep link, the editor switches to the page containing the most shapes and zooms to fit them. Viewport links set the camera to the exact specified bounds. If the parameter is missing or invalid, or the shapes or page no longer exist, the editor zooms to fit the page content instead. Use [`createDeepLinkString`](/reference/editor/createDeepLinkString) and [`parseDeepLinkString`](/reference/editor/parseDeepLinkString) to encode and decode these strings without an editor.

## API methods

### createDeepLink

Creates a URL with a deep link query parameter encoding the current viewport and page:

```ts
// Create a link to the current viewport
const url = editor.createDeepLink()
navigator.clipboard.writeText(url.toString())
```

Specify a target to link to specific shapes:

```ts
// Link to currently selected shapes
const url = editor.createDeepLink({
	to: { type: 'shapes', shapeIds: editor.getSelectedShapeIds() },
})
```

### navigateToDeepLink

Navigates the editor to the location specified by a deep link URL or object:

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

// Navigate using the current URL's query parameter
editor.navigateToDeepLink()

// Navigate to a specific URL
editor.navigateToDeepLink({ url: 'https://example.com?d=v100.100.200.200' })

// Navigate directly to shapes
editor.navigateToDeepLink({
	type: 'shapes',
	shapeIds: ['shape:abc' as TLShapeId, 'shape:xyz' as TLShapeId],
})
```

### registerDeepLinkListener

Sets up automatic URL updates as the viewport changes. The listener debounces updates (500ms by default) to avoid excessive history entries:

```ts
// Use default behavior (replaces the current URL without adding history entries)
const unlisten = editor.registerDeepLinkListener()

// Custom change handler with longer debounce
const unlisten = editor.registerDeepLinkListener({
	onChange(url) {
		window.history.replaceState({}, document.title, url.toString())
	},
	debounceMs: 1000,
})

// Clean up when done
unlisten()
```

The `deepLinks` option on the Tldraw component calls this for you. Pass a [`TLDeepLinkOptions`](/reference/editor/TLDeepLinkOptions) object instead of `true` to customize it; both the option and the method accept the same fields:

| Option       | Description                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------- |
| `param`      | The query parameter name. Defaults to `'d'`                                                  |
| `debounceMs` | How long to wait before updating the URL. Defaults to `500`                                  |
| `getTarget`  | Returns the [`TLDeepLink`](/reference/editor/TLDeepLink) to encode. Defaults to the current page and viewport             |
| `getUrl`     | Returns the URL to add the parameter to. If you supply this, you must also supply `onChange` |
| `onChange`   | Called with the updated URL. Defaults to `window.history.replaceState`                       |

```tsx
<Tldraw
	options={{
		deepLinks: {
			param: 'view',
			getUrl: () => window.location.href,
			onChange: (url) => router.replace(url.toString()),
		},
	}}
/>
```

## Related examples

- [Deep links](/examples/configuration/deep-links) - Using the `deepLinks` option and creating, parsing, and handling deep links manually with the editor methods.

--------

# Default shapes

The tldraw package includes thirteen shape types that cover common diagramming and whiteboarding needs. Each shape type has a corresponding [`ShapeUtil`](/reference/editor/ShapeUtil) that defines its rendering, geometry, and interaction behavior. You can use these shapes as-is, configure their behavior through options, or use them as reference when building custom shapes.

## Shape overview

The default shapes loosely fall into five categories based on their primary function:

| Category   | Shape types                           | Description                                                           |
| ---------- | ------------------------------------- | --------------------------------------------------------------------- |
| Text       | `text`, `note`                        | Text labels and sticky notes                                          |
| Drawing    | `geo`, `draw`, `line`, `highlight`    | Freehand strokes, multi-point lines, geometric shapes, and highlights |
| Media      | `image`, `video`, `bookmark`, `embed` | External content and media files                                      |
| Structural | `frame`, `group`                      | Organization and containment                                          |
| Connectors | `arrow`                               | Lines that connect shapes together                                    |

## Basic shapes

### Geo

The geo shape renders geometric primitives with optional text labels. It supports 20 different geometric forms—rectangles, ellipses, triangles, stars, polygons, directional arrows, and special shapes like clouds and hearts. Geo shapes can display rich text labels with configurable alignment, which makes them the usual building block for flowcharts and diagrams.

For complete documentation on geometric forms, label positioning, tool interactions, and configuration, see [Geo shape](/sdk-features/geo-shape).

Quick reference:

| Property        | Type                            | Description                                 |
| --------------- | ------------------------------- | ------------------------------------------- |
| `geo`           | `TLGeoShapeGeoStyle`            | The geometric form                          |
| `w`             | `number`                        | Width in pixels                             |
| `h`             | `number`                        | Height in pixels                            |
| `richText`      | `TLRichText`                    | Text label displayed inside the shape       |
| `color`         | `TLDefaultColorStyle`           | Stroke/outline color                        |
| `labelColor`    | `TLDefaultColorStyle`           | Text label color (separate from stroke)     |
| `fill`          | `TLDefaultFillStyle`            | Fill style                                  |
| `dash`          | `TLDefaultDashStyle`            | Stroke pattern                              |
| `size`          | `TLDefaultSizeStyle`            | Size preset affecting stroke width          |
| `font`          | `TLDefaultFontStyle`            | Font family for the label                   |
| `align`         | `TLDefaultHorizontalAlignStyle` | Horizontal text alignment                   |
| `verticalAlign` | `TLDefaultVerticalAlignStyle`   | Vertical text alignment                     |
| `growY`         | `number`                        | Additional vertical space for text overflow |
| `url`           | `string`                        | Optional hyperlink URL                      |
| `scale`         | `number`                        | Scale factor applied to the shape           |
| `flipX`         | `boolean`                       | Mirror the shape horizontally               |
| `flipY`         | `boolean`                       | Mirror the shape vertically                 |

### Text

The text shape displays formatted text content with automatic sizing. Text shapes resize to fit their content by default, or you can set them to a fixed width with text wrapping. The shape supports rich text formatting including bold, italic, and other inline styles.

For a complete guide to text shapes, including auto-size vs fixed-width modes, the text tool's interaction patterns, and configuration options, see [Text shape](/sdk-features/text-shape).

```tsx
editor.createShape({
	type: 'text',
	x: 100,
	y: 100,
	props: {
		richText: toRichText('Hello world'),
		color: 'black',
		size: 'm',
		font: 'draw',
		textAlign: 'start',
		autoSize: true,
		w: 200,
	},
})
```

Quick reference:

| Property    | Type                      | Description                                     |
| ----------- | ------------------------- | ----------------------------------------------- |
| `richText`  | `TLRichText`              | The text content with formatting                |
| `color`     | `TLDefaultColorStyle`     | Text color                                      |
| `size`      | `TLDefaultSizeStyle`      | Font size preset (`s`, `m`, `l`, `xl`)          |
| `font`      | `TLDefaultFontStyle`      | Font family (`draw`, `sans`, `serif`, `mono`)   |
| `textAlign` | `TLDefaultTextAlignStyle` | Horizontal alignment (`start`, `middle`, `end`) |
| `autoSize`  | `boolean`                 | When true, shape resizes to fit content         |
| `w`         | `number`                  | Width when autoSize is false                    |
| `scale`     | `number`                  | Scale factor applied to the shape               |

### Note

The note shape renders as a sticky note with a colored background and rich text content. Notes have special interaction behaviors: clone handles on the edges let you quickly create adjacent notes, and keyboard shortcuts navigate between them. Notes have a fixed base size but grow vertically to fit their content.

For a complete guide to note interactions, clone handles, keyboard navigation, and configuration, see [Note shape](/sdk-features/note-shape).

```tsx
editor.createShape({
	type: 'note',
	x: 100,
	y: 100,
	props: {
		color: 'yellow',
		labelColor: 'black',
		richText: toRichText('Remember this'),
		size: 'm',
		font: 'draw',
		align: 'middle',
		verticalAlign: 'middle',
	},
})
```

## Drawing shapes

### Draw

The draw shape captures freehand strokes and straight line segments. It supports pressure-sensitive input from pens and styluses, automatic shape closing, angle snapping when holding Shift, and hybrid freehand/straight-line drawing modes. Points are stored in a delta-encoded base64 format; strokes from devices without pressure are stored as 2D (`dim: 2`) and pen strokes keep the pressure value.

For complete documentation on the draw shape and draw tool, including drawing modes, pen support, angle snapping, and programmatic creation, see the [Draw shape](/sdk-features/draw-shape) article.

Quick reference:

| Property     | Type                   | Description                                                                           |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------- |
| `color`      | `TLDefaultColorStyle`  | Stroke color                                                                          |
| `fill`       | `TLDefaultFillStyle`   | Fill style (applies when `isClosed` is true)                                          |
| `dash`       | `TLDefaultDashStyle`   | Stroke pattern                                                                        |
| `size`       | `TLDefaultSizeStyle`   | Stroke width preset                                                                   |
| `segments`   | `TLDrawShapeSegment[]` | Array of segments with `type`, base64-encoded `path`, and optional `dim` (`2` or `3`) |
| `isComplete` | `boolean`              | Whether the user has finished drawing this stroke                                     |
| `isClosed`   | `boolean`              | Whether the path forms a closed shape                                                 |
| `isPen`      | `boolean`              | Whether drawn with a stylus (enables pressure-based width)                            |
| `scale`      | `number`               | Scale factor applied to the shape                                                     |
| `scaleX`     | `number`               | Horizontal scale factor for lazy resize                                               |
| `scaleY`     | `number`               | Vertical scale factor for lazy resize                                                 |

### Line

The line shape creates multi-point lines with draggable handles. Unlike draw shapes, line shapes have explicit control points that you can manipulate after creation. Each point has an ID and a fractional index for ordering. You can add, remove, or reposition points. Lines support both straight segments and smooth cubic spline interpolation.

```tsx
import { IndexKey } from 'tldraw'

editor.createShape({
	type: 'line',
	x: 100,
	y: 100,
	props: {
		color: 'black',
		dash: 'solid',
		size: 'm',
		spline: 'line',
		points: {
			a1: { id: 'a1', index: 'a1' as IndexKey, x: 0, y: 0 },
			a2: { id: 'a2', index: 'a2' as IndexKey, x: 100, y: 50 },
			a3: { id: 'a3', index: 'a3' as IndexKey, x: 200, y: 0 },
		},
		scale: 1,
	},
})
```

Properties:

| Property | Type                               | Description                                                   |
| -------- | ---------------------------------- | ------------------------------------------------------------- |
| `color`  | `TLDefaultColorStyle`              | Stroke color                                                  |
| `dash`   | `TLDefaultDashStyle`               | Stroke pattern                                                |
| `size`   | `TLDefaultSizeStyle`               | Stroke width preset                                           |
| `spline` | `TLLineShapeSplineStyle`           | Interpolation: `line` for straight, `cubic` for curves        |
| `points` | `Record<string, TLLineShapePoint>` | Dictionary of control points with IDs, indices, and positions |
| `scale`  | `number`                           | Scale factor applied to the shape                             |

Line shapes don't have configuration options.

### Highlight

The highlight shape works like draw but renders semi-transparently for marking up content. It draws two passes with configurable opacities to imitate a highlighter pen. Like draw shapes, highlights support pressure-sensitive input and automatic shape splitting for long strokes.

```tsx
import { b64Vecs } from 'tldraw'

editor.createShape({
	type: 'highlight',
	x: 100,
	y: 100,
	props: {
		color: 'yellow',
		size: 'l',
		segments: [
			{
				type: 'free',
				path: b64Vecs.encodePoints([
					{ x: 0, y: 0, z: 0.5 },
					{ x: 100, y: 10, z: 0.5 },
					{ x: 200, y: 0, z: 0.5 },
				]),
			},
		],
		isComplete: true,
		isPen: false,
		scale: 1,
	},
})
```

Properties:

| Property     | Type                   | Description                                                                               |
| ------------ | ---------------------- | ----------------------------------------------------------------------------------------- |
| `color`      | `TLDefaultColorStyle`  | Highlight color (yellow, green, blue, etc.)                                               |
| `size`       | `TLDefaultSizeStyle`   | Stroke width preset                                                                       |
| `segments`   | `TLDrawShapeSegment[]` | Array of segments with base64-encoded points (see [Draw shape](/sdk-features/draw-shape)) |
| `isComplete` | `boolean`              | Whether the user has finished this stroke                                                 |
| `isPen`      | `boolean`              | Whether drawn with a stylus                                                               |
| `scale`      | `number`               | Scale factor applied to the shape                                                         |
| `scaleX`     | `number`               | Horizontal scale factor for lazy resize                                                   |
| `scaleY`     | `number`               | Vertical scale factor for lazy resize                                                     |

Configuration options:

| Option              | Type     | Default | Description                                                               |
| ------------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `maxPointsPerShape` | `number` | `600`   | Maximum points before starting a new shape. Same behavior as draw shapes. |

The highlight's `underlayOpacity` (default `0.82`) and `overlayOpacity` (default `0.35`) are display values that can be overridden via `getCustomDisplayValues`:

```tsx
const ConfiguredHighlightUtil = HighlightShapeUtil.configure({
	maxPointsPerShape: 800,
	getCustomDisplayValues() {
		return { underlayOpacity: 0.7, overlayOpacity: 0.4 }
	},
})
```

## Media shapes

### Image

The image shape displays raster images with support for cropping and flipping. Images link to asset records that store the actual image data (either as base64 or URLs). The shape maintains aspect ratio during resize and supports circular cropping.

```tsx
editor.createShape({
	type: 'image',
	x: 100,
	y: 100,
	props: {
		w: 400,
		h: 300,
		assetId: 'asset:abc123' as TLAssetId,
		url: '',
		crop: null,
		flipX: false,
		flipY: false,
		playing: true,
		altText: 'Description for accessibility',
	},
})
```

Properties:

| Property  | Type                  | Description                                                                                           |
| --------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
| `w`       | `number`              | Display width in pixels                                                                               |
| `h`       | `number`              | Display height in pixels                                                                              |
| `assetId` | `TLAssetId \| null`   | Reference to asset record containing image data                                                       |
| `url`     | `string`              | Direct URL (used when no asset)                                                                       |
| `crop`    | `TLShapeCrop \| null` | Crop region with `topLeft`, `bottomRight` (0-1), and `isCircle`                                       |
| `flipX`   | `boolean`             | Mirror the image horizontally                                                                         |
| `flipY`   | `boolean`             | Mirror the image vertically                                                                           |
| `playing` | `boolean`             | Whether animated images (GIFs) should play (stored on the record; the default util always plays them) |
| `altText` | `string`              | Accessibility description                                                                             |

Image shapes don't have configuration options. Image handling behavior is controlled through the editor's asset management system.

### Video

The video shape displays video content with playback controls. Like images, videos link to asset records. Videos autoplay by default and respect the user's `prefers-reduced-motion` setting. The `time` and `playing` props are stored on the record, but the default util does not drive playback from them.

```tsx
editor.createShape({
	type: 'video',
	x: 100,
	y: 100,
	props: {
		w: 640,
		h: 480,
		assetId: 'asset:video123' as TLAssetId,
		url: '',
		time: 0,
		playing: false,
		autoplay: true,
		altText: 'Video description',
	},
})
```

Properties:

| Property   | Type                | Description                            |
| ---------- | ------------------- | -------------------------------------- |
| `w`        | `number`            | Display width in pixels                |
| `h`        | `number`            | Display height in pixels               |
| `assetId`  | `TLAssetId \| null` | Reference to asset record              |
| `url`      | `string`            | Direct URL (used when no asset)        |
| `time`     | `number`            | Current playback position in seconds   |
| `playing`  | `boolean`           | Whether the video is currently playing |
| `autoplay` | `boolean`           | Whether to start playing automatically |
| `altText`  | `string`            | Accessibility description              |

Configuration options:

| Option     | Type      | Default | Description                                     |
| ---------- | --------- | ------- | ----------------------------------------------- |
| `autoplay` | `boolean` | `true`  | Default autoplay behavior for new video shapes. |

```tsx
const ConfiguredVideoUtil = VideoShapeUtil.configure({
	autoplay: false,
})
```

### Bookmark

The bookmark shape displays a URL as a card with metadata including title, description, and preview image. The editor creates a bookmark when you paste a URL onto the canvas. It fetches metadata from the URL and stores it in an associated asset record. Bookmark shapes have fixed dimensions and can't be resized.

```tsx
editor.createShape({
	type: 'bookmark',
	x: 100,
	y: 100,
	props: {
		url: 'https://example.com',
		assetId: 'asset:bookmark123' as TLAssetId,
		w: 300,
		h: 320,
	},
})
```

Properties:

| Property  | Type                | Description                                             |
| --------- | ------------------- | ------------------------------------------------------- |
| `url`     | `string`            | The bookmarked URL                                      |
| `assetId` | `TLAssetId \| null` | Reference to asset containing title, description, image |
| `w`       | `number`            | Width (fixed, not user-resizable)                       |
| `h`       | `number`            | Height (fixed, not user-resizable)                      |

Bookmark shapes don't have configuration options. URL metadata fetching is handled by the editor's external content handlers.

### Embed

The embed shape displays interactive content from external services (YouTube, Figma, CodeSandbox, and more) within an iframe. When you paste a URL from a supported service, tldraw automatically converts it to an interactive embed with appropriate dimensions.

For complete documentation on supported services, URL transformation, iframe security, custom embed definitions, and interaction modes, see [Embed shape](/sdk-features/embed-shape).

```tsx
editor.createShape({
	type: 'embed',
	x: 100,
	y: 100,
	props: {
		url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
		w: 560,
		h: 315,
	},
})
```

Properties:

| Property | Type     | Description                                          |
| -------- | -------- | ---------------------------------------------------- |
| `url`    | `string` | The original URL (converted to embed URL internally) |
| `w`      | `number` | Width of the embed container                         |
| `h`      | `number` | Height of the embed container                        |

## Structural shapes

### Frame

The frame shape provides a visual container for organizing shapes. Shapes inside a frame are clipped to its bounds and move with the frame when it's repositioned. Frames display a header with the frame's name, and optionally colored borders and backgrounds. They're useful for creating sections, organizing content into logical groups, or defining artboard-like regions for export.

For a complete guide, see [Frame shape](/sdk-features/frame-shape).

```tsx
editor.createShape({
	type: 'frame',
	x: 100,
	y: 100,
	props: {
		w: 800,
		h: 600,
		name: 'Header Section',
		color: 'blue',
	},
})
```

Properties:

| Property | Type                  | Description                                           |
| -------- | --------------------- | ----------------------------------------------------- |
| `w`      | `number`              | Frame width in pixels                                 |
| `h`      | `number`              | Frame height in pixels                                |
| `name`   | `string`              | Label displayed in the frame header                   |
| `color`  | `TLDefaultColorStyle` | Color for border and header (when colors are enabled) |

Configuration options:

| Option           | Type      | Default | Description                                                                                     |
| ---------------- | --------- | ------- | ----------------------------------------------------------------------------------------------- |
| `showColors`     | `boolean` | `false` | When true, frames display colored borders and header backgrounds based on the `color` property. |
| `resizeChildren` | `boolean` | `false` | When true, resizing the frame also scales the frame's children proportionally.                  |

When `showColors` is enabled, the frame's `color` property becomes a style that users can change from the style panel. When disabled, all frames appear with the same neutral styling.

```tsx
const ConfiguredFrameUtil = FrameShapeUtil.configure({
	showColors: true,
	resizeChildren: true,
})
```

To build your own container shape that behaves like a frame, extend `BaseFrameLikeShapeUtil` rather than re-implementing every behavior on `FrameShapeUtil`. The base class provides defaults for clipping children, full-brush selection, blocking erasure from inside, and drag-and-drop reparenting — see [Shapes](/sdk-features/shapes#frames) for details and the [portal shapes example](/examples/shapes/tools/portal-shapes) for a working implementation.

### Group

The group shape logically combines multiple shapes without visual representation. Groups let you move and transform shapes together while preserving their relative positions. The group's geometry is computed as the union of all child shapes' geometries. You create groups through the editor API rather than directly. A group deletes itself when it has one child or none left.

```tsx
// Create a group from selected shapes
editor.groupShapes(editor.getSelectedShapeIds())

// Ungroup a group
editor.ungroupShapes([groupId])

// Access group children
const children = editor.getSortedChildIdsForParent(groupId)
```

Groups have no visual properties; their `props` object is empty. All visual characteristics come from their child shapes. Arrows can't bind to groups. Double-click a group to enter it and edit its children directly.

Group shapes don't have configuration options. For a complete guide, see [Groups](/sdk-features/groups).

## Connectors

### Arrow

The arrow shape creates lines that can bind to other shapes. Arrows update automatically when their connected shapes move. They support two routing modes: `arc` for smooth curves controlled by a bend parameter, and `elbow` for right-angle routing that navigates around obstacles. Arrows can display text labels positioned along their length, and offer multiple arrowhead styles for both terminals.

The arrow binding system creates connections automatically when arrow terminals are dragged near other shapes. Bindings can be "precise" (connecting to a specific point) or "imprecise" (connecting to the shape's center or edge).

```tsx
editor.createShape({
	type: 'arrow',
	x: 100,
	y: 100,
	props: {
		kind: 'arc',
		start: { x: 0, y: 0 },
		end: { x: 200, y: 100 },
		bend: 0,
		color: 'black',
		fill: 'none',
		dash: 'solid',
		size: 'm',
		arrowheadStart: 'none',
		arrowheadEnd: 'arrow',
		font: 'draw',
		richText: toRichText(''),
		labelPosition: 0.5,
		labelColor: 'black',
		scale: 1,
		elbowMidPoint: 0.5,
	},
})
```

Properties:

| Property         | Type                         | Description                                             |
| ---------------- | ---------------------------- | ------------------------------------------------------- |
| `kind`           | `TLArrowShapeKind`           | Routing mode: `arc` for curved, `elbow` for right-angle |
| `start`          | `VecModel`                   | Start terminal position (relative to shape origin)      |
| `end`            | `VecModel`                   | End terminal position                                   |
| `bend`           | `number`                     | Curvature for arc arrows (0 = straight)                 |
| `color`          | `TLDefaultColorStyle`        | Stroke color                                            |
| `fill`           | `TLDefaultFillStyle`         | Fill style (for arrowheads)                             |
| `dash`           | `TLDefaultDashStyle`         | Stroke pattern                                          |
| `size`           | `TLDefaultSizeStyle`         | Stroke width preset                                     |
| `arrowheadStart` | `TLArrowShapeArrowheadStyle` | Start terminal style                                    |
| `arrowheadEnd`   | `TLArrowShapeArrowheadStyle` | End terminal style                                      |
| `font`           | `TLDefaultFontStyle`         | Font family for label                                   |
| `richText`       | `TLRichText`                 | Optional text label                                     |
| `labelPosition`  | `number`                     | Label position along arrow (0 = start, 1 = end)         |
| `labelColor`     | `TLDefaultColorStyle`        | Label text color                                        |
| `scale`          | `number`                     | Scale factor                                            |
| `elbowMidPoint`  | `number`                     | Position of the midpoint handle for elbow arrows        |

The available arrowhead styles are: `none`, `arrow`, `triangle`, `square`, `dot`, `pipe`, `diamond`, `inverted`, `bar`

Configuration options control snap behavior, timing, and rendering:

| Option                                      | Type                                              | Default                              | Description                                                                                          |
| ------------------------------------------- | ------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `expandElbowLegLength`                      | `Record<TLDefaultSizeStyle, number>`              | `{ s: 28, m: 36, l: 44, xl: 66 }`    | How far elbow arrows extend from target shapes, per size.                                            |
| `minElbowLegLength`                         | `Record<TLDefaultSizeStyle, number>`              | Based on stroke width × 3            | Minimum length of an elbow arrow's leg segment.                                                      |
| `minElbowHandleDistance`                    | `number`                                          | `16`                                 | Minimum screen pixels between two elbow handles. Closer handles are hidden.                          |
| `arcArrowCenterSnapDistance`                | `number`                                          | `16`                                 | Screen pixels at which arc arrows snap to target shape centers. Set to 0 to disable.                 |
| `elbowArrowCenterSnapDistance`              | `number`                                          | `24`                                 | Screen pixels at which elbow arrows snap to target shape centers.                                    |
| `elbowArrowEdgeSnapDistance`                | `number`                                          | `20`                                 | Screen pixels at which elbow arrows snap to target shape edges.                                      |
| `elbowArrowPointSnapDistance`               | `number`                                          | `24`                                 | Screen pixels at which elbow arrows snap to directional points (top, right, bottom, left) of shapes. |
| `elbowArrowAxisSnapDistance`                | `number`                                          | `16`                                 | Screen pixels at which elbow arrows snap to axes through shape centers.                              |
| `labelCenterSnapDistance`                   | `number`                                          | `10`                                 | Screen pixels at which arrow labels snap to the arrow's center when dragged.                         |
| `elbowMidpointSnapDistance`                 | `number`                                          | `10`                                 | Screen pixels at which elbow midpoint handles snap to the midpoint between shapes.                   |
| `elbowMinSegmentLengthToShowMidpointHandle` | `number`                                          | `20`                                 | Minimum segment length before showing the midpoint drag handle.                                      |
| `hoverPreciseTimeout`                       | `number`                                          | `600`                                | Milliseconds to wait while hovering before switching to precise targeting.                           |
| `pointingPreciseTimeout`                    | `number`                                          | `320`                                | Milliseconds to wait while pointing/dragging before switching to precise targeting.                  |
| `shouldBeExact`                             | `(editor: Editor, isPrecise: boolean) => boolean` | Returns `editor.inputs.getAltKey()`  | Function determining whether arrows stop exactly at pointer vs. at shape edges.                      |
| `shouldIgnoreTargets`                       | `(editor: Editor) => boolean`                     | Returns `editor.inputs.getCtrlKey()` | Function determining whether to skip binding to target shapes.                                       |
| `showTextOutline`                           | `boolean`                                         | `true`                               | Whether to show a text outline on arrow labels for readability.                                      |

```tsx
const ConfiguredArrowUtil = ArrowShapeUtil.configure({
	arcArrowCenterSnapDistance: 24,
	hoverPreciseTimeout: 400,
	showTextOutline: false,
	shouldBeExact: (editor) => editor.inputs.getAltKey() || editor.inputs.getShiftKey(),
})
```

## Common properties

All shapes share base properties defined in `TLBaseShape`:

```typescript
interface TLBaseShape {
	id: TLShapeId
	type: string
	x: number // Position relative to parent
	y: number
	rotation: number // Rotation in radians
	index: IndexKey // Fractional index for z-ordering
	parentId: TLParentId // Page ID or parent shape ID
	isLocked: boolean
	opacity: number // 0-1
	props: object // Shape-specific properties
	meta: object // Custom metadata (for your application)
}
```

Most shapes also support common style properties through the style system:

| Style   | Values                                                   | Description       |
| ------- | -------------------------------------------------------- | ----------------- |
| `color` | `black`, `grey`, `light-violet`, etc.                    | Stroke/text color |
| `fill`  | `none`, `semi`, `solid`, `pattern`, `fill`, `lined-fill` | Fill style        |
| `dash`  | `draw`, `solid`, `dashed`, `dotted`, `none`              | Stroke pattern    |
| `size`  | `s`, `m`, `l`, `xl`                                      | Size preset       |
| `font`  | `draw`, `sans`, `serif`, `mono`                          | Font family       |

## Using configured shapes

To use configured shape utilities, pass them to the `shapeUtils` prop when initializing tldraw. Configured utilities replace the default utilities for their shape type:

```tsx
import { Tldraw, ArrowShapeUtil, FrameShapeUtil, NoteShapeUtil } from 'tldraw'
import 'tldraw/tldraw.css'

const ConfiguredArrowUtil = ArrowShapeUtil.configure({
	showTextOutline: false,
	hoverPreciseTimeout: 400,
})

const ConfiguredFrameUtil = FrameShapeUtil.configure({
	showColors: true,
})

const ConfiguredNoteUtil = NoteShapeUtil.configure({
	resizeMode: 'scale',
})

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw shapeUtils={[ConfiguredArrowUtil, ConfiguredFrameUtil, ConfiguredNoteUtil]} />
		</div>
	)
}
```

You can also extend shape utilities to add custom behavior beyond configuration options. See the [custom shapes](/docs/shapes) guide for details.

## Related examples

- [Custom shape](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/shapes/tools/custom-shape): Create a custom shape utility to understand how default shapes are implemented.
- [Custom styles](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/shapes/tools/shape-with-custom-styles): Add custom style properties similar to those used by default shapes.
- [Shape options](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/configure-shape-util): Configure shape utility behavior using the configure() method.

--------

# Drag and drop

The drag and drop system lets shapes respond when other shapes are dragged over them. Frames use this to reparent shapes when you drag them inside. You can use the same callbacks in your [`ShapeUtil`](/reference/editor/ShapeUtil) to build custom container shapes or any shape that should react to shapes being dragged over it.

If you want frame-like behavior (accept children, reparent them on drag in and out, clip them), extend [`BaseFrameLikeShapeUtil`](/reference/editor/BaseFrameLikeShapeUtil), which implements all of the callbacks below. Implement them yourself when you need something different.

## Drag callbacks

While the select tool translates shapes, it tracks which shape (if any) is under the cursor using [`Editor.getDraggingOverShape`](/reference/editor/Editor#getDraggingOverShape). Your shape util can implement these callbacks to respond:

| Callback                        | When it fires                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------- |
| [`ShapeUtil.onDragShapesIn`](/reference/editor/ShapeUtil#onDragShapesIn)   | Shapes are first dragged over this shape                                          |
| [`ShapeUtil.onDragShapesOver`](/reference/editor/ShapeUtil#onDragShapesOver) | Shapes continue being dragged over this shape (on an interval, when cursor moves) |
| [`ShapeUtil.onDragShapesOut`](/reference/editor/ShapeUtil#onDragShapesOut)  | Shapes are dragged away from this shape                                           |
| [`ShapeUtil.onDropShapesOver`](/reference/editor/ShapeUtil#onDropShapesOver) | Shapes are dropped onto this shape                                                |

The callbacks receive the target shape (the one being dragged over), an array of the shapes being dragged, and an info object with context about the drag operation. Locked shapes are never dragged, and if every child of a group is being dragged, the group is dragged instead of its children.

### onDragShapesIn

Called once when shapes first enter this shape's bounds. Use it to reparent shapes into a container:

```typescript
override onDragShapesIn(shape: MyContainerShape, draggingShapes: TLShape[]) {
	// Only reparent if not already a child
	const newShapes = draggingShapes.filter((s) => s.parentId !== shape.id)
	if (newShapes.length > 0) {
		this.editor.reparentShapes(newShapes, shape.id)
	}
}
```

### onDragShapesOver

Called on an interval while shapes are being dragged over this shape, but only when the cursor moves. Use it for visual feedback or custom snapping:

```typescript
override onDragShapesOver(shape: MyGridShape, draggingShapes: TLShape[]) {
	// Snap shapes to grid cells while dragging
	for (const dragging of draggingShapes) {
		const snappedX = Math.round(dragging.x / CELL_SIZE) * CELL_SIZE
		const snappedY = Math.round(dragging.y / CELL_SIZE) * CELL_SIZE

		if (dragging.x !== snappedX || dragging.y !== snappedY) {
			this.editor.updateShape({
				id: dragging.id,
				type: dragging.type,
				x: snappedX,
				y: snappedY,
			})
		}
	}
}
```

### onDragShapesOut

Called when shapes are dragged away from this shape, including when the drag moves into another shape. Use it to reparent shapes back to the page:

```typescript
override onDragShapesOut(
	shape: MyContainerShape,
	draggingShapes: TLShape[],
	info: TLDragShapesOutInfo
) {
	// Check if we're dragging into another container
	if (info.nextDraggingOverShapeId) {
		// Let the next container handle it
		return
	}

	// Reparent back to the page
	const children = draggingShapes.filter((s) => s.parentId === shape.id)
	if (children.length > 0) {
		this.editor.reparentShapes(children, this.editor.getCurrentPageId())
	}
}
```

### onDropShapesOver

Called when shapes are dropped (mouse up) while over this shape. Use it for finalization logic:

```typescript
override onDropShapesOver(shape: MySlotShape, draggingShapes: TLShape[]) {
	// Lock shapes in place after dropping
	for (const dragging of draggingShapes) {
		this.editor.updateShape({
			id: dragging.id,
			type: dragging.type,
			isLocked: true,
		})
	}
}
```

## The info object

All drag callbacks receive an info object with context about the drag operation. The exact type varies by callback:

| Callback           | Info type                 |
| ------------------ | ------------------------- |
| `onDragShapesIn`   | [`TLDragShapesInInfo`](/reference/editor/TLDragShapesInInfo)   |
| `onDragShapesOver` | [`TLDragShapesOverInfo`](/reference/editor/TLDragShapesOverInfo) |
| `onDragShapesOut`  | [`TLDragShapesOutInfo`](/reference/editor/TLDragShapesOutInfo)  |
| `onDropShapesOver` | [`TLDropShapesOverInfo`](/reference/editor/TLDropShapesOverInfo) |

All info types share these common properties:

| Property                     | Description                                           |
| ---------------------------- | ----------------------------------------------------- |
| `initialDraggingOverShapeId` | The shape that was under the cursor when drag started |
| `initialParentIds`           | Map of each shape's parent ID at drag start           |
| `initialIndices`             | Map of each shape's z-index at drag start             |

Some callbacks have additional properties:

| Property                  | Available in      | Description                              |
| ------------------------- | ----------------- | ---------------------------------------- |
| `prevDraggingOverShapeId` | `onDragShapesIn`  | The previous shape that was dragged over |
| `nextDraggingOverShapeId` | `onDragShapesOut` | The next shape being dragged into        |

The `initialParentIds` and `initialIndices` maps let you restore shapes to their original positions. Frames use them to preserve z-ordering when shapes are dragged back to their original parent.

## Determining what's under the cursor

[`Editor.getDraggingOverShape`](/reference/editor/Editor#getDraggingOverShape) determines which shape is being dragged over by checking which shape's geometry contains the cursor point. It tests shapes from front to back, skipping locked shapes, hidden shapes, and the shapes being dragged, and returns the first hit.

Only shapes that implement drag callbacks are considered as drop targets. If your shape util doesn't override any drag callbacks, shapes will pass through it when being dragged. While shapes are dragged over a target that accepts them, the editor hints the target with [`Editor.setHintingShapes`](/reference/editor/Editor#setHintingShapes).

## Controlling which shapes can be dropped

Use the [`ShapeUtil.canReceiveNewChildrenOfType`](/reference/editor/ShapeUtil#canReceiveNewChildrenOfType) method to control which shape types your container accepts. The editor uses it to decide whether `onDragShapesIn` and `onDropShapesOver` fire for a dragged shape:

```typescript
override canReceiveNewChildrenOfType(shape: MyContainerShape, type: TLShape['type']) {
	// Only accept specific shape types
	return type === 'my-item' || type === 'geo'
}
```

The default is `false`, so any shape that should accept dropped children must override this method. `onDragShapesOver` is not gated by this method, which lets you provide visual feedback even when the target won't accept the drop.

## Controlling which shapes can be dragged out

Use the [`ShapeUtil.canRemoveChildrenOfType`](/reference/editor/ShapeUtil#canRemoveChildrenOfType) method to control which child shape types can be dragged out of your container. The editor uses it to decide whether `onDragShapesOut` fires for a child shape, and to decide whether to automatically [reparent](/sdk-features/parenting) a child that has moved outside its parent's geometry:

```typescript
override canRemoveChildrenOfType(shape: MyContainerShape, type: TLShape['type']) {
	// Pin certain children in place; allow others to be removed
	return type !== 'pinned-item'
}
```

The default is `true`, so children can be dragged out of any container unless this method is overridden.

## Example: slot container

Here's a complete example of a slot-based container that accepts dropped shapes:

```tsx
import {
	HTMLContainer,
	Rectangle2d,
	ShapeUtil,
	TLBaseShape,
	TLDragShapesOutInfo,
	TLShape,
	T,
} from 'tldraw'

type SlotContainerShape = TLBaseShape<'slot-container', { slots: number }>

class SlotContainerShapeUtil extends ShapeUtil<SlotContainerShape> {
	static override type = 'slot-container' as const
	static override props = { slots: T.number }

	getDefaultProps() {
		return { slots: 4 }
	}

	getGeometry(shape: SlotContainerShape) {
		return new Rectangle2d({
			width: shape.props.slots * 100,
			height: 100,
			isFilled: true,
		})
	}

	override canReceiveNewChildrenOfType(_shape: SlotContainerShape, type: string) {
		return type === 'geo' || type === 'text'
	}

	override onDragShapesIn(shape: SlotContainerShape, draggingShapes: TLShape[]) {
		const newShapes = draggingShapes.filter((s) => s.parentId !== shape.id)
		if (newShapes.length > 0) {
			this.editor.reparentShapes(newShapes, shape.id)
		}
	}

	override onDragShapesOut(
		shape: SlotContainerShape,
		draggingShapes: TLShape[],
		info: TLDragShapesOutInfo
	) {
		if (!info.nextDraggingOverShapeId) {
			const children = draggingShapes.filter((s) => s.parentId === shape.id)
			this.editor.reparentShapes(children, this.editor.getCurrentPageId())
		}
	}

	component(shape: SlotContainerShape) {
		return (
			<HTMLContainer
				style={{
					backgroundColor: '#f0f0f0',
					border: '2px dashed #ccc',
					display: 'grid',
					gridTemplateColumns: `repeat(${shape.props.slots}, 100px)`,
				}}
			>
				{Array.from({ length: shape.props.slots }).map((_, i) => (
					<div
						key={i}
						style={{
							width: 100,
							height: 100,
							borderRight: i < shape.props.slots - 1 ? '1px dashed #ccc' : undefined,
						}}
					/>
				))}
			</HTMLContainer>
		)
	}

	getIndicatorPath(shape: SlotContainerShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.slots * 100, 100)
		return path
	}
}
```

## Related examples

- [Drag and drop](/examples/shapes/tools/drag-and-drop) - Custom shapes that can be dragged onto each other.
- [Drag and drop tray](/examples/ui/drag-and-drop-tray) - Drag items from a custom UI into the canvas.

## Related docs

- [External content handling](/sdk-features/external-content) - Handle files, URLs, and other content dragged from outside the browser. The callbacks on this page are for shape-to-shape drag and drop within the canvas.
- [Parenting and ancestors](/sdk-features/parenting) - Learn about parent-child relationships and the [`Editor.reparentShapes`](/reference/editor/Editor#reparentShapes) method.

--------

# Draw shape

The draw shape captures freehand strokes and straight line segments. The draw tool produces pressure-sensitive strokes from pens and styluses, snaps straight lines to 15° angles when you hold Shift, and closes shapes automatically when a stroke ends near its start. Its keyboard shortcuts are D, B, and X, and holding Ctrl (or Cmd) while pressing down switches temporarily to the eraser.

## Drawing modes

The draw tool supports two segment types that you can switch between while drawing:

| Mode     | Trigger                  | Behavior                                                                     |
| -------- | ------------------------ | ---------------------------------------------------------------------------- |
| Freehand | Default                  | Captures natural hand motion with optional pressure sensitivity              |
| Straight | Hold Shift while drawing | Creates straight line segments that snap to 15° angle increments (see below) |

You can mix both modes in a single stroke. Start drawing freehand, then hold Shift to switch to straight lines. Release Shift to return to freehand. Each mode change creates a new segment in the shape.

### Freehand drawing

Freehand mode captures your natural hand motion. The tool records points as you drag and interpolates them into smooth curves. When you draw with a pen or stylus, the tool captures pressure data and produces variable-width strokes.

The stroke appearance depends on the dash style. The `draw` style uses the freehand algorithm to create hand-drawn strokes with natural width variation. The `solid`, `dashed`, and `dotted` styles render uniform-width strokes.

### Straight line mode

Hold Shift while drawing to create straight line segments. The line snaps to 15° angle increments (24 divisions of a full circle) relative to the previous point, which covers horizontal and vertical lines, 45° diagonals, and the 30° and 60° angles used in isometric drawings. Hold Ctrl to disable angle snapping temporarily.

Release Shift to continue with freehand drawing from the current endpoint. The transition creates a smooth connection between the straight segment and the freehand stroke.

### Extending previous strokes

If you've already drawn a stroke and want to continue from it, hold Shift and click to connect. The draw tool creates a straight line segment from the previous stroke's endpoint to your click position. Continue holding Shift and drag to extend with more straight segments, or release Shift to switch to freehand.

This connect-the-dots behavior only activates when you Shift+click after completing a previous stroke with the same draw tool session. It won't connect across different shapes or after switching tools.

## Pen and stylus support

The draw tool distinguishes between mouse/touch input and pen/stylus input. When it detects a pen or stylus, it enables pressure-sensitive rendering:

| Input type  | Pressure behavior                                                  |
| ----------- | ------------------------------------------------------------------ |
| Mouse/touch | Simulates pressure based on velocity—faster strokes appear thinner |
| Pen/stylus  | Uses actual pressure data for variable stroke width                |

The tool treats input as a pen when the browser reports a pen pointer with non-zero pressure, or when the pressure value is strictly between 0 and 0.5 or between 0.5 and 1. Mice report exactly 0.5.

The shape stores pen detection in the `isPen` property. This affects how the stroke renders—pen strokes use a different stroke profile optimized for real pressure data.

## Automatic shape closing

Draw shapes can automatically close when you bring the endpoint near the starting point. This creates filled shapes when combined with a fill style other than "none".

The shape closes when:

- The path length exceeds 4× the scaled stroke width
- The endpoint is within a small distance of the starting point (roughly the stroke width plus a margin, boosted at low zoom levels)

When a shape closes, the shape sets `isClosed` to true and fills according to its fill style. Highlight shapes don't support closing.

## Line snapping

When drawing straight lines with Shift held, you can snap to previous segments in the current stroke. This helps create precise geometric constructions:

- Enable snap mode in user preferences, or hold Ctrl (when snap mode is disabled) to temporarily enable snapping
- Hold Ctrl (when snap mode is enabled) to temporarily disable snapping
- The tool snaps to the nearest point on earlier straight segments (excluding the current and previous segment) within 8 screen pixels

Visual snap indicators appear when snapping is active.

## Dynamic resize mode

When dynamic resize mode is enabled in user preferences, new draw shapes scale inversely with zoom level. Drawing while zoomed out creates shapes that appear the same size on screen as they would at 100% zoom. The shape's `scale` property stores this adjustment.

Access dynamic resize mode through [`Editor.user`](/reference/editor/Editor#user):

```typescript
// Check current mode
const isDynamic = editor.user.getIsDynamicResizeMode()

// Enable dynamic resize mode
editor.user.updateUserPreferences({ isDynamicSizeMode: true })
```

## Shape properties

Draw shapes store their path data in a delta-encoded base64 format. Segments from pens and styluses store x, y, and z (pressure): the first point uses full Float32 precision (12 bytes) and each subsequent point is a Float16 delta (6 bytes). Segments from mice and touch input drop the constant pressure value and store only x and y, marked with `dim: 2` (8 bytes for the first point, 4 bytes per delta).

| Property     | Type                   | Description                                                              |
| ------------ | ---------------------- | ------------------------------------------------------------------------ |
| `color`      | `TLDefaultColorStyle`  | Stroke color                                                             |
| `fill`       | `TLDefaultFillStyle`   | Fill style (applies when `isClosed` is true)                             |
| `dash`       | `TLDefaultDashStyle`   | Stroke pattern: `draw`, `solid`, `dashed`, `dotted`, `none`              |
| `size`       | `TLDefaultSizeStyle`   | Stroke width preset: `s`, `m`, `l`, `xl`                                 |
| `segments`   | `TLDrawShapeSegment[]` | Array of segments with `type`, base64-encoded `path`, and optional `dim` |
| `isComplete` | `boolean`              | Whether the user has finished drawing this stroke                        |
| `isClosed`   | `boolean`              | Whether the path forms a closed shape                                    |
| `isPen`      | `boolean`              | Whether drawn with a stylus (enables pressure-based width)               |
| `scale`      | `number`               | Scale factor applied to the shape                                        |
| `scaleX`     | `number`               | Horizontal scale factor for lazy resize                                  |
| `scaleY`     | `number`               | Vertical scale factor for lazy resize                                    |

Each segment has a `type` of `'free'` or `'straight'`, a `path` containing the encoded points, and an optional `dim` of `2` (x and y only) or `3` (x, y, and pressure; the default when omitted). Resizing a draw shape doesn't re-encode its points; it updates `scaleX` and `scaleY` instead.

## Configuration options

Configure [`DrawShapeUtil`](/reference/tldraw/DrawShapeUtil) to adjust behavior:

| Option              | Type     | Default | Description                                              |
| ------------------- | -------- | ------- | -------------------------------------------------------- |
| `maxPointsPerShape` | `number` | `600`   | Maximum points before automatically starting a new shape |

```tsx
import { DrawShapeUtil } from 'tldraw'

const ConfiguredDrawUtil = DrawShapeUtil.configure({
	maxPointsPerShape: 1000,
})
```

When a stroke exceeds the maximum point count, the draw tool completes the current shape and creates a new one at the current position. This prevents performance issues with very long strokes.

## Creating draw shapes programmatically

To create a draw shape through the editor API, you need to encode the point data:

```tsx
import { b64Vecs, createShapeId } from 'tldraw'

// Define your points with x, y, and z (pressure)
const points = [
	{ x: 0, y: 0, z: 0.5 },
	{ x: 50, y: 30, z: 0.5 },
	{ x: 100, y: 10, z: 0.5 },
]

editor.createShape({
	id: createShapeId(),
	type: 'draw',
	x: 100,
	y: 100,
	props: {
		color: 'black',
		fill: 'none',
		dash: 'draw',
		size: 'm',
		segments: [
			{
				type: 'free',
				path: b64Vecs.encodePoints(points),
			},
		],
		isComplete: true,
		isClosed: false,
		isPen: false,
		scale: 1,
		scaleX: 1,
		scaleY: 1,
	},
})
```

[`b64Vecs`](/reference/tlschema/b64Vecs)`.encodePoints` converts an array of point objects to the delta-encoded base64 format; pass `2` as the second argument to store x and y only. Use `b64Vecs.decodePoints(segment.path, segment.dim)` to read points back.

## Stroke rendering

The draw shape uses a freehand stroke algorithm to render organic-looking lines. Streamlining reduces jitter by interpolating each new point toward the previous one, smoothing rounds the outline, and thinning varies stroke width by velocity (for mouse) or pressure (for pen).

When `dash` is set to `'draw'`, the shape renders using the full freehand algorithm. Other dash styles use simpler uniform-width strokes with the appropriate dash pattern.

At low zoom levels, the shape switches to solid rendering for performance. This happens when the zoom level is below 50% and also below a threshold based on the scaled stroke width.

## Geometry

The shape's geometry depends on its content:

| Content                          | Geometry                                                         |
| -------------------------------- | ---------------------------------------------------------------- |
| Tiny single-segment stroke (dot) | A [`Circle2d`](/reference/editor/Circle2d) with a radius of roughly the scaled stroke width |
| Closed path                      | A [`Polygon2d`](/reference/editor/Polygon2d) that can be filled                              |
| Open path                        | A [`Polyline2d`](/reference/editor/Polyline2d) following the stroke's center line             |

The geometry uses the processed stroke points (after applying streamline and smoothing), not the raw input points.

## Related shapes

- [Highlight](/sdk-features/default-shapes#highlight) uses the same point capture system but renders semi-transparently for marking up content
- [Line](/sdk-features/default-shapes#line) creates editable multi-point lines with draggable handles

## Related articles

- [Default shapes](/sdk-features/default-shapes) — Overview of all built-in shapes
- [Tools](/sdk-features/tools) — How tools handle user input
- [Styles](/sdk-features/styles) — Working with shape styles like color and size

--------

# Edge scrolling

Edge scrolling pans the camera automatically when you drag shapes toward the viewport edges. This lets you move shapes across the canvas without releasing the drag to scroll manually.

## How it works

Tool states that support edge scrolling call [`EdgeScrollManager.updateEdgeScrolling`](/reference/editor/EdgeScrollManager#updateEdgeScrolling) on every tick while the user is dragging. The manager reads the pointer position from the editor's inputs, works out how close it is to each viewport edge, and moves the camera. It does nothing while the camera is locked.

The built-in select tool does this in its Translating (moving shapes), Brushing (selection box), and Resizing (dragging handles) states. The tool state, not the manager, decides when edge scrolling applies: the built-in states skip the call unless `editor.inputs.getIsDragging()` is true and `editor.inputs.getIsPanning()` is false.

## Tool integration

To add edge scrolling to a custom tool, call `updateEdgeScrolling()` from the tick handler of the state where dragging happens, and only while the user is dragging:

```typescript
import { StateNode, TLTickEventInfo } from 'tldraw'

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

	override onTick({ elapsed }: TLTickEventInfo) {
		const { editor } = this
		if (!editor.inputs.getIsDragging() || editor.inputs.getIsPanning()) return
		editor.edgeScrollManager.updateEdgeScrolling(elapsed)
	}
}
```

[`EdgeScrollManager.getIsEdgeScrolling`](/reference/editor/EdgeScrollManager#getIsEdgeScrolling) returns true while the pointer is inside the edge zone, including during the start delay, and false once it leaves. Use it to show an indicator in your own UI.

## Configuration options

Customize edge scrolling through [`TldrawOptions`](/reference/editor/TldrawOptions). Set `edgeScrollSpeed` to `0` to turn it off entirely.

| Option                   | Default | Description                                                             |
| ------------------------ | ------- | ----------------------------------------------------------------------- |
| `edgeScrollDelay`        | 200     | Milliseconds the pointer must stay in the edge zone before scrolling    |
| `edgeScrollEaseDuration` | 200     | Milliseconds to ramp up to full speed after the delay                   |
| `edgeScrollSpeed`        | 25      | Base scroll speed in pixels per tick                                    |
| `edgeScrollDistance`     | 8       | Width of the edge scroll zone in pixels                                 |
| `coarsePointerWidth`     | 12      | Extra pointer width on each side for coarse (touch) pointers, in pixels |

Set these options when creating the editor:

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

const options = {
	edgeScrollSpeed: 50, // Double the default speed
	edgeScrollDelay: 100, // Start scrolling sooner
}

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

### User preferences

Edge scroll speed is also a user preference. `editor.user.getEdgeScrollSpeed()` returns a multiplier that defaults to 1, and you can change it with `editor.user.updateUserPreferences({ edgeScrollSpeed: 2 })`. The preference persists across sessions and scales all edge scrolling without changing the base configuration.

## Edge detection and speed

The edge zone extends inward from each edge of the viewport by `edgeScrollDistance`. Inside it, the manager computes a signed proximity factor per axis between -1 and 1: 0 at the zone boundary, ±1 at the screen edge or beyond, with the sign giving the scroll direction. For coarse pointers (`isCoarsePointer` in the instance state) the pointer is widened by `coarsePointerWidth` on each side, so touch reaches the zone sooner.

Edge detection respects the instance state's `insets` array, in CSS order `[top, right, bottom, left]`. An entry is `true` when that edge of the editor is inset from the browser window rather than flush with it. For a flush edge the pointer can't move past the window, so the zone extends inward from the edge. For an inset edge the zone starts at the editor's boundary instead, and scrolling begins once the pointer moves outside the editor.

Once the pointer enters the zone, the manager waits `edgeScrollDelay` before moving the camera, which prevents accidental scrolling when the pointer briefly crosses the edge. It then ramps up over `edgeScrollEaseDuration` using `EASINGS.easeInCubic`. Leaving the zone stops scrolling and resets the timer.

The scroll delta per tick is `edgeScrollSpeed` multiplied by the user's edge scroll speed preference, the proximity factor, and a 0.612 factor on any axis where the viewport is narrower than 1000 pixels. It is divided by the zoom level so canvas-space velocity stays constant across zoom levels.

## Related examples

See the [custom tool](/examples/shapes/tools/custom-tool) example for building tools that can implement edge scrolling. For complex tools with multiple states, see the [tool with child states](/examples/shapes/tools/tool-with-child-states) example.

--------

# Editor

The [`Editor`](/reference/editor/Editor) class is the main way of controlling tldraw's editor. It has methods for creating, reading, updating, and deleting shapes, for managing selection and history, for controlling the camera, and for responding to user input. By design, the editor's surface area is very large: almost everything is available through it.

Need to create some shapes? Use [`Editor.createShapes`](/reference/editor/Editor#createShapes). Need to delete them? Use [`Editor.deleteShapes`](/reference/editor/Editor#deleteShapes). Want a sorted array of every shape on the current page? Use [`Editor.getCurrentPageShapesSorted`](/reference/editor/Editor#getCurrentPageShapesSorted). The editor is your primary interface for interacting with the canvas.

## Accessing the editor

You can access the editor in two ways:

1. From the [`Tldraw`](/reference/tldraw/Tldraw) component's `onMount` callback:

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					// Your editor code here
					editor.createShape({ type: 'geo', x: 100, y: 100 })
				}}
			/>
		</div>
	)
}
```

2. Via the [`useEditor`](/reference/editor/useEditor) hook, which must be called from within the [`Tldraw`](/reference/tldraw/Tldraw) component tree:

```tsx
function InsideOfContext() {
	const editor = useEditor()
	// Your editor code here
	return null
}

function App() {
	return (
		<Tldraw>
			<InsideOfContext />
		</Tldraw>
	)
}
```

## Architecture overview

The editor coordinates several interconnected systems.

### Store

The editor holds document data in its [`Editor.store`](/reference/editor/Editor#store) property. The store is a reactive database containing records for shapes, pages, bindings, assets, and editor state. All records are JSON-serializable.

```ts
// Access a shape record directly from the store
const shape = editor.store.get(shapeId)

// Listen to store changes
editor.store.listen((entry) => {
	console.log('Changed:', entry.changes)
})
```

The store is reactive: when data changes, the UI updates automatically. The editor wraps the store with higher-level methods like `createShapes()` and `deleteShapes()`, so you rarely need to interact with it directly.

See [Store](/sdk-features/store) for details on working with the store directly.

### Signals

Tldraw uses a signals-based reactive system. The editor exposes many of its internal values as signals—methods like `editor.getSelectedShapeIds()` and `editor.getCurrentPageShapes()` return reactive values that update automatically when the underlying state changes.

```tsx
import { track, useEditor } from 'tldraw'

const SelectedCount = track(function SelectedCount() {
	const editor = useEditor()
	return <div>{editor.getSelectedShapeIds().length} shapes selected</div>
})
```

The `track` higher-order component automatically subscribes to signals accessed during render. When those signals change, the component re-renders.

See [Signals](/sdk-features/signals) for the full reactive API.

### State chart

The editor uses a hierarchical state machine for handling user interactions. Tools like the select tool, draw tool, and hand tool are implemented as [`StateNode`](/reference/editor/StateNode) instances. Each node can have child states, and the active state determines how the editor responds to events.

```ts
// Change the current tool
editor.setCurrentTool('draw')
editor.setCurrentTool('hand')

// Check the current tool
editor.getCurrentToolId() // 'select', 'draw', 'hand', etc.

// Check the full state path
editor.root.getPath() // 'root.select.idle', 'root.draw.drawing', etc.

// Check if a state is active
editor.isIn('select') // true if select tool is active
editor.isIn('select.idle') // true if in idle state of select tool

// Check if any of several states are active
editor.isInAny('select.idle', 'hand.idle') // true if in either state
```

#### State transitions

Tools transition between child states as the user interacts. For example, the select tool has states like `idle`, `pointing_canvas`, `pointing_shape`, `brushing`, and `translating`. When you click and drag on empty canvas, the state flows like this:

1. `select.idle` — waiting for input
2. `select.pointing_canvas` — pointer down on the canvas, waiting to see if this is a click or drag
3. `select.brushing` — dragging to create a selection box
4. `select.idle` — pointer up, back to waiting

Each state handles events differently. The `idle` state responds to `pointer_down` on the canvas by transitioning to `pointing_canvas`. The `brushing` state updates the brush bounds on `pointer_move` and completes the selection on `pointer_up`.

#### Event flow

Events flow from the root state down through active children: `root` → `select` → `idle`. Each state runs its own handler first, then passes the event to its active child. If a handler transitions to a different child, the new child does not receive the same event.

States define handlers for events like `onPointerDown`, `onPointerMove`, `onKeyDown`, and `onEnter`/`onExit` for state transitions. The active state chain determines which handlers run.

See [Tools](/sdk-features/tools) for building custom tools.

### Managers

The editor delegates specialized functionality to manager classes:

| Manager                     | Responsibility                                   |
| --------------------------- | ------------------------------------------------ |
| [`HistoryManager`](/reference/editor/HistoryManager)         | Undo/redo stack and history marks                |
| [`SnapManager`](/reference/editor/SnapManager)            | Shape snapping during transforms                 |
| [`TextManager`](/reference/editor/TextManager)            | Text measurement and layout                      |
| [`FontManager`](/reference/editor/FontManager)            | Font loading and management                      |
| [`InputsManager`](/reference/editor/InputsManager)          | Pointer position and modifier key tracking       |
| [`ClickManager`](/reference/editor/ClickManager)           | Click, double-click, and long-press detection    |
| [`ScribbleManager`](/reference/editor/ScribbleManager)        | Scribble trails (eraser, laser, scribble select) |
| [`EdgeScrollManager`](/reference/editor/EdgeScrollManager)      | Auto-scroll at viewport edges                    |
| [`UserPreferencesManager`](/reference/editor/UserPreferencesManager) | User settings persistence                        |

Access managers through properties on the editor instance:

```ts
editor.snaps.getIndicators()
editor.inputs.getCurrentPagePoint()
editor.user.getUserPreferences()
editor.scribbles.addScribble({ color: 'accent' })
editor.edgeScrollManager.updateEdgeScrolling(elapsed)
```

## Working with shapes

Shapes are the content on your canvas. Each shape has a type, position, rotation, and type-specific props.

### Creating shapes

```ts
// Create a shape with auto-generated ID
editor.createShape({
	type: 'geo',
	x: 100,
	y: 100,
	props: {
		geo: 'rectangle',
		w: 200,
		h: 150,
		color: 'blue',
	},
})

// Create with a specific ID
import { createShapeId } from 'tldraw'

const id = createShapeId('my-shape')
editor.createShape({
	id,
	type: 'geo',
	x: 100,
	y: 100,
})
```

### Reading shapes

```ts
// Get a shape by ID
const shape = editor.getShape(shapeId)

// Get all shapes on the current page
const shapes = editor.getCurrentPageShapes()

// Get selected shapes
const selected = editor.getSelectedShapes()
```

### Updating shapes

```ts
editor.updateShape({
	id: shape.id,
	type: shape.type, // Required
	x: 200,
	props: {
		color: 'red',
	},
})
```

### Deleting shapes

```ts
// Delete by ID
editor.deleteShapes([shapeId])

// Delete by shape record
editor.deleteShapes([shape])
```

See [Shapes](/sdk-features/shapes) for the complete shape system.

## Selection

The editor tracks which shapes are selected. Selection drives transform handles, copy/paste, and delete.

```ts
// Select shapes
editor.select(shapeId)
editor.select(shapeId1, shapeId2)

// Add to selection
editor.setSelectedShapes([...editor.getSelectedShapeIds(), newId])

// Clear selection
editor.selectNone()

// Select all on current page
editor.selectAll()

// Get selection
editor.getSelectedShapeIds()
editor.getSelectedShapes()
```

See [Selection](/sdk-features/selection) for selection details.

## History

The editor maintains an undo/redo stack through its history manager. Changes to the store accumulate until you create a mark, which becomes an undo stopping point.

```ts
// Mark before an operation
editor.markHistoryStoppingPoint('rotate shapes')
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI / 4)

// Undo returns to the mark
editor.undo()

// Redo reapplies changes
editor.redo()
```

See [History](/sdk-features/history) for the full history API.

## Transactions

Use [`Editor.run`](/reference/editor/Editor#run) to batch changes into a single transaction. This improves performance and reduces intermediate renders.

```ts
editor.run(() => {
	editor.createShapes(shapes)
	editor.sendToBack(shapes)
	editor.selectNone()
})
```

The `run` method also accepts options for controlling history:

```ts
// Ignore changes (don't add to undo stack)
editor.run(
	() => {
		editor.updateShape({ id, type: 'geo', x: 100 })
	},
	{ history: 'ignore' }
)

// Allow editing locked shapes
editor.run(
	() => {
		editor.updateShapes(lockedShapes)
	},
	{ ignoreShapeLock: true }
)
```

See [History](/sdk-features/history) for more on how transactions interact with undo/redo.

## Camera and viewport

The editor manages a camera that determines which part of the infinite canvas is visible. The camera has x, y, and z (zoom) coordinates.

```ts
// Move camera to specific coordinates
editor.setCamera({ x: 0, y: 0, z: 1 })

// Zoom controls
editor.zoomIn()
editor.zoomOut()
editor.resetZoom()

// Fit content in view
editor.zoomToFit()
editor.zoomToSelection()

// Center on a point
editor.centerOnPoint({ x: 500, y: 500 })

// Lock the camera
editor.setCameraOptions({ isLocked: true })
```

The viewport is the visible area of the canvas. Get its bounds in screen or page coordinates:

```ts
// Screen coordinates (component size)
editor.getViewportScreenBounds()

// Page coordinates (what's visible on the canvas)
editor.getViewportPageBounds()
```

See [Camera](/sdk-features/camera) and [Coordinates](/sdk-features/coordinates) for the full camera API.

## Input state

The [`Editor.inputs`](/reference/editor/Editor#inputs) object tracks the user's current input state: cursor position, pressed keys, and drag state. All values on the inputs object are reactive signals. When you read them inside a tracked component or computed, your code re-runs when they change.

```ts
// Cursor position in page coordinates (reactive)
editor.inputs.getCurrentPagePoint()

// Cursor position in screen coordinates (reactive)
editor.inputs.getCurrentScreenPoint()

// Where the current drag started (reactive)
editor.inputs.getOriginPagePoint()

// Interaction state (reactive)
editor.inputs.getIsDragging()
editor.inputs.getIsPointing()
editor.inputs.getIsPinching()

// Modifier keys (reactive)
editor.inputs.getShiftKey()
editor.inputs.getCtrlKey()
editor.inputs.getAltKey()
```

See [Input handling](/sdk-features/input-handling) for input details.

## Instance state

The editor maintains per-instance state in a [`TLInstance`](/reference/tlschema/TLInstance) record. This includes which page is current, whether the editor is in readonly mode, tool lock state, and UI state. See [Instance state](/sdk-features/instance-state) and [Readonly mode](/sdk-features/readonly).

```ts
// Get instance state
const instance = editor.getInstanceState()

// Update instance state
editor.updateInstanceState({ isReadonly: true })

// Enable tool lock (keeps current tool active after creating shapes)
editor.updateInstanceState({ isToolLocked: true })
```

See [Tools](/sdk-features/tools#tool-lock) for more on tool lock.

Each page also has instance state ([`TLInstancePageState`](/reference/tlschema/TLInstancePageState)) tracking selection, hovered shape, and editing shape for that page:

```ts
// Get current page state
const pageState = editor.getCurrentPageState()
```

## User preferences

User preferences are shared across all editor instances. They control things like color scheme and locale.

```ts
// Turn on dark mode
editor.user.updateUserPreferences({ colorScheme: 'dark' })

// Use system color scheme
editor.user.updateUserPreferences({ colorScheme: 'system' })

// Get current preferences
editor.user.getUserPreferences()
```

See [User preferences](/sdk-features/user-preferences) for all preference options.

## Side effects

Register callbacks to respond to record lifecycle events. Side effects let you maintain relationships, enforce constraints, or sync external state.

```ts
// After a shape is created
editor.sideEffects.registerAfterCreateHandler('shape', (shape) => {
	if (shape.type === 'arrow') {
		console.log('Arrow created:', shape.id)
	}
})

// Before a shape is deleted
editor.sideEffects.registerBeforeDeleteHandler('shape', (shape) => {
	// Return false to prevent deletion
})
```

See [Side effects](/sdk-features/side-effects) for the complete API.

## Events

The editor receives events through [`Editor.dispatch`](/reference/editor/Editor#dispatch). You typically don't call this directly—the canvas handles DOM events and dispatches them for you. But you can listen for events on the editor:

```ts
editor.on('event', (info) => {
	if (info.name === 'pointer_down') {
		console.log('Pointer down at', info.point)
	}
})
```

See [Events](/sdk-features/events) for event types.

## Related examples

- **[Controlling the canvas](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/editor-api/api)** — Create and manipulate shapes, selection, and camera through the editor API.
- **[Minimal editor](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/only-editor)** — Use `TldrawEditor` for a bare-bones editor without default shapes or UI.
- **[Sublibraries](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/exploded)** — Compose tldraw from individual sublibraries for full customization.
- **[Canvas events](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/events/canvas-events)** — Listen to editor events including pointer, keyboard, and shape changes.
- **[Editor focus](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/editor-api/editor-focus)** — Control editor focus state.

--------

# Embed shape

The embed shape displays interactive content from external services within an iframe. When you paste a URL from a supported service onto the canvas, tldraw converts it to an embed with the appropriate dimensions and settings. See [`EmbedShapeUtil`](/reference/tldraw/EmbedShapeUtil) and [`TLEmbedShape`](/reference/tlschema/TLEmbedShape).

## Creating embeds

Paste a supported URL onto the canvas, or create an embed shape programmatically:

```tsx
editor.createShape({
	type: 'embed',
	x: 100,
	y: 100,
	props: {
		url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
		w: 560,
		h: 315,
	},
})
```

The embed system recognizes URLs from supported services and converts them to their embeddable equivalents. A YouTube watch URL becomes an embed URL automatically.

### Pasting iframe code

You can also paste raw `<iframe>` HTML directly onto the canvas to create an embed shape, even when the source URL doesn't match a known provider. tldraw extracts the iframe's `src` attribute and creates an embed pointing at it. For size, it reads the `width` and `height` attributes, then pixel values from the `style` attribute, and otherwise uses 425×350.

This covers services tldraw doesn't know about (OpenStreetMap, SoundCloud, Loom, internal tools) without a custom embed definition. Iframes pasted this way receive a stricter sandbox than the built-in providers ([`unknownEmbedShapePermissionOverrides`](/reference/tldraw/unknownEmbedShapePermissionOverrides): no `allow-same-origin`, no forms, no popups), since tldraw can't make any safety guarantees about the source.

## Supported services

| Service         | Hostnames                                   | Resizable | Aspect ratio locked |
| --------------- | ------------------------------------------- | --------- | ------------------- |
| tldraw          | tldraw.com, beta.tldraw.com, localhost:3000 | Yes       | No                  |
| Figma           | figma.com                                   | Yes       | No                  |
| YouTube         | youtube.com, \*.youtube.com, youtu.be       | Yes       | Yes                 |
| Google Maps     | google.\*                                   | Yes       | No                  |
| Google Calendar | calendar.google.\*                          | Yes       | No                  |
| Google Slides   | docs.google.\*                              | Yes       | No                  |
| CodeSandbox     | codesandbox.io                              | Yes       | No                  |
| CodePen         | codepen.io                                  | Yes       | No                  |
| Scratch         | scratch.mit.edu                             | No        | No                  |
| Val Town        | val.town                                    | Yes       | No                  |
| GitHub Gist     | gist.github.com                             | Yes       | No                  |
| Replit          | replit.com                                  | Yes       | No                  |
| Felt            | felt.com                                    | Yes       | No                  |
| Spotify         | open.spotify.com                            | Yes       | No                  |
| Vimeo           | vimeo.com, player.vimeo.com                 | Yes       | Yes                 |
| Observable      | observablehq.com                            | Yes       | No                  |
| Desmos          | desmos.com                                  | Yes       | No                  |
| Canva           | canva.com                                   | Yes       | No                  |

Each service has default dimensions appropriate for its content type. YouTube embeds default to 800×450 (16:9), while Spotify defaults to 720×500. Vimeo starts at 640×360 and corrects itself to the video's real aspect ratio after creation (`sizeToContentAspectRatio`). Google Maps takes an API key through `EmbedShapeUtil.configure({ embedConfig: { google_maps: { apiKey } } })`.

## Interacting with embeds

Embed shapes behave differently from other shapes because they contain live interactive content. Clicking an embed selects the shape rather than interacting with the content. Double-click it (or press Enter while it's selected) to enter editing mode. In editing mode, pointer events pass through to the iframe so you can scroll, click buttons, and use the embedded application. Click outside the shape or press Escape to exit.

Locking an embed doesn't block this: [`ShapeUtil.canEditWhileLocked`](/reference/editor/ShapeUtil#canEditWhileLocked) returns `true` for embeds (unless the definition sets `canEditWhileLocked: false`), so a locked embed can still enter editing mode and stays put while you use it. Editing also works in readonly mode.

## URL transformation

The embed system converts user-facing URLs to embed URLs automatically. When you paste `https://www.youtube.com/watch?v=dQw4w9WgXcQ`, the embed shape stores the original URL and renders `https://www.youtube.com/embed/dQw4w9WgXcQ`.

Each embed definition includes two transformation functions:

- `toEmbedUrl`: Converts a shareable URL to an embeddable URL
- `fromEmbedUrl`: Converts an embed URL back to the original URL

The shape stores the original URL and renders the embed version.

## Fallback to bookmarks

When you paste a URL that no embed definition recognizes, the default URL handler creates a [bookmark shape](/sdk-features/default-shapes#bookmark) instead of an embed. An existing embed shape whose URL doesn't match any definition still renders the URL in an iframe, using the stricter sandbox for unknown sources.

Use [`getEmbedInfo`](/reference/tldraw/getEmbedInfo) to check whether a URL is embeddable before creating a shape:

```tsx
import { getEmbedInfo, DEFAULT_EMBED_DEFINITIONS } from 'tldraw'

const embedInfo = getEmbedInfo(DEFAULT_EMBED_DEFINITIONS, 'https://youtube.com/watch?v=abc123')

if (embedInfo) {
	// URL is embeddable
	console.log(embedInfo.definition.title) // "YouTube"
	console.log(embedInfo.embedUrl) // "https://www.youtube.com/embed/abc123"
} else {
	// URL is not embeddable, will render as bookmark
}
```

## Iframe security

Embeds run in sandboxed iframes with restricted permissions. The defaults live in [`embedShapePermissionDefaults`](/reference/tldraw/embedShapePermissionDefaults):

| Permission                                | Default | Description                                       |
| ----------------------------------------- | ------- | ------------------------------------------------- |
| `allow-scripts`                           | Yes     | Allow JavaScript execution                        |
| `allow-same-origin`                       | Yes     | Allow access to same-origin storage and APIs      |
| `allow-forms`                             | Yes     | Allow form submission                             |
| `allow-popups`                            | Yes     | Allow opening new windows (for linking to source) |
| `allow-popups-to-escape-sandbox`          | No      | Popups inherit the sandbox                        |
| `allow-downloads`                         | No      | Block file downloads                              |
| `allow-downloads-without-user-activation` | No      | Block automatic downloads                         |
| `allow-modals`                            | No      | Block modal dialogs like `window.prompt()`        |
| `allow-orientation-lock`                  | No      | Block screen orientation lock                     |
| `allow-pointer-lock`                      | No      | Block pointer lock API                            |
| `allow-presentation`                      | No      | Block the Presentation API                        |
| `allow-top-navigation`                    | No      | Block navigating away from tldraw                 |
| `allow-top-navigation-by-user-activation` | No      | Block navigating away, even on user gesture       |
| `allow-storage-access-by-user-activation` | No      | Block access to parent storage                    |

Individual embed definitions override these defaults with `overridePermissions`. YouTube and Google Maps allow `allow-presentation` for fullscreen; YouTube, Google Calendar, and Google Slides allow `allow-popups-to-escape-sandbox`; tldraw embeds allow `allow-top-navigation` so users can open rooms in new tabs.

GitHub Gist embeds receive special handling: they use `srcDoc` instead of `src` to load the gist script, drop `allow-same-origin`, and restrict gist IDs to hexadecimal characters. This prevents JSONP callback attacks. See the [embed permissions example](/examples/configuration/embed-permissions).

## Custom embed definitions

Replace or extend the default embed definitions using `EmbedShapeUtil.configure()`. Type custom definitions as [`CustomEmbedDefinition`](/reference/tldraw/CustomEmbedDefinition) and give them an `icon` so they show up in the Insert embed dialog:

```tsx
import { Tldraw, EmbedShapeUtil, DEFAULT_EMBED_DEFINITIONS, CustomEmbedDefinition } from 'tldraw'
import 'tldraw/tldraw.css'

const myService: CustomEmbedDefinition = {
	type: 'myservice',
	title: 'My Service',
	hostnames: ['myservice.com'],
	width: 600,
	height: 400,
	doesResize: true,
	icon: 'https://myservice.com/favicon.png',
	toEmbedUrl: (url) => {
		const match = url.match(/myservice\.com\/item\/(\w+)/)
		if (match) {
			return `https://myservice.com/embed/${match[1]}`
		}
		return undefined
	},
	fromEmbedUrl: (url) => {
		const match = url.match(/myservice\.com\/embed\/(\w+)/)
		if (match) {
			return `https://myservice.com/item/${match[1]}`
		}
		return undefined
	},
	embedOnPaste: true,
}

const shapeUtils = [
	EmbedShapeUtil.configure({ embedDefinitions: [...DEFAULT_EMBED_DEFINITIONS, myService] }),
]

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

### Embed definition properties

| Property                   | Type                                   | Required | Description                                                               |
| -------------------------- | -------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `type`                     | `string`                               | Yes      | Unique identifier for this embed type                                     |
| `title`                    | `string`                               | Yes      | Display name shown in the UI                                              |
| `hostnames`                | `string[]`                             | Yes      | URL hostnames to match (supports glob patterns like `*.youtube.com`)      |
| `width`                    | `number`                               | Yes      | Default width in pixels                                                   |
| `height`                   | `number`                               | Yes      | Default height in pixels                                                  |
| `doesResize`               | `boolean`                              | Yes      | Whether the shape can be resized                                          |
| `toEmbedUrl`               | `(url: string) => string \| undefined` | Yes      | Convert shareable URL to embed URL                                        |
| `fromEmbedUrl`             | `(url: string) => string \| undefined` | Yes      | Convert embed URL to shareable URL                                        |
| `minWidth`                 | `number`                               | No       | Minimum width when resizing                                               |
| `minHeight`                | `number`                               | No       | Minimum height when resizing                                              |
| `isAspectRatioLocked`      | `boolean`                              | No       | Lock aspect ratio when resizing                                           |
| `canEditWhileLocked`       | `boolean`                              | No       | Allow interaction when shape is locked (default: true)                    |
| `overridePermissions`      | `TLEmbedShapePermissions`              | No       | Custom iframe sandbox permissions                                         |
| `sizeToContentAspectRatio` | `boolean`                              | No       | Correct the size to the content's real aspect ratio after creation        |
| `icon`                     | `string`                               | No       | Icon URL for the Insert embed dialog (`CustomEmbedDefinition` only)       |
| `backgroundColor`          | `string`                               | No       | Background color for the embed container                                  |
| `overrideOutlineRadius`    | `number`                               | No       | Custom border radius (Spotify uses 12px)                                  |
| `embedOnPaste`             | `boolean`                              | No       | When true, URLs are auto-converted to embeds on paste                     |
| `instructionLink`          | `string`                               | No       | Help URL for services requiring setup (like Google Calendar public links) |

## Embed-on-paste behavior

By default, pasting a URL from a supported service creates an embed shape. Set `embedOnPaste: false` in the embed definition to create a bookmark instead.

The tldraw embed definition sets `embedOnPaste: false`, so pasting a tldraw.com URL creates a bookmark. Separately, embed shapes refuse to render a nested tldraw canvas when the page itself is running inside an iframe, which prevents infinite nesting.

## Shape properties

| Property | Type     | Description                                                        |
| -------- | -------- | ------------------------------------------------------------------ |
| `url`    | `string` | The original URL (converted to embed URL internally); default `''` |
| `w`      | `number` | Width of the embed container; default `300`                        |
| `h`      | `number` | Height of the embed container; default `300`                       |

## SVG export

Embed shapes render as blank rectangles in SVG exports. The iframe content can't be captured directly, so exports show a placeholder with the embed's background color and border radius.

## Related articles

- [Default shapes](/sdk-features/default-shapes) — Overview of all built-in shape types
- [Bookmark shape](/sdk-features/default-shapes#bookmark) — URL link cards (fallback for non-embeddable URLs)
- [External content handling](/sdk-features/external-content) — Handling pasted and dropped content
- [Custom embeds example](/examples/configuration/custom-embed) — Add a custom embed definition for a new service

--------

# Environment detection

The tldraw SDK provides two objects for detecting the user's environment. [`tlenv`](/reference/editor/tlenv) holds fixed browser and platform information. [`tlenvReactive`](/reference/editor/tlenvReactive) holds values that change during a session, like whether the user is currently using touch input. We use these internally to work around browser quirks, and you can use them in custom shapes or tools.

## Static environment: tlenv

The `tlenv` object contains values detected at page load. These don't change during a session.

```typescript
import { tlenv } from 'tldraw'

// Browser detection
tlenv.isSafari // true if Safari (excluding Chrome on iOS)
tlenv.isFirefox // true if Firefox
tlenv.isChromeForIos // true if Chrome running on iOS

// Platform detection
tlenv.isIos // true if iPad or iPhone
tlenv.isAndroid // true if Android device
tlenv.isDarwin // true if macOS

// Capability detection
tlenv.hasCanvasSupport // true if Promise and HTMLCanvasElement exist
tlenv.isTouchDevice // true if the device has a touch screen
```

`isTouchDevice` reflects the hardware, so it stays true on a touchscreen laptop even while the user is using a mouse. For the pointer currently in use, read `isCoarsePointer` from `tlenvReactive` below.

### Common patterns

**Platform-specific keyboard shortcuts:**

```typescript
import { isAccelKey } from 'tldraw'

// Cmd on Mac, Ctrl elsewhere
if (isAccelKey(e)) {
	// Handle the shortcut
}
```

**Mobile detection:**

```typescript
const isMobile = tlenv.isIos || tlenv.isAndroid
if (isMobile) {
	// Adjust UI for mobile
}
```

**Browser-specific workarounds:**

```typescript
// Safari needs extra time for SVG image export
if (tlenv.isSafari) {
	await new Promise((r) => setTimeout(r, 250))
}
```

## Reactive environment: tlenvReactive

The `tlenvReactive` atom contains values that can change during a session: `isCoarsePointer` (the current pointer type) and `supportsP3ColorSpace` (whether the current display supports the P3 color gamut). Use [`useValue`](/reference/state-react/useValue) to subscribe to changes in React components.

```tsx
import { tlenvReactive, useValue } from 'tldraw'

function TouchFriendlyButton() {
	const { isCoarsePointer } = useValue(tlenvReactive)

	return (
		<button style={{ padding: isCoarsePointer ? 16 : 8 }}>
			{/* Larger touch target when using touch input */}
			Click me
		</button>
	)
}
```

### Coarse pointer detection

The `isCoarsePointer` value tracks whether the user is currently using touch input. We detect this two ways: by listening to the `(any-pointer: coarse)` media query, and by checking `pointerType` on each pointer down event. Any pointer that isn't a mouse counts as coarse, so pen input switches to coarse mode too. Laptops with touchscreens can switch input methods mid-session; the pointer down check catches that.

```typescript
import { tlenvReactive, react } from 'tldraw'

// Access the current value directly
const isCoarse = tlenvReactive.get().isCoarsePointer

// Subscribe to changes outside React
react('pointer type changed', () => {
	const { isCoarsePointer } = tlenvReactive.get()
	console.log('Coarse pointer:', isCoarsePointer)
})
```

Note: We force fine pointer mode on Firefox desktop regardless of the actual input device, since Firefox's coarse pointer reporting is unreliable there.

## Cross-window contexts

When the editor is mounted inside an iframe, an Electron pop-out window, or an Obsidian plugin, the global `document` and `window` aren't necessarily the ones the editor's DOM lives in. Reading `document.activeElement` or attaching a listener to the global `window` will silently fail or target the wrong frame.

Use the editor's container helpers instead of bare globals. They are marked internal, so their signatures may change, but they are what the SDK itself uses:

```typescript
const doc = editor.getContainerDocument() // the document the editor is mounted in
const win = editor.getContainerWindow() // the window the editor is mounted in
```

When you have a DOM node and want the document or window that owns it (rather than where the editor lives), use the standalone helpers:

```typescript
import { getOwnerDocument, getOwnerWindow } from 'tldraw'

const doc = getOwnerDocument(node)
const win = getOwnerWindow(node)
```

These are what the editor uses internally for export, measurement, focus tracking, and event listeners. Custom shapes and tools that touch the DOM directly should use them too. Anything that calls `document` or `window` directly will target the wrong realm once your app is embedded in an iframe or pop-out window.

## Browser quirks we handle

Here's a sample of what we use environment detection for internally.

**Safari** has the most workarounds. During SVG-to-image export, Safari fires the image's load event before the fonts inside the SVG have loaded, so we wait an extra 250ms—a WebKit bug that's been open for years. Text outlines are a performance problem on Safari, so we disable them there.

**iOS** support for coalesced pointer events is unreliable (`getCoalescedEvents` is sometimes missing entirely), so we skip coalesced events on iOS and dispatch individual pointer events instead. We also skip Safari's proprietary `GestureEvent` on iOS.

**Firefox** desktop's `(any-pointer: coarse)` media query reports false positives when a touchscreen is present but not in use. We force fine pointer mode on Firefox desktop to avoid jumpy UI.

**Chrome for iOS** has its own print implementation that doesn't trigger the standard `beforeprint` event, so we call our print handler manually before printing. Safari desktop needs `document.execCommand('print')` instead of `window.print()`.

See [Instance state](/sdk-features/instance-state) for `isCoarsePointer` on the instance record, which mirrors `tlenvReactive`.

--------

# Error handling

The editor uses multiple layers of React error boundaries to isolate failures. When a shape throws during render, only that shape shows a fallback. The rest of the editor keeps working. This matters because custom shapes are a common extension point, and third-party code should not crash the whole editor.

## Error boundary layers

Error boundaries exist at two levels.

At the application level, a boundary wraps the entire editor. If something throws here, the editor shows a full-screen error with options to refresh or reset local data. This is the last resort. There are actually two of these: an outer one that catches errors before the [`Editor`](/reference/editor/Editor) exists, and an inner one that has access to the editor, so it can annotate the error and still try to render your document behind the error screen.

At the shape level, each shape's component (and its background component, if it has one) renders inside its own boundary. A broken shape shows a fallback, but the user can still interact with everything else. ShapeUtil code is the most likely place for bugs, especially in custom shapes.

## Default fallbacks

Each boundary level has a default fallback component.

[`DefaultErrorFallback`](/reference/editor/DefaultErrorFallback) shows a modal with the error message and stack trace. It tries to render the canvas behind the modal so users can see their work is probably still there. The modal offers buttons to copy the error, refresh the page, or reset local data.

The default shape fallback renders a div with the class `tl-shape-error-boundary`, which the default CSS styles as a muted box labeled "Error" in the shape's place. Override this class if you want broken shapes to look different.

## Customizing error components

Replace either fallback through the `ErrorFallback` and `ShapeErrorFallback` keys of the [`TLEditorComponents`](/reference/editor/TLEditorComponents) `components` prop:

```tsx
import { Tldraw, TLErrorFallbackComponent, TLShapeErrorFallbackComponent } from 'tldraw'

const MyErrorFallback: TLErrorFallbackComponent = ({ error, editor }) => {
	return (
		<div className="my-error-screen">
			<h1>Oops!</h1>
			<p>{error instanceof Error ? error.message : String(error)}</p>
			<button onClick={() => window.location.reload()}>Refresh</button>
		</div>
	)
}

const MyShapeErrorFallback: TLShapeErrorFallbackComponent = ({ error }) => {
	return <div className="broken-shape">This shape failed to render</div>
}

;<Tldraw
	components={{
		ErrorFallback: MyErrorFallback,
		ShapeErrorFallback: MyShapeErrorFallback,
	}}
/>
```

Passing `null` for a fallback (with a cast, since the props are typed as components) disables the error boundary at that level. Errors propagate to the parent boundary instead.

## Crash handling

When an error is thrown inside a store transaction (anything wrapped in [`Editor.run`](/reference/editor/Editor#run), which includes most editor methods), the history manager catches it, annotates it, and puts the editor into a crashed state. Listen for this with the `crash` event:

```tsx
editor.on('crash', ({ error }) => {
	console.error('Editor crashed:', error)
	// Report to error tracking service
})
```

When crashed, the editor stops processing new events to prevent further damage and marks the store as possibly corrupted. The application-level error boundary then shows the fallback UI with its refresh and reset options.

## Error annotations

The SDK attaches debugging metadata to errors it catches, and you can add your own with `annotateError` from `@tldraw/utils`. Use `getErrorAnnotations` to read the tags and extras back, which is useful for error tracking services like Sentry:

```tsx
import { getErrorAnnotations, TLErrorFallbackComponent } from 'tldraw'

const MyErrorFallback: TLErrorFallbackComponent = ({ error }) => {
	const annotations = error instanceof Error ? getErrorAnnotations(error) : null

	// Send to error tracking
	if (annotations) {
		Sentry.setTags(annotations.tags)
		Sentry.setExtras(annotations.extras)
	}

	return (
		<div>
			<h1>Something went wrong</h1>
			<pre>{JSON.stringify(annotations, null, 2)}</pre>
		</div>
	)
}
```

Annotations include `tags` (key-value pairs for categorization) and `extras` (additional context data). `getErrorAnnotations` is currently marked internal, so its signature may change between versions.

## ErrorBoundary component

Use the exported [`ErrorBoundary`](/reference/editor/ErrorBoundary) component directly in your own code:

```tsx
import { ErrorBoundary, TLErrorFallbackComponent } from 'tldraw'

const MyFallback: TLErrorFallbackComponent = ({ error }) => (
	<div>Error: {error instanceof Error ? error.message : String(error)}</div>
)

function MyComponent() {
	return (
		<ErrorBoundary fallback={MyFallback} onError={(error) => console.error('Caught:', error)}>
			<RiskyComponent />
		</ErrorBoundary>
	)
}
```

The `fallback` prop accepts a [`TLErrorFallbackComponent`](/reference/editor/TLErrorFallbackComponent), which receives `{ error: unknown; editor?: Editor }`. `ErrorBoundary` itself only passes `error`; `editor` is provided by the editor's inner application-level boundary. The `onError` callback fires when an error is caught, before the fallback renders.

## API reference

| Symbol                             | Description                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------ |
| [`ErrorBoundary`](/reference/editor/ErrorBoundary)                 | Reusable error boundary component; see [`TLErrorBoundaryProps`](/reference/editor/TLErrorBoundaryProps)               |
| [`DefaultErrorFallback`](/reference/editor/DefaultErrorFallback)          | Default application-level error screen                                         |
| [`TLErrorFallbackComponent`](/reference/editor/TLErrorFallbackComponent)      | `ComponentType<{ error: unknown; editor?: Editor }>`, used for `ErrorFallback` |
| [`TLShapeErrorFallbackComponent`](/reference/editor/TLShapeErrorFallbackComponent) | `ComponentType<{ error: any }>`, used for `ShapeErrorFallback`                 |
| `annotateError`                    | Attach tags and extras to an error                                             |
| `getErrorAnnotations(error)`       | Read tags and extras from an error; marked internal                            |
| `crash` event                      | Emitted with `{ error: unknown }` when the editor enters the crashed state     |

## Related examples

- [Error boundary](/examples/ui/error-boundary): customize `ShapeErrorFallback` to display a custom message when shapes throw errors.
- [Custom error capture](/examples/ui/custom-error-capture): override `ErrorFallback` to create a custom error screen with annotations for debugging.

--------

# Events

The editor emits events for input, store changes, and lifecycle moments. Subscribe with `editor.on()` and unsubscribe with `editor.off()`. Use events to build analytics, sync external state, or extend editor behavior.

## Subscribing to events

The [`Editor`](/reference/editor/Editor) extends EventEmitter, and every event name and payload is typed by [`TLEventMap`](/reference/editor/TLEventMap):

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					editor.on('event', (info) => {
						console.log('Event:', info.type, info.name)
					})
				}}
			/>
		</div>
	)
}
```

Unsubscribe by calling `off()` with the same handler:

```tsx
const handleEvent: TLEventMapHandler<'event'> = (info) => {
	console.log('Event:', info.type)
}

editor.on('event', handleEvent)
editor.off('event', handleEvent)
```

Unsubscribe when the listener outlives the code that registered it. In React, return a cleanup function from your effect:

```tsx
useEffect(() => {
	const handleChange: TLEventMapHandler<'change'> = (entry) => {
		console.log('Store changed:', entry.changes)
	}

	editor.on('change', handleChange)
	return () => editor.off('change', handleChange)
}, [editor])
```

## Event categories

### Input events

The `event` and `before-event` events fire for every event the editor dispatches: user input plus the `misc` events (`cancel`, `complete`, `interrupt`, `tick`) that tools use internally. Each receives a [`TLEventInfo`](/reference/editor/TLEventInfo) object describing the event.

```tsx
editor.on('event', (info) => {
	if (info.type === 'pointer' && info.name === 'pointer_down') {
		console.log('Clicked at', info.point)
	}
})
```

`before-event` fires before the event reaches the tool state machine, and `event` fires after the tools have handled it.

Events have different types:

| Type       | Names                                                                                     | Description                         |
| ---------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| `pointer`  | `pointer_down`, `pointer_move`, `pointer_up`, `right_click`, `middle_click`, `long_press` | Mouse, touch, and pen interactions  |
| `click`    | `double_click`                                                                            | Double-click sequences              |
| `keyboard` | `key_down`, `key_up`, `key_repeat`                                                        | Keyboard input                      |
| `wheel`    | `wheel`                                                                                   | Scroll wheel and trackpad scrolling |
| `pinch`    | `pinch_start`, `pinch`, `pinch_end`                                                       | Two-finger pinch gestures           |
| `misc`     | `cancel`, `complete`, `interrupt`, `tick`                                                 | Internal tool lifecycle events      |

Pointer events include the target—what the pointer is over: `canvas`, `shape`, `selection`, `handle`, or `overlay`.

```tsx
editor.on('event', (info) => {
	if (info.type === 'pointer' && info.name === 'pointer_down') {
		switch (info.target) {
			case 'canvas':
				console.log('Clicked empty canvas')
				break
			case 'shape':
				console.log('Clicked shape:', info.shape.id)
				break
			case 'selection':
				console.log('Clicked selection bounds')
				break
			case 'handle':
				console.log('Clicked handle on:', info.shape.id)
				break
			case 'overlay':
				console.log('Clicked overlay:', info.overlay.type)
				break
		}
	}
})
```

### Shape events

Shape events fire from [`Editor.createShapes`](/reference/editor/Editor#createShapes), [`Editor.updateShapes`](/reference/editor/Editor#updateShapes), and [`Editor.deleteShapes`](/reference/editor/Editor#deleteShapes), just before the store is written. Changes from other sources (remote sync, undo/redo, direct `store.put` calls) don't fire them—use the `change` event for those.

| Event            | Payload       | Description                      |
| ---------------- | ------------- | -------------------------------- |
| `created-shapes` | `TLRecord[]`  | Shapes about to be added         |
| `edited-shapes`  | `TLRecord[]`  | Shapes about to be updated       |
| `deleted-shapes` | `TLShapeId[]` | Shapes about to be removed       |
| `edit`           | None          | Fires alongside any of the above |

```tsx
editor.on('created-shapes', (shapes) => {
	console.log('Created:', shapes.length, 'shapes')
})

editor.on('deleted-shapes', (ids) => {
	console.log('Deleted:', ids.length, 'shapes')
})
```

### Store changes

The `change` event fires whenever the store updates. It receives a [`HistoryEntry`](/reference/store/HistoryEntry) containing the diff and source:

```tsx
editor.on('change', (entry) => {
	const { added, updated, removed } = entry.changes

	for (const record of Object.values(added)) {
		if (record.typeName === 'shape') {
			console.log('Added shape:', record.type)
		}
	}

	for (const [from, to] of Object.values(updated)) {
		if (from.typeName === 'shape') {
			console.log('Updated shape:', from.id)
		}
	}

	for (const record of Object.values(removed)) {
		if (record.typeName === 'shape') {
			console.log('Removed shape:', record.id)
		}
	}
})
```

The `source` property indicates where the change originated:

```tsx
editor.on('change', (entry) => {
	if (entry.source === 'user') {
		// Change from local user interaction
		scheduleAutosave()
	} else if (entry.source === 'remote') {
		// Change from collaboration sync
	}
})
```

### Frame events

Two events fire on every animation frame, both carrying the milliseconds elapsed since the previous frame:

| Event   | Payload  | Description                                              |
| ------- | -------- | -------------------------------------------------------- |
| `frame` | `number` | Fires first; used internally (for example, for velocity) |
| `tick`  | `number` | Fires immediately after `frame`                          |

```tsx
editor.on('tick', (elapsed) => {
	// Update animations, physics, etc.
	updateParticleSystem(elapsed)
})
```

These fire frequently (60+ times per second). Keep handlers fast to avoid dropping frames.

### Lifecycle events

| Event     | Payload              | Description                  |
| --------- | -------------------- | ---------------------------- |
| `mount`   | None                 | Editor finished initializing |
| `unmount` | None                 | Editor component unmounted   |
| `dispose` | None                 | Editor is being cleaned up   |
| `crash`   | `{ error: unknown }` | Editor encountered an error  |
| `update`  | None                 | A store operation completed  |

```tsx
editor.on('mount', () => {
	console.log('Editor ready')
})

editor.on('crash', ({ error }) => {
	reportError(error)
})
```

### UI and camera events

| Event                   | Payload                   | Description                            |
| ----------------------- | ------------------------- | -------------------------------------- |
| `resize`                | `BoxModel`                | Viewport dimensions changed            |
| `stop-camera-animation` | None                      | Camera animation interrupted           |
| `stop-following`        | None                      | Stopped following another user         |
| `select-all-text`       | `{ shapeId: TLShapeId }`  | Editing started with all text selected |
| `place-caret`           | `{ shapeId, point }`      | Text caret positioned                  |
| `max-shapes`            | `{ name, pageId, count }` | Page reached shape limit               |

```tsx
editor.on('resize', (bounds) => {
	console.log('Canvas size:', bounds.w, 'x', bounds.h)
})

editor.on('max-shapes', ({ pageId, count }) => {
	showWarning(`Page has reached the ${count} shape limit`)
})
```

## UI events

The `Tldraw` component's `onUiEvent` prop captures high-level UI interactions separately from canvas events. This includes toolbar selections, menu actions, and keyboard shortcuts.

```tsx
<Tldraw
	onUiEvent={(name, data) => {
		console.log('UI event:', name, data)
	}}
/>
```

UI events track actions like selecting tools, grouping shapes, toggling dark mode, and zooming. They fire regardless of whether the action came from a click or keyboard shortcut. For the full list of events, see [`TLUiEventMap`](/reference/tldraw/TLUiEventMap).

## Listening to store changes directly

The `change` event is `editor.store.listen()` with no filters. For fine-grained control, call `listen()` directly:

```tsx
const cleanup = editor.store.listen(
	(entry) => {
		// Handle changes
	},
	{ source: 'user', scope: 'all' }
)

// Later, unsubscribe
cleanup()
```

The `listen()` method accepts filter options:

- `source`: `'user'`, `'remote'`, or `'all'`—filter by change origin
- `scope`: `'all'`, `'document'`, `'session'`, or `'presence'`—filter by record scope

See [Side effects](/sdk-features/side-effects) for registering handlers that can intercept and modify changes.

## Related examples

- [Canvas events](/examples/events/canvas-events) - Log pointer, keyboard, and wheel events as you interact with the canvas.
- [Store events](/examples/events/store-events) - Track shape creation, updates, and deletion through store change events.
- [UI events](/examples/events/ui-events) - Capture high-level UI interactions like tool selection and menu actions.

--------

# External content handling

The external content system handles content from outside the editor: pasted text, dropped files, embedded URLs, and more. You register handlers for specific content types, and the editor routes incoming content to the appropriate handler.

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

export default function App() {
	function handleMount(editor: Editor) {
		editor.registerExternalContentHandler('text', async (content) => {
			// Check if this is HTML content
			const htmlSource = content.sources?.find((s) => s.type === 'text' && s.subtype === 'html')
			if (htmlSource) {
				// Handle HTML specially
				const center = content.point ?? editor.getViewportPageBounds().center
				editor.createShape({
					type: 'text',
					x: center.x,
					y: center.y,
					props: { richText: toRichText('Custom HTML handling!') },
				})
			} else {
				// Fall back to default behavior
				await defaultHandleExternalTextContent(editor, content)
			}
		})
	}

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw onMount={handleMount} />
		</div>
	)
}
```

## How it works

Two systems handle external content. Content handlers transform external content into shapes: when a user pastes text, drops an image, or embeds a URL, the content handler for that type creates shapes on the canvas. Asset handlers turn external files and URLs into asset records: when an image file arrives, the asset handler extracts dimensions, uploads the file, and returns an asset record with the uploaded URL. The content handler then creates a shape referencing that asset.

The flow works like this:

1. Content arrives (paste, drop, or API call)
2. The editor calls `putExternalContent` with the content object (a no-op in readonly mode unless you pass `{ force: true }`)
3. The registered handler for that content type processes it
4. The handler creates shapes, assets, or both

`<Tldraw>` registers the default handlers before it runs your `onMount`, so any handler you register in `onMount` replaces the default for that type.

## Content types

Every content type carries an optional `point` (where to place the content) and `sources`, the other formats found on the clipboard alongside it (`text` with a `subtype` of `html`, `text`, `url`, or `json`, plus `tldraw`, `excalidraw`, and `error`).

```typescript
interface TLBaseExternalContent {
	sources?: TLExternalContentSource[]
	point?: VecLike
}
```

### Text

Text content comes from clipboard paste operations. The handler receives `text` (plain text) and optional `html`. The default handler creates a text shape, converting HTML to rich text when it's present, detecting right-to-left languages, and left-aligning multi-line text.

```typescript
interface TLTextExternalContent extends TLBaseExternalContent {
	type: 'text'
	text: string
	html?: string
}
```

### Files

File content represents one or more files dropped onto the canvas. The handler receives an array of `File` objects and validates file types and sizes before creating shapes. The `<Tldraw>` props `maxAssetSize`, `maxImageDimension`, `acceptedImageMimeTypes`, and `acceptedVideoMimeTypes` control those limits, and `editor.options.maxFilesAtOnce` caps the batch.

```typescript
interface TLFilesExternalContent extends TLBaseExternalContent {
	type: 'files'
	files: File[]
}
```

The default handler creates temporary previews for images, uploads the files, and creates image or video shapes arranged horizontally from the drop point.

### File replace

File replace content swaps an existing image or video shape's asset. The Replace media action dispatches it through [`Editor.replaceExternalContent`](/reference/editor/Editor#replaceExternalContent).

```typescript
interface TLFileReplaceExternalContent extends TLBaseExternalContent {
	type: 'file-replace'
	file: File
	shapeId: TLShapeId
	isImage: boolean // Deprecated: no longer used by the default handler
}
```

The default handler validates the file, creates a new asset, and updates the target shape to reference the new asset while preserving any existing crop settings.

### URLs

URL content represents a URL to insert. The default handler rejects invalid URLs with a toast, then checks if the URL matches a known embed pattern (YouTube, Figma, etc.) and creates an embed shape. Otherwise, it fetches Open Graph metadata and creates a bookmark shape.

```typescript
interface TLUrlExternalContent extends TLBaseExternalContent {
	type: 'url'
	url: string
}
```

### SVG text

SVG text content handles raw SVG markup. The handler sanitizes and parses the SVG, extracts dimensions, creates an image asset, and inserts an image shape.

```typescript
interface TLSvgTextExternalContent extends TLBaseExternalContent {
	type: 'svg-text'
	text: string
}
```

### Embeds

Embed content creates embed shapes for embeddable URLs like YouTube videos. This content type is usually invoked by the URL handler when it detects an embeddable URL.

```typescript
interface TLEmbedExternalContent<EmbedDefinition> extends TLBaseExternalContent {
	type: 'embed'
	url: string
	embed: EmbedDefinition
}
```

### tldraw and excalidraw content

These handlers process serialized content from other tldraw editors or Excalidraw. The `tldraw` handler calls `putContentOntoCurrentPage` to insert shapes. The `excalidraw` handler converts Excalidraw shapes to tldraw equivalents.

```typescript
interface TLTldrawExternalContent extends TLBaseExternalContent {
	type: 'tldraw'
	content: TLContent
}
```

## Asset handling

Asset handlers turn external files and URLs into asset records. There are two asset handler types:

| Type   | Input         | Output                                                                                          |
| ------ | ------------- | ----------------------------------------------------------------------------------------------- |
| `file` | `File` object | An asset record from whichever [`AssetUtil`](/reference/editor/AssetUtil) accepts the MIME type (image or video by default) |
| `url`  | URL string    | Bookmark asset with Open Graph metadata                                                         |

The default `file` handler checks the file's type and size, sanitizes SVGs, asks the matching asset util for an asset record, uploads the file via `editor.uploadAsset`, and returns the record. To support a new file type, register a custom [`AssetUtil`](/reference/editor/AssetUtil) (see [Assets](/sdk-features/assets)) rather than replacing this handler. The `url` handler fetches the page's Open Graph metadata (title, description, image) and creates a bookmark asset.

```typescript
import { AssetRecordType, MediaHelpers } from 'tldraw'

editor.registerExternalAssetHandler('file', async ({ file, assetId }) => {
	const size = await MediaHelpers.getImageSize(file)

	const asset = {
		id: assetId ?? AssetRecordType.createId(),
		type: 'image' as const,
		typeName: 'asset' as const,
		props: {
			name: file.name,
			src: '',
			w: size.w,
			h: size.h,
			mimeType: file.type,
			isAnimated: await MediaHelpers.isAnimated(file),
			fileSize: file.size,
		},
		meta: {},
	}

	const result = await editor.uploadAsset(asset, file)
	asset.props.src = result.src

	return AssetRecordType.create(asset)
})
```

## API methods

| Method                           | Purpose                                                 |
| -------------------------------- | ------------------------------------------------------- |
| `registerExternalContentHandler` | Register a handler for a content type                   |
| `registerExternalAssetHandler`   | Register a handler for an asset type                    |
| `putExternalContent`             | Process external content through the registered handler |
| `getAssetForExternalContent`     | Create an asset from external content                   |

Use `putExternalContent` to programmatically insert content:

```typescript
// Insert text at a specific point
editor.putExternalContent({
	type: 'text',
	text: 'Hello, world!',
	point: { x: 100, y: 100 },
})

// Insert a URL (creates embed or bookmark)
editor.putExternalContent({
	type: 'url',
	url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
	point: { x: 200, y: 200 },
})
```

Use `getAssetForExternalContent` when you need an asset without creating a shape:

```typescript
const asset = await editor.getAssetForExternalContent({
	type: 'file',
	file: myFile,
})
```

Remove a handler by passing `null`:

```typescript
editor.registerExternalContentHandler('text', null)
```

## Customizing handlers

Register a new handler to replace the default behavior for any content type. Your handler receives the content object and can create shapes, insert assets, or do anything else. To extend rather than replace, call the default handler from your custom handler, as the example at the top of this page does for text.

The default handlers are exported from `tldraw`. Some of them take a third [`TLDefaultExternalContentHandlerOpts`](/reference/tldraw/TLDefaultExternalContentHandlerOpts) argument carrying `toasts`, `msg`, and the file limits from `<Tldraw>`; get `toasts` and `msg` from [`useToasts`](/reference/tldraw/useToasts) and [`useTranslation`](/reference/tldraw/useTranslation) (or [`useDefaultHelpers`](/reference/tldraw/useDefaultHelpers)) inside the UI.

| Handler                                   | Extra options |
| ----------------------------------------- | ------------- |
| `defaultHandleExternalTextContent`        | No            |
| `defaultHandleExternalSvgTextContent`     | No            |
| `defaultHandleExternalEmbedContent`       | No            |
| `defaultHandleExternalTldrawContent`      | No            |
| `defaultHandleExternalExcalidrawContent`  | No            |
| `defaultHandleExternalFileContent`        | Yes           |
| `defaultHandleExternalFileReplaceContent` | Yes           |
| `defaultHandleExternalUrlContent`         | Yes           |
| `defaultHandleExternalFileAsset`          | Yes           |
| `defaultHandleExternalUrlAsset`           | Yes           |

```typescript
import { defaultHandleExternalFileContent, useToasts, useTranslation } from 'tldraw'

const toasts = useToasts()
const msg = useTranslation()

editor.registerExternalContentHandler('files', async (content) => {
	const small = content.files.filter((file) => file.size < 1024 * 1024)
	await defaultHandleExternalFileContent(editor, { ...content, files: small }, { toasts, msg })
})
```

For clipboard-only hooks that run before parsing or before the handler (`onClipboardPasteRaw`, `onBeforePasteFromClipboard`, `onBeforeCopyToClipboard`), see [Clipboard](/sdk-features/clipboard).

## Related examples

- [External content sources](/examples/data/assets/external-content-sources) - Handle pasted HTML by creating custom shapes.
- [Hosted images](/examples/data/assets/hosted-images) - Upload images to your own server using a custom asset store.

--------

# Focus

Focus determines whether the editor receives keyboard shortcuts and scroll wheel gestures. When focused, these inputs go to the editor. When unfocused, they pass through to the rest of your page.

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				autoFocus={false}
				onMount={(editor) => {
					// Focus later, for example when the user clicks the canvas
					const container = editor.getContainer()
					const focus = () => editor.focus()
					container.addEventListener('pointerdown', focus)
					return () => container.removeEventListener('pointerdown', focus)
				}}
			/>
		</div>
	)
}
```

## Controlling focus

Use [`Editor.focus`](/reference/editor/Editor#focus) and [`Editor.blur`](/reference/editor/Editor#blur) to programmatically control focus:

```typescript
editor.focus()
editor.blur()
editor.getIsFocused() // true or false
```

Both methods accept options to control whether the container element should also receive or lose DOM focus:

```typescript
editor.focus({ focusContainer: false })
editor.blur({ blurContainer: false })
```

Both are no-ops when the editor is already in that state. If the editor is focused but the container has lost DOM focus, call `editor.getContainer().focus()` directly.

### Focus/blur options

| Method  | Option           | Default | Description                                             |
| ------- | ---------------- | ------- | ------------------------------------------------------- |
| `focus` | `focusContainer` | `true`  | Whether to also call `focus()` on the container element |
| `blur`  | `blurContainer`  | `true`  | Whether to also call `blur()` on the container element  |

## Why focus is separate from DOM focus

The editor tracks focus separately from the browser's DOM focus. The browser's focus model isn't reliable enough for an editor like tldraw: iframes aren't considered descendants of their parent elements, and many menus are portalled into other parts of the document tree.

The editor maintains its own `isFocused` state in the instance record, readable with the reactive [`Editor.getIsFocused`](/reference/editor/Editor#getIsFocused). This lets you distinguish between "editor focus" (whether the editor responds to keyboard shortcuts) and "element focus" (which HTML element is active in the DOM).

When `isFocused` changes, the editor adds or removes the `tl-container__focused` CSS class on the container. Use this class for styling instead of `:focus` or `:focus-within` pseudo-selectors, which can't reliably detect editor focus.

## Auto-focus

The `autoFocus` prop controls whether the editor focuses when it mounts. It defaults to `true`. Set it to `false` when embedding the editor in a page where you don't want it to capture keyboard input immediately.

```tsx
<Tldraw autoFocus={false} />
```

## Focus ring visibility

The editor manages focus ring visibility for accessibility. Focus rings appear around focused elements during keyboard navigation but are hidden during mouse interactions.

When you press Tab, ArrowUp, or ArrowDown, the editor removes the `tl-container__no-focus-ring` class to show focus rings. Mouse clicks add the class back to hide them. Focus rings stay hidden while editing a shape, and while the container itself is focused with shapes selected (arrow keys nudge shapes then).

## Completing interactions on blur

When you call `editor.blur()`, it calls `editor.complete()` to finish any ongoing interaction like a drag or draw operation. This prevents the editor from being left mid-interaction when focus is lost.

## Multiple editors

When you have multiple editors on the same page, you'll need to manage focus yourself. The browser's DOM focus alone isn't enough to reliably switch which editor receives keyboard input.

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

function MultipleEditors() {
	const [editors, setEditors] = useState<Editor[]>([])

	function handleEditorFocus(focusedEditor: Editor) {
		for (const editor of editors) {
			if (editor === focusedEditor) {
				editor.focus()
			} else {
				editor.blur()
			}
		}
	}

	return (
		<>
			<div onFocus={() => editors[0] && handleEditorFocus(editors[0])}>
				<Tldraw autoFocus={false} onMount={(e) => setEditors((prev) => [...prev, e])} />
			</div>
			<div onFocus={() => editors[1] && handleEditorFocus(editors[1])}>
				<Tldraw autoFocus={false} onMount={(e) => setEditors((prev) => [...prev, e])} />
			</div>
		</>
	)
}
```

This switches focus when a wrapper receives DOM focus. To also blur when the user clicks elsewhere on the page, listen for pointer down on the page as the [multiple editors example](/examples/layout/multiple) does.

## Related examples

- [Editor focus](/examples/editor-api/editor-focus) - Control editor focus with focus and blur methods.
- [Multiple editors](/examples/layout/multiple) - Manage focus between multiple tldraw instances.

--------

# Frame shape

The frame shape is a container with a labeled header that holds other shapes. Children of a frame are clipped to its bounds, follow the frame when it moves, and export together as a single image. Frames are useful for laying out artboards, screen mockups, slides, and any visual region that should travel as one unit. See [`FrameShapeUtil`](/reference/tldraw/FrameShapeUtil) and [`TLFrameShape`](/reference/tlschema/TLFrameShape).

```tsx
editor.createShape({
	type: 'frame',
	x: 100,
	y: 100,
	props: {
		w: 800,
		h: 600,
		name: 'Login screen',
		color: 'black',
	},
})
```

## Creating frames

You can create a frame programmatically with [`Editor.createShape`](/reference/editor/Editor#createShape), or interactively with the frame tool. The frame tool ships in the default toolbar; users can also press `F` to switch to it. The **Frame selection** action (`Cmd/Ctrl+Alt+G`) wraps the current selection in a new frame.

When the user drags a frame around existing shapes, the frame tool reparents any sibling shapes that fall fully inside the frame's bounds. Locked shapes are skipped. This is what makes "draw a frame around the things I want to group" work as a single gesture.

Children inside a frame use coordinates relative to the frame's origin. Moving the frame moves every descendant; rotating the frame rotates them too.

## Frame header

Every frame renders a heading above its top edge that displays the frame's `name` property. Click the heading to edit the name; pressing Enter with a frame selected does not enter edit mode. The heading rotates with the frame to stay above whichever edge is currently "up", so it remains readable.

Empty names render as `Frame` so unnamed frames still get a label. The shape's `name` is also exposed via [`ShapeUtil.getAriaDescriptor`](/reference/editor/ShapeUtil#getAriaDescriptor) so screen readers announce it during keyboard navigation.

## Child clipping

Frames clip their children to the frame's rectangle during rendering. A shape that extends past the frame edge is rendered up to the boundary and then cut off. Clipping doesn't change the child's geometry or its own bounds, but hit testing respects the mask: you can't click the clipped-off part of a shape, and [`Editor.getShapeMaskedPageBounds`](/reference/editor/Editor#getShapeMaskedPageBounds) returns only the visible portion. Arrows are exempt from clipping so connectors can leave a frame.

The [`BaseFrameLikeShapeUtil`](/reference/editor/BaseFrameLikeShapeUtil) base class implements clipping via `getClipPath` and the arrow exemption via `shouldClipChild`. If you need clipping for a custom container shape, see the [Frames](/sdk-features/shapes#frames) section in the Shapes guide.

## Shape properties

| Property | Type                  | Description                                          |
| -------- | --------------------- | ---------------------------------------------------- |
| `w`      | `number`              | Frame width in pixels (default: `320`)               |
| `h`      | `number`              | Frame height in pixels (default: `180`)              |
| `name`   | `string`              | Label displayed in the frame header                  |
| `color`  | `TLDefaultColorStyle` | Color for the border and heading (when `showColors`) |

## Configuration options

`FrameShapeUtil` exposes two configuration options:

| Option           | Type      | Default | Description                                                                                             |
| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `showColors`     | `boolean` | `false` | When true, frames display a colored border and header background based on the frame's `color` property. |
| `resizeChildren` | `boolean` | `false` | When true, resizing a frame scales its children proportionally instead of leaving them in place.        |

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

const ConfiguredFrameUtil = FrameShapeUtil.configure({
	showColors: true,
	resizeChildren: true,
})

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

When `showColors` is on, `color` becomes a real style property: users can change it from the style panel and it syncs across selections like other styles. With `showColors` off (the default), `color` still validates and persists, but the frame renders with a neutral palette so it doesn't compete visually with the shapes inside it.

## Frame helpers

The editor exposes helpers that work with frames and any other shape that opts into frame-like behavior. Use [`Editor.isShapeFrameLike`](/reference/editor/Editor#isShapeFrameLike) to check whether a shape is a frame or a custom frame-like shape.

### Fitting a frame to its content

[`fitFrameToContent`](/reference/tldraw/fitFrameToContent) resizes a frame so it tightly wraps its children, with a configurable padding (50 by default). Double-clicking a frame's corner handle does the same with a padding of 10; double-clicking an edge handle fits only that axis.

```tsx
import { fitFrameToContent } from 'tldraw'

fitFrameToContent(editor, frameId)

// Or with a custom padding
fitFrameToContent(editor, frameId, { padding: 24 })
```

### Removing a frame

[`removeFrame`](/reference/tldraw/removeFrame) deletes a frame but preserves its children: they're moved out of the frame and reselected.

```tsx
import { removeFrame } from 'tldraw'

removeFrame(editor, [frameId])
```

The **Remove frame** and **Fit frame to content** actions in the main menu and the context menu's Edit submenu call these helpers when a frame is selected. **Frame selection** (`Cmd/Ctrl+Alt+G`) also removes frames when every selected shape is a frame.

## Exporting frames

Frames are export bounds containers: [`ShapeUtil.isExportBoundsContainer`](/reference/editor/ShapeUtil#isExportBoundsContainer) returns `true`. When a frame contains all the other shapes in an export, the export pipeline skips the usual padding around the result and uses the frame's bounds exactly. The export still includes every descendant of the frame.

This suits mockup workflows where you need output at a specific aspect ratio: design the frame, drop content inside, export.

## Frames vs. groups

Frames and groups both contain other shapes, but they solve different problems:

|                              | Frame                                    | Group                                   |
| ---------------------------- | ---------------------------------------- | --------------------------------------- |
| Visible on the canvas        | Yes, a bordered rectangle with a heading | No                                      |
| Clips children to its bounds | Yes                                      | No                                      |
| Has a fixed size and shape   | Yes (`w`, `h`, position)                 | No (geometry follows children)          |
| Used for export bounds       | Yes                                      | No                                      |
| Auto-deletes when empty      | No                                       | Yes (collapses at one or zero children) |
| Created by                   | Frame tool or `editor.createShape`       | [`Editor.groupShapes`](/reference/editor/Editor#groupShapes)                 |

Reach for a frame when you want a labeled, bounded region: a slide, a screen, an artboard. Reach for a group when you need to move several shapes together without changing their visual layout.

## Related articles

- [Shapes](/sdk-features/shapes#frames) — How to build your own container shape with `BaseFrameLikeShapeUtil`
- [Default shapes](/sdk-features/default-shapes#frame) — Overview of all built-in shapes
- [Shape clipping](/sdk-features/shape-clipping) — How custom shapes can clip their children
- [Image export](/sdk-features/image-export) — Exporting frames and selections as images
- [Parenting](/sdk-features/parenting) — How shapes are nested inside containers

## Related examples

- [Portal shapes](/examples/shapes/tools/portal-shapes) — A custom frame-like shape that teleports children between instances

--------

# Geo shape

The geo shape is one of the default shapes in tldraw. It renders one of 20 built-in geometric forms (rectangles, ellipses, stars, clouds, and more) with an optional rich text label. Geo shapes are the usual building blocks for flowcharts and diagrams.

## Geometric forms

The geo shape supports a variety of built-in forms, grouped by type:

### Basic shapes

| Form        | Description                                  |
| ----------- | -------------------------------------------- |
| `rectangle` | Four-sided shape with right angles (default) |
| `ellipse`   | Oval or circular shape                       |
| `triangle`  | Three-sided shape pointing upward            |
| `diamond`   | Square rotated 45 degrees                    |
| `oval`      | Stadium shape (rectangle with rounded ends)  |

### Polygons

| Form       | Description                 |
| ---------- | --------------------------- |
| `pentagon` | Five-sided regular polygon  |
| `hexagon`  | Six-sided regular polygon   |
| `octagon`  | Eight-sided regular polygon |
| `star`     | Five-pointed star           |

### Parallelograms

| Form        | Description                                   |
| ----------- | --------------------------------------------- |
| `rhombus`   | Parallelogram slanted to the right            |
| `rhombus-2` | Parallelogram slanted to the left             |
| `trapezoid` | Four-sided shape with parallel top and bottom |

### Directional arrows

| Form          | Description                   |
| ------------- | ----------------------------- |
| `arrow-up`    | Block arrow pointing upward   |
| `arrow-down`  | Block arrow pointing downward |
| `arrow-left`  | Block arrow pointing left     |
| `arrow-right` | Block arrow pointing right    |

### Special shapes

| Form        | Description                                    |
| ----------- | ---------------------------------------------- |
| `cloud`     | Organic cloud shape with randomly varied bumps |
| `heart`     | Heart shape                                    |
| `x-box`     | Rectangle with an X through it                 |
| `check-box` | Rectangle with a checkmark inside              |

## Creating geo shapes

Create a geo shape using [`Editor.createShape`](/reference/editor/Editor#createShape):

```tsx
import { toRichText } from 'tldraw'

editor.createShape({
	type: 'geo',
	x: 100,
	y: 100,
	props: {
		geo: 'rectangle',
		w: 200,
		h: 150,
		color: 'blue',
		fill: 'solid',
		dash: 'draw',
		size: 'm',
	},
})
```

### Adding text labels

Geo shapes support rich text labels positioned inside the shape:

```tsx
editor.createShape({
	type: 'geo',
	x: 100,
	y: 100,
	props: {
		geo: 'ellipse',
		w: 200,
		h: 150,
		richText: toRichText('Process step'),
		labelColor: 'black',
		align: 'middle',
		verticalAlign: 'middle',
		font: 'draw',
	},
})
```

The label text wraps within the shape bounds. When text overflows the shape height, the shape grows vertically and tracks the extra height in `growY`. If the label's minimum width is wider than the shape, the shape widens to fit it.

### Changing the geometric form

Switch between forms by updating the `geo` property:

```tsx
// Change a rectangle to an ellipse
editor.updateShape({
	id: shapeId,
	type: 'geo',
	props: {
		geo: 'ellipse',
	},
})
```

You can also set the default geometric form for the geo tool by updating the style for the next shape:

```tsx
import { GeoShapeGeoStyle } from 'tldraw'

// Set the default geo style to star
editor.setStyleForNextShapes(GeoShapeGeoStyle, 'star')
```

The geo tool's toolbar shortcuts are R for rectangle and O for ellipse.

## Using the geo tool

The geo tool creates shapes through click or click-and-drag interactions.

### Click to create

Click anywhere on the canvas to create a shape at the default size. The shape centers on your click position. Different geometric forms have different default sizes:

| Form    | Default size |
| ------- | ------------ |
| `star`  | 200 × 190    |
| `cloud` | 300 × 180    |
| Other   | 200 × 200    |

### Click and drag to create

Click and drag to create a shape at a custom size. The shape's corner follows your pointer as you drag. Release to complete the shape.

### Editing labels

Press Enter while a geo shape is selected to edit its label. The shape enters edit mode, where you can type or modify the rich text content. Press Escape to exit edit mode.

### Tool lock

When tool lock is enabled (via the toolbar or `editor.updateInstanceState({ isToolLocked: true })`), you can create multiple shapes without returning to the select tool after each one.

## Shape properties

| Property        | Type                            | Description                                                 |
| --------------- | ------------------------------- | ----------------------------------------------------------- |
| `geo`           | `TLGeoShapeGeoStyle`            | The geometric form                                          |
| `w`             | `number`                        | Width in pixels                                             |
| `h`             | `number`                        | Height in pixels                                            |
| `richText`      | `TLRichText`                    | Text label displayed inside the shape                       |
| `color`         | `TLDefaultColorStyle`           | Stroke/outline color                                        |
| `labelColor`    | `TLDefaultColorStyle`           | Text label color (separate from stroke)                     |
| `fill`          | `TLDefaultFillStyle`            | Fill style, e.g. `none`, `semi`, `solid`, `pattern`         |
| `dash`          | `TLDefaultDashStyle`            | Stroke pattern: `draw`, `solid`, `dashed`, `dotted`, `none` |
| `size`          | `TLDefaultSizeStyle`            | Size preset affecting stroke width                          |
| `font`          | `TLDefaultFontStyle`            | Font family for the label                                   |
| `align`         | `TLDefaultHorizontalAlignStyle` | Horizontal text alignment                                   |
| `verticalAlign` | `TLDefaultVerticalAlignStyle`   | Vertical text alignment                                     |
| `growY`         | `number`                        | Additional vertical space for text overflow                 |
| `url`           | `string`                        | Optional hyperlink URL                                      |
| `scale`         | `number`                        | Scale factor applied to the shape                           |
| `flipX`         | `boolean`                       | Mirror the shape horizontally                               |
| `flipY`         | `boolean`                       | Mirror the shape vertically                                 |

## Configuration options

Configure [`GeoShapeUtil`](/reference/tldraw/GeoShapeUtil) to adjust rendering behavior:

| Option            | Type      | Default | Description                                                                                      |
| ----------------- | --------- | ------- | ------------------------------------------------------------------------------------------------ |
| `showTextOutline` | `boolean` | `true`  | Whether to show a text outline (using the canvas background color) to improve label readability. |

```tsx
import { GeoShapeUtil } from 'tldraw'

const ConfiguredGeoUtil = GeoShapeUtil.configure({
	showTextOutline: false,
})
```

Pass the configured utility to the `shapeUtils` prop:

```tsx
<Tldraw shapeUtils={[ConfiguredGeoUtil]} />
```

## Custom geo types

Register custom geo types via `customGeoTypes` to add new forms without forking [`GeoShapeUtil`](/reference/tldraw/GeoShapeUtil). Custom types inherit all standard geo behavior (labels, fill/dash/color styling, resizing, SVG export, and hyperlinks) and provide their own path geometry, snap behavior, creation size, and style panel icon.

```tsx
import { GeoShapeUtil, PathBuilder } from 'tldraw'

const MyGeoShapeUtil = GeoShapeUtil.configure({
	customGeoTypes: {
		'rounded-rect': {
			getPath: (w, h, shape, strokeWidth) => {
				const r = Math.min(w, h) * 0.2
				return new PathBuilder()
					.moveTo(r, 0, { geometry: { isFilled: shape.props.fill !== 'none' } })
					.lineTo(w - r, 0)
					.circularArcTo(r, false, true, w, r)
					.lineTo(w, h - r)
					.circularArcTo(r, false, true, w - r, h)
					.lineTo(r, h)
					.circularArcTo(r, false, true, 0, h - r)
					.lineTo(0, r)
					.circularArcTo(r, false, true, r, 0)
					.close()
			},
			snapType: 'polygon',
			icon: 'geo-rectangle',
			defaultSize: { w: 200, h: 150 },
		},
	},
})
```

Each entry in `customGeoTypes` is a [`GeoTypeDefinition`](/reference/tldraw/GeoTypeDefinition). Keys that collide with a built-in form are ignored with a console warning.

| Field           | Type                                        | Description                                                                                          |
| --------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `getPath`       | `(w, h, shape, strokeWidth) => PathBuilder` | Returns the path geometry for this type at the given dimensions.                                     |
| `snapType`      | `'polygon' \| 'blobby'`                     | `'polygon'` snaps to vertices and center; `'blobby'` snaps to center only.                           |
| `icon`          | `string`                                    | Icon name used in the style panel's geo picker.                                                      |
| `defaultSize`   | `{ w: number; h: number }` (optional)       | Size used when the shape is created via click rather than drag. Defaults to 200 × 200.               |
| `onDoubleClick` | `(shape) => { props } \| void` (optional)   | Custom double-click handler. Return a partial props update to mutate the shape, or nothing to no-op. |

Custom types appear in the style panel's geo picker alongside the built-in shapes. See the [custom geo types example](/examples/shapes/tools/custom-geo-types) for a full implementation.

## Label positioning

The `align` and `verticalAlign` properties control where labels appear within the shape:

### Horizontal alignment

| Value    | Position              |
| -------- | --------------------- |
| `start`  | Left edge of shape    |
| `middle` | Horizontally centered |
| `end`    | Right edge of shape   |

### Vertical alignment

| Value    | Position            |
| -------- | ------------------- |
| `start`  | Top of shape        |
| `middle` | Vertically centered |
| `end`    | Bottom of shape     |

When the label text exceeds the shape's height, the shape automatically grows by adding to `growY`. The shape never shrinks below its original `h` value to accommodate shorter text—instead, `growY` returns to 0.

## Resizing behavior

Geo shapes resize from any corner or edge handle. When resizing a shape with a label:

- The shape won't shrink smaller than the label's measured dimensions
- `growY` resets to 0 when you resize, and the shape recalculates the needed height
- Dragging a handle past the opposite edge flips the shape by toggling `flipX` or `flipY`

When you first add a label to a shape smaller than 51 × 51 unscaled pixels, the shape grows to at least that size and becomes square.

## Special interactions

### Rectangle/checkbox toggle

Double-click a rectangle while holding Alt to convert it to a checkbox. Double-click the checkbox with Alt held to convert it back to a rectangle. This lets you quickly add checkmarks to items.

### Cloud shape variation

The cloud shape generates its bumps procedurally based on the shape's ID. Each cloud has unique bump positions, giving visual variety while maintaining a consistent style. Larger clouds have more bumps; smaller clouds have fewer but at least six.

### Handle snap geometry

When you drag a line handle (or any custom handle with `snapType` set) near a geo shape, it snaps to the shape's outline. Polygon-based forms (rectangle, triangle, pentagon, and so on) also snap to each vertex and the center; curved forms (ellipse, oval, cloud, heart) snap only to the center. Arrow terminals bind to geo shapes through a separate system; see [Bindings](/sdk-features/bindings).

## Dynamic resize mode

When dynamic resize mode is enabled in user preferences, new geo shapes scale inversely with zoom level. Drawing while zoomed out creates shapes that appear the same size on screen as they would at 100% zoom.

```tsx
// Enable dynamic resize mode
editor.user.updateUserPreferences({ isDynamicSizeMode: true })
```

## Hyperlinks

Geo shapes can link to URLs. When a shape has a URL, a link button appears on the shape:

```tsx
editor.createShape({
	type: 'geo',
	x: 100,
	y: 100,
	props: {
		geo: 'rectangle',
		w: 200,
		h: 100,
		url: 'https://tldraw.dev',
	},
})
```

Click the link button to open the URL in a new tab.

## Path rendering

Geo shapes use a path-based rendering system. Each geometric form, built-in or custom, has a [`GeoTypeDefinition`](/reference/tldraw/GeoTypeDefinition) whose `getPath` method generates the outline used for both fills and strokes. The same path drives solid, semi-transparent, and pattern fills as well as solid, dashed, and dotted stroke styles. Path calculations are cached per shape.

When the `dash` property is set to `'draw'`, the shape renders with organic, hand-drawn strokes. The randomness is seeded by the shape's ID, so each shape's hand-drawn look stays stable across renders.

## Geometry

The shape's geometry returns a [`Group2d`](/reference/editor/Group2d) containing:

1. The outline path geometry (polygon or curve depending on the form)
2. A label rectangle for hit testing text interactions

The label rectangle is excluded from the shape's bounds but used for hit testing.

## Related articles

- [Default shapes](/sdk-features/default-shapes) — Overview of all built-in shapes
- [Rich text](/sdk-features/rich-text) — Working with formatted text content
- [Styles](/sdk-features/styles) — Working with shape styles like color and fill
- [Tools](/sdk-features/tools) — How tools handle user input

--------

# Geometry

Geometry in tldraw is a mathematical description of a shape's form. Each shape has a [`Geometry2d`](/reference/editor/Geometry2d) that defines its outline, bounds, and spatial properties. The editor uses it to decide whether a click hit the shape, whether a selection brush intersects it, and where an arrow should snap to its edge. For the broader shape system, see [Shapes](/sdk-features/shapes).

## How geometry works

Each [`ShapeUtil`](/reference/editor/ShapeUtil) implements a [`ShapeUtil.getGeometry`](/reference/editor/ShapeUtil#getGeometry) method that returns a [`Geometry2d`](/reference/editor/Geometry2d) instance. The editor calls this method to calculate bounds, test hits, find intersections, and measure distances. It receives an optional [`TLGeometryOpts`](/reference/editor/TLGeometryOpts) with a `context` string, and callers can pass the same option to [`Editor.getShapeGeometry`](/reference/editor/Editor#getShapeGeometry) to request context-specific geometry.

```typescript
class MyShapeUtil extends ShapeUtil<MyShape> {
	getGeometry(shape: MyShape): Geometry2d {
		return new Rectangle2d({
			width: shape.props.w,
			height: shape.props.h,
			isFilled: true,
		})
	}
}
```

The `isFilled` property controls hit testing behavior. A filled geometry registers hits inside its area. An unfilled geometry only responds to hits on its outline—useful for shapes like frames where you want to click through the middle.

Geometry also powers [snapping](/sdk-features/snapping). When you drag shapes, the snapping system uses geometry to find edges, centers, and corners to align to. Custom shapes can provide additional snap points by implementing [`ShapeUtil.getBoundsSnapGeometry`](/reference/editor/ShapeUtil#getBoundsSnapGeometry).

## Geometry primitives

The SDK includes geometry classes for common shapes.

### Rectangle2d

Axis-aligned rectangles. The most common geometry for box-shaped elements.

```typescript
new Rectangle2d({
	width: 200,
	height: 100,
	isFilled: true,
})
```

You can offset the rectangle from the origin:

```typescript
new Rectangle2d({
	x: 10,
	y: 10,
	width: 200,
	height: 100,
	isFilled: true,
})
```

### Ellipse2d

Circles and ellipses.

```typescript
new Ellipse2d({
	width: 100,
	height: 100, // circle
	isFilled: true,
})

new Ellipse2d({
	width: 200,
	height: 100, // ellipse
	isFilled: true,
})
```

### Circle2d

A specialized circle geometry that stores radius directly. The `x` and `y` parameters offset the circle's bounding box, not its center.

```typescript
new Circle2d({
	radius: 50,
	isFilled: true,
})

// Offset from origin
new Circle2d({
	x: 10,
	y: 10,
	radius: 50,
	isFilled: true,
})
```

### Polygon2d

Arbitrary closed polygons defined by vertices.

```typescript
new Polygon2d({
	points: [new Vec(0, 50), new Vec(100, 0), new Vec(100, 100), new Vec(0, 100)],
	isFilled: true,
})
```

Polygon2d requires at least three points and automatically closes the path.

### Polyline2d

Open paths defined by vertices. Use this for lines that don't form closed shapes. Requires at least two points.

```typescript
new Polyline2d({
	points: [new Vec(0, 0), new Vec(50, 100), new Vec(100, 0)],
})
```

Polylines are never filled since they don't enclose an area. Polygon2d extends Polyline2d but sets `isClosed` to true.

### Edge2d

A single line segment between two points.

```typescript
new Edge2d({
	start: new Vec(0, 0),
	end: new Vec(100, 100),
})
```

Arrows use Edge2d for straight arrow bodies.

### Arc2d

A circular arc defined by center, start, end, and arc flags. All parameters are required.

```typescript
new Arc2d({
	center: new Vec(50, 50),
	start: new Vec(0, 50),
	end: new Vec(100, 50),
	sweepFlag: 1,
	largeArcFlag: 0,
})
```

The `sweepFlag` and `largeArcFlag` follow SVG arc conventions: `sweepFlag` controls clockwise vs counterclockwise direction, and `largeArcFlag` chooses between the two possible arcs. Arrows use Arc2d for curved arrow bodies.

### Stadium2d

A pill or capsule shape (rectangle with semicircular ends). The shorter dimension determines the radius of the rounded ends.

```typescript
new Stadium2d({
	width: 200,
	height: 50,
	isFilled: true,
})
```

### CubicBezier2d

A single cubic bezier curve segment.

```typescript
new CubicBezier2d({
	start: new Vec(0, 0),
	cp1: new Vec(30, 100),
	cp2: new Vec(70, 100),
	end: new Vec(100, 0),
})
```

### CubicSpline2d

A smooth curve through multiple points, automatically generating smooth cubic bezier segments between them.

```typescript
new CubicSpline2d({
	points: [new Vec(0, 0), new Vec(50, 100), new Vec(100, 50), new Vec(150, 100)],
})
```

### Point2d

A single point. The constructor requires both `point` and `margin` parameters.

```typescript
new Point2d({
	point: new Vec(50, 50),
	margin: 10,
})
```

The `margin` option doesn't expand the hit area: hit-test margins are supplied by the editor at query time, like every other geometry.

### Group2d

Combines multiple geometries into a single composite geometry. The children don't need to be the same type.

```typescript
new Group2d({
	children: [
		new Rectangle2d({ width: 100, height: 80, isFilled: true }),
		new Circle2d({ x: 50, y: -20, radius: 20, isFilled: true }),
	],
})
```

Use Group2d for shapes with multiple parts. The geo shape uses it to combine its outline with its label bounds. The arrow shape uses it to combine the arrow body with its label. Nested groups are flattened: a Group2d passed as a child contributes its own children.

## Geometry operations

All Geometry2d classes provide methods for spatial queries.

### Bounds and center

Get the axis-aligned bounding box:

```typescript
const geometry = editor.getShapeGeometry(shape)
const bounds = geometry.bounds // Box { x, y, w, h, ... }
const center = geometry.center // Vec at center of bounds
```

### Vertices

Get the points that define the geometry's outline:

```typescript
const vertices = geometry.vertices // Vec[]
```

For curves, this returns a discretized approximation. By default `vertices` excludes label geometry.

### Hit testing

Test if a point hits the geometry:

```typescript
geometry.hitTestPoint(point, margin, hitInside)
```

The `margin` expands the hit area. The `hitInside` parameter controls whether points inside unfilled shapes count as hits.

Test if a line segment passes within `distance` of the geometry:

```typescript
geometry.hitTestLineSegment(A, B, distance)
```

After a hit succeeds, the editor calls `geometry.ignoreHit(point)`. Override it to reject hits at specific points and let shapes behind this one be selected instead; the image shape uses this for transparent pixels.

### Distance and intersection

Find the nearest point on the geometry to a given point:

```typescript
const nearest = geometry.nearestPoint(point)
```

Get the distance from a point to the geometry:

```typescript
const distance = geometry.distanceToPoint(point)
```

Negative distances mean the point is inside a filled geometry.

Get intersection points with a line segment, circle, polygon, or polyline:

```typescript
const intersections = geometry.intersectLineSegment(A, B)
const circleHits = geometry.intersectCircle(center, radius)
const polygonHits = geometry.intersectPolygon(points)
```

### Length, area, and interpolation

Get the perimeter length and area:

```typescript
const length = geometry.length // perimeter length
const area = geometry.area // enclosed area (0 for open paths)
```

A Group2d reports the area of its first child, not the union of its children.

Find a point at a fraction along the edge:

```typescript
const point = geometry.interpolateAlongEdge(0.5) // midpoint
```

Convert a point back to a fraction:

```typescript
const t = geometry.uninterpolateAlongEdge(point)
```

Generate an SVG path:

```typescript
const pathData = geometry.toSimpleSvgPath() // "M0,0 L100,0 L100,100 L0,100 Z"
```

## Implementing getGeometry

The `getGeometry` method receives the shape and returns geometry in shape-local coordinates (origin at top-left of shape).

### Simple shapes

For shapes with a single outline:

```typescript
getGeometry(shape: MyShape) {
	return new Rectangle2d({
		width: shape.props.w,
		height: shape.props.h,
		isFilled: shape.props.fill !== 'none',
	})
}
```

### Shapes with labels

Shapes that have text labels typically return a Group2d with the main geometry and a label rectangle:

```typescript
getGeometry(shape: MyShape) {
	const outline = new Rectangle2d({
		width: shape.props.w,
		height: shape.props.h,
		isFilled: shape.props.fill !== 'none',
	})

	const label = new Rectangle2d({
		x: labelX,
		y: labelY,
		width: labelWidth,
		height: labelHeight,
		isFilled: true,
		isLabel: true,
	})

	return new Group2d({
		children: [outline, label],
	})
}
```

The `isLabel` property marks geometry that represents text labels; see [Geometry filtering](#Geometry-filtering).

### Custom polygons

For non-rectangular shapes, calculate vertices and use Polygon2d:

```typescript
getGeometry(shape: HouseShape) {
	const { w, h } = shape.props
	const roofPeak = h * 0.3

	return new Polygon2d({
		points: [
			new Vec(0, roofPeak),
			new Vec(w / 2, 0),
			new Vec(w, roofPeak),
			new Vec(w, h),
			new Vec(0, h),
		],
		isFilled: true,
	})
}
```

### Composite shapes

For shapes with multiple distinct parts:

```typescript
getGeometry(shape: HouseShape) {
	const house = new Polygon2d({
		points: getHouseVertices(shape),
		isFilled: true,
	})

	const door = new Rectangle2d({
		x: shape.props.w / 2 - 15,
		y: shape.props.h - 40,
		width: 30,
		height: 40,
		isFilled: true,
	})

	return new Group2d({
		children: [house, door],
	})
}
```

## Geometry caching

The editor caches geometry computations. Without caching, dragging a selection box over hundreds of shapes would recompute each shape's geometry on every frame.

Access cached geometry through the editor:

```typescript
const geometry = editor.getShapeGeometry(shape)
const pageBounds = editor.getShapePageBounds(shape)
```

The cache invalidates automatically when a shape's props or meta change. You don't need to manage invalidation yourself.

## Geometry filtering

Group2d supports filtering to include or exclude certain geometry children during operations. This lets you mark parts of a shape's geometry for different purposes.

The `isLabel` flag marks geometry that represents text label bounds. Label geometry participates in click-to-edit detection but is typically excluded from outline calculations and snapping.

The `isInternal` flag marks geometry that exists for internal calculations but shouldn't be part of the shape's visible outline.

```typescript
// Mark geometry as a label
new Rectangle2d({
	// ...
	isLabel: true,
})

// Mark geometry as internal (not part of main outline)
new Rectangle2d({
	// ...
	isInternal: true,
})
```

The geometry system provides filter presets for common scenarios:

| Filter                 | Includes labels | Includes internal |
| ---------------------- | --------------- | ----------------- |
| `EXCLUDE_NON_STANDARD` | No              | No                |
| `INCLUDE_ALL`          | Yes             | Yes               |
| `EXCLUDE_LABELS`       | No              | Yes               |
| `EXCLUDE_INTERNAL`     | Yes             | No                |

The `vertices` and `length` getters, and Group2d's hit tests, default to `EXCLUDE_LABELS`: labels are left out but internal geometry is included. Arrow routing passes `EXCLUDE_NON_STANDARD` to get the bare outline. Pass a filter explicitly to any method that accepts one when you need something else.

## Advanced options

Geometry2d has additional options for special cases.

### excludeFromShapeBounds

When set, the geometry won't contribute to the shape's bounding box calculation. The geometry still participates in hit testing and other operations, but `getBoundsVertices()` returns an empty array for it.

```typescript
const label = new Rectangle2d({
	x: labelX,
	y: labelY,
	width: labelWidth,
	height: labelHeight,
	isFilled: true,
	isLabel: true,
	excludeFromShapeBounds: true, // label won't affect shape bounds
})
```

### ignore

When set on geometry inside a Group2d, that geometry is placed in an `ignoredChildren` array and won't participate in the group's hit testing, bounds, or other queries. The geometry debug view still draws it.

```typescript
new Group2d({
	children: [
		mainGeometry,
		new Rectangle2d({
			// ...
			ignore: true, // won't participate in group operations
		}),
	],
})
```

### debugColor

A color string used when rendering geometry in the debug view. Defaults to red if not specified.

```typescript
new Rectangle2d({
	width: 100,
	height: 100,
	isFilled: true,
	debugColor: 'blue', // shows as blue in geometry debugging view
})
```

Turn on the `debugGeometry` flag in the debug menu to draw shape geometry on the canvas during development.

## Transformed geometry

The [`TransformedGeometry2d`](/reference/editor/TransformedGeometry2d) class wraps a geometry with a transformation matrix, so you can query it in a different coordinate space without rebuilding it. Group shapes use this to combine their children's geometry in the group's local space.

```typescript
const transformed = geometry.transform(matrix)
```

All operations on the transformed geometry apply the transformation automatically. One limitation: transformed geometry throws from `getSvgPathData()`. Call it on the source geometry and transform the result if you need path data.

## Related examples

- **[Custom shape geometry](/examples/shapes/tools/shape-with-geometry)** - A house-shaped custom shape using Polygon2d and Group2d geometry.
- **[Cubic bezier curve shape](/examples/shapes/tools/cubic-bezier-shape)** - Interactive bezier curve editing with CubicBezier2d geometry and custom handles.
- **[Custom bounds snapping](/examples/shapes/tools/bounds-snapping-shape)** - Playing card shapes with custom snap geometry so they stack with visible icons.

--------

# Groups

Groups are logical containers that combine multiple shapes into a single selectable unit. Unlike frames, groups draw nothing of their own apart from a dashed outline while the group is focused. Their geometry is the union of their children's geometries, their bounds update automatically as children change, and they clean themselves up when their contents are deleted. Groups can be nested inside other groups.

## Creating groups

Use [`Editor.groupShapes`](/reference/editor/Editor#groupShapes) to combine shapes into a group. Pass an array of shape IDs or shape objects, and the method creates a new group containing those shapes:

```typescript
import { createShapeId } from 'tldraw'

// Group selected shapes
editor.groupShapes(editor.getSelectedShapeIds())

// Group specific shapes
editor.groupShapes([shapeId1, shapeId2, shapeId3])

// Group with options
editor.groupShapes([shapeId1, shapeId2], {
	groupId: createShapeId('my-group'), // Custom ID for the group
	select: false, // Don't select the group after creation
})
```

Grouping requires at least two shapes. The method does nothing if you pass fewer, and it skips [locked shapes](/sdk-features/locked-shapes). Users can also group shapes with Ctrl+G (Cmd+G on Mac); when the only selected shape is a group, the same shortcut ungroups it.

The new group is positioned at the top-left of the combined bounds of all grouped shapes. It takes the z-index of the topmost grouped shape, so it sits where that shape was in its parent's layer stack.

## Ungrouping

Use [`Editor.ungroupShapes`](/reference/editor/Editor#ungroupShapes) to dissolve groups and release their children:

```typescript
// Ungroup selected groups
editor.ungroupShapes(editor.getSelectedShapeIds())

// Ungroup specific groups
editor.ungroupShapes([groupId])

// Ungroup without selecting the released children
editor.ungroupShapes([groupId], { select: false })
```

Ungrouping moves children to the group's parent and preserves their page positions and rotations. Layer order is maintained: children appear where the group was in the z-stack. If you pass a mix of groups and non-groups, only the groups are ungrouped and the non-groups stay selected. Users can ungroup with Ctrl+Shift+G (Cmd+Shift+G on Mac).

Ungrouping is not recursive. If a group contains other groups, those inner groups remain intact. Ungroup them separately if needed.

## Focused groups

The editor tracks a focused group that defines the current editing scope. When you're focused inside a group, you can select and manipulate the shapes within it. Without focus, clicking a shape inside a group selects the group itself, not the individual shape.

Use [`Editor.getFocusedGroup`](/reference/editor/Editor#getFocusedGroup), [`Editor.getFocusedGroupId`](/reference/editor/Editor#getFocusedGroupId), [`Editor.setFocusedGroup`](/reference/editor/Editor#setFocusedGroup), and [`Editor.popFocusedGroupId`](/reference/editor/Editor#popFocusedGroupId):

```typescript
// Get the current focused group
const focusedGroup = editor.getFocusedGroup()

// Get the focused group ID (returns page ID if no group is focused)
const focusedId = editor.getFocusedGroupId()

// Focus a specific group
editor.setFocusedGroup(groupId)

// Exit the current focused group and select it
editor.popFocusedGroupId()
```

The editor manages focus automatically based on selection:

- Selecting a shape inside a group focuses that group
- Selecting shapes across multiple groups focuses their common ancestor
- Pressing Escape pops focus one level up (or back to the page)
- Pressing Enter with only groups selected selects their children
- Clearing selection keeps the current focus

### Layered selection

Clicking shapes inside groups follows a layered pattern:

1. First click selects the outermost group
2. Second click focuses the group and selects the parent of the target shape (or the shape if directly inside)
3. Further clicks drill down through nested groups

This lets you work at different levels of the hierarchy without keyboard modifiers.

## Nested groups

Groups can contain other groups, creating hierarchies:

```typescript
// Create a nested structure
editor.select(boxA, boxB)
editor.groupShapes(editor.getSelectedShapeIds())
const innerGroupId = editor.getOnlySelectedShapeId()

editor.select(innerGroupId, boxC, boxD)
editor.groupShapes(editor.getSelectedShapeIds())
const outerGroupId = editor.getOnlySelectedShapeId()

// Result:
// outerGroup
// ├── innerGroup
// │   ├── boxA
// │   └── boxB
// ├── boxC
// └── boxD
```

When grouping shapes that already have different parents, the editor finds their common ancestor and creates the group there. This prevents orphaning shapes from their natural hierarchy.

## Automatic cleanup

Groups maintain themselves through the [`ShapeUtil.onChildrenChange`](/reference/editor/ShapeUtil#onChildrenChange) lifecycle hook. If you delete all children of a group, the group is removed. If a group ends up with only one child, it dissolves and reparents that child to the group's parent.

This cleanup happens immediately when children change, so you never end up with degenerate groups.

```typescript
// Start with a group containing boxA and boxB
editor.deleteShapes([boxA])
// Group now has only boxB, so it auto-ungroups
// boxB is now a direct child of the page (or the group's former parent)
```

## Bounds and transforms

Group bounds are computed from their children's geometries. The [`Group2d`](/reference/editor/Group2d) geometry class aggregates all child geometries for hit testing and bounds calculation:

```typescript
// Get a group's bounds
const bounds = editor.getShapePageBounds(groupId)

// Bounds update automatically when children move
editor.updateShape({ id: childId, type: 'geo', x: newX, y: newY })
const updatedBounds = editor.getShapePageBounds(groupId)
```

When you transform a group (move, rotate, resize), all children transform with it. The group's position and rotation are applied to children through the standard parent-child transform composition.

Position preservation works both ways. When you group shapes, their page positions are preserved—only their `parentId` and local coordinates change. When you ungroup, shapes return to their original page positions even if the group was rotated.

## Creating shapes inside groups

When you create new shapes while focused inside a group, those shapes become children of the focused group unless they're positioned over a container such as a frame, which takes precedence:

```typescript
// Focus a group by selecting a shape inside it
editor.select(shapeInsideGroup)
// Now getFocusedGroupId() returns the group's ID

// Create a new shape - it becomes a child of the focused group
editor.createShape({
	type: 'geo',
	x: 100,
	y: 100,
	props: { w: 50, h: 50 },
})
// The new shape's parentId is the focused group
```

If no group is focused, new shapes are created on the current page.

## Limitations

Arrows can't bind to groups. [`ShapeUtil.canBind`](/reference/editor/ShapeUtil#canBind) returns `false` for group shapes, so arrows must bind to individual shapes within the group.

Groups have no visual properties. You can't style a group itself, only its children.

Both grouping and ungrouping require the select tool to be active, and do nothing in readonly mode. If you're in the middle of another interaction, the editor cancels it before running the operation.

## Related examples

- [Layer panel](/examples/ui/layer-panel) - Build a hierarchical layer panel that shows shape and group structure with visibility controls.

--------

# Handles

In tldraw, handles are interactive control points on shapes that let users manipulate shape geometry. Arrows have handles at their endpoints, lines have handles at each vertex, and notes have clone handles for quick duplication.

## Handle basics

Handles appear when a single shape is selected with the select tool. Each handle has a position, type, and optional snapping behavior. You define handles by implementing [`ShapeUtil.getHandles`](/reference/editor/ShapeUtil#getHandles) on your [`ShapeUtil`](/reference/editor/ShapeUtil):

```tsx
import { ShapeUtil, TLHandle, ZERO_INDEX_KEY } from 'tldraw'

class MyShapeUtil extends ShapeUtil<MyShape> {
	// ...

	override getHandles(shape: MyShape): TLHandle[] {
		return [
			{
				id: 'point',
				type: 'vertex',
				index: ZERO_INDEX_KEY,
				x: shape.props.pointX,
				y: shape.props.pointY,
			},
		]
	}
}
```

Handle coordinates are in the shape's local coordinate system, where `(0, 0)` is the shape's top-left corner.

## Handle types

There are four handle types:

| Type      | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| `vertex`  | A primary control point that defines part of the shape's geometry             |
| `virtual` | A secondary handle that isn't a vertex, like the arrow's midpoint bend handle |
| `create`  | A handle for adding new geometry, like inserting a point into a line segment  |
| `clone`   | A handle for duplicating the shape, used by notes for quick adjacent copies   |

Most custom shapes use `vertex` handles. The arrow shape uses a `virtual` handle for its midpoint, and the line shape uses `create` handles to let users add points between vertices.

## Responding to handle drags

When a user drags a handle, tldraw calls [`ShapeUtil.onHandleDrag`](/reference/editor/ShapeUtil#onHandleDrag) with the updated handle position. Return a partial of the shape with the changed props:

```tsx
import { ShapeUtil, TLHandleDragInfo } from 'tldraw'

class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
	// ...

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

The `handle` in [`TLHandleDragInfo`](/reference/editor/TLHandleDragInfo) carries the new `x` and `y` after any snapping. The info object also has these fields:

| Field             | Description                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| `initial`         | The shape as it was when the drag started                               |
| `isPrecise`       | Whether the user is dragging precisely, for example by holding Alt      |
| `isCreatingShape` | Whether the handle drag is part of creating the shape, like a new arrow |

### Lifecycle callbacks

For more control over handle interactions, implement these additional methods:

| Method               | When it's called                    |
| -------------------- | ----------------------------------- |
| `onHandleDragStart`  | When the user starts dragging       |
| `onHandleDragEnd`    | When the user releases the handle   |
| `onHandleDragCancel` | When the drag is cancelled (escape) |

## Handle snapping

Handles can snap to other shapes' geometry. Set `snapType` on the handle. Snapping engages while the user holds Ctrl (Cmd on Mac); with snap mode turned on in preferences, it's the reverse: snapping is on and Ctrl disables it. The older `canSnap: true` flag is deprecated; use `snapType: 'point'` instead. See [Snapping](/sdk-features/snapping) for how snapping works across the editor.

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

The `snapType` options are:

| Value     | Behavior                                                                               |
| --------- | -------------------------------------------------------------------------------------- |
| `'point'` | Snaps to key points on other shapes first, then to the nearest point on their outlines |
| `'align'` | Snaps the handle's x and y independently to the x and y of key points on other shapes  |

### Angle snapping

When the user holds Shift while dragging, handles snap to 15-degree angles. By default, the angle is measured relative to the next vertex handle on the shape. You can snap relative to a specific handle by setting `snapReferenceHandleId`:

```tsx
{
	id: 'controlPoint',
	type: 'vertex',
	index: getIndexAbove(ZERO_INDEX_KEY),
	x: shape.props.cpX,
	y: shape.props.cpY,
	snapType: 'align',
	snapReferenceHandleId: 'start', // Angle snaps relative to 'start' handle
}
```

Bezier curves use this so control points snap to angles relative to their associated endpoint.

### Custom snap geometry

By default, handles snap to a shape's outline (its geometry) and to no key points. Override [`ShapeUtil.getHandleSnapGeometry`](/reference/editor/ShapeUtil#getHandleSnapGeometry) to customize what handles snap to:

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

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

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

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

The [`HandleSnapGeometry`](/reference/editor/HandleSnapGeometry) object has these properties:

| Property             | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| `outline`            | Custom outline geometry for snapping (default: shape geometry) |
| `points`             | Key points to snap to (default: none)                          |
| `getSelfSnapOutline` | Returns outline for self-snapping given a handle               |
| `getSelfSnapPoints`  | Returns points for self-snapping given a handle                |

## Complete example

Here's a speech bubble shape with a draggable tail handle:

```tsx
import {
	Polygon2d,
	ShapeUtil,
	TLHandle,
	TLHandleDragInfo,
	TLShape,
	Vec,
	ZERO_INDEX_KEY,
} from 'tldraw'

const SPEECH_BUBBLE_TYPE = 'speech-bubble'

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

type SpeechBubbleShape = TLShape<typeof SPEECH_BUBBLE_TYPE>

class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
	static override type = SPEECH_BUBBLE_TYPE

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

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

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

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

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

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

## Reading handles

Use [`Editor.getShapeHandles`](/reference/editor/Editor#getShapeHandles) to get the handles for any shape:

```ts
const handles = editor.getShapeHandles(shape)
if (handles) {
	for (const handle of handles) {
		console.log(handle.id, handle.x, handle.y)
	}
}
```

Returns `undefined` if the shape doesn't have handles.

## Examples

- [Custom shape with handles](/examples/shapes/tools/speech-bubble) — A speech bubble shape with a draggable tail handle
- [Cubic bezier curve shape](/examples/shapes/tools/cubic-bezier-shape) — Multiple handles with custom snapping and control point behavior

--------

# Highlighting

Shape highlighting shows visual indicators on shapes to provide feedback during user interactions. The editor tracks two types of highlighting: **hover** (the shape under the pointer) and **hints** (shapes you want to emphasize programmatically).

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					// Highlight specific shapes with a visual indicator
					const shapes = editor.getCurrentPageShapes()
					if (shapes.length > 0) {
						editor.setHintingShapes([shapes[0]])
					}
				}}
			/>
		</div>
	)
}
```

## Hover highlighting

The editor automatically tracks which shape is under the pointer and displays a selection-style indicator around it. Hovering a child of a group hovers the group, unless that group is focused or selected, in which case the child itself is hovered.

### Reading hover state

Use [`Editor.getHoveredShapeId`](/reference/editor/Editor#getHoveredShapeId) or [`Editor.getHoveredShape`](/reference/editor/Editor#getHoveredShape) to check which shape is currently hovered:

```typescript
// Get the hovered shape ID
const hoveredId = editor.getHoveredShapeId()

// Get the full shape object
const hoveredShape = editor.getHoveredShape()

if (hoveredShape) {
	console.log('Hovering over:', hoveredShape.type)
}
```

### Setting hover manually

Use [`Editor.setHoveredShape`](/reference/editor/Editor#setHoveredShape) to set the hover state yourself:

```typescript
// Set hover by shape or ID
editor.setHoveredShape(myShape)
editor.setHoveredShape(myShape.id)

// Clear hover
editor.setHoveredShape(null)
```

The select tool overwrites this value on the next pointer move while it's idle or editing, so a manual hover only sticks inside your own tool or state. For programmatic emphasis, use hints instead.

### Automatic hover detection

The select tool updates hover state as the pointer moves (throttled to 32ms, and paused while the camera is moving). The hover indicator appears when:

- The select tool is in `idle` or `editing_shape`
- The pointer is over the canvas (not UI elements)
- The pointer is not coarse (touch, and pen on some devices)
- The editor is not changing styles
- The shape is not already selected

Touch devices don't show hover indicators because touch has no hovering concept.

## Hint highlighting

Hints let you highlight multiple shapes programmatically. Unlike hover (single shape, automatic), hints are set explicitly and can include any number of shapes. The select tool uses them too: it hints the drop target during drag-and-drop and the shapes a new frame will enclose, so hints you set may be replaced while the user is dragging.

### Reading hints

Use [`Editor.getHintingShapeIds`](/reference/editor/Editor#getHintingShapeIds) or [`Editor.getHintingShape`](/reference/editor/Editor#getHintingShape) to get currently hinted shapes:

```typescript
// Get array of hinted shape IDs
const hintedIds = editor.getHintingShapeIds()

// Get array of hinted shape objects
const hintedShapes = editor.getHintingShape()
```

### Setting hints

Use [`Editor.setHintingShapes`](/reference/editor/Editor#setHintingShapes) to highlight shapes:

```typescript
// Highlight shapes by ID or shape object
editor.setHintingShapes([shape1, shape2])
editor.setHintingShapes([shape1.id, shape2.id])

// Clear all hints
editor.setHintingShapes([])
```

Hinted shapes render with a thicker stroke (2.5 screen pixels) than selected or hovered shapes (1.5). Setting hints never creates an undo entry, and ids are deduplicated on write.

For example, to hint the arrows bound to the selected shape, react to the selection:

```typescript
import { react } from 'tldraw'

const stop = react('hint bound arrows', () => {
	const selected = editor.getOnlySelectedShape()
	if (selected) {
		const bindings = editor.getBindingsToShape(selected, 'arrow')
		editor.setHintingShapes(bindings.map((b) => b.fromId))
	} else {
		editor.setHintingShapes([])
	}
})
```

## Visual rendering

Both hover and hint indicators use the theme's selection color. The [`ShapeIndicatorOverlayUtil`](/reference/tldraw/ShapeIndicatorOverlayUtil) strokes them on a canvas overlay using each shape's [`ShapeUtil.getIndicatorPath`](/reference/editor/ShapeUtil#getIndicatorPath). Collaborator selections render at 1.5px in the collaborator's color at 0.7 opacity. See [Indicators](/sdk-features/indicators) for the stroke widths and how to customize them.

## Page state storage

Hover and hint state are stored in [`TLInstancePageState`](/reference/tlschema/TLInstancePageState), which tracks per-page interaction state. Each page maintains its own hover and hint values.

```typescript
const pageState = editor.getCurrentPageState()

pageState.hoveredShapeId // TLShapeId | null
pageState.hintingShapeIds // TLShapeId[]
```

Both properties are ephemeral—they don't persist across sessions or sync between collaborators.

## Related articles

- [Indicators](/sdk-features/indicators) — How indicator outlines are drawn and customized
- [Instance state](/sdk-features/instance-state) — Session state including page state
- [Selection](/sdk-features/selection) — Working with selected shapes
- [Cursors](/sdk-features/cursors) — Cursor types and customization

## API reference

| Method                         | Description                            |
| ------------------------------ | -------------------------------------- |
| [`Editor.getHoveredShapeId`](/reference/editor/Editor#getHoveredShapeId)  | Get the ID of the shape under pointer  |
| [`Editor.getHoveredShape`](/reference/editor/Editor#getHoveredShape)    | Get the shape object under pointer     |
| [`Editor.setHoveredShape`](/reference/editor/Editor#setHoveredShape)    | Manually set or clear hover state      |
| [`Editor.getHintingShapeIds`](/reference/editor/Editor#getHintingShapeIds) | Get IDs of shapes with hint indicators |
| [`Editor.getHintingShape`](/reference/editor/Editor#getHintingShape)    | Get shapes with hint indicators        |
| [`Editor.setHintingShapes`](/reference/editor/Editor#setHintingShapes)   | Set shapes to show hint indicators     |

--------

# History (undo/redo)

The editor's history system tracks changes to the [store](/sdk-features/store) and provides undo/redo. Changes are organized into batches separated by marks, which act as stopping points, so a complex interaction undoes as one step instead of many.

The history manager captures all user-initiated store changes automatically and batches rapid changes into single undo steps. You control which changes are recorded with history options. The default UI binds undo to Cmd/Ctrl+Z and redo to Cmd/Ctrl+Shift+Z.

## How it works

The history manager maintains two stacks: one for undos and one for redos. Each stack contains entries that are either diffs (record changes) or marks (stopping points).

When you modify the store, the history manager captures the change as a diff. Changes accumulate until you create a mark, then the pending changes are flushed to the undo stack as a single entry. This batching prevents every keystroke or mouse movement from becoming a separate undo step.

```typescript
editor.updateShape({ id: myShapeId, type: 'geo', x: 100, y: 100 })
editor.updateShape({ id: myShapeId, type: 'geo', x: 110, y: 100 })
editor.updateShape({ id: myShapeId, type: 'geo', x: 120, y: 100 })
// All three updates are batched together until a mark is created
```

When you undo, the manager reverses all changes back to the previous mark, moves them to the redo stack, and applies the reversed diff atomically. Redo does the inverse.

## Marks and stopping points

Marks define where undo and redo operations stop. Create marks with [`Editor.markHistoryStoppingPoint`](/reference/editor/Editor#markHistoryStoppingPoint) at the start of user interactions so that complex operations can be undone in one step. The optional name only shows up in the mark id, which is useful for debugging.

```typescript
const markId = editor.markHistoryStoppingPoint('rotate shapes')
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI / 4)
// Undoing will return to this mark
```

Each mark has a unique identifier that you can use with [bailToMark](#bailing) or [squashToMark](#squashing). Creating a mark flushes pending changes onto the undo stack. It doesn't clear the redo stack; the next recorded change does that.

## Basic operations

### Undo and redo

Use [`Editor.undo`](/reference/editor/Editor#undo) and [`Editor.redo`](/reference/editor/Editor#redo) to move through history marks.

```typescript
editor.undo() // Reverse to previous mark
editor.redo() // Reapply changes
```

Both methods return the editor instance for chaining.

The [`Editor.canUndo`](/reference/editor/Editor#canUndo) and [`Editor.canRedo`](/reference/editor/Editor#canRedo) methods are reactive, so you can use them to update UI button states automatically:

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

function UndoButton() {
	const editor = useEditor()
	const canUndo = useValue('canUndo', () => editor.canUndo(), [editor])
	return (
		<button disabled={!canUndo} onClick={() => editor.undo()}>
			Undo
		</button>
	)
}
```

### Running operations with history options

The [`Editor.run`](/reference/editor/Editor#run) method executes a function while controlling how changes affect history. Use it to make changes that don't pollute the undo stack or that preserve the redo stack for special operations.

```typescript
// Ignore changes (don't add to undo stack)
editor.run(
	() => {
		editor.updateShape({ id: myShapeId, type: 'geo', x: 100 })
	},
	{ history: 'ignore' }
)

// Record but preserve redo stack
editor.run(
	() => {
		editor.updateShape({ id: myShapeId, type: 'geo', x: 100 })
	},
	{ history: 'record-preserveRedoStack' }
)
```

The three history modes are:

| Mode                       | Undo stack | Redo stack |
| -------------------------- | ---------- | ---------- |
| `record`                   | Add        | Clear      |
| `record-preserveRedoStack` | Add        | Keep       |
| `ignore`                   | Skip       | Keep       |

> We use `record-preserveRedoStack` when selecting shapes. This way you can undo, select some shapes, copy them, and then redo back to where you were. The selection goes on the undo stack, but existing redos aren't cleared.

> We use `ignore` when writing your own pointer position for collaborators to see. Where your cursor was doesn't need to be undoable. (Changes that arrive from other users are marked `'remote'` and are never recorded.)

Nested `run` calls keep the outer mode unless they set their own, and no mode is applied while an undo or redo is in progress.

## Advanced features

### Bailing

Bailing reverses changes without adding them to the redo stack. The changes are discarded entirely. Use this when canceling an interaction.

```typescript
const markId = editor.markHistoryStoppingPoint('begin drag')
// User drags shapes around
// User presses escape to cancel
editor.bailToMark(markId) // Roll back and discard all changes since mark
```

[`Editor.bail`](/reference/editor/Editor#bail) reverts to the most recent mark. [`Editor.bailToMark`](/reference/editor/Editor#bailToMark) reverts to a specific mark by ID.

> We use bailing while cloning shapes. A user can switch between translating and cloning by pressing or releasing the alt (option) key during a drag. When this changes, we bail on the changes since the interaction started, then apply the new mode's changes.

### Squashing

[`Editor.squashToMark`](/reference/editor/Editor#squashToMark) combines all changes since a mark into a single undo step. Intermediate marks are removed. This simplifies the undo experience for complex multi-step operations.

```typescript
const markId = editor.markHistoryStoppingPoint('bump shapes')
editor.nudgeShapes(shapes, { x: 10, y: 0 })
editor.nudgeShapes(shapes, { x: 0, y: 10 })
editor.nudgeShapes(shapes, { x: -5, y: -5 })
editor.squashToMark(markId) // All three nudges become one undo step
```

Squashing doesn't change the current state, only how history is organized. If the mark isn't on the undo stack, `squashToMark` logs an error and does nothing.

> We use squashing during image cropping. While the user adjusts the crop, each change is recorded and can be undone individually. When the user exits crop mode, we squash the intermediate changes into one history entry. A single undo restores the image to its state before cropping began.

### Clearing history

[`Editor.clearHistory`](/reference/editor/Editor#clearHistory) removes all undo and redo entries. Use this when loading new documents or resetting the editor state.

```typescript
editor.loadSnapshot(snapshot)
editor.clearHistory() // Start with clean history
```

## Integration with the store

The history manager listens to [store](/sdk-features/store) changes through a history interceptor. It only captures changes with source `'user'`; changes merged from other clients (source `'remote'`) are ignored, and internal writes that shouldn't be undoable use `history: 'ignore'`. Only store records take part in undo/redo; state held outside the store, like your own atoms, does not.

The three history modes map onto three internal states: `Recording`, `RecordingPreserveRedoStack`, and `Paused`. The manager pauses itself while applying an undo or redo so those writes don't create new entries.

## Related examples

- [Timeline scrubber](/examples/use-cases/timeline-scrubber) - A visual timeline that lets users scrub through document history.
- [Store events](/examples/events/store-events) - Listen to store changes, which is how the history manager tracks modifications.

--------

# Image export

The export system converts shapes to SVG and raster image formats for download, embedding, or integration with external tools. The editor handles the full pipeline from rendering shapes as SVG to converting those SVGs into PNG, JPEG, or WebP images. Exports are fully self-contained: the editor embeds fonts, inlines styles, and converts media elements to data URLs.

## How it works

Export has two stages: SVG generation and optional raster conversion. The SVG stage renders shapes into a self-contained SVG document, while the raster stage converts that SVG into a bitmap image.

### SVG generation

The editor gathers the shapes to export, calculates their bounding box, creates a React tree representing the SVG, renders it into a temporary DOM element, and processes it to be self-contained.

Each shape defines how it renders to SVG through its [`ShapeUtil`](/reference/editor/ShapeUtil). If the shape implements [`ShapeUtil.toSvg`](/reference/editor/ShapeUtil#toSvg) or [`ShapeUtil.toBackgroundSvg`](/reference/editor/ShapeUtil#toBackgroundSvg), those methods return React SVG elements. Otherwise the editor renders the shape's normal HTML inside an SVG `<foreignObject>` element.

```tsx
override toSvg(shape: MyShape, ctx: SvgExportContext) {
	const fill = ctx.isDarkMode ? '#333' : '#eee'
	return <rect width={shape.props.w} height={shape.props.h} fill={fill} />
}
```

The [`SvgExportContext`](/reference/editor/SvgExportContext) tells you the color mode, `scale`, and `pixelRatio` of the export, resolves asset URLs at the right size via `resolveAssetUrl`, and lets you defer the snapshot with `waitUntil` while an image loads. Shapes rendered through `<foreignObject>` can do the same with [`useDelaySvgExport`](/reference/editor/useDelaySvgExport).

The temporary render step is necessary because CSS and layout aren't computed until elements are in the document. `<foreignObject>` elements in particular need their styles and content inlined to work when the SVG is extracted.

### Making SVG self-contained

SVG files must be self-contained to work outside the document. The editor processes the rendered SVG to embed all external resources:

Fonts come first. The `FontEmbedder` finds `@font-face` declarations in the document's stylesheets, fetches the font files, and inlines them as data URLs, so text renders identically regardless of what the viewer has installed.

Then styles. The `StyleEmbedder` reads computed styles from every element inside `<foreignObject>` sections and writes them as inline styles. Pseudo-elements like `::before` and `::after` can't be inlined, so their rules go into a `<style>` tag within the SVG.

Finally media. `embedMedia` converts images to data URLs, videos to a single captured frame, and canvas elements to images via `toDataURL()`.

### Raster conversion

Once the editor generates the SVG, it can convert it to a raster image. The `getSvgAsImage` function loads the SVG into an `Image` element, draws it to a canvas at the requested resolution, and exports the canvas as a blob.

The `pixelRatio` option controls output resolution. The default of 2 is sharp on high-DPI displays; raise it for print. The editor automatically clamps dimensions to browser canvas limits to avoid out-of-memory errors.

## Export options

SVG export methods (`getSvgElement`, `getSvgString`) accept [`TLSvgExportOptions`](/reference/editor/TLSvgExportOptions). Raster export methods (`toImage`, `toImageDataUrl`) accept [`TLImageExportOptions`](/reference/editor/TLImageExportOptions), which extends `TLSvgExportOptions` with format-specific options.

**Shared options (all export methods):**

| Option                | Description                                                                                                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bounds`              | The bounding box in page coordinates to export. If omitted, the editor calculates bounds from the shapes.                                                                                              |
| `scale`               | Logical scale multiplier. A scale of 2 doubles the SVG size. Defaults to `1`.                                                                                                                          |
| `pixelRatio`          | For SVG exports, passed to the asset store so it can provide appropriately sized assets. For raster exports, multiplies output dimensions. Defaults to `undefined` for SVG and `2` for raster formats. |
| `background`          | Whether to include the background color. If `false`, the export is transparent (for formats that support it). Defaults to the `exportBackground` instance state.                                       |
| `padding`             | Space around the shape bounds: `'auto'` (default), a `number` of pixels, or `0`. See below.                                                                                                            |
| `darkMode`            | Whether to render in dark mode. Defaults to the current theme setting.                                                                                                                                 |
| `preserveAspectRatio` | The SVG `preserveAspectRatio` attribute.                                                                                                                                                               |

In `'auto'` padding mode the editor renders with `editor.options.defaultSvgPadding` (32px), then trims to the visual content bounds. This captures overflow like thick strokes and arrowheads without extra whitespace. A numeric value adds fixed padding and clips overflow beyond it; `0` means no padding and no trimming. Padding is skipped when exporting a single frame, and when a shape whose [`ShapeUtil.isExportBoundsContainer`](/reference/editor/ShapeUtil#isExportBoundsContainer) returns true (images and frames by default) contains every other exported shape.

**`toImage` and `toImageDataUrl` options:**

| Option    | Description                                                                                               |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `format`  | Output format: `'png'`, `'jpeg'`, `'webp'`, or `'svg'`. Defaults to `'png'`. `'svg'` returns an SVG blob. |
| `quality` | Compression quality for lossy formats (JPEG, WebP) as a number between 0 and 1.                           |

## Editor export methods

The [`Editor`](/reference/editor/Editor) class provides four methods for exporting shapes. All methods accept either shape IDs or shape objects, and an empty array exports all shapes on the current page.

### getSvgElement

[`Editor.getSvgElement`](/reference/editor/Editor#getSvgElement) returns the SVG as a DOM element along with its width and height. Use this when you need to manipulate the SVG programmatically or insert it into the DOM.

```typescript
const result = await editor.getSvgElement(shapes, { scale: 2 })
if (result) {
	document.body.appendChild(result.svg)
}
```

### getSvgString

[`Editor.getSvgString`](/reference/editor/Editor#getSvgString) returns the SVG as a serialized string. Use this for saving to a file or sending to a server.

```typescript
const result = await editor.getSvgString(shapes, { background: true })
if (result) {
	console.log(result.svg) // SVG markup as string
}
```

### toImage

[`Editor.toImage`](/reference/editor/Editor#toImage) returns a blob of the exported image in the specified format. This is the primary method for raster images. For a ready-made download or copy-to-clipboard flow, use [`exportAs`](/reference/tldraw/exportAs) and [`copyAs`](/reference/tldraw/copyAs) from `tldraw`, which wrap it.

```typescript
const result = await editor.toImage(shapes, {
	format: 'png',
	pixelRatio: 2,
	background: true,
})

// Download the image
const link = document.createElement('a')
link.href = URL.createObjectURL(result.blob)
link.download = 'export.png'
link.click()
```

### toImageDataUrl

[`Editor.toImageDataUrl`](/reference/editor/Editor#toImageDataUrl) returns the exported image as a data URL string. Use this when you need the image as a base64-encoded string, for example to display in an `<img>` element or store in a database.

```typescript
const result = await editor.toImageDataUrl(shapes, { format: 'png' })
const img = document.createElement('img')
img.src = result.url
```

## Error handling

The SVG methods ([`Editor.getSvgElement`](/reference/editor/Editor#getSvgElement) and [`Editor.getSvgString`](/reference/editor/Editor#getSvgString)) return `undefined` when there's nothing to export. Check the result before using it:

```typescript
const result = await editor.getSvgString(shapes)
if (!result) {
	console.error('Nothing to export')
	return
}
// result.svg is available
```

The raster methods ([`Editor.toImage`](/reference/editor/Editor#toImage) and [`Editor.toImageDataUrl`](/reference/editor/Editor#toImageDataUrl)) throw instead. Wrap them in a try/catch when the export might fail:

```typescript
try {
	const { blob } = await editor.toImage(shapes, { format: 'png' })
} catch (e) {
	console.error('Export failed', e)
}
```

The raster conversion automatically clamps dimensions to stay within browser canvas limits, which vary by browser. Very large exports at high pixel ratios are scaled down to fit rather than failing.

## Related examples

- [Export canvas as image](/examples/data/assets/export-canvas-as-image) - Export the entire canvas using [`Editor.toImage`](/reference/editor/Editor#toImage) and download it.
- [Export canvas as image (with settings)](/examples/data/assets/export-canvas-settings) - Export with configurable format, scale, background, and other options.
- [Custom shape SVG export](/examples/shapes/tools/toSvg-method-example) - Define how custom shapes render when exported using [`ShapeUtil.toSvg`](/reference/editor/ShapeUtil#toSvg) and [`ShapeUtil.toBackgroundSvg`](/reference/editor/ShapeUtil#toBackgroundSvg).

--------

# Indicators

Indicators are the colored outlines that appear around shapes when they're selected, hovered, or being interacted with. Every shape defines its own indicator through the [`ShapeUtil.getIndicatorPath`](/reference/editor/ShapeUtil#getIndicatorPath) method.

## How indicators work

When you hover over or select a shape, tldraw draws an outline that matches the shape's geometry. The indicator is separate from the shape itself: the [`ShapeIndicatorOverlayUtil`](/reference/tldraw/ShapeIndicatorOverlayUtil) strokes it on a canvas overlay above the shapes, in the theme's selection color.

Indicators appear in three contexts:

| Context  | When it appears                                                                                   | Stroke weight |
| -------- | ------------------------------------------------------------------------------------------------- | ------------- |
| Selected | Shape is in the current selection                                                                 | 1.5px         |
| Hovered  | Pointer is over an unselected shape while the select tool is idle (fine pointers only, not touch) | 1.5px         |
| Hinting  | Shape is a drop target during drag operations                                                     | 2.5px         |

For collaborative editing, [`CollaboratorShapeIndicatorOverlayUtil`](/reference/tldraw/CollaboratorShapeIndicatorOverlayUtil) also shows which shapes other users have selected, in each collaborator's cursor color. Locked shapes never show indicators.

## Defining an indicator

Every [`ShapeUtil`](/reference/editor/ShapeUtil) must implement the `getIndicatorPath` method. This method returns a `Path2D`, a richer [`TLIndicatorPath`](/reference/editor/TLIndicatorPath) object for indicators that need clipping or additional stroked paths, or `undefined` to draw no indicator:

```tsx
import { ShapeUtil, TLShape, Rectangle2d, T, RecordProps } from 'tldraw'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		myshape: { w: number; h: number }
	}
}

type MyShape = TLShape<'myshape'>

class MyShapeUtil extends ShapeUtil<MyShape> {
	static override type = 'myshape' as const
	static override props: RecordProps<MyShape> = {
		w: T.number,
		h: T.number,
	}

	getDefaultProps() {
		return { w: 100, h: 100 }
	}

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

	component(shape: MyShape) {
		return <div style={{ width: shape.props.w, height: shape.props.h }} />
	}

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

The `getIndicatorPath` method receives the shape and returns paths in the shape's local coordinate space. You don't need to set stroke color or width—tldraw applies those automatically based on context.

### Common indicator patterns

For circular shapes, use an ellipse path:

```tsx
getIndicatorPath(shape: MyShape) {
	const { w, h } = shape.props
	const path = new Path2D()
	path.ellipse(w / 2, h / 2, w / 2, h / 2, 0, 0, Math.PI * 2)
	return path
}
```

For complex paths, use the shape's geometry:

```tsx
getIndicatorPath(shape: MyShape) {
	const geometry = this.editor.getShapeGeometry(shape)
	return new Path2D(geometry.toSimpleSvgPath())
}
```

### Indicators with labels

Shapes with labels may need to clip the indicator where the label appears. Arrow shapes do this to prevent the indicator from overlapping label text. Return an object with `path`, an optional `clipPath`, and optional `additionalPaths`. The clip is applied even-odd before stroking `path`, so an outer rectangle plus the label rectangle punches a hole for the label. `additionalPaths` are stroked afterwards without the clip:

```tsx
override getIndicatorPath(shape: MyShape) {
	const path = new Path2D()
	path.moveTo(0, 0)
	path.lineTo(shape.props.w, shape.props.h)

	// Even-odd: the outer rect keeps everything, the inner rect punches a hole
	const clipPath = new Path2D()
	clipPath.rect(-100, -100, shape.props.w + 200, shape.props.h + 200)
	clipPath.rect(40, 40, 20, 20)

	return { path, clipPath }
}
```

## Hinting shapes

Hinting shapes are shapes that receive a highlighted indicator during drag operations. Use [`Editor.setHintingShapes`](/reference/editor/Editor#setHintingShapes) to mark shapes as drop targets:

```tsx
// Highlight a shape as a potential drop target
editor.setHintingShapes([targetShapeId])

// Clear hinting
editor.setHintingShapes([])
```

## Customizing indicators

The stroke widths and paint order live on `ShapeIndicatorOverlayUtil.options` (`lineWidth`, `hintedLineWidth`, `zIndex`). Adjust them with `configure`, or subclass the util and override `getOverlays()` to change which shapes get indicators, then pass it through the `overlayUtils` prop. See [Overlay utils](/sdk-features/overlay-utils) for how overlay utils are registered and replaced.

```tsx
import { ShapeIndicatorOverlayUtil, Tldraw } from 'tldraw'

const ThickIndicators = ShapeIndicatorOverlayUtil.configure({ lineWidth: 3 })

function App() {
	return <Tldraw overlayUtils={[ThickIndicators]} />
}
```

## Related articles

- [Shapes](/sdk-features/shapes) - Learn how to create custom shapes with their own indicators
- [Selection](/sdk-features/selection) - Understand how selection state controls indicator visibility
- [Overlay utils](/sdk-features/overlay-utils) - The overlay system that draws indicators

## Related examples

- [Custom shape](/examples/shapes/tools/custom-shape) - Create a custom shape with an indicator
- [Custom indicators](/examples/ui/indicators-logic) - Control which shapes show indicators

--------

# Input handling

The [`InputsManager`](/reference/editor/InputsManager) class tracks pointer and keyboard state for the editor. It stores pointer positions in both screen space and page space, tracks pressed keys and buttons, detects device types (mouse, touch, pen), and calculates pointer velocity. Access it through `editor.inputs`.

All input state is reactive. The manager stores values as atoms from `@tldraw/state`, so components that read input state automatically update when those values change. The manager updates on every input event, converting coordinates between screen space and page space.

## Pointer position tracking

The manager tracks pointer positions in two coordinate spaces. Screen space is pixels relative to the canvas container's origin. Page space is the position on the infinite canvas, adjusted for camera position and zoom.

In each space, the manager keeps three positions: current, previous, and origin.

### Current and previous positions

```typescript
editor.inputs.getCurrentScreenPoint() // Current position in screen space
editor.inputs.getCurrentPagePoint() // Current position in page space

editor.inputs.getPreviousScreenPoint() // Previous position in screen space
editor.inputs.getPreviousPagePoint() // Previous position in page space
```

The current position updates on every pointer event. The previous position stores where the pointer was before the most recent update. You can use these together to calculate deltas for dragging and panning:

```typescript
const delta = Vec.Sub(editor.inputs.getCurrentPagePoint(), editor.inputs.getPreviousPagePoint())
```

### Origin positions

The origin position captures where the most recent `pointer_down` event occurred:

```typescript
editor.inputs.getOriginScreenPoint() // Where pointer_down occurred in screen space
editor.inputs.getOriginPagePoint() // Where pointer_down occurred in page space
```

Tools use the origin to calculate drag distances and determine whether an interaction has moved far enough to trigger behaviors like dragging. The origin resets on every `pointer_down` event and continuously while a pinch is in progress.

### Coordinate space conversion

The manager converts screen coordinates to page coordinates using the camera's position and zoom:

```typescript
// Screen to page conversion
const pageX = screenX / camera.z - camera.x
const pageY = screenY / camera.z - camera.y
```

## Pointer velocity

The manager tracks pointer velocity for gesture detection:

```typescript
editor.inputs.getPointerVelocity() // Vec with x/y velocity in pixels per millisecond
```

The manager listens to the editor's `frame` event and recomputes velocity once per frame (not on each pointer event) from the screen-space distance traveled since the previous frame. It smooths the result against the previous value and clamps components below 0.01 to zero to prevent jitter.

Tools use velocity to distinguish between slow, precise interactions and fast flick gestures. Velocity resets to zero on `pointer_down` events and continuously while a pinch is in progress.

## Input device detection

The manager tracks whether the most recent pointer event came from a pen (`pointerType === 'pen'`):

```typescript
editor.inputs.getIsPen() // true for stylus input
```

Pen mode ignores non-pen input to prevent accidental touch interactions while using a stylus. The editor only turns pen mode on automatically for direct-display pens (Apple Pencil, Surface Pen), flagged as `isPenDirect` on the pointer event; desktop graphics tablets still draw as pens without enabling it.

## Modifier keys and button states

The manager tracks modifier key states:

```typescript
editor.inputs.getShiftKey()
editor.inputs.getAltKey()
editor.inputs.getCtrlKey()
editor.inputs.getMetaKey()
editor.inputs.getAccelKey() // Cmd on Mac, Ctrl elsewhere
```

The `getAccelKey()` method returns true for Command on macOS and Control on other platforms. Use this for cross-platform shortcuts.

### Button tracking

The manager tracks currently pressed pointer buttons in a reactive set:

```typescript
editor.inputs.buttons.has(0) // Primary button (left click)
editor.inputs.buttons.has(1) // Middle button
editor.inputs.buttons.has(2) // Secondary button (right click)
```

Buttons are added on `pointer_down` events and removed on `pointer_up` events.

### Keyboard key tracking

The manager tracks pressed keyboard keys in a reactive set:

```typescript
editor.inputs.keys.has('Space')
editor.inputs.keys.has('ShiftLeft')
```

The editor adds keys on `key_down` and removes them on `key_up`. Tools can use this to detect held keys during pointer operations. For example, the editor checks `keys.has('Space')` on pointer up to decide whether to keep spacebar panning active.

## Interaction state flags

The manager tracks the current interaction state:

```typescript
editor.inputs.getIsPointing() // Pointer button is down
editor.inputs.getIsRightPointing() // Right button is down, before the drag threshold
editor.inputs.getIsDragging() // Pointer moved beyond drag threshold while pointing
editor.inputs.getIsPinching() // Two-finger pinch gesture active
editor.inputs.getIsEditing() // Editing text or other content
editor.inputs.getIsPanning() // Panning the canvas
editor.inputs.getIsSpacebarPanning() // Panning via spacebar (vs. other panning modes)
```

The editor sets these flags during event processing. For example, `isPointing` becomes true on `pointer_down` and false on `pointer_up`. The `isDragging` flag becomes true when the pointer moves beyond the drag distance threshold (`dragDistanceSquared` or `coarseDragDistanceSquared` in the editor's [options](/sdk-features/options)) while pointing.

## Event processing flow

When an input event occurs, the editor processes it through these stages:

1. The browser fires a native DOM event
2. The canvas event handlers transform it into a typed event info object and call [`Editor.dispatch`](/reference/editor/Editor#dispatch)
3. `pointer_move`, `wheel`, and `pinch` events are queued and flushed once per frame; other events flush immediately
4. The editor emits `before-event`, then updates modifier key state
5. For pointer, pinch, and wheel events, the editor calls `updateFromEvent()` on the `InputsManager`
6. For pointer events, the editor updates buttons and interaction flags, then hands the event to the `ClickManager` for double-click detection
7. The editor sends the event to the state machine via `root.handleEvent()`, which propagates it through active tool states, then emits `event`

See [Events](/sdk-features/events) for subscribing to `before-event` and `event`.

The typed event info objects are:

| Event type      | Info type             |
| --------------- | --------------------- |
| Pointer events  | `TLPointerEventInfo`  |
| Click events    | `TLClickEventInfo`    |
| Keyboard events | `TLKeyboardEventInfo` |
| Wheel events    | `TLWheelEventInfo`    |
| Pinch events    | `TLPinchEventInfo`    |

In collaborative sessions, `updateFromEvent()` also updates the user's pointer presence record in the store, broadcasting pointer position to other users.

## Input normalization

The editor listens to Pointer Events, so mouse, touch, and pen input arrive through the same handlers, and the manager tracks the device type through the `isPen` flag.

Pointer positions include a `z` coordinate carrying the pointer event's pressure; synthetic events without a `z` default to 0.5. The manager subtracts the container's screen bounds from client coordinates, so the editor works correctly in nested layouts and scrolled containers.

## State serialization

The manager provides a `toJson()` method for debugging:

```typescript
const state = editor.inputs.toJson()
// Returns all position vectors, modifier key states, interaction flags,
// device type, and the contents of the keys and buttons sets
```

We use this serialized form when generating crash reports.

## Related examples

- [Reactive inputs](/examples/editor-api/reactive-inputs) - Display pointer positions, velocity, and other input state reactively
- [Canvas events](/examples/events/canvas-events) - Log pointer, keyboard, and wheel events to see the event flow

--------

# Instance state

Instance state is the per-tab state that tracks your current session. It includes which page you're viewing, whether the grid is visible, if debug mode is on, and transient interaction state like the current cursor.

Unlike document state (shapes, pages, assets), instance state belongs to a single browser tab and isn't synced between collaborators.

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					// Enable grid mode and debug mode
					editor.updateInstanceState({
						isGridMode: true,
						isDebugMode: true,
					})
				}}
			/>
		</div>
	)
}
```

## Reading instance state

Use [`Editor.getInstanceState`](/reference/editor/Editor#getInstanceState) to access the current instance state. The returned object contains all session properties:

```typescript
const instance = editor.getInstanceState()

// Check modes
instance.isGridMode // true if grid is visible
instance.isDebugMode // true if debug overlays are shown
instance.isFocusMode // true if UI is minimized
instance.isPenMode // true once a direct-display stylus (e.g. Apple Pencil) is used
instance.isToolLocked // true if tool stays active after creating shapes
instance.isReadonly // true if editing is disabled

// Current state
instance.currentPageId // which page is active
instance.cursor // cursor type and rotation
instance.isFocused // whether the editor has focus

// Screen information
instance.screenBounds // viewport dimensions
instance.devicePixelRatio // display scaling factor
instance.isCoarsePointer // true for touch input
```

The result is reactive. When you access it inside a `track` component or `react` callback, your code re-runs when the state changes:

```tsx
import { track, useEditor } from 'tldraw'

const DebugIndicator = track(function DebugIndicator() {
	const editor = useEditor()
	const { isDebugMode, isGridMode } = editor.getInstanceState()

	return (
		<div>
			Debug: {isDebugMode ? 'on' : 'off'}, Grid: {isGridMode ? 'on' : 'off'}
		</div>
	)
})
```

## Updating instance state

Use [`Editor.updateInstanceState`](/reference/editor/Editor#updateInstanceState) to modify instance properties:

```typescript
// Enable grid mode
editor.updateInstanceState({ isGridMode: true })

// Enable multiple options at once
editor.updateInstanceState({
	isDebugMode: true,
	isToolLocked: true,
})

// Toggle a mode
const { isGridMode } = editor.getInstanceState()
editor.updateInstanceState({ isGridMode: !isGridMode })
```

Changes take effect immediately. By default they are not added to the undo stack; pass `{ history: 'record' }` as the second argument to record them. When using a `persistenceKey`, some properties persist across sessions (see [Session persistence](#session-persistence) below).

Note that `currentPageId` cannot be changed through `updateInstanceState`. Use [`Editor.setCurrentPage`](/reference/editor/Editor#setCurrentPage) instead.

## Available properties

### Mode flags

These boolean flags control major editor behaviors:

| Property       | Description                                                                                           | Persists |
| -------------- | ----------------------------------------------------------------------------------------------------- | -------- |
| `isGridMode`   | Show grid overlay on the canvas                                                                       | Yes      |
| `isDebugMode`  | Show the debug panel (current tool state, debug menu)                                                 | Yes      |
| `isFocusMode`  | Minimize the UI to just the canvas                                                                    | Yes      |
| `isToolLocked` | Keep current tool active after creating a shape                                                       | Yes      |
| `isReadonly`   | Prevent document edits, except for shapes whose util allows editing in readonly                       | No       |
| `isPenMode`    | Set automatically when a direct-display stylus (e.g. Apple Pencil) is used; touch is ignored while on | No       |
| `isFocused`    | Whether the editor currently has keyboard focus                                                       | No       |

### Display state

Properties that track the current display environment:

| Property           | Description                                                                                      | Persists |
| ------------------ | ------------------------------------------------------------------------------------------------ | -------- |
| `screenBounds`     | Viewport position and dimensions (x, y, w, h)                                                    | No       |
| `devicePixelRatio` | Display scaling factor (e.g., 2 for Retina)                                                      | No       |
| `isCoarsePointer`  | Indicates touch or low-precision input is active; mirrors `tlenvReactive`                        | No       |
| `isHoveringCanvas` | Whether pointer is over the canvas (null if no hover support)                                    | No       |
| `insets`           | Whether the container is inset from the document edge on each side, `[top, right, bottom, left]` | No       |

### Navigation state

| Property        | Description                                            | Persists |
| --------------- | ------------------------------------------------------ | -------- |
| `currentPageId` | ID of the currently active page                        | Yes      |
| `openMenus`     | Unused by the SDK; open menus are tracked by `tlmenus` | No       |

### Interaction state

Temporary state used during user interactions:

| Property          | Description                                                  | Persists |
| ----------------- | ------------------------------------------------------------ | -------- |
| `cursor`          | Current cursor type and rotation                             | No       |
| `brush`           | Selection brush bounds during drag selection                 | No       |
| `zoomBrush`       | Zoom brush bounds during zoom-to-area                        | No       |
| `scribbles`       | Active scribble animations (eraser trails, etc.)             | No       |
| `isChangingStyle` | Set after a style change; resets after 1s or on pointer move | No       |
| `cameraState`     | Whether the camera is `'idle'` or `'moving'`                 | No       |

### Shape creation

Settings that affect newly created shapes:

| Property              | Description                         | Persists |
| --------------------- | ----------------------------------- | -------- |
| `opacityForNextShape` | Opacity applied to new shapes (0-1) | No       |
| `stylesForNextShape`  | Style values applied to new shapes  | No       |
| `duplicateProps`      | State for smart duplicate offset    | No       |

### Collaboration

Properties for multiplayer features:

| Property             | Description                                | Persists |
| -------------------- | ------------------------------------------ | -------- |
| `followingUserId`    | ID of user being followed, or null         | No       |
| `highlightedUserIds` | IDs of users whose cursors are highlighted | No       |
| `chatMessage`        | Current chat message being composed        | No       |
| `isChatting`         | Whether chat input is active               | No       |

### Custom data

| Property           | Description                              | Persists |
| ------------------ | ---------------------------------------- | -------- |
| `meta`             | Arbitrary JSON data for your application | No       |
| `exportBackground` | Include background color when exporting  | Yes      |

The "Persists" column shows what a `persistenceKey` saves between sessions. Separately, when you call `loadSnapshot`, a wider set of instance properties (screen bounds, pointer type, readonly, and the mode flags above) is preserved from the existing store rather than overwritten by the snapshot; see [`TLSessionStateSnapshot`](/reference/editor/TLSessionStateSnapshot).

## Common patterns

### Focus mode

Focus mode hides most of the UI for presentation or distraction-free editing:

```typescript
editor.updateInstanceState({ isFocusMode: true })
```

### Grid mode

Show a grid overlay to help with alignment:

```typescript
editor.updateInstanceState({ isGridMode: true })
```

The grid respects the camera zoom level. You can customize the grid appearance by overriding the `Grid` component via the `components` prop.

### Debug mode

Debug mode shows the debug panel: the current tool state path, an optional FPS counter, and the debug menu:

```typescript
editor.updateInstanceState({ isDebugMode: true })
```

### Tool lock

When tool lock is enabled, the current tool stays active after creating a shape instead of returning to the select tool:

```typescript
editor.updateInstanceState({ isToolLocked: true })
```

Custom tools should check this property to decide whether to return to select after completing their action. See [Tools](/sdk-features/tools#tool-lock) for implementation details.

### Cursor customization

Set a custom cursor type and rotation:

```typescript
// Use the setCursor helper
editor.setCursor({ type: 'cross', rotation: 0 })

// Or update directly
editor.updateInstanceState({
	cursor: { type: 'grab', rotation: 0 },
})
```

See [Cursors](/sdk-features/cursors) for the full list of cursor types and rotation handling.

### Detecting touch input

Check `isCoarsePointer` to adapt your UI for touch:

```tsx
const { isCoarsePointer } = editor.getInstanceState()
const buttonSize = isCoarsePointer ? 48 : 32 // Larger touch targets
```

The value updates automatically when the user switches between mouse and touch.

## Session persistence

When you use a `persistenceKey` on the [`Tldraw`](/reference/tldraw/Tldraw) component, some instance properties persist across browser sessions. Properties marked "Persists: Yes" in the tables above are saved and restored, along with each page's camera and selection.

Temporary state like cursor position, selection brushes, and scribbles always resets when the page reloads. `currentPageId` is restored only if that page still exists in the document.

## Instance state vs page state

Instance state ([`TLInstance`](/reference/tlschema/TLInstance)) is global to the editor: there's one instance record per browser tab. Page state ([`TLInstancePageState`](/reference/tlschema/TLInstancePageState)) is per-page and tracks selection, hover, editing, cropping, and focused group for that page. See [Selection](/sdk-features/selection).

```typescript
// Instance state: global to the editor
const instance = editor.getInstanceState()
instance.currentPageId // which page is active
instance.isGridMode // applies to all pages

// Page state: specific to the current page
const pageState = editor.getCurrentPageState()
pageState.selectedShapeIds // selection on this page
pageState.editingShapeId // shape being edited on this page
pageState.hoveredShapeId // shape under cursor on this page
```

When you switch pages, the instance's `currentPageId` changes, but each page retains its own selection and editing state.

## Related articles

- [Cursors](/sdk-features/cursors) — Cursor types and rotation handling
- [Readonly mode](/sdk-features/readonly) — Disable editing with `isReadonly`
- [Focus](/sdk-features/focus) — Editor focus state with `isFocused`
- [Tools](/sdk-features/tools#tool-lock) — Tool lock behavior with `isToolLocked`
- [User preferences](/sdk-features/user-preferences) — Global preferences that persist across editor instances

## Related examples

- **[Focus mode](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/editor-api/focus-mode)** — Enable focus mode to minimize the UI.
- **[Custom grid](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/ui/custom-grid)** — Use `isGridMode` with a custom grid component.
- **[Read-only](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/readonly)** — Disable editing with `isReadonly`.

--------

# Internationalization

Tldraw's UI supports 49 languages out of the box, including right-to-left languages like Arabic, Hebrew, Farsi, and Urdu. The translation system loads language files on demand, detects the user's browser language, and lets you override any translation string or add custom ones.

## Setting the locale

The user's locale is stored in [user preferences](/sdk-features/user-preferences). By default, tldraw detects the browser's language and selects the closest match from supported languages. The default main menu also includes a language submenu where users can change it.

To set the locale from your application, update the user's locale preference. The UI reads its language from `editor.user.getLocale()`, so this takes effect immediately:

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					// Change the locale to French
					editor.user.updateUserPreferences({ locale: 'fr' })

					// Get the current locale
					const locale = editor.user.getLocale() // "fr"
				}}
			/>
		</div>
	)
}
```

The `locale` value uses lowercase language codes: `'en'`, `'fr'`, `'de'`, `'ja'`, `'zh-cn'`, `'ar'`, and so on.

The `Tldraw` component also has a `locale` prop. Today it only sets the language for the outer translation provider (used by the loading screen); the editor UI itself keeps reading the user preference, so prefer `updateUserPreferences` to change the visible language.

### Automatic detection

When no locale is set, tldraw uses [`getDefaultTranslationLocale`](/reference/tlschema/getDefaultTranslationLocale) to detect the user's preferred language from the browser:

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

// Returns 'fr', 'en', 'zh-cn', etc. based on browser settings
const locale = getDefaultTranslationLocale()
```

For each entry in the browser's `navigator.languages` array, in order, it:

1. Tries an exact match against supported languages
2. Falls back to a language-only match (e.g., `'fr-CA'` → `'fr'`)
3. Applies region defaults for Chinese (`'zh'` → `'zh-cn'`), Portuguese (`'pt'` → `'pt-br'`), Korean (`'ko'` → `'ko-kr'`), and Hindi (`'hi'` → `'hi-in'`)

The first entry that matches wins. If none match, it defaults to `'en'`.

## Using translations in components

The [`useTranslation`](/reference/tldraw/useTranslation) hook returns a function for looking up translation strings. Unknown keys are returned as-is, so you can pass plain text or your own keys:

```tsx
import { useTranslation } from 'tldraw'

function CopyButton() {
	const msg = useTranslation()
	return <button>{msg('action.copy')}</button>
}
```

Use [`useCurrentTranslation`](/reference/tldraw/useCurrentTranslation) for the full translation object, including locale and text direction:

```tsx
import { useCurrentTranslation } from 'tldraw'

function LocaleInfo() {
	const translation = useCurrentTranslation()
	return (
		<div dir={translation.dir}>
			<p>Locale: {translation.locale}</p>
			<p>Label: {translation.label}</p>
		</div>
	)
}
```

The [`TLUiTranslation`](/reference/tldraw/TLUiTranslation) object contains a `locale` code (e.g., `'fr'`), a `label` in the native script (e.g., `'Français'`), a `messages` record with all translation strings, and a `dir` indicating text direction (`'ltr'` or `'rtl'`).

## Overriding translations

Pass translation overrides through the `overrides` prop on `Tldraw`:

```tsx
import { Tldraw } from 'tldraw'

function App() {
	return (
		<Tldraw
			overrides={{
				translations: {
					en: {
						'action.copy': 'Copy to clipboard',
						'action.paste': 'Paste from clipboard',
					},
					fr: {
						'action.copy': 'Copier dans le presse-papiers',
					},
				},
			}}
		/>
	)
}
```

Overrides are merged with the base translations for each language. English is the fallback: any key missing from the target language uses the English string. If you add your own keys (for example a custom tool label), provide at least an `en` override for them.

### Translation keys

Translation keys follow a hierarchical naming convention. Common prefixes include `action.*` for user actions like copy and paste, `tool.*` for tool names, `menu.*` for menu labels, `style-panel.*` for style panel UI, and `a11y.*` for accessibility announcements.

The [`TLUiTranslationKey`](/reference/tldraw/TLUiTranslationKey) type provides autocomplete for all available keys:

```ts
import type { TLUiTranslationKey } from 'tldraw'

const key: TLUiTranslationKey = 'action.copy'
```

## Supported languages

Import [`LANGUAGES`](/reference/tlschema/LANGUAGES) from `tldraw` for the complete list of supported languages:

```tsx
import { LANGUAGES } from 'tldraw'

function LanguageSelector() {
	return (
		<select>
			{LANGUAGES.map(({ locale, label }) => (
				<option key={locale} value={locale}>
					{label}
				</option>
			))}
		</select>
	)
}
```

Each entry in `LANGUAGES` is a [`TLLanguage`](/reference/tlschema/TLLanguage) with a `locale` code and a `label` in that language's native script. Translation files are only loaded for locales in this list, so you can't add a new language by supplying a translation file alone.

The supported languages include: English, Spanish, French, German, Italian, Portuguese (Brazilian and European), Dutch, Russian, Polish, Czech, Danish, Finnish, Swedish, Hungarian, Norwegian, Romanian, Turkish, Ukrainian, Greek, Croatian, Slovenian, Arabic, Hebrew, Farsi, Urdu, Hindi, Tamil, Telugu, Malayalam, Kannada, Bengali, Gujarati, Nepali, Marathi, Punjabi, Thai, Khmer, Vietnamese, Indonesian, Malay, Filipino, Somali, Japanese, Korean, Simplified Chinese, Traditional Chinese (Taiwan), Catalan, and Galician.

## Right-to-left support

Languages like Arabic, Hebrew, Farsi, and Urdu automatically set `dir: 'rtl'` in the translation object. The tldraw UI respects this direction. Layout and text alignment mirror automatically. The `dir` attribute is set on the editor's root container, and the built-in components use CSS logical properties (`margin-inline-start`, `inset-inline-end`, and so on) so they flip without per-component code.

When building custom UI components, use the [`useDirection`](/reference/tldraw/useDirection) hook to get the current text direction. It returns `'ltr'` or `'rtl'` from the active translation context, the same value as `useCurrentTranslation().dir`:

```tsx
import { useDirection } from 'tldraw'

function CustomPanel() {
	const dir = useDirection()
	return <aside dir={dir}>{/* Panel content */}</aside>
}
```

Use `useCurrentTranslation` instead when you also need the locale, label, or `messages` from the same render.

## Building a language picker

Here's a language picker that updates the user's locale preference:

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

function LanguagePicker() {
	const editor = useEditor()
	const currentLocale = useValue('locale', () => editor.user.getLocale(), [editor])

	return (
		<select
			value={currentLocale}
			onChange={(e) => {
				editor.user.updateUserPreferences({ locale: e.target.value })
			}}
		>
			{LANGUAGES.map(({ locale, label }) => (
				<option key={locale} value={locale}>
					{label}
				</option>
			))}
		</select>
	)
}
```

The language change applies immediately without a page reload. The preference persists to localStorage and synchronizes across browser tabs.

## Translation loading

Translations load asynchronously when the locale changes. The system:

1. Fetches the translation JSON file for the selected locale
2. Merges it with English translations (ensuring all keys have values)
3. Applies any custom overrides
4. Updates the translation context

During loading, the UI uses the previous translations to avoid flicker. If loading fails, English remains as the fallback.

To use translations outside the full tldraw UI, wrap your components in [`TldrawUiTranslationProvider`](/reference/tldraw/TldrawUiTranslationProvider) (inside an `AssetUrlsProvider`).

## Related examples

- [Custom translations and overrides](/examples/ui/custom-language-translations) - Override translation strings and use them in custom UI.

--------

# License key

The tldraw SDK requires a license key to work in production. Without a valid key, the SDK runs in development mode only. License keys unlock production deployment and, depending on your license type, may remove the "made with tldraw" watermark.

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw licenseKey="your-license-key" />
		</div>
	)
}
```

## How license keys work

License keys are validated on the client. They can be public: you can safely include them in your frontend code. The SDK decodes and verifies the key's signature locally without making network requests to a license server.

Each key encodes the allowed hosts (the domains where the license is valid), the license type (trial, commercial, or hobby), and the expiration date.

## Using the license key

Pass the key to the `licenseKey` prop on [`Tldraw`](/reference/tldraw/Tldraw), [`TldrawEditor`](/reference/editor/TldrawEditor), or [`TldrawImage`](/reference/tldraw/TldrawImage):

```tsx
<Tldraw licenseKey="tldraw-abc123..." />
```

```tsx
<TldrawImage snapshot={snapshot} licenseKey="tldraw-abc123..." />
```

You can also reference an environment variable explicitly:

```tsx
<Tldraw licenseKey={process.env.NEXT_PUBLIC_TLDRAW_LICENSE_KEY} />
```

### Automatic environment variable detection

The SDK also checks for license keys in common environment variables. If you set one of these, you don't need to pass the `licenseKey` prop:

- `TLDRAW_LICENSE_KEY`
- `NEXT_PUBLIC_TLDRAW_LICENSE_KEY` (Next.js)
- `REACT_APP_TLDRAW_LICENSE_KEY` (Create React App)
- `GATSBY_TLDRAW_LICENSE_KEY` (Gatsby)
- `VITE_TLDRAW_LICENSE_KEY` (Vite)
- `PUBLIC_TLDRAW_LICENSE_KEY` (SvelteKit, etc.)

The SDK checks both `process.env` and `import.meta.env` versions of each variable.

## License types

| Type       | Watermark | Duration | Purpose                           |
| ---------- | --------- | -------- | --------------------------------- |
| Trial      | No        | 100 days | Evaluate before purchasing        |
| Commercial | No        | Annual   | Production use in commercial apps |
| Hobby      | Yes       | Varies   | Non-commercial projects           |

### Trial licenses

Get a free 100-day trial by completing the [trial license form](https://tldraw.dev/get-a-license/trial). You'll receive a license key immediately by email. One trial per company or project.

### Commercial licenses

Request a commercial license through the [plans form](https://tldraw.dev/get-a-license/plans). The sales team will discuss your requirements and pricing. Commercial licenses remove the watermark and are required for any commercial use in production.

### Hobby licenses

For non-commercial projects, request a [hobby license](https://tldraw.dev/get-a-license/hobby). Hobby licenses keep the "made with tldraw" watermark visible. They're discretionary: we review each request.

## Development vs production

In development environments, the SDK works without a license key. The SDK treats the environment as development if any of these are true: the protocol is not HTTPS, the hostname is `localhost` or a loopback address (`127.x.x.x`, `::1`), or `NODE_ENV` is not `'production'`.

In production (HTTPS on a non-loopback domain with `NODE_ENV=production`), the SDK requires a valid license key. Without one, the SDK logs errors to the console and, after five seconds, stops rendering the editor.

Keys are only verified when `crypto.subtle` is available. On plain HTTP in development, the browser doesn't expose it, so the SDK skips verification and logs a note asking you to check the key in production separately.

## Domain validation

License keys specify which domains they work on. The SDK validates the current hostname against the allowed hosts in the key.

An exact host like `example.com` matches `example.com` and `www.example.com`. A wildcard like `*.example.com` matches any subdomain. Some enterprise licenses allow `*` for any domain.

If you deploy to a domain not covered by your license, the SDK treats it as unlicensed.

## Grace period

Annual and perpetual licenses have a 30-day grace period after expiration. During this period, the SDK continues working but logs a message to the console. This gives you time to renew without service interruption. After the grace period the SDK stops rendering the editor.

Evaluation (trial) licenses have no grace period. They stop working immediately on expiration.

## Perpetual licenses

Perpetual licenses don't have a time-based expiration. Instead, they're tied to a version: they work with any patch release indefinitely, but major or minor versions released after the license expiration date (plus the 30-day grace period) require renewal.

Early versions of tldraw were sold with a perpetual license. While we no longer sell these licenses (except in exceptional cases), we still support them for existing customers.

## Data collection

Data collection differs by license type:

| License type | Data sent                                           |
| ------------ | --------------------------------------------------- |
| Commercial   | None                                                |
| Hobby        | License ID, license type, SDK version, and page URL |
| Trial        | License ID, license type, SDK version, and page URL |
| Unlicensed   | SDK version and page URL (production only)          |

Trial and hobby licenses ping tldraw's servers with the license ID, license type, SDK version, build environment, and deployment URL for analytics. No user data, canvas content, or personally identifiable information is collected. Nothing is sent from development environments.

## Troubleshooting

**Console shows "No tldraw license key provided" and "A license is required for production deployments"**: You're in production without a key, and the editor will stop rendering after five seconds. Add a valid `licenseKey` prop or set an environment variable.

**Console shows "License key is not valid for this domain"**: Your key doesn't include the current domain. Contact sales@tldraw.com to update your allowed domains.

**Console shows "Your tldraw evaluation license has expired"**: Trial licenses have no grace period. Contact sales@tldraw.com to purchase a full license.

**Console shows "Your tldraw license has been expired for more than 30 days"**: Your license is past the 30-day grace period. Contact sales@tldraw.com to renew.

**Key works locally but not in production**: Development mode doesn't require a key. Make sure you're passing the key correctly in your production build and that the domain matches your license.

## Learn more

See the [License](/community/license) page for full details on the tldraw license terms, including information about open source usage and trademark guidelines.

--------

# Locked shapes

Locked shapes can't be selected, moved, resized, edited, or deleted through normal interactions. Lock a shape when you want it to stay exactly where it is: background elements, reference images, or layout guides that shouldn't move while you work on other parts of the canvas.

## The isLocked property

Every [shape](/docs/shapes) has an `isLocked` boolean property. When `true`, the shape is protected from most modifications:

```typescript
// Create a locked shape
editor.createShape({
	type: 'geo',
	x: 100,
	y: 100,
	isLocked: true,
	props: { w: 200, h: 150, geo: 'rectangle' },
})

// Check if a shape is locked
const shape = editor.getShape(shapeId)
if (shape.isLocked) {
	// Shape is locked
}
```

## Toggling lock state

Use [`Editor.toggleLock`](/reference/editor/Editor#toggleLock) to flip the lock state of shapes. If shapes have mixed lock states, they all become locked:

```typescript
// Lock selected shapes
editor.toggleLock(editor.getSelectedShapeIds())

// Lock specific shapes by ID
editor.toggleLock([shapeId1, shapeId2])
```

When you lock shapes that were all previously unlocked, they automatically deselect. This prevents accidentally manipulating them while they're protected.

## What locking prevents

Locked shapes resist most operations:

| Operation    | Behavior                                                                                                 |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| Selection    | Clicking a locked shape doesn't select it. Brush selection and [`Editor.selectAll`](/reference/editor/Editor#selectAll) skip locked shapes. |
| Movement     | Pointer drags pass through locked shapes to the canvas.                                                  |
| Modification | [`Editor.updateShape`](/reference/editor/Editor#updateShape) ignores locked shapes, except for an update that unlocks them.                   |
| Deletion     | [`Editor.deleteShapes`](/reference/editor/Editor#deleteShapes) and [`Editor.duplicateShapes`](/reference/editor/Editor#duplicateShapes) skip locked shapes.                             |
| Grouping     | [`Editor.groupShapes`](/reference/editor/Editor#groupShapes) and [`Editor.ungroupShapes`](/reference/editor/Editor#ungroupShapes) skip locked shapes.                                |
| Editing      | Double-clicking a locked shape doesn't enter edit mode.                                                  |

Right-clicking a locked shape still selects it so the context menu can offer an unlock option. If you want left-click, brush, and scribble selection to include locked shapes too, set the `selectLockedShapes` option in [`TldrawOptions`](/reference/editor/TldrawOptions). The shapes stay protected from moves, edits, and deletes; `selectAll` still skips them.

## Ancestor locking

Lock state inherits through the shape hierarchy. If a shape's ancestor is locked, the shape behaves as locked too. Check this with [`Editor.isShapeOrAncestorLocked`](/reference/editor/Editor#isShapeOrAncestorLocked):

```typescript
// True if the shape or any of its parents is locked
const isProtected = editor.isShapeOrAncestorLocked(shape)
```

Locking a frame or group protects its children from pointer interactions and [`Editor.updateShapes`](/reference/editor/Editor#updateShapes) without locking each shape individually. Bulk operations such as [`Editor.deleteShapes`](/reference/editor/Editor#deleteShapes) only check each shape's own `isLocked`, so a child of a locked frame can still be deleted programmatically.

## Bypassing locks programmatically

Sometimes you need to modify locked shapes from code: migrations, admin tools, or automated operations. Wrap your operations in [`Editor.run`](/reference/editor/Editor#run) with `ignoreShapeLock: true`:

```typescript
editor.run(
	() => {
		// These operations affect locked shapes
		editor.updateShape({ id: lockedShapeId, type: 'geo', x: 200 })
		editor.deleteShapes([lockedShapeId])
	},
	{ ignoreShapeLock: true }
)
```

This bypasses the lock check for all operations inside the callback.

Even with `ignoreShapeLock: true`, some behaviors remain unchanged: locked shapes still can't be selected by clicking, pointer events still pass through to the canvas, and `selectAll()` still skips locked shapes. The flag affects [`Editor.updateShapes`](/reference/editor/Editor#updateShapes), [`Editor.deleteShapes`](/reference/editor/Editor#deleteShapes), [`Editor.duplicateShapes`](/reference/editor/Editor#duplicateShapes), [`Editor.groupShapes`](/reference/editor/Editor#groupShapes), and [`Editor.ungroupShapes`](/reference/editor/Editor#ungroupShapes), not the selection and interaction model.

## Shapes that can be edited while locked

Some shapes have interactive content that should remain usable even when locked. Embed shapes (YouTube videos, Figma files, interactive maps) are a good example: you might want the embed locked in place but still playable or navigable.

[ShapeUtils](/sdk-features/shapes#shapeutil) can override [`ShapeUtil.canEditWhileLocked`](/reference/editor/ShapeUtil#canEditWhileLocked) (default `false`) to allow editing interactions on locked shapes. The built-in embed shape returns `true` unless its embed definition says otherwise:

```typescript
class MyInteractiveShapeUtil extends ShapeUtil<MyShape> {
	override canEditWhileLocked(shape: MyShape): boolean {
		return true
	}
}
```

When this returns `true`, [`Editor.canEditShape`](/reference/editor/Editor#canEditShape) allows the shape to enter edit mode while locked, so users can interact with its content without moving or resizing it. It doesn't make the shape hit-testable on its own: with default options a double-click on a locked shape still passes through to the canvas. The shape enters edit mode when you call [`Editor.setEditingShape`](/reference/editor/Editor#setEditingShape), or when the user selects it (for example with `selectLockedShapes` enabled) and presses Enter or double-clicks.

## Locking in the UI

In the default tldraw UI, users can lock shapes through the context menu or the keyboard shortcut (`Shift+L`). Right-clicking a locked shape opens the context menu with an unlock option, and the main menu has an "Unlock all" action.

## Related examples

- [Locked shapes](/examples/editor-api/locked-shapes) - Create locked shapes and modify them with `ignoreShapeLock`.

--------

# Note shape

The note shape is a sticky note: a colored square with text. Notes are built for brainstorming: you can spawn new notes next to existing ones with clone handles or keyboard shortcuts, and they snap into a grid beside their neighbors. See [`NoteShapeUtil`](/reference/tldraw/NoteShapeUtil) and [`TLNoteShape`](/reference/tlschema/TLNoteShape).

```tsx
import { toRichText } from 'tldraw'

editor.createShape({
	type: 'note',
	x: 100,
	y: 100,
	props: {
		color: 'yellow',
		labelColor: 'black',
		richText: toRichText('My note'),
		size: 'm',
		font: 'draw',
		align: 'middle',
		verticalAlign: 'middle',
	},
})
```

## Sizing behavior

Notes have a fixed base width of 200 pixels (the `noteWidth` display value). Unlike most shapes, you can't manually resize a note by default. Instead, notes grow vertically to fit their text. The `growY` property tracks how much extra height the note needs beyond its base size.

When text is too wide, the note shrinks the font size (down to a minimum of 14px) before allowing text to wrap. This keeps notes compact without hiding content.

## Clone handles

Notes display clone handles on their edges—small plus buttons at the top, right, bottom, and left sides. These handles let you quickly create adjacent notes.

Click a clone handle to create a new note in that direction. If a note already exists there, tldraw selects it and starts editing instead. Drag a clone handle to create a new note and immediately start moving it; when you release, the new note enters edit mode.

Clone handles only appear when the note is selected and the effective zoom (zoom × note `scale`) is high enough. Below 25% they're hidden entirely, and between 25% and 50% only the bottom handle appears. Touch input never shows clone handles.

The handles come from [`ShapeUtil.getHandles`](/reference/editor/ShapeUtil#getHandles): each has `type: 'clone'` and an id of `top`, `right`, `bottom`, or `left`.

## Adjacent snapping

When you create a note with the note tool (`N` key) or drag an existing note, tldraw checks whether you're near an "adjacent position": an empty slot next to another note. If you're within 10 screen pixels of a slot, the note snaps into place with consistent spacing.

Snapping only considers notes with the same `scale`. New notes created with the tool only snap next to unrotated notes; dragged notes snap next to notes with matching rotation. The spacing comes from `editor.options.adjacentShapeMargin` (10 pixels by default; see [`TldrawOptions`](/reference/editor/TldrawOptions)).

## Keyboard navigation

When editing a note, you can use keyboard shortcuts to create adjacent notes:

| Shortcut                 | Action                      |
| ------------------------ | --------------------------- |
| **Tab**                  | Create or select note right |
| **Shift+Tab**            | Create or select note left  |
| **Cmd/Ctrl+Enter**       | Create or select note below |
| **Shift+Cmd/Ctrl+Enter** | Create or select note above |

These shortcuts respect the current note's rotation. They also handle right-to-left text: in RTL content, Tab moves left instead of right. When the cursor is inside a list, Tab indents the list item instead of creating a note.

When moving down, the keyboard shortcut accounts for the current note's `growY`. This keeps notes from overlapping when one note has grown taller than the base size.

## Visual appearance

Notes render with a subtle drop shadow seeded from the shape's ID, so each note has slightly different lift and opacity. The shadow responds to the note's rotation on the canvas. Below 25% effective zoom (adjusted for the note's `scale`) the shadow is replaced with a plain bottom border to keep rendering cheap.

The note's text color is determined by its `labelColor` property. When set to `'black'` (the default), the note uses a color that contrasts well with the background. Other label colors override this automatic selection.

## Properties

| Property             | Type                            | Description                                                                      |
| -------------------- | ------------------------------- | -------------------------------------------------------------------------------- |
| `color`              | `TLDefaultColorStyle`           | Background color of the note                                                     |
| `labelColor`         | `TLDefaultColorStyle`           | Text color (independent of background)                                           |
| `richText`           | `TLRichText`                    | Note content with formatting                                                     |
| `size`               | `TLDefaultSizeStyle`            | Size preset (`s`, `m`, `l`, `xl`) affecting base font                            |
| `font`               | `TLDefaultFontStyle`            | Font family (`draw`, `sans`, `serif`, `mono`)                                    |
| `align`              | `TLDefaultHorizontalAlignStyle` | Horizontal text alignment                                                        |
| `verticalAlign`      | `TLDefaultVerticalAlignStyle`   | Vertical text alignment                                                          |
| `fontSizeAdjustment` | `number \| null`                | Ratio applied to the base font size when text shrinks to fit (set automatically) |
| `growY`              | `number`                        | Additional height beyond the base 200px (set automatically)                      |
| `url`                | `string`                        | Optional hyperlink URL                                                           |
| `scale`              | `number`                        | Scale factor applied to the shape                                                |
| `textLastEditedBy`   | `string \| null`                | ID of the user who last edited the note's text (set automatically)               |

## Configuration

Notes support the following configuration options:

| Option       | Type                  | Default  | Description                                                       |
| ------------ | --------------------- | -------- | ----------------------------------------------------------------- |
| `resizeMode` | `'none'` \| `'scale'` | `'none'` | How the note resizes. Set to `'scale'` for manual resize handles. |

By default, notes can't be manually resized—they only grow based on text content. To allow user resizing with locked aspect ratio:

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

const ConfiguredNoteUtil = NoteShapeUtil.configure({
	resizeMode: 'scale',
})

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

See the [note resizing example](/examples/configuration/resize-note) for a working demo. Other display values, such as `noteWidth`, `noteHeight`, and colors, can be customized through the display value hooks on `NoteShapeUtil` options; see [Themes](/sdk-features/themes).

## Dynamic resize mode

When `editor.user.getIsDynamicResizeMode()` is true, new notes are created at a scale inversely proportional to the current zoom level, so they stay visually consistent regardless of zoom. [`Editor.getResizeScaleFactor`](/reference/editor/Editor#getResizeScaleFactor) returns that scale. See [Text shape](/sdk-features/text-shape#dynamic-resize-mode) for details.

## Related articles

- [Attribution](/sdk-features/attribution) — How notes display who last edited them in multiplayer sessions
- [Default shapes](/sdk-features/default-shapes) — Overview of all built-in shapes
- [Rich text](/sdk-features/rich-text) — Working with formatted text content
- [Styles](/sdk-features/styles) — Working with shape styles like color and size

--------

# Options

The tldraw editor accepts two kinds of configuration: **editor options** for core behavior (timing, limits, performance) and **component props** for UI, persistence, and content handling. Editor options are fixed after initialization; component props configure how the editor sets up.

## Editor options

The `options` prop accepts a `Partial<`[`TldrawOptions`](/reference/editor/TldrawOptions)`>` object that configures core editor behavior: limits like maximum pages and shapes, timing for interactions and animations, sizing for handles and hit testing, and feature toggles.

Options are set once when the editor initializes and cannot change afterward. Pass a partial options object to override specific values; everything else uses the defaults.

```tsx
import { Tldraw, TldrawOptions } from 'tldraw'

const options: Partial<TldrawOptions> = {
	maxPages: 3,
	maxShapesPerPage: 1000,
}

function App() {
	return <Tldraw options={options} />
}
```

## Reading options at runtime

After the editor initializes, access options through `editor.options`:

```typescript
const maxPages = editor.options.maxPages
const animationDuration = editor.options.animationMediumMs
```

The options object is readonly. Attempting to modify it has no effect and TypeScript will flag the error.

## Editor option categories

### Limits

Cap shape, page, and file counts:

| Option             | Default | Description                         |
| ------------------ | ------- | ----------------------------------- |
| `maxShapesPerPage` | 4000    | Maximum shapes allowed on one page  |
| `maxPages`         | 40      | Maximum pages in a document         |
| `maxFilesAtOnce`   | 100     | Maximum files to handle in one drop |

Setting `maxPages` to 1 effectively disables multi-page functionality and removes the page menu from the UI.

### Interaction timing

Configure how the editor interprets user input timing:

| Option                  | Default | Description                                       |
| ----------------------- | ------- | ------------------------------------------------- |
| `doubleClickDurationMs` | 450     | Maximum interval for double-click detection       |
| `multiClickDurationMs`  | 200     | Window for triple- and quadruple-click detection  |
| `longPressDurationMs`   | 500     | Duration to trigger long press                    |
| `animationMediumMs`     | 320     | Duration for camera animations (zoom, pan to fit) |

### Drag detection

Control when pointer movement becomes a drag operation:

| Option                        | Default | Description                              |
| ----------------------------- | ------- | ---------------------------------------- |
| `dragDistanceSquared`         | 16      | Distance² threshold for mouse drag (4px) |
| `coarseDragDistanceSquared`   | 36      | Distance² threshold for touch drag (6px) |
| `uiDragDistanceSquared`       | 16      | Distance² for UI element drag (4px)      |
| `uiCoarseDragDistanceSquared` | 625     | Distance² for touch UI drag (25px)       |

Values are squared to avoid computing square roots during drag detection. The larger touch thresholds prevent accidental drags on mobile devices.

### Handle and hit testing

Configure selection handles and click target areas:

| Option                | Default | Description                                   |
| --------------------- | ------- | --------------------------------------------- |
| `handleRadius`        | 12      | Radius of selection handles                   |
| `coarseHandleRadius`  | 20      | Handle radius for touch input                 |
| `hitTestMargin`       | 3       | Additional margin around shapes for hit tests |
| `coarseHitTestMargin` | 4       | Hit test margin when using a coarse pointer   |

### Edge scrolling

Configure auto-scroll behavior when dragging near viewport edges:

| Option                   | Default | Description                                                              |
| ------------------------ | ------- | ------------------------------------------------------------------------ |
| `edgeScrollDelay`        | 200     | Milliseconds before scroll starts                                        |
| `edgeScrollEaseDuration` | 200     | Milliseconds to accelerate to full speed                                 |
| `edgeScrollSpeed`        | 25      | Base scroll speed, multiplied by the user's edge scroll speed preference |
| `edgeScrollDistance`     | 8       | Width of the edge scroll trigger zone                                    |
| `coarsePointerWidth`     | 12      | Pointer width used to widen the trigger zone for touch                   |

See [Edge scrolling](/sdk-features/edge-scrolling) for details on how these options affect behavior.

### Camera

Control camera movement and viewport behavior:

| Option                    | Default                  | Description                                                                       |
| ------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| `cameraSlideFriction`     | 0.09                     | Friction applied to camera momentum                                               |
| `cameraMovingTimeoutMs`   | 64                       | Time before camera is considered stopped                                          |
| `followChaseViewportSnap` | 2                        | Snap threshold when following collaborators                                       |
| `spacebarPanning`         | true                     | Enable spacebar to activate pan mode                                              |
| `rightClickPanning`       | true                     | Enable right-click and drag to pan the camera                                     |
| `zoomToFitPadding`        | 128                      | Padding around content when zooming to fit bounds                                 |
| `camera`                  | `DEFAULT_CAMERA_OPTIONS` | Initial [`TLCameraOptions`](/reference/editor/TLCameraOptions); change at runtime with [`Editor.setCameraOptions`](/reference/editor/Editor#setCameraOptions) |
| `deepLinks`               | undefined                | Sync camera state with the URL: `true` or a [`TLDeepLinkOptions`](/reference/editor/TLDeepLinkOptions) object         |

The `camera` and `deepLinks` options replace the deprecated `cameraOptions` and `deepLinks` props on the component. See [Camera](/sdk-features/camera) for the camera options.

### Snapping

| Option               | Default | Description                                                                                    |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `snapThreshold`      | 8       | Distance in pixels at which snapping engages                                                   |
| `selectLockedShapes` | false   | Allow left-clicking and brushing to select locked shapes (they still can't be moved or edited) |

### Collaboration

Configure timing for collaborator presence:

| Option                          | Default | Description                               |
| ------------------------------- | ------- | ----------------------------------------- |
| `collaboratorInactiveTimeoutMs` | 60000   | Time before collaborator marked inactive  |
| `collaboratorIdleTimeoutMs`     | 3000    | Time before collaborator marked idle      |
| `collaboratorCheckIntervalMs`   | 1200    | Interval for checking collaborator status |

### Export

Configure image and SVG export behavior:

| Option                      | Default  | Description                              |
| --------------------------- | -------- | ---------------------------------------- |
| `defaultSvgPadding`         | 32       | Padding around exported SVG content      |
| `maxExportDelayMs`          | 5000     | Maximum wait time for export completion  |
| `flattenImageBoundsExpand`  | 64       | Expansion when flattening images         |
| `flattenImageBoundsPadding` | 16       | Padding when flattening images           |
| `exportProvider`            | Fragment | React provider wrapping exported content |

The `exportProvider` option wraps exported content in a React component. Use this when your custom shapes depend on context providers that must be present during rendering:

```tsx
const options: Partial<TldrawOptions> = {
	exportProvider: ({ children }) => <ThemeProvider theme={myTheme}>{children}</ThemeProvider>,
}
```

### Grid

Configure the alignment grid:

```typescript
gridSteps: [
	{ min: -1, mid: 0.15, step: 64 },
	{ min: 0.05, mid: 0.375, step: 16 },
	{ min: 0.15, mid: 1, step: 4 },
	{ min: 0.7, mid: 2.5, step: 1 },
]
```

Each entry defines a grid step size based on zoom level. The `min` and `mid` values define the zoom range where the `step` applies. Zoomed out, the grid uses larger steps; zoomed in, finer ones.

### Performance

Options that affect rendering performance:

| Option                       | Default  | Description                              |
| ---------------------------- | -------- | ---------------------------------------- |
| `debouncedZoom`              | true     | Use cached zoom while camera is moving   |
| `debouncedZoomThreshold`     | 500      | Shape count threshold for debounced zoom |
| `maxFontsToLoadBeforeRender` | Infinity | Fonts to load before showing canvas      |
| `textShadowLod`              | 0.35     | Zoom threshold for text shadow rendering |

When `debouncedZoom` is enabled and the page has more shapes than `debouncedZoomThreshold`, the editor returns a cached zoom level during camera movement. This reduces re-renders of complex documents.

### UI and features

| Option                           | Default   | Description                                                                                             |
| -------------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `createTextOnCanvasDoubleClick`  | true      | Create text shape on empty canvas double-click                                                          |
| `enableToolbarKeyboardShortcuts` | true      | Enable number keys (1-9, 0) for toolbar items                                                           |
| `actionShortcutsLocation`        | 'swap'    | Where the quick actions (undo, redo, delete, duplicate) render                                          |
| `tooltipDelayMs`                 | 700       | Delay before showing tooltips                                                                           |
| `laserDelayMs`                   | 1200      | Duration laser pointer remains visible                                                                  |
| `laserFadeoutMs`                 | 500       | Duration for laser pointer fadeout animation                                                            |
| `quickZoomPreservesScreenBounds` | true      | Whether quick zoom brush keeps viewport scale                                                           |
| `branding`                       | undefined | App name for accessibility labels                                                                       |
| `nonce`                          | undefined | CSP nonce for inline styles                                                                             |
| `adjacentShapeMargin`            | 10        | Gap used when placing adjacent notes, duplicating, stacking, and packing shapes                         |
| `text`                           | `{}`      | [`TLTextOptions`](/reference/editor/TLTextOptions): TipTap configuration and font handling (replaces the deprecated `textOptions` prop) |

The `actionShortcutsLocation` option controls where the quick actions render:

- `'menu'` - Always in the menu panel
- `'toolbar'` - Always in the toolbar
- `'swap'` - In the menu panel on tablet-sized screens and up, in the toolbar below that

### Asset handling

| Option                            | Default | Description                                       |
| --------------------------------- | ------- | ------------------------------------------------- |
| `temporaryAssetPreviewLifetimeMs` | 180000  | How long temporary asset previews persist (3 min) |

### Clipboard hooks

These callbacks let you intercept and customize clipboard operations:

| Option                       | Description                                                                                                                                                                                          |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onBeforeCopyToClipboard`    | Called before content is written to the clipboard during copy or cut. Return modified `TLContent` to transform, `false` to cancel, or `void` to pass through.                                        |
| `onBeforePasteFromClipboard` | Called before pasted content is processed and shapes are created. Return `false` to cancel, a modified content object to transform, or `void` to pass through. Only fires for paste, not file drops. |
| `onClipboardPasteRaw`        | Called first for keyboard and menu paste, before tldraw parses clipboard data. Return `false` to cancel default paste handling, or `void` to continue.                                               |

See [Clipboard](/sdk-features/clipboard) for more details on clipboard operations.

### Drop handling

| Option                         | Description                                                                                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `experimental__onDropOnCanvas` | Called when content is dropped on the canvas. Receives the page position and drag event. Return `true` to prevent default drop handling. |

## Default values

The [`defaultTldrawOptions`](/reference/editor/defaultTldrawOptions) export provides all default values:

```typescript
import { defaultTldrawOptions } from 'tldraw'

console.log(defaultTldrawOptions.maxPages) // 40
```

Use this to check defaults or spread into your own options:

```typescript
const options: Partial<TldrawOptions> = {
	...defaultTldrawOptions,
	maxPages: 10,
}
```

## Tldraw component props

The `<Tldraw>` component accepts additional props beyond those available on `<TldrawEditor>`. These props configure the UI layer, external content handling, and other features that the full SDK provides.

### UI configuration

| Prop          | Type                    | Description                                        |
| ------------- | ----------------------- | -------------------------------------------------- |
| `hideUi`      | `boolean`               | Hide all UI elements, showing only the canvas      |
| `forceMobile` | `boolean`               | Force mobile breakpoints regardless of screen size |
| `overrides`   | `TLUiOverrides`         | Override actions, tools, and translations          |
| `onUiEvent`   | `TLUiEventHandler`      | Callback for UI interaction events                 |
| `components`  | `TLComponents`          | Override or disable UI and canvas components       |
| `assetUrls`   | `TLUiAssetUrlOverrides` | Custom URLs for fonts, icons, and other UI assets  |

The `hideUi` prop is useful when building custom interfaces around the canvas:

```tsx
function CustomEditor() {
	return (
		<Tldraw hideUi>
			<MyCustomToolbar />
		</Tldraw>
	)
}
```

### External content handling

These props control how the editor handles dropped or pasted files:

| Prop                     | Default                         | Description                                             |
| ------------------------ | ------------------------------- | ------------------------------------------------------- |
| `maxImageDimension`      | 5000                            | Maximum width/height for images (larger images resized) |
| `maxAssetSize`           | 10485760                        | Maximum file size in bytes (10 MB)                      |
| `acceptedImageMimeTypes` | `DEFAULT_SUPPORTED_IMAGE_TYPES` | Allowed image MIME types                                |
| `acceptedVideoMimeTypes` | `DEFAULT_SUPPORT_VIDEO_TYPES`   | Allowed video MIME types                                |

```tsx
function App() {
	return (
		<Tldraw
			maxImageDimension={2000}
			maxAssetSize={5 * 1024 * 1024} // 5 MB
			acceptedImageMimeTypes={['image/png', 'image/jpeg']}
		/>
	)
}
```

### Embeds

Customize which embed types the editor recognizes using `EmbedShapeUtil.configure()`:

```tsx
import { Tldraw, EmbedShapeUtil, DEFAULT_EMBED_DEFINITIONS } from 'tldraw'

const shapeUtils = [
	EmbedShapeUtil.configure({
		embedDefinitions: [
			...DEFAULT_EMBED_DEFINITIONS,
			{
				type: 'custom-video',
				title: 'Custom Video',
				hostnames: ['videos.example.com'],
				width: 560,
				height: 315,
				doesResize: true,
				toEmbedUrl: (url) => url.replace('/watch/', '/embed/'),
				fromEmbedUrl: (url) => url.replace('/embed/', '/watch/'),
			},
		],
	}),
]

function App() {
	return <Tldraw shapeUtils={shapeUtils} />
}
```

See [Embed shape](/sdk-features/embed-shape#custom-embed-definitions) for the full embed definition API.

### Editor setup

These props configure how the editor initializes:

| Prop                 | Type                                                    | Description                                             |
| -------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
| `autoFocus`          | `boolean`                                               | Automatically focus the editor on mount                 |
| `initialState`       | `string`                                                | Initial tool state (`<Tldraw>` defaults to `'select'`)  |
| `shapeUtils`         | `TLAnyShapeUtilConstructor[]`                           | Custom shape utilities                                  |
| `bindingUtils`       | `TLAnyBindingUtilConstructor[]`                         | Custom binding utilities                                |
| `overlayUtils`       | `TLAnyOverlayUtilConstructor[]`                         | Custom [overlay utilities](/sdk-features/overlay-utils) |
| `tools`              | `TLStateNodeConstructor[]`                              | Custom tools                                            |
| `onMount`            | `TLOnMountHandler`                                      | Callback when editor mounts                             |
| `getShapeVisibility` | `(shape, editor) => 'visible' \| 'hidden' \| 'inherit'` | Conditionally hide shapes                               |
| `user`               | `TLCurrentUser`                                         | Current user information                                |
| `colorScheme`        | `'light' \| 'dark' \| 'system'`                         | Color scheme (defaults to `'light'`)                    |
| `licenseKey`         | `string`                                                | License key to remove watermark                         |
| `themes`             | `Partial<TLThemes>`                                     | Named themes for the editor                             |
| `initialTheme`       | `TLThemeId`                                             | Initially active theme (defaults to `'default'`)        |
| `locale`             | `string`                                                | UI locale; overrides browser and user preferences       |

The `cameraOptions`, `deepLinks`, `textOptions`, and `embeds` props are deprecated. Use `options.camera`, `options.deepLinks`, `options.text`, and `EmbedShapeUtil.configure` instead.

The `getShapeVisibility` callback lets you conditionally hide shapes based on their properties:

```tsx
<Tldraw
	getShapeVisibility={(shape, editor) => {
		// Hide shapes marked as hidden in meta
		if (shape.meta.hidden) return 'hidden'
		// Force-show shapes regardless of parent visibility
		if (shape.meta.alwaysVisible) return 'visible'
		// Default: visible unless parent is hidden
		return 'inherit'
	}}
/>
```

### Store configuration

When not providing your own store, these props configure automatic store creation:

| Prop             | Type                  | Description                                           |
| ---------------- | --------------------- | ----------------------------------------------------- |
| `persistenceKey` | `string`              | Key for IndexedDB persistence (enables local storage) |
| `sessionId`      | `string`              | Session identifier for persistence                    |
| `snapshot`       | `TLEditorSnapshot`    | Initial document state                                |
| `migrations`     | `MigrationSequence[]` | Additional migrations for custom schemas              |

```tsx
function App() {
	return <Tldraw persistenceKey="my-document" snapshot={savedSnapshot} />
}
```

Alternatively, provide your own store with the `store` prop for full control over data management.

## Examples

- **[Editor options](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/custom-options)** - Override default options like max pages and animation speed.
- **[Disable pages](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/disable-pages)** - Set `maxPages` to 1 to create a single-page editor.

--------

# Overlay utils

Overlay utils render ephemeral UI on the canvas: selection handles, brush rectangles, snap lines, scribbles, and shape handles. They draw directly to a `<canvas>` element using the Canvas 2D API and can optionally provide hit-test geometry for pointer interactions.

Each overlay util defines a specific type of canvas UI. The editor queries all registered overlay utils reactively: when the editor state changes, overlay utils determine whether they are active, produce overlay instances, and render them.

## How it works

An [`OverlayUtil`](/reference/editor/OverlayUtil) is an abstract class with four responsibilities:

1. **Activation** — `isActive()` returns whether the overlay should render right now
2. **Overlay instances** — `getOverlays()` returns the current set of overlay objects
3. **Rendering** — `render()` draws overlays into a canvas 2D context
4. **Hit testing** (optional) — `getGeometry()` returns geometry for interactive overlays

The editor calls these methods reactively. When `isActive()` returns `false`, the overlay is skipped entirely. When it returns `true`, `getOverlays()` re-runs whenever the editor state it reads changes, and `render()` re-runs on that plus camera movement and viewport resizes.

Paint order across utils comes from `options.zIndex`: higher numbers paint on top and are hit-tested first, ties keep registration order, and the default is `0`. Built-in utils use values like 50, 100, 200, and 300 so custom utils can slot between them.

## Default overlay utils

The `tldraw` package includes these overlay utils by default:

| Overlay util                               | Purpose                                       |
| ------------------------------------------ | --------------------------------------------- |
| [`ShapeIndicatorOverlayUtil`](/reference/tldraw/ShapeIndicatorOverlayUtil)             | Selection, hover, and hint outlines on shapes |
| [`SelectionForegroundOverlayUtil`](/reference/tldraw/SelectionForegroundOverlayUtil)        | Selection box, resize handles, corners        |
| [`ShapeHandleOverlayUtil`](/reference/tldraw/ShapeHandleOverlayUtil)                | Shape handles (arrows, lines, etc.)           |
| [`BrushOverlayUtil`](/reference/tldraw/BrushOverlayUtil)                      | Selection brush rectangle                     |
| [`ZoomBrushOverlayUtil`](/reference/tldraw/ZoomBrushOverlayUtil)                  | Zoom brush rectangle                          |
| [`SnapIndicatorOverlayUtil`](/reference/tldraw/SnapIndicatorOverlayUtil)              | Snap alignment guides                         |
| [`ScribbleOverlayUtil`](/reference/tldraw/ScribbleOverlayUtil)                   | Eraser and lasso scribbles                    |
| [`ArrowHintOverlayUtil`](/reference/tldraw/ArrowHintOverlayUtil)                  | Target hints while drawing arrows             |
| [`ArrowBindingHintOverlayUtil`](/reference/tldraw/ArrowBindingHintOverlayUtil)           | Binding hints when dragging arrow handles     |
| [`CollaboratorBrushOverlayUtil`](/reference/tldraw/CollaboratorBrushOverlayUtil)          | Remote users' brush rectangles                |
| [`CollaboratorScribbleOverlayUtil`](/reference/tldraw/CollaboratorScribbleOverlayUtil)       | Remote users' scribbles                       |
| [`CollaboratorHintOverlayUtil`](/reference/tldraw/CollaboratorHintOverlayUtil)           | Remote users' viewport-edge hint arrows       |
| [`CollaboratorShapeIndicatorOverlayUtil`](/reference/tldraw/CollaboratorShapeIndicatorOverlayUtil) | Remote users' selection indicators            |

These are exported as [`defaultOverlayUtils`](/reference/tldraw/defaultOverlayUtils) from `tldraw`.

## Creating an overlay util

Extend the [`OverlayUtil`](/reference/editor/OverlayUtil) class and implement at least `isActive()`, `getOverlays()`, and `render()`:

```tsx
import { OverlayUtil, TLOverlay } from 'tldraw'

interface MyHighlightOverlay extends TLOverlay {
	props: {
		x: number
		y: number
		radius: number
	}
}

class HighlightOverlayUtil extends OverlayUtil<MyHighlightOverlay> {
	static override type = 'highlight'

	override isActive(): boolean {
		// Active when there's exactly one selected shape
		return this.editor.getSelectedShapeIds().length === 1
	}

	override getOverlays(): MyHighlightOverlay[] {
		const shape = this.editor.getOnlySelectedShape()
		if (!shape) return []

		const bounds = this.editor.getShapePageBounds(shape)
		if (!bounds) return []

		return [
			{
				id: 'highlight',
				type: 'highlight',
				props: {
					x: bounds.midX,
					y: bounds.midY,
					radius: Math.max(bounds.width, bounds.height) / 2 + 20,
				},
			},
		]
	}

	override render(ctx: CanvasRenderingContext2D, overlays: MyHighlightOverlay[]): void {
		const zoom = this.editor.getZoomLevel()
		for (const overlay of overlays) {
			const { x, y, radius } = overlay.props
			ctx.beginPath()
			ctx.arc(x, y, radius, 0, Math.PI * 2)
			ctx.strokeStyle = 'dodgerblue'
			ctx.lineWidth = 2 / zoom
			ctx.stroke()
		}
	}
}
```

### The overlay interface

Each overlay is a plain object with `id`, `type`, and `props`:

```tsx
interface TLOverlay {
	id: string // Unique identifier for this instance
	type: string // Matches the overlay util's static type
	props: Record<string, unknown> // Data needed for rendering and hit testing
}
```

Define a custom interface extending [`TLOverlay`](/reference/editor/TLOverlay) to type your props. The `id` must be globally unique across all overlay utils — hit testing and hover lookup use the `id` alone. Namespace your ids to avoid collisions: a fixed string like `'highlight'` works for single-instance overlays, while per-item overlays should include the item's identity (e.g. `'handle:<shapeId>:<handleId>'`).

### Rendering

The `render()` method receives a `CanvasRenderingContext2D` already transformed to page space (camera offset and zoom applied). Scale line widths and radii by `1 / zoom` to keep them constant on screen:

```tsx
override render(ctx: CanvasRenderingContext2D, overlays: MyOverlay[]): void {
    const zoom = this.editor.getEfficientZoomLevel()
    ctx.lineWidth = 1 / zoom
    // ...draw your overlays
}
```

### Hit testing

By default, overlays are non-interactive. To make an overlay respond to pointer events, implement `getGeometry()` to return a [`Geometry2d`](/reference/editor/Geometry2d) in page coordinates:

```tsx
import { Circle2d, Geometry2d, TLCursorType } from 'tldraw'

class MyInteractiveOverlayUtil extends OverlayUtil<MyOverlay> {
	// ...isActive, getOverlays, render...

	override getGeometry(overlay: MyOverlay): Geometry2d | null {
		return new Circle2d({
			x: overlay.props.x - 10,
			y: overlay.props.y - 10,
			radius: 10,
			isFilled: true,
		})
	}

	override getCursor(): TLCursorType | undefined {
		return 'pointer'
	}
}
```

While the select tool is idle, it hit-tests overlays on every pointer move, records the result with [`OverlayManager.setHoveredOverlay`](/reference/editor/OverlayManager#setHoveredOverlay), and applies the cursor from `getCursor()`. Overlays take priority over shapes for hover. To handle clicks yourself, implement `onPointerDown(overlay, info)`; it runs before the default routing, and returning `false` falls through to the default behavior.

## Registering overlay utils

Pass your overlay utils through the `overlayUtils` prop on [`Tldraw`](/reference/tldraw/Tldraw) or [`TldrawEditor`](/reference/editor/TldrawEditor):

```tsx
import { Tldraw } from 'tldraw'

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

When using the [`Tldraw`](/reference/tldraw/Tldraw) component, your custom overlay utils are merged with the defaults, so you don't need to re-include them. If your custom overlay util has the same `type` as a default one, it replaces the default. [`TldrawEditor`](/reference/editor/TldrawEditor) has no defaults; pass [`defaultOverlayUtils`](/reference/tldraw/defaultOverlayUtils) yourself if you want them.

## Customizing default overlays

To replace a default overlay, extend it and override the methods you want to change. Give it the same static `type` so it replaces the built-in:

```tsx
import { Tldraw, BrushOverlayUtil, type TLBrushOverlay } from 'tldraw'

class BlueBrushOverlayUtil extends BrushOverlayUtil {
	override render(ctx: CanvasRenderingContext2D, overlays: TLBrushOverlay[]): void {
		const overlay = overlays[0]
		if (!overlay) return

		const { x, y, w, h } = overlay.props
		const zoom = this.editor.getZoomLevel()

		ctx.beginPath()
		ctx.rect(x, y, w, h)
		ctx.fillStyle = 'rgba(0, 0, 255, 0.1)'
		ctx.fill()
		ctx.lineWidth = 1 / zoom
		ctx.strokeStyle = 'blue'
		ctx.stroke()
	}
}

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

### Options via configure

Overlay utils can define an `options` property for configuration. Keep `zIndex` in it, since the base type is `{ zIndex?: number }`. Use the static [`OverlayUtil.configure`](/reference/editor/OverlayUtil#configure) method to create a customized version without subclassing:

```tsx
class MyOverlayUtil extends OverlayUtil<MyOverlay> {
	static override type = 'my_overlay'
	override options = { zIndex: 50, color: 'red', radius: 10 }

	// ...use this.options.color and this.options.radius in render()
}

// Create a variant with different options
const BlueOverlay = MyOverlayUtil.configure({ color: 'blue' })
```

The built-in utils expose their colors and line widths as theme-aware display values, so you can recolor one with `configure({ getCustomDisplayValues })` instead of overriding `render()`. See [`BrushOverlayUtilOptions`](/reference/tldraw/BrushOverlayUtilOptions) for an example.

## Accessing overlay utils at runtime

Use [`Editor.overlays`](/reference/editor/Editor#overlays) to interact with the overlay system:

```tsx
// Get a specific overlay util
const brushUtil = editor.overlays.getOverlayUtil<BrushOverlayUtil>('brush')

// Get all currently active overlays
const activeOverlays = editor.overlays.getCurrentOverlays()

// Hit test at a page point
const overlay = editor.overlays.getOverlayAtPoint({ x: 100, y: 200 })

// Check what's hovered
const hoveredId = editor.overlays.getHoveredOverlayId()
```

## Related articles

- [Shapes](/sdk-features/shapes) - The shape system that overlays interact with
- [Indicators](/sdk-features/indicators) - Shape indicators rendered alongside overlays
- [Scribble](/sdk-features/scribble) - Scribble system rendered via overlay utils

## Related examples

- [Custom overlay](/examples/editor-api/custom-overlay) - Draw a custom canvas overlay on top of the editor.
- [Replace a built-in overlay](/examples/editor-api/replace-brush-overlay) - Swap out the brush overlay for a custom implementation.
- [Hovered overlay](/examples/editor-api/hovered-overlay) - Read the overlay that the user is hovering.

--------

# Pages

The pages system provides multiple independent sub-documents within a single tldraw document. Each page acts as a separate scene graph root with its own shapes, camera position, and selection state.

When you switch pages, the editor preserves your camera position and selected shapes on the previous page and restores the state you left on the new page. In collaborative sessions, users can see which pages their collaborators are viewing and follow them across page boundaries.

## How it works

Each page is a [`TLPage`](/reference/tlschema/TLPage) record in the store with a unique ID, a name for display, an index for ordering, and a `meta` object for your own data. Pages belong to the document scope: they persist across sessions and sync in collaborative environments. When you create a page, the editor automatically creates associated records for the camera position and instance page state.

The camera record associated with a page tracks viewport position and zoom for that page only. When you navigate to a different page, the editor switches to the camera for that page, so each user keeps their own view of each page. Camera options and constraints are editor-wide, not per page; they apply to whichever page is current.

The instance page state record tracks selection, editing state, focused groups, and other transient UI state unique to both a page and a browser session. This state belongs to the session scope and doesn't sync in collaborative environments. Each user maintains their own instance page state for each page they visit.

Pages are ordered. As with shapes, the page record's `index` property determines its order among other pages.

## Page methods

### Access

Get the current page or page ID with [`Editor.getCurrentPage`](/reference/editor/Editor#getCurrentPage) and [`Editor.getCurrentPageId`](/reference/editor/Editor#getCurrentPageId):

```typescript
const currentPage = editor.getCurrentPage()
const currentPageId = editor.getCurrentPageId()
```

Access any page by ID with [`Editor.getPage`](/reference/editor/Editor#getPage), or list them all with [`Editor.getPages`](/reference/editor/Editor#getPages):

```typescript
import { TLPageId } from 'tldraw'

const page = editor.getPage('page:page1' as TLPageId)
const allPages = editor.getPages()
```

### Navigation

Switch to a different page using [`Editor.setCurrentPage`](/reference/editor/Editor#setCurrentPage):

```typescript
editor.setCurrentPage('page:page2' as TLPageId)
```

When switching pages, the editor completes any in-progress interactions and stops following other users. The camera constraints are reapplied to ensure the new page's camera respects its configured bounds.

### Creating and deleting pages

Create new pages with [`Editor.createPage`](/reference/editor/Editor#createPage), which ensures unique page names and proper index ordering:

```typescript
editor.createPage({ name: 'Wireframes' })
```

The editor enforces a maximum page count through the `maxPages` option (see [`TldrawOptions`](/reference/editor/TldrawOptions), default: 40). Attempts to create pages beyond this limit are ignored. Set `maxPages` to 1 to disable multi-page UI entirely. All page mutations are no-ops when the editor is readonly.

Delete pages with [`Editor.deletePage`](/reference/editor/Editor#deletePage):

```typescript
editor.deletePage('page:page1' as TLPageId)
```

When deleting the current page, the editor switches to an adjacent page automatically. The last remaining page cannot be deleted. When a page is deleted, all shapes on that page are removed and the associated camera and instance page state records are cleaned up. If a collaborator deletes the page you're viewing, the editor moves you to another page.

### Duplicating pages

Use [`Editor.duplicatePage`](/reference/editor/Editor#duplicatePage) to copy an entire page including all its shapes and camera position:

```typescript
editor.duplicatePage('page:main' as TLPageId)
```

The duplicated page receives a copy of all shapes from the source page, preserving their positions, properties, and bindings between copied shapes. The camera position is copied from the source page and the editor switches to the new page. The new page's name appends " Copy" to the original page name. Like `createPage`, this respects `maxPages`.

### Renaming and updating pages

Rename a page with [`Editor.renamePage`](/reference/editor/Editor#renamePage):

```typescript
editor.renamePage('page:page1' as TLPageId, 'New Name')
```

For other updates, like changing the page's `meta`, use [`Editor.updatePage`](/reference/editor/Editor#updatePage):

```typescript
editor.updatePage({ id: 'page:page1' as TLPageId, meta: { description: 'Main design page' } })
```

## Working with shapes across pages

### Page-specific shape queries

Each page maintains its own shape hierarchy. Get shapes on the current page with [`Editor.getCurrentPageShapes`](/reference/editor/Editor#getCurrentPageShapes) and [`Editor.getCurrentPageShapeIds`](/reference/editor/Editor#getCurrentPageShapeIds):

```typescript
const shapes = editor.getCurrentPageShapes()
const shapeIds = editor.getCurrentPageShapeIds()
```

Get shape IDs from any page with [`Editor.getPageShapeIds`](/reference/editor/Editor#getPageShapeIds):

```typescript
const pageShapeIds = editor.getPageShapeIds('page:page2' as TLPageId)
```

These queries return only the top-level and nested shapes that belong to the specified page. Shapes are parented to pages through their `parentId` field.

### Moving shapes between pages

Transfer shapes from one page to another using [`Editor.moveShapesToPage`](/reference/editor/Editor#moveShapesToPage):

```typescript
import { TLShapeId } from 'tldraw'

editor.moveShapesToPage(
	['shape:rect1' as TLShapeId, 'shape:circle2' as TLShapeId],
	'page:page2' as TLPageId
)
```

The operation removes the shapes from the source page, switches to the destination page, and puts them there at the same position and with the same IDs. It then matches the source page's zoom, centers the camera on the moved shapes, and selects them.

Bindings between moved shapes are preserved. Bindings to shapes that stay behind are removed, and their binding utils receive `onBeforeIsolateFromShape` callbacks. If the move would push the destination page over the `maxShapesPerPage` option, nothing moves and the editor emits a `max-shapes` event.

## Collaboration and pages

In collaborative sessions, each user's current page is tracked through the presence system. Use [`Editor.getCollaboratorsOnCurrentPage`](/reference/editor/Editor#getCollaboratorsOnCurrentPage) to see who is on your page:

```typescript
const collaboratorsOnThisPage = editor.getCollaboratorsOnCurrentPage()
```

When following the viewport of a user who switches pages, your editor switches pages automatically to maintain the follow relationship. See [User following](/sdk-features/user-following) for details on cross-page following behavior.

## Undo and deep links

Undo and redo operations are document-wide, not page-specific. Undoing a page creation removes the page and all its shapes.

URLs can encode a page ID with the [deep links](/sdk-features/deep-links) API, so a document can open directly on a particular page.

## Related articles

- [Camera](/sdk-features/camera) - Camera options and constraints
- [User following](/sdk-features/user-following) - Following collaborators across pages
- [Deep links](/sdk-features/deep-links) - Encoding pages and viewports in URLs

## Related examples

- [Disable pages](/examples/configuration/disable-pages) - Disable page-related UI for single-page use cases by setting the `maxPages` option to 1.
- [Deep links](/examples/configuration/deep-links) - Create URLs that navigate to specific pages using the deep links API.

--------

# Parenting and ancestors

Every shape in tldraw has a parent: either the page it lives on or another shape that contains it. Groups and frames use this hierarchy to hold other shapes. The editor uses it for transforms, selection, and rendering order.

## The parentId property

Every shape record has a `parentId` property that points to its parent. For shapes directly on the canvas, this is a page ID. For shapes inside groups or frames, it's the containing shape's ID:

```typescript
// A shape on the page
const shape = editor.getShape(myShapeId)
console.log(shape.parentId) // "page:somePage"

// A shape inside a group
const groupedShape = editor.getShape(childShapeId)
console.log(groupedShape.parentId) // "shape:someGroup"
```

You can check what type of parent a shape has using `isPageId` and `isShapeId`, both exported from `tldraw`:

```typescript
import { isPageId, isShapeId } from 'tldraw'

if (isPageId(shape.parentId)) {
	// Shape is directly on a page
}

if (isShapeId(shape.parentId)) {
	// Shape is inside another shape (group, frame, etc.)
}
```

## Getting a shape's parent

Use [`Editor.getShapeParent`](/reference/editor/Editor#getShapeParent) to get the parent shape. It returns `undefined` if the shape is directly on a page:

```typescript
const parent = editor.getShapeParent(myShape)

if (parent) {
	console.log('Parent shape:', parent.type)
} else {
	console.log('Shape is on the page')
}
```

## Getting ancestors

The ancestor chain is the path from a shape up to the page. Use [`Editor.getShapeAncestors`](/reference/editor/Editor#getShapeAncestors) to get all ancestors in order from the root to the immediate parent:

```typescript
// For a deeply nested shape:
// page > frameA > groupB > myShape
const ancestors = editor.getShapeAncestors(myShapeId)
// Returns: [frameA, groupB]
```

The array is ordered from root ancestor to immediate parent. The page itself is never included—ancestors only contain shapes.

### Finding a specific ancestor

Use [`Editor.findShapeAncestor`](/reference/editor/Editor#findShapeAncestor) to find the first ancestor matching a condition:

```typescript
// Find the containing frame
const frame = editor.findShapeAncestor(myShape, (ancestor) => ancestor.type === 'frame')

// Find the first locked ancestor
const lockedAncestor = editor.findShapeAncestor(myShape, (ancestor) => ancestor.isLocked)
```

### Checking for a specific ancestor

Use [`Editor.hasAncestor`](/reference/editor/Editor#hasAncestor) to check if a shape is inside a specific container:

```typescript
if (editor.hasAncestor(myShape, frameId)) {
	// myShape is somewhere inside this frame
}
```

### Finding the common ancestor

When working with multiple shapes, use [`Editor.findCommonAncestor`](/reference/editor/Editor#findCommonAncestor) to find their nearest shared parent:

```typescript
const shapeIds = [shapeA, shapeB, shapeC]
const commonAncestorId = editor.findCommonAncestor(shapeIds)

if (commonAncestorId) {
	// All shapes share this ancestor
} else {
	// Shapes are on the page with no common parent shape
}
```

You can also filter by a predicate:

```typescript
// Find the common frame ancestor
const commonFrame = editor.findCommonAncestor(shapeIds, (shape) => shape.type === 'frame')
```

## Getting children

Use [`Editor.getSortedChildIdsForParent`](/reference/editor/Editor#getSortedChildIdsForParent) to get a shape's children in z-index order:

```typescript
const childIds = editor.getSortedChildIdsForParent(groupId)
// Returns child IDs sorted from back to front
```

This works for pages too:

```typescript
const topLevelShapes = editor.getSortedChildIdsForParent(editor.getCurrentPageId())
```

### Visiting descendants

For recursive traversal, use [`Editor.visitDescendants`](/reference/editor/Editor#visitDescendants):

```typescript
editor.visitDescendants(frameId, (childId) => {
	const child = editor.getShape(childId)
	console.log('Found:', child.type)
	// Return false to skip this shape's children
})
```

To collect all descendants including the shape itself, use [`Editor.getShapeAndDescendantIds`](/reference/editor/Editor#getShapeAndDescendantIds):

```typescript
const allIds = editor.getShapeAndDescendantIds([frameId])
// Returns a Set containing frameId and all nested shape IDs
```

## Reparenting shapes

Use [`Editor.reparentShapes`](/reference/editor/Editor#reparentShapes) to move shapes into a new parent. This preserves the shapes' page positions—only their local coordinates change to match the new parent's coordinate space:

```typescript
// Move shapes into a frame
editor.reparentShapes([shapeA, shapeB], frameId)

// Move shapes to the page root
editor.reparentShapes([shapeA, shapeB], editor.getCurrentPageId())
```

The method handles coordinate transformation automatically. If the parent is rotated, children's positions and rotations are adjusted so they appear in the same place on the page.

You can pass an `IndexKey` (a fractional index string, not a numeric position) as the third argument to control z-ordering. The reparented shapes are inserted at that key among the new parent's children:

```typescript
// Put the child where the group sat in its parent's stack
editor.reparentShapes([newChild], group.parentId, group.index)
```

When you omit `parentId` from [`Editor.createShapes`](/reference/editor/Editor#createShapes), the editor picks one for you: the focused group, or a container such as a frame under the shape's `x` and `y`. Deleting a shape with [`Editor.deleteShapes`](/reference/editor/Editor#deleteShapes) also deletes its descendants.

## Transforms and coordinates

Parent-child relationships affect coordinate systems. A child shape's `x` and `y` are relative to its parent, not the page.

Use [`Editor.getPointInShapeSpace`](/reference/editor/Editor#getPointInShapeSpace) and [`Editor.getShapePageTransform`](/reference/editor/Editor#getShapePageTransform) to convert between coordinate systems:

```typescript
// Convert a page point to a shape's local space
const localPoint = editor.getPointInShapeSpace(parentShape, pagePoint)

// Get a shape's position in page coordinates
const pageTransform = editor.getShapePageTransform(childShape)
const pagePoint = pageTransform.point()
```

[`Editor.getShapeParentTransform`](/reference/editor/Editor#getShapeParentTransform) and [`Editor.getShapeLocalTransform`](/reference/editor/Editor#getShapeLocalTransform) give you the other two pieces of the composition.

When you move a parent, all children move with it. Their local coordinates stay the same, but their page coordinates change.

For more about coordinate systems and transforms, see [Coordinates](/sdk-features/coordinates).

## Checking page membership

Use [`Editor.isShapeInPage`](/reference/editor/Editor#isShapeInPage) to check if a shape is on a specific page (even if nested):

```typescript
if (editor.isShapeInPage(myShape, pageId)) {
	// Shape is on this page (directly or nested)
}
```

To get the page a shape belongs to, use [`Editor.getAncestorPageId`](/reference/editor/Editor#getAncestorPageId):

```typescript
const pageId = editor.getAncestorPageId(myShape)
```

## Locked ancestors

A shape is effectively locked if any of its ancestors are locked. Use [`Editor.isShapeOrAncestorLocked`](/reference/editor/Editor#isShapeOrAncestorLocked) to check:

```typescript
if (editor.isShapeOrAncestorLocked(myShape)) {
	// Shape can't be interacted with
}
```

The editor uses this for pointer interactions and [`Editor.updateShapes`](/reference/editor/Editor#updateShapes). Bulk operations such as [`Editor.deleteShapes`](/reference/editor/Editor#deleteShapes) only check each shape's own `isLocked`. See [Locked shapes](/sdk-features/locked-shapes).

## Hidden shapes

Visibility also inherits through the hierarchy: a shape is hidden if the `getShapeVisibility` prop returns `'hidden'` for it or for any ancestor, unless the shape returns `'visible'`. Check with [`Editor.isShapeHidden`](/reference/editor/Editor#isShapeHidden). See [Visibility](/sdk-features/visibility).

## The focused group

The editor tracks a "focused group" that determines which level of the hierarchy you're working in. When you're focused inside a group, new shapes are created as children of that group. See [Groups](/sdk-features/groups) for details on focused groups.

## Related examples

- [Layer panel](/examples/ui/layer-panel) - Build a hierarchical layer panel that shows parent-child relationships.
- [Drag and drop](/examples/shapes/tools/drag-and-drop) - Handle reparenting when dropping shapes onto containers, using [`ShapeUtil.canReceiveNewChildrenOfType`](/reference/editor/ShapeUtil#canReceiveNewChildrenOfType) and [`ShapeUtil.onDragShapesIn`](/reference/editor/ShapeUtil#onDragShapesIn).

--------

# Performance

The tldraw SDK uses several techniques to maintain smooth performance even with thousands of shapes on the canvas. This article covers what the SDK does for you and what to do in custom shapes.

## How tldraw optimizes rendering

### Viewport culling

Shapes outside the viewport don't need to render. The editor maintains a spatial index that tracks which shapes are visible, and hides off-screen shapes by setting `display: none` on their DOM elements. This means a canvas with 10,000 shapes might only render 50 if the rest are out of view.

Culling happens automatically for all shapes. The shapes remain in the store and can still be selected or updated; they just don't incur rendering cost. Selected shapes and the shape being edited are never culled. See [Culling](/sdk-features/culling) for details on how to control this behavior for custom shapes.

### Reactive signals

The SDK uses reactive [signals](/sdk-features/signals) instead of React's built-in state management. Signals automatically track dependencies and update only the parts of your application that actually depend on changed data.

When a shape's props change, only that shape's component re-renders—not the entire canvas. The system tracks dependencies at a granular level, so changing a shape's color won't trigger updates for shapes that don't care about color.

This is why methods like `editor.getSelectedShapeIds()` return reactive values. If you access them inside a `track()` component or `useValue()` hook, your code automatically re-runs when the underlying data changes.

### Batched store updates

The [store](/sdk-features/store) batches multiple changes into single updates. When you call methods like `editor.createShapes()` or `editor.updateShapes()` with multiple shapes, observers receive one notification with all changes rather than one per shape:

```ts
// These changes are batched automatically
editor.updateShapes([
	{ id: shape1.id, type: 'geo', x: 100 },
	{ id: shape2.id, type: 'geo', x: 200 },
	{ id: shape3.id, type: 'geo', x: 300 },
])
```

For complex operations spanning multiple calls, wrap them in `editor.run()`:

```ts
editor.run(() => {
	editor.createShapes([...])
	editor.updateShapes([...])
	editor.deleteShapes([...])
})
// All changes applied together, listeners notified once
```

### Debounced zoom

When the camera moves, shape components receive the new zoom level to scale stroke widths and other visual properties. On documents with many shapes, recalculating everything mid-zoom causes jank.

The editor provides [`Editor.getEfficientZoomLevel`](/reference/editor/Editor#getEfficientZoomLevel), which returns a stable value during camera movement when the document has more than 500 shapes (configurable via the `debouncedZoomThreshold` option). Once the camera stops, the value updates to the true zoom level.

Shape components should use this value rather than `editor.getZoomLevel()` for properties that affect rendering:

```tsx
function MyShapeComponent({ shape }: { shape: MyShape }) {
	const editor = useEditor()
	const zoom = useValue('zoom', () => editor.getEfficientZoomLevel(), [editor])

	// Stroke width stays stable during camera movement
	const strokeWidth = 2 / zoom

	return <path d={getPathForShape(shape)} strokeWidth={strokeWidth} />
}
```

### Geometry caching

Computing a shape's geometry (bounds, hit test regions, outline) can be expensive. The editor caches these computations and invalidates them only when a shape's props change.

Access cached geometry through [`Editor.getShapeGeometry`](/reference/editor/Editor#getShapeGeometry) rather than calling `shapeUtil.getGeometry()` directly. The editor handles caching, transforms, and bounds calculation.

### Level of detail

tldraw adjusts rendering fidelity based on zoom level and on-screen size, a technique called level of detail (LOD). When a shape is small on screen, rendering every pixel of a high-resolution image or every detail of a complex shape is wasted work.

**Image resolution scaling**

When you zoom out or resize an image shape, tldraw requests a lower-resolution version from your asset store. The `resolve` method on [`TLAssetStore`](/reference/tlschema/TLAssetStore) receives a [`TLAssetContext`](/reference/tlschema/TLAssetContext) with `steppedScreenScale`: the ratio of the shape's on-screen size (in CSS pixels) to the image's native size, rounded up to the nearest power of two. Multiply by `dpr` to get device pixels:

```ts
const assetStore: TLAssetStore = {
	async resolve(asset, context) {
		if (asset.type !== 'image') return asset.props.src

		// Request a version of the image scaled to what's actually visible on screen
		const width = Math.ceil(asset.props.w * context.steppedScreenScale * context.dpr)
		return `${asset.props.src}?w=${width}`
	},
}
```

A 4000px-wide photo zoomed out to take up 200px on screen has a screen scale of 0.05, which steps up to 0.0625, so you'd serve a 250px-wide image (times `dpr`) instead of the full 4000px. This reduces memory usage and decoding cost. Resolution updates are debounced so images don't thrash between sizes during zooming.

**Built-in shape simplifications**

The built-in shapes reduce rendering complexity at low zoom levels. Sticky notes drop their box shadow in favor of a plain bottom border. Dashed and dotted freehand strokes render as solid lines. The hatch pattern fill switches to a solid fallback color. Text outlines turn off below the `textShadowLod` threshold (default 0.35) to reduce compositing cost, and are always off on Safari.

These transitions use [`Editor.getEfficientZoomLevel`](/reference/editor/Editor#getEfficientZoomLevel) so they stay stable during camera movement rather than updating every frame. Custom shapes can use the same technique. See [Simplify at small sizes](#simplify-at-small-sizes) below.

## Tips for custom shapes

### Simplify at small sizes

When shapes are very small on screen, fine details become invisible. Rendering simpler geometry at low zoom levels improves performance without visible quality loss.

Use `editor.getEfficientZoomLevel()` to detect when shapes are small enough to simplify:

```tsx
function MyShapeComponent({ shape }: { shape: MyShape }) {
	const editor = useEditor()
	const isSmall = useValue(
		'is small',
		() => {
			const zoom = editor.getEfficientZoomLevel()
			// Shape is small if its screen size is under 50px
			return shape.props.w * zoom < 50
		},
		[editor, shape.props.w]
	)

	if (isSmall) {
		// Render simplified version
		return <rect width={shape.props.w} height={shape.props.h} fill="currentColor" />
	}

	// Render full detail version
	return <ComplexShapeContent shape={shape} />
}
```

### Avoid shape animations

Animating shape properties causes continuous re-renders. A spinning shape triggers updates every frame. If you have many shapes or complex rendering, this adds up quickly.

If you need animation, use CSS animations for purely visual effects that don't change shape data, use a canvas for particle systems or complex effects, and keep the number of concurrently animating shapes small.

The [Animation](/sdk-features/animation) article covers the editor's animation system. It handles camera movement and occasional shape transitions. It's not designed for continuous per-shape animation.

### Keep component functions cheap

Shape components render frequently. Avoid expensive operations inside them:

```tsx
// Avoid: expensive calculation every render
function MyShapeComponent({ shape }) {
	const complexData = computeExpensiveData(shape) // runs every render
	return <div>{complexData}</div>
}

// Better: use memoization or move to getGeometry
function MyShapeComponent({ shape }) {
	const complexData = useMemo(() => computeExpensiveData(shape), [shape.props.relevantProp])
	return <div>{complexData}</div>
}
```

For calculations that affect hit testing or bounds, put them in `getGeometry()` instead. The editor caches geometry automatically.

### Disable culling only when necessary

By default, all shapes participate in culling. Override [`ShapeUtil.canCull`](/reference/editor/ShapeUtil#canCull) to return `false` only for shapes that genuinely need to stay rendered off-screen:

```ts
class MyShapeUtil extends ShapeUtil<MyShape> {
	override canCull(shape: MyShape): boolean {
		// Only disable culling for shapes that measure their DOM
		return !shape.props.dynamicSize
	}
}
```

Reasons to disable culling include shapes that measure their DOM content to determine size, shapes with visual effects (shadows, glows) that extend beyond their bounds, and shapes running animations that should continue off-screen. For most shapes, leave culling enabled.

## Editor options for performance

Several [editor options](/sdk-features/options) affect performance:

| Option                   | Default | Description                                      |
| ------------------------ | ------- | ------------------------------------------------ |
| `debouncedZoom`          | `true`  | Use stable zoom during camera movement           |
| `debouncedZoomThreshold` | 500     | Shape count above which debounced zoom activates |
| `maxShapesPerPage`       | 4000    | Maximum shapes allowed per page                  |
| `textShadowLod`          | 0.35    | Zoom threshold below which text shadows disable  |

```tsx
import { Tldraw } from 'tldraw'

function App() {
	return (
		<Tldraw
			options={{
				debouncedZoomThreshold: 1000, // Higher threshold for simpler documents
				maxShapesPerPage: 10000, // Allow more shapes if needed
			}}
		/>
	)
}
```

## Measuring performance

When investigating performance issues, start with the numbers: `editor.getCurrentPageShapeIds().size` tells you how many shapes are on the current page and [`Editor.getCulledShapes`](/reference/editor/Editor#getCulledShapes) tells you how many of them are hidden by culling. Then use React DevTools and Chrome's Performance tab to find slow components, and test with a production build, since development mode has overhead that production builds don't.

If performance degrades with many shapes, look for shapes that disable culling unnecessarily, components that use `getZoomLevel()` instead of `getEfficientZoomLevel()`, expensive calculations inside component render functions, and continuous animations on many shapes.

### Subscribing to performance events

For programmatic monitoring (telemetry or in-app dashboards), the editor exposes [`PerformanceManager`](/reference/editor/PerformanceManager) at `editor.performance`. Subscribe to events and you'll get aggregated frame-time stats from real interactions, with no overhead when no listeners are attached:

```ts
const unsub = editor.performance.on('interaction-end', (event) => {
	console.log(`${event.name}: ${event.fps.toFixed(1)} fps, p95=${event.p95FrameTime.toFixed(1)}ms`)
})
// later: unsub()
```

The `'interaction-end'` event fires when an interaction state exits, with `fps`, `p95FrameTime`, and (in supporting browsers) Long Animation Frame attribution. `'camera-end'` fires after pan/zoom debounce with the same shape. `'shapes-created'`, `'shapes-updated'`, and `'shapes-deleted'` carry per-type counts. `'frame'` fires every animation frame while a listener is attached. See [`TLPerfEventMap`](/reference/editor/TLPerfEventMap) for the full set.

Custom tools opt into interaction tracking by setting [`StateNode.trackPerformance`](/reference/editor/StateNode#trackPerformance) on the state node class. When the state is entered, the manager starts a tracking window; when it exits, it emits `'interaction-start'` / `'interaction-end'` with the state path. Built-in interactions like `select.translating` and `draw.drawing` already track, so you only need this for custom states.

If you're profiling in Chrome DevTools, [`PerformanceApiAdapter`](/reference/editor/PerformanceApiAdapter) wires the same events into native `performance.mark()` / `performance.measure()` calls so they show up on the Performance timeline:

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

const adapter = new PerformanceApiAdapter(editor.performance)
// later: adapter.dispose()
```

## Related

- [Culling](/sdk-features/culling): how viewport culling works and how to control it
- [Signals](/sdk-features/signals): the reactive state system
- [Store](/sdk-features/store): how the reactive database batches changes
- [Options](/sdk-features/options): all available editor options
- [Animation](/sdk-features/animation): the shape and camera animation systems

--------

# Persistence

In tldraw, persistence means storing the editor's state to a database and restoring it later. The SDK provides several approaches: automatic local persistence with a single prop, manual snapshots for custom storage backends, and a migration system for handling schema changes.

## The persistenceKey prop

The simplest way to persist an editor is with the `persistenceKey` prop:

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

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

With this prop, the editor saves to IndexedDB whenever it changes and loads from IndexedDB on mount. It also stores assets alongside the document and keeps tabs with the same key in sync. Under the hood this is the internal `useLocalStore` hook.

Each persistence key represents a separate document:

```tsx
<Tldraw persistenceKey="document-a" />
<Tldraw persistenceKey="document-b" />
```

Two editors with the same key share the same document and stay in sync. Each editor still maintains its own session state (camera position, selection, current page), saved per tab under the `sessionId` prop, which defaults to a unique id for the tab.

## Snapshots

For custom storage backends, use snapshots to save and load editor state. A snapshot is a JSON-serializable object containing the full document.

### Getting a snapshot

Call [`getSnapshot`](/reference/editor/getSnapshot) with the editor's store (or [`Editor.getSnapshot`](/reference/editor/Editor#getSnapshot)) to get the current state:

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

const { document, session } = getSnapshot(editor.store)
```

The snapshot has two parts:

| Part       | Contents                                  | When to share                 |
| ---------- | ----------------------------------------- | ----------------------------- |
| `document` | Shapes, pages, bindings, assets           | Save to server in multiplayer |
| `session`  | Camera, current page, selection, UI state | Keep per-user locally         |

For single-user apps, save both together:

```ts
localStorage.setItem('my-drawing', JSON.stringify({ document, session }))
```

For multiplayer, save them separately:

```ts
await saveToServer(documentId, document)
localStorage.setItem(`session-${documentId}`, JSON.stringify(session))
```

### Loading a snapshot

Call [`loadSnapshot`](/reference/editor/loadSnapshot) (or [`Editor.loadSnapshot`](/reference/editor/Editor#loadSnapshot)) to restore state into an existing editor:

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

const saved = JSON.parse(localStorage.getItem('my-drawing'))
loadSnapshot(editor.store, saved)
```

You can load document and session separately:

```ts
// Load document from server
const document = await fetchFromServer(documentId)
loadSnapshot(editor.store, { document })

// Optionally load session from local storage
const session = JSON.parse(localStorage.getItem(`session-${documentId}`))
if (session) {
	loadSnapshot(editor.store, { session })
}
```

Loading a `document` on its own preserves the editor's current session state. Pass `{ forceOverwriteSessionState: true }` as a third argument to replace it with the snapshot's session instead.

### Initial state

Pass a snapshot to the `Tldraw` component to initialize with saved data:

```tsx
import { useState, useEffect } from 'react'
import { Tldraw, TLEditorSnapshot } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
	const [snapshot, setSnapshot] = useState<TLEditorSnapshot | null>(null)

	useEffect(() => {
		async function load() {
			const document = await fetchDocument(documentId)
			const session = getLocalSession(documentId)
			setSnapshot({ document, session })
		}
		load()
	}, [])

	if (!snapshot) return <div>Loading...</div>

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw snapshot={snapshot} />
		</div>
	)
}
```

## Custom persistence with store

For more control, create your own store and pass it to the editor. This lets you load data before mounting and implement custom sync logic.

### Creating a store

Use [`createTLStore`](/reference/editor/createTLStore) to create a standalone store:

```tsx
import { useState } from 'react'
import { createTLStore, loadSnapshot, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
	const [store] = useState(() => {
		const store = createTLStore()

		const saved = localStorage.getItem('my-drawing')
		if (saved) {
			loadSnapshot(store, JSON.parse(saved))
		}

		return store
	})

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw store={store} />
		</div>
	)
}
```

### Async loading with TLStoreWithStatus

When loading data asynchronously, use [`TLStoreWithStatus`](/reference/editor/TLStoreWithStatus) to handle loading and error states:

```tsx
import { useState, useEffect } from 'react'
import { createTLStore, loadSnapshot, Tldraw, TLStoreWithStatus } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
	const [storeWithStatus, setStoreWithStatus] = useState<TLStoreWithStatus>({
		status: 'loading',
	})

	useEffect(() => {
		let cancelled = false

		async function load() {
			try {
				const snapshot = await fetchSnapshot()
				if (cancelled) return

				const store = createTLStore()
				loadSnapshot(store, snapshot)

				setStoreWithStatus({ status: 'synced-local', store })
			} catch (error) {
				if (cancelled) return
				setStoreWithStatus({ status: 'error', error: error as Error })
			}
		}

		load()
		return () => {
			cancelled = true
		}
	}, [])

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw store={storeWithStatus} />
		</div>
	)
}
```

The editor shows the `LoadingScreen` component while the status is `loading`, throws the `error` to the nearest error boundary, and renders normally for the other statuses. The possible values are:

| Status          | Meaning                                                             |
| --------------- | ------------------------------------------------------------------- |
| `loading`       | The store is loading                                                |
| `error`         | Loading failed                                                      |
| `not-synced`    | Store created without persistence                                   |
| `synced-local`  | Store loaded from local storage                                     |
| `synced-remote` | Store synced with remote server (includes `connectionStatus` field) |

## Listening for changes

Subscribe to store changes with [`Store.listen`](/reference/store/Store#listen) to implement auto-save or sync:

```ts
const cleanup = editor.store.listen((entry) => {
	for (const record of Object.values(entry.changes.added)) {
		console.log('Added:', record.typeName, record.id)
	}

	for (const [prev, next] of Object.values(entry.changes.updated)) {
		console.log('Updated:', next.id)
	}

	for (const record of Object.values(entry.changes.removed)) {
		console.log('Removed:', record.id)
	}
})
```

The `listen` method returns a cleanup function you should call when unmounting.

### Filtering changes

Filter by source and scope to listen for specific changes:

```ts
// Only user changes (not remote sync)
editor.store.listen(handleChanges, { source: 'user', scope: 'all' })

// Only document records (not session state)
editor.store.listen(handleChanges, { source: 'all', scope: 'document' })
```

| Filter   | Values                                           | Purpose                 |
| -------- | ------------------------------------------------ | ----------------------- |
| `source` | `'user'`, `'remote'`, `'all'`                    | Where changes came from |
| `scope`  | `'document'`, `'session'`, `'presence'`, `'all'` | Type of records         |

### Throttled auto-save

Here's a pattern for auto-saving with throttling (`lodash` isn't a tldraw dependency, so bring your own throttle):

```ts
import { throttle } from 'lodash'
import { getSnapshot } from 'tldraw'

const saveToStorage = throttle(() => {
	const snapshot = getSnapshot(editor.store)
	localStorage.setItem('my-drawing', JSON.stringify(snapshot))
}, 500)

const cleanup = editor.store.listen(saveToStorage)
```

## Remote changes

When synchronizing with a multiplayer backend, use [`Store.mergeRemoteChanges`](/reference/store/Store#mergeRemoteChanges) with [`Store.put`](/reference/store/Store#put) and [`Store.remove`](/reference/store/Store#remove) to apply updates from other users:

```ts
myRemoteSource.on('change', (changes) => {
	editor.store.mergeRemoteChanges(() => {
		for (const change of changes) {
			if (change.type === 'add' || change.type === 'update') {
				editor.store.put([change.record])
			} else if (change.type === 'remove') {
				editor.store.remove([change.id])
			}
		}
	})
})
```

Changes inside `mergeRemoteChanges` are tagged with `source: 'remote'`. This lets you filter them out when listening, so you don't create an infinite sync loop:

```ts
// Only save user changes, not remote changes
editor.store.listen(saveToServer, { source: 'user', scope: 'document' })
```

For production multiplayer apps, use the [@tldraw/sync](/docs/sync) package instead of building your own sync layer.

## Migrations

Snapshots include schema version information. When you load a snapshot from an older version, the store migrates it automatically. You don't need to do anything for tldraw's built-in types.

### Shape props migrations

If you have custom shapes, define migrations to handle changes to their props over time:

```ts
import { createShapePropsMigrationIds, createShapePropsMigrationSequence, ShapeUtil } from 'tldraw'

// Version IDs must start at 1 and increment
const versions = createShapePropsMigrationIds('my-shape', {
	AddColor: 1,
	RenameSize: 2,
})

const migrations = createShapePropsMigrationSequence({
	sequence: [
		{
			id: versions.AddColor,
			up(props) {
				props.color = 'black'
			},
			down(props) {
				delete props.color
			},
		},
		{
			id: versions.RenameSize,
			up(props) {
				props.dimensions = props.size
				delete props.size
			},
			down(props) {
				props.size = props.dimensions
				delete props.dimensions
			},
		},
	],
})

// Attach migrations to your shape util
class MyShapeUtil extends ShapeUtil<MyShape> {
	static override type = 'my-shape' as const
	static override migrations = migrations
	// ...
}
```

Multiplayer sync uses the `down` migrations when a peer is running an older schema version.

### General migrations

For migrating other data like `meta` properties, use the general migration API:

```ts
import { createMigrationIds, createMigrationSequence } from 'tldraw'

const sequenceId = 'com.example.my-app'

const versions = createMigrationIds(sequenceId, {
	RemoveLegacyField: 1,
})

const migrations = createMigrationSequence({
	sequenceId,
	sequence: [
		{
			id: versions.RemoveLegacyField,
			scope: 'record',
			filter: (record) => record.typeName === 'page',
			up(page: any) {
				delete page.meta.legacyField
			},
		},
	],
})
```

Pass migrations to the `Tldraw` component or when creating a store:

```tsx
<Tldraw migrations={[migrations]} />
```

```ts
const store = createTLStore({ migrations: [migrations] })
```

### Migration scopes

Migrations support different scopes depending on what you need to change:

| Scope     | Use case                                                                                                          |
| --------- | ----------------------------------------------------------------------------------------------------------------- |
| `record`  | Runs on individual records matching an optional filter                                                            |
| `store`   | Receives the entire serialized store for cross-record changes                                                     |
| `storage` | Receives a `SynchronousRecordStorage` with `get`, `set`, `delete`, `keys`, `values`, and `entries`. Has no `down` |

Most migrations use `record` scope. Use `store` or `storage` when you need to read or modify multiple records together.

## Examples

- [Persistence key](/examples/configuration/persistence-key) - Automatic local persistence with a single prop
- [Snapshots](/examples/editor-api/snapshots) - Saving and loading editor state
- [Local storage](/examples/data/assets/local-storage) - Custom persistence with throttled auto-save
- [Store events](/examples/events/store-events) - Listening to store changes
- [Shape with migrations](/examples/shapes/tools/shape-with-migrations) - Migrations for custom shape props
- [Meta migrations](/examples/data/assets/meta-migrations) - General migrations for meta properties

--------

# Readonly mode

Readonly mode turns the editor into a viewer. Users can pan, zoom, and select shapes to inspect them, but they can't create, modify, or delete anything. Use readonly mode when you want to display canvas content without allowing changes: embedding documents in a presentation, sharing a design for feedback, or showing a preview of saved work.

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

export default function ReadOnlyViewer() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					editor.updateInstanceState({ isReadonly: true })
				}}
			/>
		</div>
	)
}
```

## Enabling readonly mode

Readonly state lives in the editor's instance state. Toggle it with [`Editor.updateInstanceState`](/reference/editor/Editor#updateInstanceState) and read it with [`Editor.getIsReadonly`](/reference/editor/Editor#getIsReadonly):

```typescript
// Enable readonly mode
editor.updateInstanceState({ isReadonly: true })

// Disable readonly mode
editor.updateInstanceState({ isReadonly: false })

// Check current state
const isReadonly = editor.getIsReadonly()
```

Readonly state is session-scoped and is not saved by `persistenceKey`, so set it on every load, as the example above does in `onMount`. Loading a snapshot with [`Editor.loadSnapshot`](/reference/editor/Editor#loadSnapshot) preserves the current in-memory value.

## What readonly mode blocks

When readonly is enabled, the editor prevents document mutations. Methods that block include:

| Category   | Blocked methods                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Shapes     | `createShape`, `deleteShapes`, `updateShape`, `groupShapes`, `ungroupShapes`, `toggleLock`                                     |
| Pages      | `createPage`, `deletePage`, `renamePage`, `updatePage`, `moveShapesToPage`                                                     |
| Assets     | `createAssets`, `updateAssets`, `deleteAssets`                                                                                 |
| Transforms | `flipShapes`, `packShapes`, `stackShapes`, `alignShapes`, `distributeShapes`, `stretchShapes`, `rotateShapesBy`, `resizeShape` |
| Styles     | `setStyleForSelectedShapes`, `setOpacityForSelectedShapes`                                                                     |
| Content    | `putExternalContent`, `replaceExternalContent`, `putContentOntoCurrentPage`, plus the `cut` and `paste` UI actions             |

Methods that only touch instance state, such as `setStyleForNextShapes` and `setOpacityForNextShapes`, still work.

The toolbar automatically hides editing tools. Only the select tool, hand tool, and laser pointer remain visible. UI actions like undo and redo are also disabled in readonly mode.

## What readonly mode allows

Navigation and viewing operations work normally. You can pan, zoom, and use camera methods like `zoomIn`, `zoomOut`, `zoomToFit`, and `zoomToSelection`. Selection works too: clicking shapes, brush selection, `selectAll`, and `selectNone`.

You can also hover over shapes to inspect them and switch between pages. Exporting with the `exportAs` or `copyAs` helper functions works because exporting doesn't modify the document.

## Using the useReadonly hook

In React components, the [`useReadonly`](/reference/tldraw/useReadonly) hook provides reactive access to the readonly state (and returns `false` outside an editor context). Import it from `tldraw`:

```tsx
import { useReadonly } from 'tldraw'

function ReadonlyIndicator() {
	const isReadonly = useReadonly()

	if (!isReadonly) return null

	return <div className="readonly-badge">View only</div>
}
```

The component re-renders automatically when readonly state changes.

## Actions in readonly mode

[`TLUiActionItem`](/reference/tldraw/TLUiActionItem) has a `readonlyOk` property that determines whether the UI offers the action in readonly mode. When an action has `readonlyOk: false` (the default), menus hide it and its keyboard shortcut is ignored in readonly mode.

Built-in actions that work in readonly mode include zoom controls (`zoom-in`, `zoom-out`, `zoom-to-fit`, `zoom-to-selection`), selection actions (`select-all`, `select-none`, `copy`), export actions (`export-as-svg`, `export-as-png`, `print`), navigation (`back-to-content`, `change-page-prev`, `change-page-next`), and preference toggles like `toggle-dark-mode`.

When defining custom actions, set `readonlyOk: true` if the action should work in readonly mode:

```typescript
import { TLUiOverrides } from 'tldraw'

const overrides: TLUiOverrides = {
	actions(editor, actions, helpers) {
		actions['share-link'] = {
			id: 'share-link',
			label: 'action.share-link',
			readonlyOk: true,
			onSelect() {
				// This works in readonly mode
				navigator.clipboard.writeText(window.location.href)
			},
		}
		return actions
	},
}
```

## Shapes that remain interactive

Some shapes have interactive content that works even when the document is readonly. Embed shapes (YouTube videos, Figma files, interactive maps) are the built-in case: the embed itself is locked in place, but users can still play videos or interact with the embedded content.

ShapeUtils can override [`ShapeUtil.canEditInReadonly`](/reference/editor/ShapeUtil#canEditInReadonly) to allow editing interactions on their shapes:

```typescript
class InteractiveWidgetUtil extends ShapeUtil<InteractiveWidget> {
	override canEditInReadonly(shape: InteractiveWidget): boolean {
		return true
	}
}
```

When this returns `true`, double-clicking the shape enters edit mode even in readonly mode. The shape's interactive content becomes usable while the shape itself stays fixed.

## Forcing operations in readonly mode

For programmatic use cases like migrations or admin tools, you can bypass the readonly check by passing `force: true` to [`Editor.putExternalContent`](/reference/editor/Editor#putExternalContent) and [`Editor.replaceExternalContent`](/reference/editor/Editor#replaceExternalContent):

```typescript
// This works even in readonly mode
editor.putExternalContent({ type: 'files', files: myFiles, point: { x: 0, y: 0 } }, { force: true })
```

Only these two methods support this option. Use it sparingly since readonly mode exists to prevent unintended changes.

## Collaboration and readonly mode

When using tldraw's sync packages for collaboration, readonly mode integrates with room permissions. A user with read-only access to a shared document sees the editor in readonly mode automatically. The sync layer communicates the mode through a reactive signal, and the editor updates `isReadonly` in response.

Changes from other collaborators still appear (the document updates in real time) but the readonly user can't contribute changes themselves.

## Related examples

- [Read-only](/examples/configuration/readonly): set up a readonly editor that disables all editing functionality.

--------

# Rich text

Rich text lets you add formatted text to tldraw shapes. You get inline formatting like bold, italic, code, and highlighting, plus structural features like lists and links. Text, note, geo, and arrow label shapes all support rich text editing.

Under the hood, tldraw uses TipTap (a headless editor toolkit built on ProseMirror) as the rich text engine. Text is stored as structured JSON rather than plain strings, which enables reliable formatting operations, custom extensions, and consistent serialization.

## How it works

Rich text content is a JSON tree ([`TLRichText`](/reference/tlschema/TLRichText)). The root document contains paragraphs, and paragraphs contain text nodes with optional formatting marks.

### Document structure

A rich text document has three main components: the document root, content blocks, and text nodes with marks.

```typescript
const richText: TLRichText = {
	type: 'doc',
	content: [
		{
			type: 'paragraph',
			content: [
				{ type: 'text', text: 'Hello ' },
				{
					type: 'text',
					text: 'world',
					marks: [{ type: 'bold' }],
				},
			],
		},
	],
}
```

The `type` field identifies the node kind. The `content` array holds child nodes. Text nodes include a `marks` array for formatting information.

### Converting between formats

Use [`toRichText`](/reference/tlschema/toRichText) to convert plain text strings to rich text documents. Each line becomes a separate paragraph:

```typescript
import { toRichText } from 'tldraw'

const richText = toRichText('First line\nSecond line')
// Creates two paragraphs
```

Note that `toRichText` treats all input as plain text—it doesn't parse markdown or other formatting. To create formatted content programmatically, build the rich text JSON structure directly or use the TipTap editor API.

To extract plain text from a rich text document, use [`renderPlaintextFromRichText`](/reference/tldraw/renderPlaintextFromRichText). It strips all formatting and preserves line breaks:

```typescript
import { renderPlaintextFromRichText } from 'tldraw'

const text = renderPlaintextFromRichText(editor, shape.props.richText)
// Returns: "First line\nSecond line"
```

For HTML output, use [`renderHtmlFromRichText`](/reference/tldraw/renderHtmlFromRichText). It preserves all styling and structure, which is useful for rendering rich text outside the editor or exporting content. [`renderRichTextFromHTML`](/reference/tldraw/renderRichTextFromHTML) goes the other way, from HTML to `TLRichText`.

```typescript
import { renderHtmlFromRichText } from 'tldraw'

const html = renderHtmlFromRichText(editor, shape.props.richText)
// Returns: '<p dir="auto">First line</p><p dir="auto">Second line</p>'
```

## TipTap integration

TipTap handles the rich text editing experience. The editor appears when users double-click a text shape or press Enter while one is selected, and it handles focus, keyboard shortcuts, and formatting commands.

### Default extensions

[`tipTapDefaultExtensions`](/reference/tldraw/tipTapDefaultExtensions) is TipTap's StarterKit plus tldraw's customizations: the `Highlight` mark, a Shift+Enter tweak, and automatic text direction for right-to-left languages. StarterKit is configured to disable blockquotes, code blocks, and horizontal rules; headings, lists, links, and the standard marks stay on. Links don't open on click during editing, which prevents accidental navigation.

To tweak StarterKit without losing tldraw's extensions, build the list with [`getTipTapDefaultExtensions`](/reference/tldraw/getTipTapDefaultExtensions), which accepts StarterKit options:

```typescript
import { getTipTapDefaultExtensions } from 'tldraw'

// The default set, minus headings
const extensions = getTipTapDefaultExtensions({ heading: false })
```

### Custom extensions

You can add custom TipTap extensions through the `text` field of the `options` prop on the Tldraw component ([`TLTextOptions`](/reference/editor/TLTextOptions)):

```tsx
import { Mark, mergeAttributes } from '@tiptap/core'
import { Tldraw, tipTapDefaultExtensions } from 'tldraw'
import 'tldraw/tldraw.css'

const CustomMark = Mark.create({
	name: 'custom',
	parseHTML() {
		return [{ tag: 'span.custom' }]
	},
	renderHTML({ HTMLAttributes }) {
		return ['span', mergeAttributes({ class: 'custom' }, HTMLAttributes), 0]
	},
	addCommands() {
		return {
			toggleCustom:
				() =>
				({ commands }) =>
					commands.toggleMark(this.name),
		}
	},
})

const options = {
	text: {
		tipTapConfig: {
			extensions: [...tipTapDefaultExtensions, CustomMark],
		},
	},
}

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

The `extensions` array replaces the default list entirely, so spread `tipTapDefaultExtensions` (or the result of `getTipTapDefaultExtensions`) to keep tldraw's defaults. Passing `[StarterKit, CustomMark]` alone drops highlighting and text direction, and StarterKit's default link config opens links on click while editing.

### Rich text toolbar

The rich text toolbar appears when editing any rich-text shape (it's hidden on touch devices). It gives you quick access to formatting commands like bold, italic, and lists, and shows which formats are active at the current cursor position.

You can customize the toolbar by overriding the `RichTextToolbar` component. Use [`Editor.getRichTextEditor`](/reference/editor/Editor#getRichTextEditor) to get the TipTap editor instance and execute formatting commands:

```tsx
import {
	DefaultRichTextToolbar,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	preventDefault,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'

const components: TLComponents = {
	RichTextToolbar: () => {
		const editor = useEditor()
		const textEditor = useValue('textEditor', () => editor.getRichTextEditor(), [editor])

		return (
			<DefaultRichTextToolbar>
				<TldrawUiButton
					type="icon"
					onClick={() => textEditor?.chain().focus().toggleBold().run()}
					onPointerDown={preventDefault}
				>
					B
				</TldrawUiButton>
			</DefaultRichTextToolbar>
		)
	},
}

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

[`DefaultRichTextToolbar`](/reference/tldraw/DefaultRichTextToolbar) provides the toolbar frame and positioning. Passing children replaces the default buttons; render [`DefaultRichTextToolbarContent`](/reference/tldraw/DefaultRichTextToolbarContent) alongside your own buttons to keep them, or replace the component entirely.

## Shapes with rich text

Four default shapes have a `richText` prop: text, note, geo, and arrow. Each renders it through the [`RichTextLabel`](/reference/tldraw/RichTextLabel) component, which handles both display and editing. [Text shapes](/sdk-features/text-shape) are standalone blocks that auto-size or wrap at a fixed width. [Note shapes](/sdk-features/note-shape) have a fixed width and grow taller to fit their text. Geo shapes position their label with `align` and `verticalAlign` (centered by default) and wrap inside the shape's padding. Arrow labels sit along the arrow path at `labelPosition` and move with the arrow.

## Font management

Rich text can include multiple fonts and font styles within a single text block. Shapes report the fonts they need from [`ShapeUtil.getFontFaces`](/reference/editor/ShapeUtil#getFontFaces), and the font manager loads them before rendering to prevent layout shifts.

Use [`getFontsFromRichText`](/reference/editor/getFontsFromRichText) to collect the required font faces from the text content and formatting marks:

```typescript
import { getFontsFromRichText } from 'tldraw'

const fonts = getFontsFromRichText(editor, richText, {
	family: 'tldraw_draw',
	weight: 'normal',
	style: 'normal',
})
```

The function accepts an initial font state representing the base font. It walks the document tree, examining marks on text nodes to determine when bold or italic variants are needed. When code marks are present, it switches to the monospace font family.

### Custom font resolution

You can override font resolution by providing a custom `addFontsFromNode` function through `options.text`. The function receives the current node, the font state, and a callback to register required fonts. It returns the updated state, which is passed down to the node's children. Call `addFont` for every face the node needs; [`defaultAddFontsFromNode`](/reference/tldraw/defaultAddFontsFromNode) is the built-in implementation to wrap or copy:

```typescript
import { defaultAddFontsFromNode, TLTextOptions } from 'tldraw'
import { myBrandFont } from './fonts'

const textOptions: TLTextOptions = {
	addFontsFromNode: (node, state, addFont) => {
		if (node.marks.some((m) => m.type.name === 'brand')) {
			addFont(myBrandFont)
			return { ...state, family: myBrandFont.family }
		}
		return defaultAddFontsFromNode(node, state, addFont)
	},
}
```

See the [rich text font extensions example](/examples/shapes/tools/rich-text-font-extensions) for a full implementation.

## Programmatic formatting

You can apply formatting to rich text programmatically by accessing the TipTap editor instance. This enables bulk operations like applying formatting to multiple shapes or implementing custom formatting commands:

```typescript
const textEditor = editor.getRichTextEditor()
if (textEditor) {
	// Make all selected text bold
	textEditor.chain().focus().selectAll().toggleBold().run()
}
```

The chain API lets you compose multiple operations. Each command returns a chainable object, and `run()` executes the composed command sequence.

For operations outside the editing context, you can manipulate the rich text JSON directly. `TLRichText.content` is typed as `unknown[]`, so cast to TipTap's `JSONContent` when walking the tree:

```typescript
import { JSONContent } from '@tiptap/core'

function makeAllTextBold(richText: TLRichText): TLRichText {
	const content = (richText.content as JSONContent[]).map((paragraph) => {
		if (!paragraph.content) return paragraph

		return {
			...paragraph,
			content: paragraph.content.map((node) => {
				if (node.type !== 'text') return node

				const marks = node.marks || []
				if (marks.some((m) => m.type === 'bold')) return node

				return {
					...node,
					marks: [...marks, { type: 'bold' }],
				}
			}),
		}
	})

	return { ...richText, content }
}
```

## Measurement and rendering

Rich text measurement uses the same system as plain text, with HTML replacing the plain text content. [`TextManager.measureHtml`](/reference/editor/TextManager#measureHtml) measures rich text by rendering the HTML into the measurement element and reading the computed dimensions:

```typescript
import { renderHtmlFromRichTextForMeasurement } from 'tldraw'

const html = renderHtmlFromRichTextForMeasurement(editor, richText)
// Returns HTML wrapped in measurement container
```

The measurement system accounts for formatting that affects layout, like bold text or lists. Font loading completes before measurement so dimensions are accurate.

For SVG export, the [`RichTextSVG`](/reference/tldraw/RichTextSVG) component renders rich text as a `foreignObject` element. Exported images keep the same formatting and layout as the canvas.

## Text options

`options.text` ([`TLTextOptions`](/reference/editor/TLTextOptions)) has two fields: `tipTapConfig`, which passes through to TipTap's editor configuration, and `addFontsFromNode` for font resolution:

```typescript
const options = {
	text: {
		tipTapConfig: {
			extensions: [...],
			editorProps: {
				attributes: {
					class: 'custom-editor',
				},
			},
		},
		addFontsFromNode: customFontResolver,
	},
}
```

## Related examples

- [Rich text with custom extension](/examples/shapes/tools/rich-text-custom-extension) — Adding a custom TipTap extension and toolbar button.
- [Rich text with font extensions](/examples/shapes/tools/rich-text-font-extensions) — Extending the editor with font-family and font-size controls.
- [Format rich text on multiple shapes](/examples/ui/rich-text-on-multiple-shapes) — Applying formatting to multiple selected shapes programmatically.

--------

# Scribble

The scribble system draws temporary freehand paths for pointer-based interactions. Use scribbles to show visual feedback during tool operations like erasing, laser pointer drawing, or scribble-brush selection. Access the system through [`Editor.scribbles`](/reference/editor/Editor#scribbles).

Scribbles exist only in instance state and fade out automatically after the tool operation completes. They're never persisted to the document, though they are broadcast to collaborators through presence so peers see your eraser and laser trails.

## How it works

### Scribble lifecycle

A scribble's `state` is one of five values from [`TLScribble`](/reference/tlschema/TLScribble):

| State    | Description                                                                                                                      |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Starting | The scribble collects points until it has more than 8. This prevents flickering for very short strokes.                          |
| Active   | The scribble accumulates points as the pointer moves.                                                                            |
| Complete | Drawing finished but fading hasn't started. Set with [`ScribbleManager.complete`](/reference/editor/ScribbleManager#complete) so the end cap tapers when the pointer lifts. |
| Stopping | The scribble fades out by progressively removing points from its tail. The manager deletes the scribble once all points clear.   |
| Paused   | Defined in the schema but not used by the manager.                                                                               |

The [`ScribbleManager.tick`](/reference/editor/ScribbleManager#tick) method updates all scribbles on every animation frame, handling state transitions, point management, and fade-out timing.

### Fade-out behavior

During fade-out, the scribble shrinks from the tail by removing points at regular intervals. By default (`shrink: 0.1`) the stroke width also decreases as points are removed; set `shrink: 0` to fade at constant width.

The `delay` property controls how long a scribble stays at full length before shrinking. Stopping a scribble caps any remaining delay at 200ms. Self-consuming scribbles (the default) remove points from the start as you draw, maintaining a constant length.

## Using scribbles

The [`ScribbleManager`](/reference/editor/ScribbleManager) provides two APIs: a direct API for single self-consuming strokes, and a session API for when several strokes should fade together, as the laser pointer's do.

### Direct API

The direct API works well for tools like the eraser that use self-consuming scribbles:

```typescript
import { StateNode, TLPointerEventInfo } from '@tldraw/editor'

export class Erasing extends StateNode {
	static override id = 'erasing'

	private scribbleId = ''

	override onEnter(info: TLPointerEventInfo) {
		const scribble = this.editor.scribbles.addScribble({
			color: 'muted-1',
			size: 12,
		})
		this.scribbleId = scribble.id
		this.pushPointToScribble()
	}

	override onExit() {
		this.editor.scribbles.stop(this.scribbleId)
	}

	override onPointerMove() {
		this.pushPointToScribble()
	}

	private pushPointToScribble() {
		const { x, y } = this.editor.inputs.getCurrentPagePoint()
		this.editor.scribbles.addPoint(this.scribbleId, x, y)
	}
}
```

[`ScribbleManager.addScribble`](/reference/editor/ScribbleManager#addScribble) takes optional configuration and returns a [`ScribbleItem`](/reference/editor/ScribbleItem) containing the scribble's ID. [`ScribbleManager.addPoint`](/reference/editor/ScribbleManager#addPoint) ignores points less than one page unit from the previous one; pass an optional `z` value after the coordinates (default `0.5`) for pressure-based width. [`ScribbleManager.stop`](/reference/editor/ScribbleManager#stop) moves the scribble to the stopping state, and the manager removes it once all points clear.

The scribble-brush selection in the select tool uses the same API with `color: 'selection-stroke'`, `opacity: 0.32`, and `size: 12`.

### Session API

Sessions group multiple scribbles together and control how they fade. The laser pointer uses a session so that every stroke from one drawing burst fades together. Simplified from the real [`LaserTool`](/reference/tldraw/LaserTool):

```typescript
import { StateNode } from '@tldraw/editor'

export class LaserTool extends StateNode {
	static override id = 'laser'
	static override initial = 'idle'
	static override children() {
		return [Idle, Lasering]
	}

	private sessionId: string | null = null

	getSessionId(): string {
		// Reuse existing session if it's still active
		if (this.sessionId && this.editor.scribbles.isSessionActive(this.sessionId)) {
			return this.sessionId
		}

		// Create a new session
		this.sessionId = this.editor.scribbles.startSession({
			selfConsume: false,
			idleTimeoutMs: this.editor.options.laserDelayMs,
			fadeMode: 'grouped',
			fadeEasing: 'ease-in',
		})

		return this.sessionId
	}

	override onCancel() {
		if (this.sessionId && this.editor.scribbles.isSessionActive(this.sessionId)) {
			this.editor.scribbles.clearSession(this.sessionId)
			this.sessionId = null
		}
	}
}
```

The idle state adds a scribble to the session with [`ScribbleManager.addScribbleToSession`](/reference/editor/ScribbleManager#addScribbleToSession) and hands its id to the lasering state:

```typescript
export class Idle extends StateNode {
	static override id = 'idle'

	override onPointerDown() {
		const sessionId = (this.parent as LaserTool).getSessionId()
		const scribble = this.editor.scribbles.addScribbleToSession(sessionId, {
			color: 'laser',
			opacity: 0.7,
			size: 4,
			taper: false,
		})
		this.parent.transition('lasering', { sessionId, scribbleId: scribble.id })
	}
}
```

The lasering state adds points with [`ScribbleManager.addPointToSession`](/reference/editor/ScribbleManager#addPointToSession) and keeps the session alive with [`ScribbleManager.extendSession`](/reference/editor/ScribbleManager#extendSession):

```typescript
export class Lasering extends StateNode {
	static override id = 'lasering'

	private scribbleId = ''
	private sessionId = ''

	override onEnter(info: { sessionId: string; scribbleId: string }) {
		this.sessionId = info.sessionId
		this.scribbleId = info.scribbleId
		this.pushPointToScribble()
	}

	override onPointerMove() {
		this.pushPointToScribble()
	}

	private pushPointToScribble() {
		const { x, y } = this.editor.inputs.getCurrentPagePoint()
		this.editor.scribbles.addPointToSession(this.sessionId, this.scribbleId, x, y)
	}

	override onTick() {
		// Reset idle timeout on activity
		this.editor.scribbles.extendSession(this.sessionId)
	}

	override onPointerUp() {
		// Mark complete to apply taper, then let session handle fade
		this.editor.scribbles.complete(this.scribbleId)
		this.parent.transition('idle')
	}
}
```

## Scribble properties

Scribbles support these visual properties:

| Property  | Default        | Description                                                                                                         |
| --------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`      | auto-generated | Unique identifier for the scribble                                                                                  |
| `color`   | `'accent'`     | Canvas UI color: `'accent'`, `'white'`, `'black'`, `'selection-stroke'`, `'selection-fill'`, `'laser'`, `'muted-1'` |
| `size`    | `20`           | Stroke width in screen pixels                                                                                       |
| `opacity` | `0.8`          | Transparency from 0 to 1                                                                                            |
| `delay`   | `0`            | Milliseconds before shrinking starts (for self-consuming scribbles)                                                 |
| `shrink`  | `0.1`          | Rate at which stroke width decreases during fade-out (0 to 1)                                                       |
| `taper`   | `true`         | Whether the stroke tapers at the ends                                                                               |

All properties have defaults, so you only need to specify what you want to change.

## Session options

When using the session API, you can configure how scribbles behave:

| Property         | Default                   | Description                                                                         |
| ---------------- | ------------------------- | ----------------------------------------------------------------------------------- |
| `id`             | auto-generated            | Session identifier                                                                  |
| `selfConsume`    | `true`                    | Whether scribbles eat their own tail as you draw                                    |
| `idleTimeoutMs`  | `0`                       | Auto-stop session after this many milliseconds of inactivity (0 disables)           |
| `fadeMode`       | `'individual'`            | How scribbles fade: `'individual'` (each on its own) or `'grouped'` (fade together) |
| `fadeEasing`     | `'linear'` or `'ease-in'` | Easing for grouped fade. Defaults to `'ease-in'` when fadeMode is `'grouped'`       |
| `fadeDurationMs` | `laserFadeoutMs` (500ms)  | Duration of the fade in milliseconds                                                |

When `selfConsume` is `false`, points accumulate while the session is active and only fade after the session stops. A session stops when you call [`ScribbleManager.stopSession`](/reference/editor/ScribbleManager#stopSession), or automatically after `idleTimeoutMs` of no activity. In grouped fade mode, the manager removes points from all scribbles in the session proportionally over `fadeDurationMs`; `'ease-in'` removes them slowly at first and faster toward the end. [`ScribbleManager.clearSession`](/reference/editor/ScribbleManager#clearSession) removes everything immediately, and [`ScribbleManager.isSessionActive`](/reference/editor/ScribbleManager#isSessionActive) tells you whether a session is still accepting points.

## Customizing scribble rendering

Scribbles are rendered on an HTML Canvas overlay via the [`ScribbleOverlayUtil`](/reference/tldraw/ScribbleOverlayUtil) from the `tldraw` package. To customize rendering, extend this class (keeping its static `type`) and pass it in the `overlayUtils` prop, which replaces the default util of the same type. See [Overlay utils](/sdk-features/overlay-utils) for how overlay utils are registered and replaced.

## Related articles

- [Tools](/sdk-features/tools) - How tools use state nodes and handle pointer events
- [Overlay utils](/sdk-features/overlay-utils) - The canvas overlay system that renders scribbles

--------

# Selection

The editor tracks which shapes are selected. You can change the selection, read the selected shapes, and get their combined bounds and rotation.

The editor also enforces a few rules on its own: you can't select both a group and its children at the same time, and selecting shapes inside a group focuses that group.

## Selected shape IDs

The editor tracks selection through the `selectedShapeIds` array in the current page's [instance state](/sdk-features/instance-state). This array holds the IDs of all currently selected shapes. Everything else about the selection (bounds, rotation, the selected shape records) is derived from it.

```typescript
// Get currently selected shape IDs
const selectedIds = editor.getSelectedShapeIds()

// Get the actual shape objects
const selectedShapes = editor.getSelectedShapes()
```

[`Editor.getSelectedShapes`](/reference/editor/Editor#getSelectedShapes) resolves the IDs to shape records and drops any IDs that no longer exist in the store.

## Selection methods

### Basic selection

Use [`Editor.select`](/reference/editor/Editor#select), [`Editor.setSelectedShapes`](/reference/editor/Editor#setSelectedShapes), [`Editor.deselect`](/reference/editor/Editor#deselect), and [`Editor.selectNone`](/reference/editor/Editor#selectNone) to change the selection:

```typescript
// Select specific shapes (replaces current selection)
editor.select(shapeId1, shapeId2)
editor.setSelectedShapes([shapeId1, shapeId2])

// Deselect specific shapes (removes from current selection)
editor.deselect(shapeId1)

// Clear all selection
editor.selectNone()
```

Both `select()` and `setSelectedShapes()` replace the current selection entirely. Use `deselect()` to remove specific shapes while keeping others selected. Selection changes are recorded in history without clearing the redo stack.

### Select all

[`Editor.selectAll`](/reference/editor/Editor#selectAll) selects all unlocked shapes, scoped by the current selection:

```typescript
editor.selectAll()
```

- If nothing is selected, it selects all shapes on the current page
- If the selected shapes share a common parent (like shapes inside a group), it selects all shapes within that parent
- If the selected shapes have different parents, it does nothing

### Adjacent selection

Use [`Editor.selectAdjacentShape`](/reference/editor/Editor#selectAdjacentShape) to select the next or previous shape in reading order, or to move by cardinal direction:

```typescript
editor.selectAdjacentShape('next')
editor.selectAdjacentShape('prev')
editor.selectAdjacentShape('left')
editor.selectAdjacentShape('right')
editor.selectAdjacentShape('up')
editor.selectAdjacentShape('down')
```

Cardinal directions score candidate shapes by distance and by how far they sit off the axis of travel, then pick the lowest score. If the selection is inside a group or frame, only siblings in that container are considered. Shapes whose util returns `false` from [`ShapeUtil.canTabTo`](/reference/editor/ShapeUtil#canTabTo) are skipped. In the default UI, Tab and Shift+Tab move to the next and previous shape, and Cmd/Ctrl+Arrow moves by direction.

### Hierarchical selection

Use [`Editor.selectParentShape`](/reference/editor/Editor#selectParentShape) and [`Editor.selectFirstChildShape`](/reference/editor/Editor#selectFirstChildShape) to move up and down the shape hierarchy:

```typescript
// Select the parent of the currently selected shape
editor.selectParentShape()

// Select the first child of the currently selected shape
editor.selectFirstChildShape()
```

`selectParentShape()` only acts when exactly one shape is selected. `selectFirstChildShape()` picks the first child (in reading order) of the first selected shape. Both zoom to the new selection if it's offscreen. In the default UI these are bound to Cmd/Ctrl+Shift+Up and Cmd/Ctrl+Shift+Down.

## Single shape helpers

When you need to work with exactly one selected shape, use [`Editor.getOnlySelectedShapeId`](/reference/editor/Editor#getOnlySelectedShapeId) and [`Editor.getOnlySelectedShape`](/reference/editor/Editor#getOnlySelectedShape):

```typescript
// Get the ID if exactly one shape is selected, null otherwise
const id = editor.getOnlySelectedShapeId()

// Get the shape if exactly one shape is selected, null otherwise
const shape = editor.getOnlySelectedShape()
```

Both methods return `null` if zero shapes or multiple shapes are selected.

### Selected shape at point

To find which selected shape is at a specific point (useful for hit testing during interactions), use [`Editor.getSelectedShapeAtPoint`](/reference/editor/Editor#getSelectedShapeAtPoint):

```typescript
const shape = editor.getSelectedShapeAtPoint({ x: 100, y: 200 })
```

This returns the top-most selected shape at the given point, ignoring groups. It returns `undefined` if no selected shape is at that point.

## Selection bounds

The editor computes bounds for the current selection in two ways: axis-aligned and rotated.

### Axis-aligned bounds

[`Editor.getSelectionPageBounds`](/reference/editor/Editor#getSelectionPageBounds) returns the axis-aligned bounding box that contains all selected shapes:

```typescript
const bounds = editor.getSelectionPageBounds()
if (bounds) {
	console.log(bounds.x, bounds.y, bounds.width, bounds.height)
}
```

If the selection includes rotated shapes, these bounds represent the smallest axis-aligned box that contains the rotated shapes. The method returns `null` if nothing is selected.

### Rotated bounds

[`Editor.getSelectionRotatedPageBounds`](/reference/editor/Editor#getSelectionRotatedPageBounds) returns bounds that respect the shared rotation of the selection:

```typescript
const rotatedBounds = editor.getSelectionRotatedPageBounds()
```

The selection box UI uses this for display. If all selected shapes share the same rotation, the bounds rotate with them. If shapes have different rotations, this falls back to axis-aligned bounds. It returns `undefined` if nothing is selected.

You can access the shared rotation angle via [`Editor.getSelectionRotation`](/reference/editor/Editor#getSelectionRotation), which returns `0` if shapes have different rotations.

### Screen space bounds

Both bound types have screen-space equivalents, [`Editor.getSelectionScreenBounds`](/reference/editor/Editor#getSelectionScreenBounds) and [`Editor.getSelectionRotatedScreenBounds`](/reference/editor/Editor#getSelectionRotatedScreenBounds), that account for the camera's zoom and pan:

```typescript
const screenBounds = editor.getSelectionScreenBounds()
const rotatedScreenBounds = editor.getSelectionRotatedScreenBounds()
```

## Selection rules

The editor automatically enforces selection consistency through store side effects.

### Ancestor-descendant filtering

When the selection changes, the editor filters out any shape whose ancestor is also selected:

```typescript
// If you try to select a shape and its parent, only the parent remains selected
editor.select(groupId, childOfGroupId)
// Result: only groupId is selected
```

This prevents ambiguous situations where both a container and its contents are selected. The filtering happens in the `instance_page_state` after-change side effect.

### Focused group management

When you select shapes that are children of a group, the editor automatically updates the focused group. The focused group is the group that defines the current editing scope: while a group is focused, clicks select shapes inside it rather than the group itself. See [Groups](/sdk-features/groups) for details.

```typescript
// Selecting shapes inside a group focuses that group
editor.select(shapeInsideGroup)
// The group becomes the focused group
```

If all selected shapes share a common group ancestor, that group becomes focused. If you select shapes without a common group ancestor, the editor clears the focused group. Clearing the selection leaves the focused group in place.

## Locked shapes

The editor excludes locked shapes from bulk selection operations:

```typescript
// selectAll only selects unlocked shapes
editor.selectAll()

// Operations like delete and duplicate also respect locks
editor.deleteShapes(shapeIds) // Only deletes unlocked shapes
```

Locks don't restrict individual shape selection through `select()`. You can still select locked shapes explicitly when needed. By default, users can't select locked shapes by clicking or brushing; the `selectLockedShapes` option in [`TldrawOptions`](/reference/editor/TldrawOptions) allows that while keeping the shapes protected from edits. See [Locked shapes](/sdk-features/locked-shapes).

## Ancestor checking

To determine if a shape's ancestor is selected, use [`Editor.isAncestorSelected`](/reference/editor/Editor#isAncestorSelected):

```typescript
const hasSelectedAncestor = editor.isAncestorSelected(shape)
```

This walks up the shape's parent chain and returns `true` if any ancestor is in the current selection.

## Related examples

- [Selection UI](/examples/ui/selection-ui) - Add custom UI elements that appear around the current selection using selection bounds.
- [Prevent multi-shape selection](/examples/events/prevent-multi-shape-selection) - Use side effects to restrict selection to a single shape at a time.
- [Lasso select tool](/examples/editor-api/lasso-select-tool) - Create a custom freehand selection tool.

--------

# Shape clipping

Shape clipping lets parent shapes mask their children so content outside the parent's boundary is hidden. Frames are the primary example: drop shapes into a frame and they're cropped to the frame's edges. Custom shapes can define their own clip boundaries using any polygon. For the wider shape system, see [Shapes](/sdk-features/shapes).

## How clipping works

The clipping system uses two [`ShapeUtil`](/reference/editor/ShapeUtil) methods that work together: [`ShapeUtil.getClipPath`](/reference/editor/ShapeUtil#getClipPath) defines the clipping boundary as an array of points, and [`ShapeUtil.shouldClipChild`](/reference/editor/ShapeUtil#shouldClipChild) controls which children get clipped. `shouldClipChild` is only consulted when `getClipPath` returns a polygon.

When a shape is a child of a clipping parent, the editor:

1. Gets the parent's clip path from `getClipPath`
2. Checks if this child should be clipped via `shouldClipChild`
3. Transforms the clip path to page coordinates
4. Applies it as a CSS clip-path during rendering

If a shape has multiple clipping ancestors, their clip paths are intersected. A shape nested inside two clipping parents is clipped by both, so only the overlapping region shows.

## Implementing clipping

To make a custom shape clip its children, implement `getClipPath` in your ShapeUtil:

```tsx
import { Rectangle2d, ShapeUtil, SVGContainer, T, TLBaseShape, Vec } from 'tldraw'

type MyClipShape = TLBaseShape<'my-clip', { w: number; h: number }>

class MyClipShapeUtil extends ShapeUtil<MyClipShape> {
	static override type = 'my-clip' as const
	static override props = { w: T.number, h: T.number }

	override getDefaultProps() {
		return { w: 200, h: 200 }
	}

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

	override component(shape: MyClipShape) {
		return (
			<SVGContainer>
				<rect width={shape.props.w} height={shape.props.h} fill="transparent" stroke="black" />
			</SVGContainer>
		)
	}

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

	override getClipPath(shape: MyClipShape): Vec[] | undefined {
		// Return polygon vertices in local coordinates
		return [
			new Vec(0, 0),
			new Vec(shape.props.w, 0),
			new Vec(shape.props.w, shape.props.h),
			new Vec(0, shape.props.h),
		]
	}

	override canReceiveNewChildrenOfType() {
		return true
	}
}
```

The returned points define a polygon in the shape's local coordinate space. The editor transforms these points to page space before applying the clip. Return `undefined` to disable clipping entirely.

> If your clipping shape has a stroke, inset the clip path by half the stroke width so children are clipped to the inner edge of the stroke rather than its center line. Otherwise children overlap the stroke.

### Selective clipping

By default, all children of a clipping parent are clipped. Override [`ShapeUtil.shouldClipChild`](/reference/editor/ShapeUtil#shouldClipChild) to change this:

```typescript
override shouldClipChild(child: TLShape): boolean {
	// Don't clip text shapes
	if (child.type === 'text') return false
	return true
}
```

You might clip geometric shapes but let labels extend beyond the edge.

## Frame clipping

Frames are the primary built-in example of clipping. [`FrameShapeUtil`](/reference/tldraw/FrameShapeUtil) extends [`BaseFrameLikeShapeUtil`](/reference/editor/BaseFrameLikeShapeUtil), which implements clipping by returning its geometry vertices and skips clipping for arrows:

```typescript
override getClipPath(shape: Shape): Vec[] | undefined {
	return this.editor.getShapeGeometry(shape.id).vertices
}

override shouldClipChild(child: TLShape): boolean {
	return child.type !== 'arrow'
}
```

This clips to the frame's rectangular boundary. Content that extends beyond the frame's edges is hidden during rendering but still exists in the document; move the shapes out of the frame (or remove the frame) to see the clipped portions. If you're building your own container shape, extend `BaseFrameLikeShapeUtil` to get this behavior along with drag-and-drop reparenting and the other frame-like defaults.

## Reading shape masks

The editor computes and caches a mask for any clipped shape. Use these methods to read it:

| Method                               | Returns                  | Description                                    |
| ------------------------------------ | ------------------------ | ---------------------------------------------- |
| [`Editor.getShapeMask`](/reference/editor/Editor#getShapeMask)             | `VecLike[] \| undefined` | Mask polygon in page coordinates               |
| [`Editor.getShapeClipPath`](/reference/editor/Editor#getShapeClipPath)         | `string \| undefined`    | CSS `polygon(...)` string in local coordinates |
| [`Editor.getShapeMaskedPageBounds`](/reference/editor/Editor#getShapeMaskedPageBounds) | `Box \| undefined`       | Page bounds intersected with the mask          |

```typescript
const mask = editor.getShapeMask(shapeId)
// Returns array of points in page space, or undefined if not clipped

const clipPath = editor.getShapeClipPath(shapeId)
// Returns a "polygon(...)" CSS string, or undefined

const clippedBounds = editor.getShapeMaskedPageBounds(shapeId)
// Returns the shape's page bounds intersected with its mask
```

When a shape is fully clipped (the mask is empty), `getShapeMask` returns an empty array and `getShapeClipPath` returns a degenerate `polygon(0px 0px, 0px 0px, 0px 0px)`.

## Non-rectangular clip paths

Clip paths can be any polygon. For a circular clip, approximate the circle with polygon segments:

```typescript
override getClipPath(shape: CircleShape): Vec[] | undefined {
	const centerX = shape.props.w / 2
	const centerY = shape.props.h / 2
	const radius = Math.min(shape.props.w, shape.props.h) / 2
	const segments = 48

	const points: Vec[] = []
	for (let i = 0; i < segments; i++) {
		const angle = (i / segments) * Math.PI * 2
		points.push(
			new Vec(
				centerX + Math.cos(angle) * radius,
				centerY + Math.sin(angle) * radius
			)
		)
	}
	return points
}
```

More segments create smoother curves. Clip paths are cached and only recomputed when the shape changes, so the cost is minimal.

## Backgrounds and clipping

Shapes that clip typically also provide a background for their children. `BaseFrameLikeShapeUtil` does this by returning `true` from `providesBackgroundForChildren`, which makes child shapes' background layers (their `backgroundComponent`) render above the container rather than above the canvas background. Both methods are internal APIs; extend `BaseFrameLikeShapeUtil` rather than overriding them yourself.

## Clipping and hit testing

Clipping affects more than rendering. [`Editor.getShapeAtPoint`](/reference/editor/Editor#getShapeAtPoint) and [`Editor.isPointInShape`](/reference/editor/Editor#isPointInShape) reject points that fall outside the shape's mask, so you can't select a clipped shape by clicking its hidden portions. Brush selection, scribble selection, erasing, arrow binding, SVG export bounds, and the minimap also use the mask.

Snapping and [`Editor.getShapePageBounds`](/reference/editor/Editor#getShapePageBounds) use the shape's full geometry, so a clipped shape's bounds may extend beyond what's visible. Use [`Editor.getShapeMaskedPageBounds`](/reference/editor/Editor#getShapeMaskedPageBounds) when you need the visible bounds.

For an example of custom clipping shapes, see the [custom clipping shape example](/examples/editor-api/custom-clipping-shape).

--------

# Shape indexing

Every shape in tldraw has an `index` property that determines its visual stacking order (z-order) on the canvas. Shapes with higher index values appear in front of shapes with lower values. The index system uses string-based fractional indexing, which allows efficient reordering and supports real-time collaboration.

## Why fractional indexing?

Integer indices don't leave room to insert. If you have shapes at indices `[0, 1, 2]` and want to insert between 0 and 1, you'd need to renumber subsequent shapes or use floats that eventually lose precision.

Fractional indexing uses lexicographically sortable strings. You can always generate a new index between any two existing indices. Standard JavaScript string comparison sorts them correctly, and reordering only updates the moved shapes, not every shape on the canvas.

## Index structure

Indices are strings like `'a1'`, `'a2'`, or `'a1V'`. The leading letter says how many characters make up the integer part (`a` means two characters, `b` means three, and so on), and anything after that is the fractional part for inserting between existing indices. Digits are base-62. The `@tldraw/utils` package uses a vendored copy of the [jittered fractional indexing](https://www.npmjs.com/package/jittered-fractional-indexing) algorithm to generate these strings.

## Generating indices

The `@tldraw/utils` package exports functions for generating indices:

```ts
import {
	getIndexBetween,
	getIndexAbove,
	getIndexBelow,
	getIndicesAbove,
	getIndicesBelow,
	getIndicesBetween,
	sortByIndex,
	IndexKey,
} from '@tldraw/utils'

// Generate a single index between two existing indices
const between = getIndexBetween('a1' as IndexKey, 'a3' as IndexKey) // e.g. 'a2'

// Generate indices above or below an existing index
const above = getIndexAbove('a1' as IndexKey) // e.g. 'a2'
const below = getIndexBelow('a2' as IndexKey) // e.g. 'a1'

// Generate multiple indices at once
const multipleAbove = getIndicesAbove('a0' as IndexKey, 3)
const multipleBelow = getIndicesBelow('a2' as IndexKey, 2)
const multipleBetween = getIndicesBetween('a0' as IndexKey, 'a2' as IndexKey, 2)

// Sort objects by their index property
const shapes = [{ index: 'a2' as IndexKey }, { index: 'a1' as IndexKey }]
shapes.sort(sortByIndex) // [{ index: 'a1' }, { index: 'a2' }]
```

The algorithm jitters (randomizes) the generated keys, so the exact values above vary between calls. This reduces conflicts in collaborative environments: when two users insert shapes at the same position simultaneously, they generate different indices instead of identical ones, and both operations merge cleanly. Jittering is disabled when `NODE_ENV` is `test` so tests are deterministic.

`getIndices(n, start?)` returns the starting index (default `'a1'`) followed by `n` indices above it. `ZERO_INDEX_KEY` is the first index, `'a0'`. To find the next free index in a parent, use [`Editor.getHighestIndexForParent`](/reference/editor/Editor#getHighestIndexForParent) with `getIndexAbove`.

## Reordering shapes

The [`Editor`](/reference/editor/Editor) provides four methods for changing shape z-order. You can pass either shape IDs or shape objects to any of these methods.

### Send to back and bring to front

```ts
// Move shapes to the very back or front
editor.sendToBack(['shape:abc123' as TLShapeId, 'shape:def456' as TLShapeId])
editor.bringToFront(['shape:abc123' as TLShapeId])
```

These move shapes to the bottom or top of the z-order within their parent.

### Send backward and bring forward

```ts
// Move shapes one step back or forward
editor.sendBackward(['shape:abc123' as TLShapeId])
editor.bringForward(['shape:abc123' as TLShapeId])
```

By default, these methods only move shapes past other shapes whose page bounds overlap theirs. This makes keyboard shortcuts feel intuitive: pressing "send backward" moves a shape behind the shape it's actually covering, not behind some distant shape.

To move past any shape regardless of overlap:

```ts
editor.sendBackward(['shape:abc123' as TLShapeId], { considerAllShapes: true })
```

### Order preservation

All reordering methods preserve relative order. If you select shapes A, B, and C (stacked A-B-C from back to front) and bring them forward, they stay in A-B-C order at their new position.

## How reordering works internally

Shape indices are always relative to siblings within the same parent. When you reorder shapes, tldraw:

1. Groups shapes by parent
2. Finds the insertion point (front, back, or adjacent to an overlapping shape)
3. Generates new indices using `getIndicesBetween`
4. Updates only the shapes that actually need new indices

If shapes are already at the target position, no updates occur.

If you need full control over ordering (for example in a layer panel), set a shape's `index` directly with [`Editor.updateShapes`](/reference/editor/Editor#updateShapes).

## Index validation

`IndexKey` is a branded type, so you can't accidentally pass an arbitrary string as an index. To validate a string at runtime, use the `indexKey` validator from `@tldraw/validate`:

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

T.indexKey.validate('a1') // returns 'a1' as IndexKey
T.indexKey.validate('invalid!') // throws a ValidationError
```

The store validates indices when you create or update shapes, so the editor won't enter an invalid state.

## Related examples

- [Layer panel](/examples/ui/layer-panel) - Shows shape hierarchy and z-order in a custom panel

--------

# Shape transforms

Shape transforms are operations that manipulate multiple shapes together: grouping, aligning, distributing, stacking, packing, stretching, flipping, and rotating. Each operation has a dedicated method on the [`Editor`](/reference/editor/Editor) class.

All transform operations respect the editor's parent-child coordinate system and work with shapes that have different parents or rotations. Shapes connected by arrow bindings move together as clusters.

## Transform operations

Transform methods take an array of shape IDs or shape objects; pass `editor.getSelectedShapeIds()` to operate on the selection. All of them are no-ops when the editor is read-only. Grouping changes the shape hierarchy. The spatial operations reposition shapes without changing their parent relationships.

### Grouping and ungrouping

[`Editor.groupShapes`](/reference/editor/Editor#groupShapes) creates a new group shape that becomes the parent of the given shapes. The editor finds the shapes' common ancestor and creates the group there. The grouped shapes keep their visual positions on the page, but their coordinates become relative to the group.

```typescript
editor.groupShapes([shape1, shape2, shape3])
editor.groupShapes([shape1, shape2], { groupId: myGroupId, select: false })
editor.ungroupShapes([groupShape])
```

`groupShapes` only runs while the select tool is active, and it cancels any in-progress select interaction first. It needs at least two shapes.

[`Editor.ungroupShapes`](/reference/editor/Editor#ungroupShapes) reverses this: it moves the group's children back to the group's parent and deletes the group shape. The shapes keep their page positions but return to their original parent's coordinate space.

### Alignment

[`Editor.alignShapes`](/reference/editor/Editor#alignShapes) moves shapes so they share a common edge or center line. The six single-axis operations are `left`, `right`, `top`, `bottom`, `center-horizontal`, and `center-vertical`. Use `center` to align shapes by both their horizontal and vertical centers in one call.

When aligning shapes, the editor first calculates the common bounding box of all selected shapes. It then moves each shape to the appropriate edge or center of that common box.

```typescript
editor.alignShapes(editor.getSelectedShapeIds(), 'left')
editor.alignShapes([box1, box2], 'center-vertical')
editor.alignShapes([box1, box2], 'center')
```

Selected shapes connected by arrow bindings move together as a cluster during alignment. If shapes A and B are connected by an arrow and you align them with shape C, A and B move together as a single unit.

### Distribution

[`Editor.distributeShapes`](/reference/editor/Editor#distributeShapes) spaces shapes evenly between the outermost shapes in a selection. The editor identifies the first and last shapes based on their positions, then calculates the gap needed to distribute the remaining shapes evenly in the space between them. This can create negative gaps if shapes overlap.

```typescript
editor.distributeShapes(editor.getSelectedShapeIds(), 'horizontal')
editor.distributeShapes([box1, box2, box3], 'vertical')
```

Distribution requires at least three shape clusters. Like alignment, shapes connected by arrows form clusters that move together, so the actual number of moveable units may be less than the number of selected shapes.

### Stacking

[`Editor.stackShapes`](/reference/editor/Editor#stackShapes) arranges shapes in a sequence with consistent gaps between them. Unlike distribution, which spaces shapes within a fixed range, stacking positions each shape relative to the previous one with a specified gap.

```typescript
editor.stackShapes(editor.getSelectedShapeIds(), 'horizontal', 16)
editor.stackShapes([box1, box2, box3], 'vertical')
```

If you don't pass a gap, the editor uses its `adjacentShapeMargin` [option](/sdk-features/options). Pass a gap of `0` for automatic gap detection: the editor measures the current spacing between shapes and uses the most common gap, or the average gap if no pattern exists. Automatic detection needs at least three clusters; with fewer, the call does nothing.

### Packing

[`Editor.packShapes`](/reference/editor/Editor#packShapes) arranges shapes into a compact grid using a bin-packing algorithm based on [potpack](https://github.com/mapbox/potpack). Shapes connected by arrows form clusters, and all clusters are packed into a single grid centered on the shapes' original center point, so shapes move as little as possible.

```typescript
editor.packShapes(editor.getSelectedShapeIds(), 8)
editor.packShapes([box1, box2, box3, box4])
```

The gap parameter controls the padding between packed shapes and defaults to the editor's `adjacentShapeMargin` option.

### Flipping

[`Editor.flipShapes`](/reference/editor/Editor#flipShapes) mirrors shapes along the horizontal or vertical axis. The flip origin is the center of the shapes' common bounding box. Each shape is scaled by -1 on that axis, which inverts its position and appearance while keeping its size.

```typescript
editor.flipShapes(editor.getSelectedShapeIds(), 'horizontal')
editor.flipShapes([box1, box2], 'vertical')
```

When flipping groups, the editor includes all children of the group so the whole hierarchy flips together. Shapes can opt out of flipping by returning `false` from [`ShapeUtil.canBeLaidOut`](/reference/editor/ShapeUtil#canBeLaidOut); arrows do this when the shape they're bound to isn't part of the flip.

### Rotation

[`Editor.rotateShapesBy`](/reference/editor/Editor#rotateShapesBy) rotates shapes by a delta in radians around a common center point. The editor calculates the center of all the shapes' rotated bounds, then rotates each shape around that point and around its own origin: shapes orbit the selection center while also rotating individually. Pass `{ center }` to rotate around a different point.

```typescript
editor.rotateShapesBy(editor.getSelectedShapeIds(), Math.PI / 4)
editor.rotateShapesBy([box1, box2], Math.PI / 2, { center: { x: 0, y: 0 } })
```

Shape utils can respond to rotation through [`ShapeUtil.onRotateStart`](/reference/editor/ShapeUtil#onRotateStart), [`ShapeUtil.onRotate`](/reference/editor/ShapeUtil#onRotate), and [`ShapeUtil.onRotateEnd`](/reference/editor/ShapeUtil#onRotateEnd). For a one-off `rotateShapesBy` call, all three fire in sequence; during an interactive rotate, `onRotate` fires on every update.

### Stretching

[`Editor.stretchShapes`](/reference/editor/Editor#stretchShapes) resizes shapes to fill their common bounding box along one axis. Only shapes whose page rotation is a multiple of 90 degrees participate.

```typescript
editor.stretchShapes(editor.getSelectedShapeIds(), 'horizontal')
```

## Parent coordinate transforms

Align, distribute, stack, and pack calculate movement in page space but apply it in each shape's parent space. When a shape's parent is rotated, the editor rotates the page-space delta by the negative of the parent's rotation (from [`Editor.getShapeParentTransform`](/reference/editor/Editor#getShapeParentTransform)) before updating the shape's `x` and `y`. Moving a child shape produces the correct visual result regardless of parent rotation or nesting depth. See [Coordinates](/sdk-features/coordinates).

## Shape clustering via arrow bindings

Align, distribute, stack, and pack group shapes into clusters based on arrow bindings. Starting from each shape, the editor follows arrow bindings recursively and collects every connected shape that is also in the input list. If A connects to B via an arrow but only A is passed in, B is not included.

Each cluster is treated as a single unit with a common bounding box. When the transform calculates movement for the cluster, it applies that movement to every shape in the cluster, so their relative positions and arrow relationships stay intact.

## Opting out with canBeLaidOut

Shape utils control whether their shapes participate in transforms through [`ShapeUtil.canBeLaidOut`](/reference/editor/ShapeUtil#canBeLaidOut). It receives the transform type and the full list of shapes being transformed, so the util can decide based on context.

```typescript
canBeLaidOut(shape: MyShape, info: TLShapeUtilCanBeLaidOutOpts): boolean {
	// info.type is one of: 'align' | 'distribute' | 'pack' | 'stack' | 'flip' | 'stretch' | 'resize_to_bounds'
	return true
}
```

## Related examples

- **[Keyboard shortcuts](/examples/ui/keyboard-shortcuts)** - Customize shortcuts for align, distribute, and other transform operations.
- **[Selection UI](/examples/ui/selection-ui)** - Build custom controls that can trigger transform operations on selected shapes.

--------

# Shapes

In tldraw, a shape is something that can exist on the page: a rectangle, an arrow, a text box, a freehand stroke. Each shape is a record in the store, and each shape type has a [`ShapeUtil`](/reference/editor/ShapeUtil) class that defines how it renders, responds to interaction, and computes its [geometry](/sdk-features/geometry).

Shapes can be parented to other shapes (see [Parent-child relationships](#Parent-child-relationships)), are stacked by [index](/sdk-features/shape-indexing), and can be related to other shapes through [bindings](/sdk-features/bindings). This article covers the shape system; for a tutorial on writing your own shape, see [Shapes](/docs/shapes).

## Shape records

A shape record is a plain object stored in the editor's reactive store. All shape types extend `TLBaseShape`, which defines the common properties every shape has: a unique identifier, position and rotation, z-ordering index, parent reference, lock state, opacity, and a `props` field for shape-specific properties. The `props` field contains data unique to each shape type. A geo shape stores its width, height, and geometry type. A text shape stores its text content and font size. Each shape type defines its own props structure.

Shapes also have a `meta` field for your own application data, which tldraw stores but doesn't use itself. See [Meta](/docs/shapes#Meta) for how to set, type, and validate it.

### Shape types in tldraw

The default tldraw installation includes these shape types:

| Category   | Types                                 |
| ---------- | ------------------------------------- |
| Basic      | `geo`, `text`, `note`                 |
| Drawing    | `draw`, `line`, `highlight`           |
| Media      | `image`, `video`, `bookmark`, `embed` |
| Structural | `frame`, `group`                      |
| Connectors | `arrow`                               |

Each type has a corresponding ShapeUtil that implements its behavior.

### Creating and accessing shapes

The editor has methods for each step of a shape's life:

| Method                           | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| [`Editor.createShape`](/reference/editor/Editor#createShape)          | Create a shape from a partial (type, position, props). |
| [`Editor.getShape`](/reference/editor/Editor#getShape)             | Get a shape by ID.                                     |
| [`Editor.getCurrentPageShapes`](/reference/editor/Editor#getCurrentPageShapes) | Get all shapes on the current page.                    |
| [`Editor.updateShape`](/reference/editor/Editor#updateShape)          | Apply a partial update to an existing shape.           |
| [`Editor.deleteShape`](/reference/editor/Editor#deleteShape)          | Delete a shape and its descendants.                    |

```typescript
import { createShapeId, Editor } from 'tldraw'

function addRectangle(editor: Editor) {
	const id = createShapeId()

	editor.createShape({
		id,
		type: 'geo',
		x: 100,
		y: 100,
		props: { w: 200, h: 150, geo: 'rectangle' },
	})

	const shape = editor.getShape(id)!

	// Move it to the right
	editor.updateShape({ id: shape.id, type: shape.type, x: 200 })
}
```

Shapes are immutable records. When you update a shape, the editor creates a new record with the changes and stores it in place of the old one.

## ShapeUtil

A ShapeUtil class defines how a shape type behaves. The editor maintains one ShapeUtil instance per shape type, and uses it for all shapes of that type. ShapeUtil is an abstract class with required and optional methods that control rendering, geometry, and interaction.

### Required methods

Every ShapeUtil must implement four methods:

| Method                          | Description                                                          |
| ------------------------------- | -------------------------------------------------------------------- |
| [`ShapeUtil.getDefaultProps`](/reference/editor/ShapeUtil#getDefaultProps)  | Default props for new shapes.                                        |
| [`ShapeUtil.getGeometry`](/reference/editor/ShapeUtil#getGeometry)      | The shape's [`Geometry2d`](/reference/editor/Geometry2d), used for hit testing and bounds.        |
| [`ShapeUtil.component`](/reference/editor/ShapeUtil#component)        | A React component that renders the shape.                            |
| [`ShapeUtil.getIndicatorPath`](/reference/editor/ShapeUtil#getIndicatorPath) | A `Path2D` for the selection outline, or `undefined` for no outline. |

```tsx
import { Geometry2d, HTMLContainer, Rectangle2d, ShapeUtil, T, TLBaseShape } from 'tldraw'

type MyShape = TLBaseShape<'my-shape', { w: number; h: number }>

class MyShapeUtil extends ShapeUtil<MyShape> {
	static override type = 'my-shape' as const
	static override props = { w: T.number, h: T.number }

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

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

	component(shape: MyShape) {
		return <HTMLContainer style={{ width: shape.props.w, height: shape.props.h }} />
	}

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

Wrap your rendered content in [`HTMLContainer`](/reference/editor/HTMLContainer) or [`SVGContainer`](/reference/editor/SVGContainer) so it's positioned correctly on the canvas. `getIndicatorPath` can also return a [`TLIndicatorPath`](/reference/editor/TLIndicatorPath) object with a `clipPath` and `additionalPaths` for shapes like arrows with labels.

### Capability methods

ShapeUtils override capability methods to declare what interactions the shape supports. These return booleans: [`ShapeUtil.canEdit`](/reference/editor/ShapeUtil#canEdit), [`ShapeUtil.canResize`](/reference/editor/ShapeUtil#canResize), [`ShapeUtil.canCrop`](/reference/editor/ShapeUtil#canCrop), [`ShapeUtil.canScroll`](/reference/editor/ShapeUtil#canScroll), [`ShapeUtil.canBind`](/reference/editor/ShapeUtil#canBind), and so on. [`ShapeUtil.canReceiveNewChildrenOfType`](/reference/editor/ShapeUtil#canReceiveNewChildrenOfType) controls whether the shape can accept other shapes as children, and [`ShapeUtil.canRemoveChildrenOfType`](/reference/editor/ShapeUtil#canRemoveChildrenOfType) controls whether children can be dragged back out.

### Lifecycle hooks

ShapeUtils respond to shape changes through lifecycle hooks. [`ShapeUtil.onBeforeCreate`](/reference/editor/ShapeUtil#onBeforeCreate) and [`ShapeUtil.onBeforeUpdate`](/reference/editor/ShapeUtil#onBeforeUpdate) intercept shape creation and updates before they reach the store, so you can modify the shape. [`ShapeUtil.onResize`](/reference/editor/ShapeUtil#onResize), [`ShapeUtil.onRotate`](/reference/editor/ShapeUtil#onRotate), and [`ShapeUtil.onTranslate`](/reference/editor/ShapeUtil#onTranslate) (with their `Start`/`End` variants) respond to transformations. [`ShapeUtil.onChildrenChange`](/reference/editor/ShapeUtil#onChildrenChange) responds to changes in a shape's children. Interaction hooks like [`ShapeUtil.onDoubleClick`](/reference/editor/ShapeUtil#onDoubleClick), [`ShapeUtil.onDragShapesOver`](/reference/editor/ShapeUtil#onDragShapesOver), and [`ShapeUtil.onDropShapesOver`](/reference/editor/ShapeUtil#onDropShapesOver) handle user interactions.

`onResize` receives a [`TLResizeInfo`](/reference/editor/TLResizeInfo) with the scale factors and the handle being dragged. It returns a partial containing just the props you want to change (without `id` or `type`):

```typescript
onResize(shape: MyShape, info: TLResizeInfo<MyShape>) {
	return {
		props: {
			w: shape.props.w * info.scaleX,
			h: shape.props.h * info.scaleY,
		},
	}
}
```

### Static properties

ShapeUtil classes use static properties for type registration and schema configuration:

```typescript
const versions = createShapePropsMigrationIds('my-shape', {
	AddColor: 1,
})

class MyShapeUtil extends ShapeUtil<MyShape> {
	static override type = 'my-shape' as const

	// Define props validators (including style props)
	static override props = {
		w: T.number,
		h: T.number,
		color: DefaultColorStyle, // StyleProp instances are recognized automatically
	}

	// Define migrations for schema evolution
	static override migrations = createShapePropsMigrationSequence({
		sequence: [
			{
				id: versions.AddColor,
				up(props) {
					props.color = 'black'
				},
				down(props) {
					delete props.color
				},
			},
		],
	})
}
```

See [Persistence](/sdk-features/persistence) for more on migrations.

### Configuring built-in shapes

Use [`ShapeUtil.configure`](/reference/editor/ShapeUtil#configure) to customize the options of built-in shape utilities without subclassing them:

```typescript
import { FrameShapeUtil, NoteShapeUtil, Tldraw } from 'tldraw'

const shapeUtils = [
	// Enable colors for frame shapes
	FrameShapeUtil.configure({ showColors: true }),

	// Enable resizing for note shapes
	NoteShapeUtil.configure({ resizeMode: 'scale' }),
]

function App() {
	return <Tldraw shapeUtils={shapeUtils} />
}
```

Each shape util declares its own `options` object, and `configure` returns a new class with your overrides merged in. Custom shape utils can declare their own options the same way.

### Registering ShapeUtils

Register custom ShapeUtils by passing them to the `shapeUtils` prop of the [`Tldraw`](/reference/tldraw/Tldraw) component. The editor creates one instance of each ShapeUtil and uses it for all shapes of that type.

## Geometry

Every ShapeUtil returns a [`Geometry2d`](/reference/editor/Geometry2d) from `getGeometry`. The editor uses it for hit testing, bounds, snapping, and collision detection. Geometry classes cover rectangles, circles, ellipses, polygons, polylines, arcs, and composites ([`Group2d`](/reference/editor/Group2d)). The editor caches each shape's geometry and page bounds; read them with [`Editor.getShapeGeometry`](/reference/editor/Editor#getShapeGeometry) and [`Editor.getShapePageBounds`](/reference/editor/Editor#getShapePageBounds). See [Geometry](/sdk-features/geometry) for the full system.

## Shape rendering

The editor renders shapes through a React component hierarchy. Each shape is wrapped in a container that handles positioning, transforms, and culling. When a shape renders, the editor:

1. computes the shape's page transform by combining its local position and rotation with all ancestor transforms
2. skips rendering if the shape is outside the viewport and its ShapeUtil allows culling
3. renders the shape's content through the ShapeUtil's `component` method
4. if the shape is selected, strokes the selection outline from `getIndicatorPath` on the canvas overlay

### Transform composition

Shapes are positioned relative to their parent's coordinate space. Get the transform from shape space to page space with [`Editor.getShapePageTransform`](/reference/editor/Editor#getShapePageTransform), the local transform with [`Editor.getShapeLocalTransform`](/reference/editor/Editor#getShapeLocalTransform), and convert a page point to shape-local coordinates with [`Editor.getPointInShapeSpace`](/reference/editor/Editor#getPointInShapeSpace). See [Coordinates](/sdk-features/coordinates) for the coordinate spaces.

### Opacity

Shape opacity multiplies with parent opacity. A shape at 50% opacity inside a frame at 50% opacity renders at 25% opacity. Access a shape's opacity directly from the shape record via `shape.opacity`. The editor computes the final rendered opacity by combining the shape's opacity with all ancestor opacities.

## Shape lifecycle

Shapes go through creation, updates, and deletion. The editor provides hooks and events at each stage.

### Creation flow

When you call `createShape`, the editor assigns an ID if none is provided, determines the parent (explicit `parentId`, otherwise a container shape under the given position, otherwise the focused group or current page), calculates the fractional index for z-ordering, calls `ShapeUtil.onBeforeCreate` for any modifications, validates the shape against the schema, and puts it in the store.

### Update flow

When you call `updateShape`, the editor skips the update if the shape or an ancestor is locked (unless the update unlocks it), merges the partial with the existing shape, calls `ShapeUtil.onBeforeUpdate` for any modifications, validates and stores the updated shape, and emits update events.

### Deletion flow

When you call `deleteShape`, the editor collects all descendant shapes and removes them from the store. Deleting a frame or group deletes all its children. Store side effects clean up bindings that involve the deleted shapes; the binding utils receive `onBeforeIsolate*` and `onBeforeDelete*` callbacks so connected shapes like arrows can update. See [Bindings](/sdk-features/bindings).

## Parent-child relationships

Shapes can be parented to pages or other shapes. This creates a hierarchy used for grouping, frames, and coordinate transforms.

### Frames

Frames are container shapes that clip their children and provide a visual boundary. Shapes inside a frame position relative to the frame's origin. Moving the frame moves all its children. The frame clips content at its boundaries during rendering. See [Shape clipping](/sdk-features/shape-clipping) for details on implementing custom clipping shapes.

To build your own container shape that behaves like a frame, extend `BaseFrameLikeShapeUtil` instead of `ShapeUtil` directly. It provides defaults for the full set of frame behaviors (clipping children, full-brush selection, blocking erasure from inside, drag-and-drop reparenting, providing a background for children) and any of them can be overridden. Custom shapes that don't extend the base class can still opt into the same behavior by overriding the `isFrameLike()` capability method to return `true`. See the [portal shapes example](/examples/shapes/tools/portal-shapes) for a custom shape that behaves like a frame and teleports its children between instances.

### Groups

Groups are logical containers without visual representation. Group shapes with [`Editor.groupShapes`](/reference/editor/Editor#groupShapes) and ungroup with [`Editor.ungroupShapes`](/reference/editor/Editor#ungroupShapes). A group's geometry is the union of its children's geometry. When a group is left with fewer than two children, it removes itself: an empty group is deleted, and a group with one child reparents that child to the group's parent and then deletes itself. See [Groups](/sdk-features/groups).

### Focused groups

The editor tracks a focused group that defines the current editing scope. When you double-click a group, it becomes focused, and you can select and edit shapes inside it. Get the current focused group with [`Editor.getFocusedGroup`](/reference/editor/Editor#getFocusedGroup), focus a group with [`Editor.setFocusedGroup`](/reference/editor/Editor#setFocusedGroup), and exit it with [`Editor.popFocusedGroupId`](/reference/editor/Editor#popFocusedGroupId).

## Coordinate spaces

The editor works with four coordinate spaces: screen space (the browser viewport), page space (the canvas), parent space (a shape's parent), and local space (the shape itself). Convert between them with [`Editor.screenToPage`](/reference/editor/Editor#screenToPage), [`Editor.pageToScreen`](/reference/editor/Editor#pageToScreen), and [`Editor.getPointInShapeSpace`](/reference/editor/Editor#getPointInShapeSpace). See [Coordinates](/sdk-features/coordinates).

## Shape derivations

The editor maintains computed derivations that update automatically as shapes change.

### Parents to children index

Maps parent IDs to sorted arrays of child shape IDs. Updated incrementally as shapes are added, removed, or reparented. Get children of a shape or page, sorted by z-index, with [`Editor.getSortedChildIdsForParent`](/reference/editor/Editor#getSortedChildIdsForParent).

### Culled shapes

Tracks which shapes are outside the viewport. Shapes whose ShapeUtil returns `true` from [`ShapeUtil.canCull`](/reference/editor/ShapeUtil#canCull) are candidates for culling. Selected shapes and the shape being edited are never culled. Culled shapes stay in the DOM with `display: none`. Check whether a shape is culled with `editor.getCulledShapes().has(shapeId)`. See [Culling](/sdk-features/culling).

### Shape geometry cache

Caches each shape's geometry and page bounds, invalidating when the shape's props or meta change. See [Geometry](/sdk-features/geometry#Geometry-caching).

## Related examples

- **[Custom shape](/examples/shapes/tools/custom-shape)** - A minimal ShapeUtil.
- **[Editable custom shape](/examples/shapes/tools/editable-shape)** - A custom shape that enters the editing state on double-click.
- **[Clickable custom shape](/examples/shapes/tools/interactive-shape)** - A custom shape that responds to onClick.
- **[Custom shape geometry](/examples/shapes/tools/shape-with-geometry)** - A house-shaped custom shape with custom geometry.
- **[Custom shape with custom styles](/examples/shapes/tools/shape-with-custom-styles)** - Shows how to create your own styles and use them in custom shapes.
- **[Custom shape with tldraw styles](/examples/shapes/tools/shape-with-tldraw-styles)** - Use tldraw's default styles in your custom shapes.
- **[Custom shape migrations](/examples/shapes/tools/shape-with-migrations)** - Migrate shapes and their data between versions using the migrations system.
- **[Custom shape with handles](/examples/shapes/tools/speech-bubble)** - A speech bubble shape with custom handles for interaction.
- **[Shape options](/examples/configuration/configure-shape-util)** - Change the behavior of built-in shapes by setting their options via ShapeUtil.configure.
- **[Custom snapping](/examples/shapes/tools/bounds-snapping-shape)** - Custom shapes with special bounds snapping behavior, demonstrated with playing cards.
- **[Cubic bezier curve shape](/examples/shapes/tools/cubic-bezier-shape)** - A custom shape with interactive bezier curve editing using draggable control handles.
- **[Data grid shape](/examples/shapes/tools/ag-grid-shape)** - A custom shape that renders AG Grid.
- **[Popup shape](/examples/shapes/tools/popup-shape)** - Create a 3D illusion of depth with dynamic shadows and CSS transforms.
- **[Custom clipping shape](/examples/editor-api/custom-clipping-shape)** - Custom shapes that can clip their children with any polygon geometry.
- **[DOM-based shape size](/examples/shapes/tools/size-from-dom)** - A custom shape whose size is derived from its rendered DOM.

--------

# Side effects

Side effects are lifecycle hooks that run when records are created, updated, or deleted. You can use them to intercept and modify records, validate changes, or react to completed operations by updating related data.

The editor uses side effects internally to keep data consistent. When you delete a shape, the editor automatically removes its bindings. When a binding changes, its `BindingUtil` gets a chance to update the connected shapes. These hooks let independent parts of the system stay in sync without being directly coupled. Side effects live on the [store](/sdk-features/store) and are exposed as [`Editor.sideEffects`](/reference/editor/Editor#sideEffects), a [`StoreSideEffects`](/reference/store/StoreSideEffects) instance.

## How it works

### Before and after handlers

Side effects provide six handler types organized around three operations: create, change, and delete. Each operation has a "before" and "after" phase. Handlers are registered per record `typeName` (`'shape'`, `'binding'`, `'page'`, or a custom type); check `shape.type` inside the handler if you only care about one kind of shape.

| Handler        | Runs                       | Return value                                                                  |
| -------------- | -------------------------- | ----------------------------------------------------------------------------- |
| `beforeCreate` | Before a record is stored  | The record to store. Return a modified copy to change it.                     |
| `beforeChange` | Before an update is stored | The record to store. Return `prev` to block the change, or a modified `next`. |
| `beforeDelete` | Before a record is removed | `false` to prevent deletion.                                                  |
| `afterCreate`  | After a record is stored   | Nothing. Update other records in response.                                    |
| `afterChange`  | After an update is stored  | Nothing. Update other records in response.                                    |
| `afterDelete`  | After a record is removed  | Nothing. Clean up references or cascade deletions.                            |

Use before handlers to modify the record being operated on, and after handlers to update other records in response. Returning `prev` from `beforeChange` blocks the change because the store sees no difference from what's already stored and skips the write.

### Source tracking

Every handler receives a `source` parameter indicating whether the change came from user interaction (`'user'`) or remote synchronization (`'remote'`). This lets you handle local and synced changes differently:

```typescript
editor.sideEffects.registerAfterCreateHandler('shape', (shape, source) => {
	if (source === 'user') {
		logUserAction('created shape', shape.type)
	}
})
```

You might auto-save only after user operations, or skip validation for trusted remote data.

### Registration and cleanup

Register side effects using the type-specific methods on `editor.sideEffects`. Each method returns a cleanup function you can call to remove the handler:

```typescript
const cleanup = editor.sideEffects.registerAfterCreateHandler('shape', (shape, source) => {
	if (shape.type === 'note') {
		editor.updateShape({ id: shape.id, type: 'note', meta: { createdAt: Date.now() } })
	}
})

// Later, when no longer needed
cleanup()
```

To register several handlers at once, pass an object keyed by type name to `editor.sideEffects.register({ shape: { afterCreate, beforeDelete } })`; it returns a single cleanup function.

### Execution order

Handlers execute in registration order. If one handler reads a value another handler writes, register the writer first.

Before handlers run inline as each record is written. After handlers are queued and run when the outermost store operation completes, so changes made inside them belong to the same transaction and the same undo step. If an after handler makes further changes, their handlers run in a follow-up pass. The `operationComplete` handler runs once at the end, after every pass has finished.

## Use cases

### Constraining shape positions

Before handlers can enforce constraints on records. This example blocks moves into negative coordinates by returning the previous record:

```typescript
editor.sideEffects.registerBeforeChangeHandler('shape', (prev, next, source) => {
	if (next.x < 0 || next.y < 0) {
		return prev // Block the change by returning the previous record
	}
	return next
})
```

### Cascading deletions

You can cascade deletions to related records. This example deletes a frame when its last child is removed:

```typescript
editor.sideEffects.registerAfterDeleteHandler('shape', (shape, source) => {
	const parent = editor.getShape(shape.parentId)
	if (parent && parent.type === 'frame') {
		const siblings = editor.getSortedChildIdsForParent(parent.id)
		if (siblings.length === 0) {
			editor.deleteShape(parent.id)
		}
	}
})
```

### Batch processing with operationComplete

The `operationComplete` handler runs once after all changes in a transaction finish. Use it for expensive operations that should happen once per batch rather than on every record change:

```typescript
editor.sideEffects.registerOperationCompleteHandler((source) => {
	if (source === 'user') {
		scheduleAutosave()
	}
})
```

## Related examples

- [Before create/update shape](/examples/events/before-create-update-shape) - Constrain shapes to a circular area
- [Before delete shape](/examples/events/before-delete-shape) - Prevent deletion of certain shapes
- [After create/update shape](/examples/events/after-create-update-shape) - Ensure only one red shape exists at a time
- [After delete shape](/examples/events/after-delete-shape) - Delete empty frames automatically
- [Shape meta (on change)](/examples/events/meta-on-change) - Track modification history with a before-change handler

--------

# Signals

The tldraw SDK uses signals for state management. Signals automatically track dependencies: when state changes, only the parts of your application that depend on that state update.

The editor exposes many of its internal values as signals. Methods like `editor.getSelectedShapeIds()` and `editor.getCurrentPageShapes()` return reactive values that update automatically when the underlying state changes. The React bindings connect these signals to components. You don't need to manage subscriptions yourself.

The signals library lives in `@tldraw/state` and its React bindings in `@tldraw/state-react`. Both are re-exported from `tldraw`, so `import { atom, useValue, track } from 'tldraw'` also works.

## Core concepts

### Atoms

An atom holds a mutable value. When you change the value, any computeds or effects that depend on the atom will update.

```ts
import { atom } from '@tldraw/state'

const count = atom('count', 0)

count.get() // 0
count.set(5)
count.get() // 5

// Update based on current value
count.update((n) => n + 1)
count.get() // 6
```

The first argument is a name for debugging. The second is the initial value. Atoms accept an options object with `isEqual` (a custom equality function), `historyLength` (the number of diffs to retain for incremental updates), and `computeDiff` (a function to compute diffs between values, only used when `historyLength` is set).

### Computed values

A computed derives its value from other signals. It recomputes only when its dependencies change.

```ts
import { atom, computed } from '@tldraw/state'

const firstName = atom('firstName', 'Jane')
const lastName = atom('lastName', 'Doe')

const fullName = computed('fullName', () => {
	return `${firstName.get()} ${lastName.get()}`
})

fullName.get() // 'Jane Doe'

firstName.set('John')
fullName.get() // 'John Doe' — recomputed automatically
```

Computed values are lazy: they don't calculate until you call `.get()`. They also cache their result. If you call `.get()` multiple times without any dependencies changing, the derivation function runs only once.

The `@computed` decorator provides the same functionality for class methods:

```ts
import { atom, computed } from '@tldraw/state'

class Counter {
	count = atom('count', 0)

	@computed getDoubled() {
		return this.count.get() * 2
	}
}
```

### Effects and reactors

Effects run side effects in response to signal changes. There are two ways to create them:

```ts
import { atom, react, reactor } from '@tldraw/state'

const count = atom('count', 0)

// react() starts immediately and returns a cleanup function
const stop = react('log count', () => {
	console.log('Count is:', count.get())
})

count.set(1) // logs: Count is: 1
count.set(2) // logs: Count is: 2

stop() // Stop listening

// reactor() gives you control over when to start
const r = reactor('log count', () => {
	console.log('Count is:', count.get())
})

r.start() // Begin listening
r.stop() // Stop listening
```

Effects track which signals they read and re-run when those signals change. The `scheduleEffect` option lets you batch updates, for example using `requestAnimationFrame`:

```ts
react(
	'update-dom',
	() => {
		// DOM updates based on signal state
	},
	{
		scheduleEffect: (execute) => requestAnimationFrame(execute),
	}
)
```

### Transactions

Transactions batch multiple changes into a single update. Effects only run once after all changes complete:

```ts
import { atom, react, transact } from '@tldraw/state'

const a = atom('a', 1)
const b = atom('b', 2)

react('sum', () => {
	console.log('Sum:', a.get() + b.get())
})

// Without transaction: effect runs twice
a.set(10) // logs: Sum: 12
b.set(20) // logs: Sum: 30

// With transaction: effect runs once
transact(() => {
	a.set(100)
	b.set(200)
})
// logs: Sum: 300
```

The `transaction` function supports rollback:

```ts
import { transaction } from '@tldraw/state'

transaction((rollback) => {
	a.set(999)
	if (somethingWentWrong) {
		rollback() // Restores original values
	}
})
```

## React integration

The `@tldraw/state-react` package connects signals to React components.

### useValue

The most common hook. It reads a signal value and subscribes the component to changes:

```tsx
import { atom } from '@tldraw/state'
import { useValue } from '@tldraw/state-react'

const count = atom('count', 0)

function Counter() {
	const value = useValue(count)
	return <div>Count: {value}</div>
}
```

You can also compute a value inline with a dependency array:

```tsx
function ShapeInfo({ editor }) {
	const selectedCount = useValue('selected count', () => editor.getSelectedShapeIds().length, [
		editor,
	])
	return <div>{selectedCount} shapes selected</div>
}
```

### track

The `track` higher-order component automatically tracks signal access during render:

```tsx
import { track } from '@tldraw/state-react'

const Counter = track(function Counter() {
	return <div>Count: {count.get()}</div>
})
```

Tracked components re-render when any signal accessed during render changes. This is the pattern used throughout tldraw's internal components. The component is also wrapped in `React.memo`, so it only re-renders when props change or tracked signals update.

### useAtom and useComputed

Create component-local signals that persist across renders. Reading `.get()` during render only subscribes the component if it's wrapped in `track` (otherwise read the value with `useValue`), so wrap the component:

```tsx
import { track, useAtom, useComputed } from '@tldraw/state-react'

const Counter = track(function Counter() {
	const count = useAtom('count', 0)
	const doubled = useComputed('doubled', () => count.get() * 2, [count])

	return (
		<div>
			<button onClick={() => count.update((n) => n + 1)}>Increment</button>
			<div>Count: {count.get()}</div>
			<div>Doubled: {doubled.get()}</div>
		</div>
	)
})
```

### useReactor and useQuickReactor

Run effects tied to component lifecycle. The effect automatically tracks which signals it reads:

```tsx
import { useReactor, useQuickReactor } from '@tldraw/state-react'

function SelectionLogger({ editor }) {
	// Throttled to next animation frame — good for DOM updates
	useReactor(
		'update title',
		() => {
			const count = editor.getSelectedShapeIds().length
			document.title = `${count} shapes selected`
		},
		[editor]
	)

	// Runs immediately — for critical state synchronization
	useQuickReactor(
		'sync selection',
		() => {
			syncSelectionToServer(editor.getSelectedShapeIds())
		},
		[editor]
	)

	return null
}
```

### useStateTracking

Lower-level hook for manual tracking. This is what `track` uses internally:

```tsx
import { useStateTracking } from '@tldraw/state-react'

function CustomComponent() {
	return useStateTracking('CustomComponent', () => {
		return <div>{someSignal.get()}</div>
	})
}
```

## Signals in the editor

The editor uses signals extensively. Most getter methods return reactive values:

```tsx
function SelectionInfo({ editor }) {
	const selectedShapes = useValue('shapes', () => editor.getSelectedShapes(), [editor])
	const currentPage = useValue('page', () => editor.getCurrentPage(), [editor])
	const zoomLevel = useValue('zoom', () => editor.getZoomLevel(), [editor])

	return (
		<div>
			<div>Page: {currentPage.name}</div>
			<div>Zoom: {Math.round(zoomLevel * 100)}%</div>
			<div>{selectedShapes.length} shapes selected</div>
		</div>
	)
}
```

You can use `track` for cleaner syntax when accessing many signals:

```tsx
const SelectionInfo = track(function SelectionInfo({ editor }) {
	const shapes = editor.getSelectedShapes()
	const page = editor.getCurrentPage()
	const zoom = editor.getZoomLevel()

	return (
		<div>
			<div>Page: {page.name}</div>
			<div>Zoom: {Math.round(zoom * 100)}%</div>
			<div>{shapes.length} shapes selected</div>
		</div>
	)
})
```

## Debugging

The `whyAmIRunning` function helps trace what triggered an update. Call it inside an effect or computed to see which signals changed:

```ts
import { atom, react, whyAmIRunning } from '@tldraw/state'

const name = atom('name', 'Bob')

react('greeting', () => {
	whyAmIRunning()
	console.log('Hello', name.get())
})

name.set('Alice')
// Console output:
// Effect(greeting) is executing because:
//  ↳ Atom(name) changed
```

For nested dependencies, the output shows the full chain:

```ts
const firstName = atom('firstName', 'Jane')
const lastName = atom('lastName', 'Doe')
const fullName = computed('fullName', () => `${firstName.get()} ${lastName.get()}`)

react('log name', () => {
	whyAmIRunning()
	console.log(fullName.get())
})

firstName.set('John')
// Console output:
// Effect(log name) is executing because:
//  ↳ Computed(fullName) changed
//    ↳ Atom(firstName) changed
```

All signals have a `name` property (the first argument when creating them) that appears in debug output.

## Reading without tracking

Sometimes you want to read a signal's value without creating a dependency. Use `unsafe__withoutCapture` to read signals without triggering re-runs:

```ts
import { atom, react, unsafe__withoutCapture } from '@tldraw/state'

const name = atom('name', 'Sam')
const time = atom('time', Date.now())

// Update time every second
setInterval(() => time.set(Date.now()), 1000)

react('log name changes', () => {
	// Only re-run when name changes, not when time changes
	const currentTime = unsafe__withoutCapture(() => time.get())
	console.log(name.get(), 'was changed at', currentTime)
})
```

## API reference

### @tldraw/state

| Export                               | Description                                                    |
| ------------------------------------ | -------------------------------------------------------------- |
| `atom(name, value, options)`         | Create a mutable signal                                        |
| `computed(name, fn, options)`        | Create a derived signal                                        |
| `@computed`                          | Decorator for computed class methods                           |
| `react(name, fn, options)`           | Run an effect immediately, returns cleanup function            |
| `reactor(name, fn, options)`         | Create a controllable effect with `start()` and `stop()`       |
| `transact(fn)`                       | Batch changes into a single update                             |
| `transaction(fn)`                    | Batch changes with rollback support                            |
| `isAtom(value)`                      | Type guard for atoms                                           |
| `isSignal(value)`                    | Type guard for any signal                                      |
| `getComputedInstance(o, p)`          | Get the underlying computed for a `@computed` decorated method |
| `whyAmIRunning()`                    | Debug helper to trace update triggers                          |
| `unsafe__withoutCapture(fn)`         | Read signals without creating dependencies                     |
| `RESET_VALUE`                        | Symbol returned by `getDiffSince` when history is insufficient |
| `isUninitialized(value)`             | Check if a computed is running its first derivation            |
| `withDiff(value, diff)`              | Manually provide a diff when returning from a computed         |
| `localStorageAtom(name, v, options)` | Returns `[atom, cleanup]` tuple; atom persists to localStorage |

### @tldraw/state-react

| Export                             | Description                                 |
| ---------------------------------- | ------------------------------------------- |
| `useValue(signal)`                 | Subscribe to a signal, returns its value    |
| `useValue(name, fn, deps)`         | Compute and subscribe to a derived value    |
| `useAtom(name, initialValue)`      | Create a component-local atom               |
| `useComputed(name, fn, deps)`      | Create a component-local computed           |
| `useReactor(name, fn, deps)`       | Effect throttled to animation frames        |
| `useQuickReactor(name, fn, deps)`  | Effect that runs immediately                |
| `useStateTracking(name, renderFn)` | Manual signal tracking for render functions |
| `track(Component)`                 | HOC that tracks signal access during render |

## Related examples

- [Signals](/examples/events/signals) - Subscribing to store values and running side effects with `track`, `useValue`, and `useReactor`.
- [Reactive inputs](/examples/editor-api/reactive-inputs) - Using `useValue` with editor input state.

--------

# Snapping

When you move or resize shapes, tldraw snaps them to key geometry on nearby shapes.

There are two snap systems. Bounds snapping aligns edges, centers, and corners during movement and resizing, and also keeps gaps between shapes consistent. Handle snapping connects handles to outlines and key points, like arrow tips to shape edges.

Snap lines appear when shapes come within the snap threshold.

## When snapping happens

Snapping is off by default. Users hold Ctrl (Cmd on Mac) while translating, resizing, or dragging a handle to snap. Turning on snap mode inverts this: snapping is always on and holding Ctrl disables it. Snap mode is a [user preference](/sdk-features/user-preferences), toggled from the Preferences submenu in the main menu:

```typescript
editor.user.updateUserPreferences({ isSnapMode: !editor.user.getIsSnapMode() })
```

Grid snapping is a separate system, controlled by the `isGridMode` flag on [`TLInstance`](/reference/tlschema/TLInstance).

## SnapManager

The [`SnapManager`](/reference/editor/SnapManager) coordinates all snapping behavior. Access it at `editor.snaps`:

```typescript
// The two snap systems
editor.snaps.shapeBounds // BoundsSnaps - edge, center, and gap alignment
editor.snaps.handles // HandleSnaps - precise point connections

// Shared utilities
editor.snaps.getSnapThreshold() // Distance threshold (options.snapThreshold / zoom)
editor.snaps.getSnappableShapes() // Which shapes can be snapped to
editor.snaps.getIndicators() // Current snap indicators
editor.snaps.setIndicators(indicators) // Update visual snap lines
editor.snaps.clearIndicators() // Remove all snap indicators
```

The snap threshold is `editor.options.snapThreshold` screen pixels (default 8), scaled by the current zoom level. At 100% zoom, shapes snap when within 8 pixels. At 200% zoom, the threshold becomes 4 canvas units (still 8 screen pixels).

### Snappable shape filtering

[`SnapManager.getSnappableShapes`](/reference/editor/SnapManager#getSnappableShapes) determines which shapes can be snapped to. Starting from the selection's common ancestor, it walks down the shape tree and skips selected shapes (you don't snap to what you're dragging), shapes outside the viewport, and shapes whose util's [`ShapeUtil.canSnap`](/reference/editor/ShapeUtil#canSnap) returns `false`. Frames are included as snap targets. For groups, it recurses into children and snaps to them, but not to the group itself.

To keep other shapes from snapping to your shape at all, override `canSnap()`:

```typescript
class MyShapeUtil extends ShapeUtil<MyShape> {
	override canSnap() {
		return false
	}
}
```

The method returns a computed set that updates reactively as shapes move, selection changes, or the viewport pans.

## Bounds snapping

Bounds snapping aligns bounding box edges and centers. When you move or resize shapes, the [`BoundsSnaps`](/reference/editor/BoundsSnaps) system compares snap points on the selection against snap points on nearby shapes.

### Snap points

Each shape defines snap points through [`ShapeUtil.getBoundsSnapGeometry`](/reference/editor/ShapeUtil#getBoundsSnapGeometry). By default, shapes snap to their bounding box corners and center. Override this to provide custom snap points:

```typescript
class MyShapeUtil extends ShapeUtil<MyShape> {
	getBoundsSnapGeometry(shape: MyShape): BoundsSnapGeometry {
		return {
			points: [
				{ x: 0, y: 0 },
				{ x: shape.props.w, y: 0 },
				{ x: shape.props.w / 2, y: shape.props.h / 2 },
			],
		}
	}
}
```

Return `{ points: [] }` to drop point snapping for a shape while keeping it as a gap snapping target. To opt out of all snapping, use `canSnap()` instead.

### Translation snapping

When moving shapes, [`BoundsSnaps.snapTranslateShapes`](/reference/editor/BoundsSnaps#snapTranslateShapes) finds the nearest snap alignment in each axis:

```typescript
const snapData = editor.snaps.shapeBounds.snapTranslateShapes({
	lockedAxis: null, // or 'x' | 'y' to constrain to one axis
	initialSelectionPageBounds: selectionBounds,
	initialSelectionSnapPoints: selectionSnapPoints,
	dragDelta: delta,
})

// Apply the nudge to achieve snapping
const snappedDelta = Vec.Add(delta, snapData.nudge)
```

The returned `nudge` vector indicates how much to adjust the drag delta to achieve alignment. When multiple shapes align at the same distance, the system displays all of them.

### Resize snapping

When resizing, [`BoundsSnaps.snapResizeShapes`](/reference/editor/BoundsSnaps#snapResizeShapes) snaps the corners and edges being moved. Which snap points are used depends on the resize handle:

- Corner handles snap both x and y axes using that corner
- Edge handles snap only the perpendicular axis using both corners on that edge
- When aspect ratio is locked, the dominant snap axis determines both

```typescript
const snapData = editor.snaps.shapeBounds.snapResizeShapes({
	initialSelectionPageBounds: selectionBounds,
	dragDelta: delta,
	handle: 'bottom_right',
	isAspectRatioLocked: false,
	isResizingFromCenter: false,
})
```

### Gap snapping

Gap snapping is part of bounds snapping and keeps spacing between shapes consistent. It detects gaps between adjacent snappable shapes and snaps in two ways.

Gap center snapping centers the selection within a gap larger than itself, with equal spacing on both sides. Gap duplication snapping repeats an existing gap on the opposite side of a shape: if two shapes have a 100px gap between them, dragging a third shape snaps to create another 100px gap. When several gaps have matching lengths, the indicators show all of them together.

Gaps are calculated separately for horizontal and vertical directions. A gap exists when two shapes don't overlap in one axis but have overlapping ranges in the perpendicular axis.

## Handle snapping

Handle snapping connects handles to other shapes. When dragging a handle (like an arrow endpoint), the [`HandleSnaps`](/reference/editor/HandleSnaps) system snaps to nearby geometry. See [Handles](/sdk-features/handles) for how to define handles.

### Handle snap geometry

Shapes define what handles can snap to through [`ShapeUtil.getHandleSnapGeometry`](/reference/editor/ShapeUtil#getHandleSnapGeometry). The method returns an object with these properties:

| Property               | Description                                                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `outline`              | A `Geometry2d` describing the shape's outline. Defaults to the shape's geometry. Set to `null` to disable outline snapping. |
| `points`               | Key points on the shape to snap to. These have higher priority than outlines.                                               |
| `getSelfSnapOutline()` | Returns a stable outline for snapping to the shape's own geometry.                                                          |
| `getSelfSnapPoints()`  | Returns stable points for self-snapping.                                                                                    |

```typescript
class MyShapeUtil extends ShapeUtil<MyShape> {
	getHandleSnapGeometry(shape: MyShape): HandleSnapGeometry {
		return {
			outline: this.getGeometry(shape),
			points: [
				{ x: 0, y: 0 },
				{ x: shape.props.w, y: shape.props.h },
			],
		}
	}
}
```

By default, handles cannot snap to their own shape. Moving the handle would change the snap target and create a feedback loop. The `getSelfSnapOutline()` and `getSelfSnapPoints()` methods enable opt-in self-snapping when the snap geometry remains stable regardless of handle position.

### Snap types

Handles support two snap types controlled by the `snapType` property on [`TLHandle`](/reference/tlschema/TLHandle).

Point snapping (`snapType: 'point'`) snaps to the single nearest location. The system checks snap points first, then falls back to the nearest point on any outline.

Align snapping (`snapType: 'align'`) aligns the handle with nearby snap points on the x and y axes independently, with a snap line in each direction.

> The older `canSnap` property on handles is deprecated. Use `snapType: 'point'` or `snapType: 'align'` instead. If both are set, `canSnap` wins and the handle uses point snapping.

### Snapping handles

Tools call [`HandleSnaps.snapHandle`](/reference/editor/HandleSnaps#snapHandle) to snap a handle position:

```typescript
// Get the handle from the shape (TLHandle type)
const handle = editor.getShapeHandles(shape)?.find((h) => h.id === handleId)

if (handle) {
	const snapData = editor.snaps.handles.snapHandle({
		currentShapeId: shape.id,
		handle, // TLHandle with x, y, snapType, etc.
	})

	if (snapData) {
		// Apply nudge to achieve snapping
		const snappedPosition = Vec.Add(handle, snapData.nudge)
	}
}
```

The method returns `null` if no snap is found within the threshold, or a `SnapData` object with the `nudge` vector to achieve snapping. Snap indicators are automatically set on the manager for visual feedback.

## Snap indicators

Snap indicators provide visual feedback when snapping occurs. The `SnapManager` holds the current [`SnapIndicator`](/reference/editor/SnapIndicator) list, which the UI renders as SVG overlays. Read it with `getIndicators()`.

There are two kinds. Points indicators (`type: 'points'`) display as lines connecting aligned points; when several snap points align on the same axis, they appear as one continuous line. Gaps indicators (`type: 'gaps'`) display spacing between shapes with measurement lines at each gap, and show every matching gap when several have equal size.

The manager drops redundant gap indicators: if every gap in one indicator already appears in a larger indicator for the same direction, only the larger one is kept.

Indicators are cleared automatically when dragging stops or when you call `clearIndicators()`.

## Related examples

For working examples of custom snapping, see:

- [Custom bounds snapping](/examples/shapes/tools/bounds-snapping-shape): Create shapes with custom snap geometry so they snap to specific points, like playing cards that stack with visible icons.
- [Custom handle snap reference](/examples/shapes/tools/custom-relative-snapping): Use `snapReferenceHandleId` to control which handle Shift-angle snapping measures from.

--------

# Store

The store is tldraw's reactive database. It holds all shapes, pages, bindings, assets, and other records that make up your document. The store is reactive: when data changes, the UI updates automatically. It validates all records against a schema and tracks every change for undo/redo, persistence, and synchronization.

In most cases you won't interact with the store directly. The editor wraps it with higher-level methods like [`Editor.createShapes`](/reference/editor/Editor#createShapes) and [`Editor.getCurrentPageShapes`](/reference/editor/Editor#getCurrentPageShapes). But understanding the store helps when you need snapshots for persistence, want to listen for changes, or need direct access to records.

## Records

Everything in the store is a record. A record is a JSON object with an `id` and a `typeName`. Here's what a shape record looks like:

```ts
{
  id: 'shape:abc123',
  typeName: 'shape',
  type: 'geo',
  x: 100,
  y: 200,
  props: {
    geo: 'rectangle',
    w: 300,
    h: 150,
    color: 'blue',
  },
  // ... other fields
}
```

The `id` is a branded string that includes the type prefix (`shape:`, `page:`, `binding:`). This prevents accidentally mixing up IDs from different record types.

### Record scopes

Records have a scope that determines how they're persisted and synchronized:

| Scope      | Persisted | Synced to other users | Example                          |
| ---------- | --------- | --------------------- | -------------------------------- |
| `document` | Yes       | Yes                   | Shapes, pages, bindings          |
| `session`  | Optional  | No                    | Current page, camera position    |
| `presence` | No        | Yes                   | Cursor positions, user selection |

Document records are your actual drawing data, saved to storage and synced across instances. Session records are local to one editor instance, like which page you're viewing. Presence records sync to other users in real time but aren't saved. They're for showing cursors and selections in multiplayer.

## Custom record types

Shapes, bindings, and assets cover most drawing use cases, but some data doesn't fit any of them, like comments attached to a shape or per-user annotations. Register a custom record type and these records live in the store like any other: validated, migrated, persisted, and synced according to the scope you pick.

Pass record definitions to [`createTLStore`](/reference/editor/createTLStore) under the `records` option, then give that store to the `Tldraw` component. (Under the hood this calls [`createTLSchema`](/reference/tlschema/createTLSchema) with the same `records` option, so you can also build a schema directly.)

```tsx
import { createTLStore, T, Tldraw } from 'tldraw'

const store = createTLStore({
	records: {
		comment: {
			scope: 'document',
			validator: T.object({
				id: T.string,
				typeName: T.literal('comment'),
				shapeId: T.string,
				authorId: T.string,
				text: T.string,
				createdAt: T.number,
			}),
			createDefaultProperties: () => ({ createdAt: Date.now() }),
		},
	},
})

function App() {
	return <Tldraw store={store} />
}
```

For multiplayer, pass the same `records` option to `useSync`. Type names must not collide with tldraw's built-in types (`shape`, `page`, `asset`, and so on); `createTLSchema` throws if they do.

Each entry is a [`CustomRecordInfo`](/reference/tlschema/CustomRecordInfo):

| Field                     | Type                                     | Description                                                                                                                                                                              |
| ------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`                   | `'document' \| 'session'`                | `document` for synced and persisted data, `session` for local-only data. Custom `presence`-scoped types aren't supported by tldraw sync, which allows only one presence type per schema. |
| `validator`               | `T.Validatable`                          | Validates the full record (including `id` and `typeName`) on every write.                                                                                                                |
| `createDefaultProperties` | `() => Record<string, unknown>`          | Optional. Default properties used when you build a record with `store.schema.types.<name>.create()`.                                                                                     |
| `migrations`              | `MigrationSequence \| TLPropsMigrations` | Optional. Schema evolution for the record type. An empty sequence is created automatically if you omit it.                                                                               |

For type-safe IDs and TypeScript narrowing across your app, augment [`TLGlobalRecordPropsMap`](/reference/tlschema/TLGlobalRecordPropsMap) so the SDK's `TLRecord` union knows about your record types:

```ts
import { BaseRecord, RecordId } from 'tldraw'

interface TLComment extends BaseRecord<'comment', RecordId<TLComment>> {
	shapeId: string
	authorId: string
	text: string
	createdAt: number
}

declare module 'tldraw' {
	export interface TLGlobalRecordPropsMap {
		comment: TLComment
	}
}
```

### Creating and reading custom records

Use [`createCustomRecordId`](/reference/tlschema/createCustomRecordId) to mint IDs that match the `typeName:suffix` convention the store expects. It returns a generic record ID, so cast it to your own ID type. The companion guards [`isCustomRecordId`](/reference/tlschema/isCustomRecordId) and [`isCustomRecord`](/reference/tlschema/isCustomRecord) check the type name but return plain booleans; they don't narrow the TypeScript type, so cast after checking:

```ts
import { createCustomRecordId, isCustomRecord, RecordId } from 'tldraw'

const commentId = createCustomRecordId('comment') as RecordId<TLComment>

editor.store.put([
	{
		id: commentId,
		typeName: 'comment',
		shapeId: 'shape:abc123',
		authorId: 'user:alice',
		text: 'Looks good',
		createdAt: Date.now(),
	},
])

for (const record of editor.store.allRecords()) {
	if (isCustomRecord('comment', record)) {
		console.log((record as TLComment).text)
	}
}
```

Custom records appear in `store.listen` diffs and participate in undo/redo when written through the usual store APIs. `editor.store.query.records('comment')` gives you a typed, reactive list of them. Sync clients include `document`-scoped records in the synced document automatically.

### Custom record migrations

Define migrations the same way you would for shape props. Use [`createCustomRecordMigrationIds`](/reference/tlschema/createCustomRecordMigrationIds) to generate the canonical `com.tldraw.<type>/<version>` IDs, then [`createCustomRecordMigrationSequence`](/reference/tlschema/createCustomRecordMigrationSequence) for the sequence itself:

```ts
import { createCustomRecordMigrationIds, createCustomRecordMigrationSequence } from 'tldraw'

const commentVersions = createCustomRecordMigrationIds('comment', {
	AddAuthorId: 1,
})

const commentMigrations = createCustomRecordMigrationSequence({
	sequence: [
		{
			id: commentVersions.AddAuthorId,
			up: (record) => ({ ...record, authorId: record.authorId ?? 'unknown' }),
			down: ({ authorId, ...rest }) => rest,
		},
	],
})
```

Pass `commentMigrations` as the `migrations` field on the comment's `CustomRecordInfo` and the store will run them when loading older snapshots. See the [custom records example](/examples/data/assets/custom-records) for a complete app.

## Basic operations

### Reading records

The store provides reactive and non-reactive access to records:

```ts
// Reactive — creates a dependency, component will re-render when record changes
const shape = editor.store.get(shapeId)

// Non-reactive — for hot paths where you don't want re-renders
const shape = editor.store.unsafeGetWithoutCapture(shapeId)

// Check if a record exists
const exists = editor.store.has(shapeId)

// Get all records
const allRecords = editor.store.allRecords()
```

The reactive [`Store.get`](/reference/store/Store#get) integrates with tldraw's signals system. When you call it inside a tracked component or computed, the component re-renders when that record changes.

### Creating and updating records

The [`Store.put`](/reference/store/Store#put) method handles both creation and updates. A `put` with a new `id` creates the record; a `put` with an existing `id` replaces it. For shapes, [`Editor.createShape`](/reference/editor/Editor#createShape) fills in the required fields for you, so you'll usually reach for `put` when updating:

```ts
// Create a shape through the editor, which fills in defaults
editor.createShape({ id: shapeId, type: 'geo', x: 0, y: 0 })

// Update an existing record (put with same id)
const shape = editor.store.get(shapeId)!
editor.store.put([{ ...shape, x: 100 }])
```

The [`Store.update`](/reference/store/Store#update) helper is more convenient for single-record updates:

```ts
editor.store.update(shapeId, (shape) => ({
	...shape,
	x: shape.x + 50,
}))
```

### Deleting records

```ts
// Remove specific records
editor.store.remove([shapeId])

// Clear everything
editor.store.clear()
```

## Listening to changes

Subscribe to store changes with [`Store.listen`](/reference/store/Store#listen). The callback receives a diff describing what changed:

```ts
const cleanup = editor.store.listen((entry) => {
	// Records that were created
	for (const record of Object.values(entry.changes.added)) {
		console.log('Added:', record.typeName, record.id)
	}

	// Records that were updated [before, after]
	for (const [prev, next] of Object.values(entry.changes.updated)) {
		console.log('Updated:', next.id)
	}

	// Records that were deleted
	for (const record of Object.values(entry.changes.removed)) {
		console.log('Removed:', record.id)
	}
})

// Stop listening
cleanup()
```

### Filtering listeners

You can filter by source and scope:

```ts
// Only listen to user changes (not remote sync)
editor.store.listen(handleChanges, { source: 'user', scope: 'all' })

// Only document records
editor.store.listen(handleChanges, { source: 'all', scope: 'document' })
```

The `source` indicates where the change came from: `'user'` for local edits, `'remote'` for synchronized changes from other users.

To keep data internally consistent, like cleaning up bindings when a shape is deleted, use [side effects](/sdk-features/side-effects) instead. Side effects are lifecycle hooks that can intercept and modify records during operations.

## Snapshots

Snapshots serialize the store for persistence or transfer.

### Saving state

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

// Get a snapshot of document and session state
const { document, session } = getSnapshot(editor.store)

// Save to storage
localStorage.setItem('my-drawing', JSON.stringify({ document, session }))
```

The `document` snapshot contains shapes, pages, bindings, and assets: everything that makes up the drawing itself. The `session` snapshot contains per-instance state like the current page and camera position.

For multiplayer apps, you typically save document state to your server and session state per-user locally.

### Loading state

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

const saved = JSON.parse(localStorage.getItem('my-drawing'))
loadSnapshot(editor.store, saved)
```

See [`getSnapshot`](/reference/editor/getSnapshot) and [`loadSnapshot`](/reference/editor/loadSnapshot) for more details.

You can load document and session separately:

```ts
// Load just the document
loadSnapshot(editor.store, { document: saved.document })

// Later, restore session state
loadSnapshot(editor.store, { session: saved.session })
```

### Initial state

Pass a snapshot to the `Tldraw` component to initialize with saved data:

```tsx
function App() {
	return <Tldraw snapshot={savedSnapshot} />
}
```

### Migrations

Snapshots include schema version information. When you load a snapshot from an older schema version, the store migrates it automatically:

```ts
// Migrate a snapshot without loading it
const migrated = editor.store.migrateSnapshot(oldSnapshot)
```

The migration system handles schema changes between tldraw versions. You can also define migrations for custom shape props and custom record types. See [persistence](/sdk-features/persistence#migrations) for details.

## Queries

The store provides indexed queries for efficient lookups through [`Store.query`](/reference/store/Store#query):

```ts
// Create an index by property value
const shapesByParent = editor.store.query.index('shape', 'parentId')

// Get all shapes with a specific parent
const childShapes = shapesByParent.get().get(frameId) ?? new Set()
```

Indexes are reactive computed values. They update automatically when records change and track dependencies like any other signal.

```ts
// Filter by type and query expression
const textShapes = editor.store.query.records('shape', () => ({
	type: { eq: 'text' },
}))

// Get all records of a type
const allShapes = editor.store.query.records('shape')
```

Query expressions support `eq` (equals), `neq` (not equals), and `gt` (greater than, for numbers). The `records()` method returns a computed array that updates when matching records change, while `index()` returns a computed map from property values to sets of record IDs.

## Transactions

Batch multiple changes with [`Editor.run`](/reference/editor/Editor#run). Changes inside the callback are applied together, side effects see a consistent state, and the whole batch becomes one undo step:

```ts
editor.run(() => {
	editor.store.put([shape1, shape2])
	editor.store.update(shape3Id, (s) => ({ ...s, x: 100 }))
	editor.store.remove([shape4Id])
})
```

Store listeners are already batched: the store collects changes and notifies listeners once per animation frame, squashing adjacent changes from the same source. See [history](/sdk-features/history) for the undo/redo options `run` accepts.

## Computed caches

For expensive derived data, use [`Store.createComputedCache`](/reference/store/Store#createComputedCache):

```ts
const boundsCache = editor.store.createComputedCache('shape-bounds', (shape: TLShape) => {
	return calculateBounds(shape)
})

// Get cached value (recalculates only when shape changes)
const bounds = boundsCache.get(shapeId)
```

The cache lazily computes values when accessed and invalidates them when the underlying record changes. This is how the editor efficiently maintains shape bounds, geometry, and other derived data.

## Creating a standalone store

Most of the time you use the store through the editor. But you can create a standalone store for testing or headless scenarios using [`createTLStore`](/reference/editor/createTLStore):

```ts
import { createTLStore, loadSnapshot } from 'tldraw'

// Create a store and load saved data
const store = createTLStore()
loadSnapshot(store, savedSnapshot)

// Pass the pre-loaded store to Tldraw
function App() {
	return <Tldraw store={store} />
}
```

Creating your own store is useful when you need to load data before mounting the editor, share a store between multiple components, or work with tldraw data without rendering the editor at all.

## Related examples

- [Store events](/examples/events/store-events) - Listening to store changes and displaying them in real time.
- [Snapshots](/examples/editor-api/snapshots) - Saving and loading editor state with `getSnapshot` and `loadSnapshot`.
- [Local storage](/examples/data/assets/local-storage) - Persisting to localStorage with throttled saves.
- [Custom records](/examples/data/assets/custom-records) - Registering and rendering a custom record type.

--------

# Styles

The styles system manages visual properties like color, size, font, fill, and dash patterns across shapes. Style properties differ from regular shape properties in two ways: the same value can be set on many shapes at once, and the editor remembers the last-used value and applies it to newly created shapes.

Styles are defined using [`StyleProp`](/reference/tlschema/StyleProp) instances that specify valid values and defaults. The editor tracks "shared styles" across the current selection (whether all selected shapes share the same value or have different values) to drive the UI and enable batch updates.

## How it works

### StyleProp

A [`StyleProp`](/reference/tlschema/StyleProp) represents a reusable style property that can be applied across different shape types. Each `StyleProp` has a unique identifier, a default value, and optional validation.

You define a `StyleProp` using one of two static methods, [`StyleProp.define`](/reference/tlschema/StyleProp#define) for arbitrary types and [`StyleProp.defineEnum`](/reference/tlschema/StyleProp#defineEnum) for a fixed list of values:

```typescript
import { StyleProp, T } from 'tldraw'

// Define a numeric style property
const LineWidthStyle = StyleProp.define('myApp:lineWidth', {
	defaultValue: 2,
	type: T.number,
})

// Define an enumerated style property
const CapStyle = StyleProp.defineEnum('myApp:cap', {
	defaultValue: 'round',
	values: ['round', 'square', 'butt'],
})
```

The unique identifier should be namespaced to avoid conflicts with other style properties. Use your app or library name as a prefix.

### Shape integration

To use a style property in your shape, include the `StyleProp` instance in your shape's props definition. This works the same way for your own styles and for tldraw's defaults. The editor recognizes `StyleProp` instances and handles them specially: it saves their values, applies them to new shapes, and tracks them across selections.

```typescript
import {
	DefaultColorStyle,
	DefaultSizeStyle,
	RecordProps,
	T,
	TLDefaultColorStyle,
	TLDefaultSizeStyle,
	TLShape,
} from 'tldraw'

// Register the shape type and its props
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		'my-shape': {
			w: number
			h: number
			color: TLDefaultColorStyle
			size: TLDefaultSizeStyle
			lineWidth: number
		}
	}
}

type TLMyShape = TLShape<'my-shape'>

// Pass StyleProp instances in the props object for validation
const myShapeProps: RecordProps<TLMyShape> = {
	w: T.number,
	h: T.number,
	color: DefaultColorStyle,
	size: DefaultSizeStyle,
	lineWidth: LineWidthStyle,
}
```

When you create a shape, provide the actual style values. If you omit a style prop, the editor uses its saved value from previous shapes:

```typescript
editor.createShape({
	type: 'my-shape',
	props: {
		w: 100,
		h: 100,
		color: 'red',
		size: 'm',
	},
})
```

### Shared styles

The editor computes shared styles across the current selection. Use [`Editor.getSharedStyles`](/reference/editor/Editor#getSharedStyles) to get a [`ReadonlySharedStyleMap`](/reference/editor/ReadonlySharedStyleMap) from each style property to its [`SharedStyle`](/reference/editor/SharedStyle) status: either "shared" (all shapes have the same value) or "mixed" (shapes have different values).

```typescript
const sharedStyles = editor.getSharedStyles()
const colorStyle = sharedStyles.get(DefaultColorStyle)

if (colorStyle && colorStyle.type === 'shared') {
	console.log('All shapes are', colorStyle.value)
} else if (colorStyle && colorStyle.type === 'mixed') {
	console.log('Shapes have different colors')
}
```

For convenience, use `getAsKnownValue` when you only care about the shared case:

```typescript
const sharedStyles = editor.getSharedStyles()
const color = sharedStyles.getAsKnownValue(DefaultColorStyle)
// Returns the color if all shapes share it, undefined otherwise
```

The `getSharedStyles` method examines each selected shape, extracts its style values, and compares them. For groups, it recursively examines the group's children rather than the group itself, since groups don't have visual styles.

When you're not in the select tool with a selection, `getSharedStyles` returns the styles for the current tool if that tool creates shapes. This lets the UI show and modify the styles that will be applied to the next shape.

### Setting styles

Use [`Editor.setStyleForSelectedShapes`](/reference/editor/Editor#setStyleForSelectedShapes) to change styles on the current selection:

```typescript
// Change color for all selected shapes
editor.setStyleForSelectedShapes(DefaultColorStyle, 'red')

// Change size
editor.setStyleForSelectedShapes(DefaultSizeStyle, 'l')
```

This method recursively applies the style to all shapes in the selection, including shapes nested inside groups. It only updates shapes that support the given style property.

Use [`Editor.setStyleForNextShapes`](/reference/editor/Editor#setStyleForNextShapes) to change the style for subsequently created shapes, and [`Editor.getStyleForNextShape`](/reference/editor/Editor#getStyleForNextShape) to read it:

```typescript
// Next shapes will be blue
editor.setStyleForNextShapes(DefaultColorStyle, 'blue')

// Create a new shape - it will be blue
editor.createShape({ type: 'geo', props: { w: 100, h: 100 } })

const nextColor = editor.getStyleForNextShape(DefaultColorStyle) // 'blue'
```

`setStyleForSelectedShapes` only updates the selected shapes; it does not change the value for next shapes. The style panel calls both methods when the user picks a value, so the change applies to the selection and carries over to the next shape. Do the same in your own code if you want that behavior:

```typescript
editor.run(() => {
	editor.setStyleForSelectedShapes(DefaultColorStyle, 'blue')
	editor.setStyleForNextShapes(DefaultColorStyle, 'blue')
})
```

## Default styles

The `@tldraw/tlschema` package provides a set of default style properties that the built-in shapes use. Colors reference theme values rather than raw hex codes, so shapes adapt to light and dark modes.

| Style                              | Values                                                | Used for                                   |
| ---------------------------------- | ----------------------------------------------------- | ------------------------------------------ |
| [`DefaultColorStyle`](/reference/tlschema/DefaultColorStyle)             | black, red, blue, green, and other named colors       | Primary shape color                        |
| [`DefaultFillStyle`](/reference/tlschema/DefaultFillStyle)              | none, semi, solid, pattern, fill, lined-fill          | Fill pattern                               |
| [`DefaultDashStyle`](/reference/tlschema/DefaultDashStyle)              | draw, solid, dashed, dotted, none                     | Stroke style                               |
| [`DefaultSizeStyle`](/reference/tlschema/DefaultSizeStyle)              | s, m, l, xl                                           | Relative size scale                        |
| [`DefaultFontStyle`](/reference/tlschema/DefaultFontStyle)              | draw, sans, serif, mono                               | Font family                                |
| [`DefaultTextAlignStyle`](/reference/tlschema/DefaultTextAlignStyle)         | start, middle, end                                    | Horizontal text alignment                  |
| [`DefaultHorizontalAlignStyle`](/reference/tlschema/DefaultHorizontalAlignStyle)   | start, middle, end                                    | Horizontal content alignment within bounds |
| [`DefaultVerticalAlignStyle`](/reference/tlschema/DefaultVerticalAlignStyle)     | start, middle, end                                    | Vertical content alignment within bounds   |
| [`GeoShapeGeoStyle`](/reference/tlschema/GeoShapeGeoStyle)              | rectangle, ellipse, triangle, and other geo types     | Geometric shape type                       |
| [`ArrowShapeArrowheadStartStyle`](/reference/tlschema/ArrowShapeArrowheadStartStyle) | arrow, triangle, dot, none, and other arrowhead types | Start arrowhead                            |
| [`ArrowShapeArrowheadEndStyle`](/reference/tlschema/ArrowShapeArrowheadEndStyle)   | Same values as the start style                        | End arrowhead                              |
| [`ArrowShapeKindStyle`](/reference/tlschema/ArrowShapeKindStyle)           | arc, elbow                                            | Arrow routing                              |
| [`LineShapeSplineStyle`](/reference/tlschema/LineShapeSplineStyle)          | line, cubic                                           | Line spline type                           |

The shape-specific styles are defined in `@tldraw/tlschema` next to their shape's record type.

Opacity is not a `StyleProp`. It's a regular property on the base shape ([`TLBaseShape`](/reference/tlschema/TLBaseShape)) that all shapes inherit, but it behaves like a style through its own methods: [`Editor.getSharedOpacity`](/reference/editor/Editor#getSharedOpacity), [`Editor.setOpacityForSelectedShapes`](/reference/editor/Editor#setOpacityForSelectedShapes), and [`Editor.setOpacityForNextShapes`](/reference/editor/Editor#setOpacityForNextShapes).

## Customizing default styles

Change the default value of any style with `setDefaultValue`. Enum styles also support `addValues` and `removeValues` for extending the built-in set at runtime:

```typescript
import { DefaultSizeStyle } from 'tldraw'

DefaultSizeStyle.setDefaultValue('s')
```

## Related examples

- [Custom shape with custom styles](/examples/shapes/tools/shape-with-custom-styles) - Create your own custom styles and use them in custom shapes.
- [Custom shape with tldraw styles](/examples/shapes/tools/shape-with-tldraw-styles) - Use tldraw's default styles in your custom shapes and integrate with the style panel.
- [Change default styles](/examples/ui/changing-default-style) - Change the default value for a style property (e.g., setting size to small by default).
- [Change default colors](/examples/ui/changing-default-colors) - Customize the color values in the tldraw theme.
- [Easter egg styles](/examples/editor-api/easter-egg-styles) - Access hidden styles like white color, special fill variants, and label colors programmatically.

--------

# Text measurement

The editor measures text to calculate shape bounds, handle text wrapping, and position labels. Two managers handle this: [`TextManager`](/reference/editor/TextManager) measures text dimensions using a hidden DOM element, and [`FontManager`](/reference/editor/FontManager) loads custom fonts before measurement so dimensions are accurate. Access them through `editor.textMeasure` and `editor.fonts`.

## How text measurement works

The `TextManager` creates a hidden measurement element on initialization and appends it to the editor container. This element stays in the DOM throughout the editor's lifecycle, so repeated measurements don't pay the cost of creating and removing elements.

```typescript
// Simplified for clarity - see TextManager.ts for full implementation
const elm = this.editor.getContainerDocument().createElement('div')
elm.classList.add('tl-text', 'tl-text-measure')
elm.setAttribute('dir', 'auto')
this.editor.getContainer().appendChild(elm)
```

The element is absolutely positioned and hidden from users, but the browser still lays it out, so measurements are accurate.

### Measuring text

The `measureText` method calculates text dimensions. Pass in text content and [`TLMeasureTextOpts`](/reference/editor/TLMeasureTextOpts), and it returns a box model with width and height.

```typescript
const dimensions = editor.textMeasure.measureText('Hello world', {
	fontFamily: 'Inter',
	fontSize: 16,
	fontWeight: 'normal',
	fontStyle: 'normal',
	lineHeight: 1.35,
	maxWidth: null, // No wrapping
	padding: '4px',
})
// Returns: { x: 0, y: 0, w: 85, h: 22, scrollWidth: 0 }
```

The method applies styles to the measurement element, reads the computed dimensions, then restores the previous styles. This means rapid successive measurements don't interfere with each other.

You can also use `measureHtml` to measure HTML content directly instead of plain text, or `measureHtmlBatch` to measure many pieces of HTML in one layout pass using a pool of elements.

### Text wrapping

Set `maxWidth` to a number and the browser wraps text to fit within that width. The `TextManager` uses the browser's native text layout algorithm rather than implementing its own wrapping logic.

```typescript
const wrapped = editor.textMeasure.measureText('This is a long line of text', {
	fontFamily: 'Inter',
	fontSize: 16,
	fontWeight: 'normal',
	fontStyle: 'normal',
	lineHeight: 1.35,
	maxWidth: 100, // Wrap at 100px
	padding: '4px',
})
// Returns dimensions accounting for multiple lines
```

Set `maxWidth: null` to preserve explicit line breaks and spaces without wrapping. This is useful for measuring single-line text or when wrapping is handled elsewhere.

## Measuring text spans

For SVG export or precise text selection, `measureTextSpans` breaks text into individual spans based on line breaks and word boundaries. It takes [`TLMeasureTextSpanOpts`](/reference/editor/TLMeasureTextSpanOpts):

```typescript
const spans = editor.textMeasure.measureTextSpans('Hello world\nSecond line', {
	width: 200,
	height: 100,
	padding: 8,
	fontSize: 16,
	fontWeight: 'normal',
	fontFamily: 'Inter',
	fontStyle: 'normal',
	lineHeight: 1.35,
	textAlign: 'start',
	overflow: 'wrap',
})
```

Each span includes the text content and its bounding box. Runs of whitespace become their own spans (widths are illustrative):

```typescript
;[
	{ text: 'Hello', box: { x: 0, y: 0, w: 40, h: 22 } },
	{ text: ' ', box: { x: 40, y: 0, w: 5, h: 22 } },
	{ text: 'world', box: { x: 45, y: 0, w: 40, h: 22 } },
	{ text: 'Second', box: { x: 0, y: 22, w: 47, h: 22 } },
	{ text: ' ', box: { x: 47, y: 22, w: 5, h: 22 } },
	{ text: 'line', box: { x: 52, y: 22, w: 32, h: 22 } },
]
```

The algorithm positions a `Range` around each grapheme, measures it with `getClientRects()`, then groups graphemes into spans wherever the line position changes or the text switches between whitespace and non-whitespace.

### Truncation handling

The required `overflow` option controls how text exceeding the available space is handled:

| Value               | Behavior                                              |
| ------------------- | ----------------------------------------------------- |
| `wrap`              | Text wraps to multiple lines                          |
| `truncate-clip`     | Text truncates to the first line, no visual indicator |
| `truncate-ellipsis` | Text truncates with an ellipsis character             |

When using `truncate-ellipsis`, the algorithm first measures the ellipsis width, then subtracts it from the available width and remeasures to find the cut point.

## Font loading

The `FontManager` loads custom fonts before text measurement. If you measure text before its font loads, you get incorrect dimensions and layout shifts when the font finally becomes available.

### Declaring font requirements

Shapes declare which fonts they need by overriding [`ShapeUtil.getFontFaces`](/reference/editor/ShapeUtil#getFontFaces) and returning [`TLFontFace`](/reference/tlschema/TLFontFace) objects:

```typescript
class MyTextShapeUtil extends ShapeUtil<MyTextShape> {
	override getFontFaces(shape: MyTextShape): TLFontFace[] {
		return [
			{
				family: 'MyCustomFont',
				src: { url: '/fonts/my-custom-font.woff2', format: 'woff2' },
				weight: 'normal',
				style: 'normal',
			},
		]
	}
}
```

The `FontManager` tracks these font requirements and loads them before the shape renders.

### Loading fonts

Use `ensureFontIsLoaded` to load a specific font, or `requestFonts` to batch multiple font loading requests:

```typescript
// Load a single font
await editor.fonts.ensureFontIsLoaded(fontFace)

// Batch load multiple fonts (batched into a single microtask)
editor.fonts.requestFonts([fontFace1, fontFace2])
```

The manager caches font loading state to avoid redundant loading. Multiple concurrent requests for the same font share a single loading promise.

### Tracking fonts reactively

To make a computation re-run once a shape's fonts load, call `trackFontsForShape` inside it. [`Editor.getShapeGeometry`](/reference/editor/Editor#getShapeGeometry) already does this for you, so you only need it in your own caches, like a text size cache:

```typescript
editor.fonts.trackFontsForShape(shape)
```

### Loading fonts for the current page

Use `loadRequiredFontsForCurrentPage` to load all fonts needed by shapes on the current page. The editor calls it before the first render and before exports:

```typescript
await editor.fonts.loadRequiredFontsForCurrentPage()
// All fonts for shapes on the current page are now loaded
```

Pass a `limit` argument to skip the wait entirely when the page needs more than that many fonts. The editor uses the `maxFontsToLoadBeforeRender` option (see [`TldrawOptions`](/reference/editor/TldrawOptions), default `Infinity`) for this, so a page with many fonts doesn't block the canvas.

## Performance considerations

The `TextManager` doesn't cache measurements itself. Shape utilities cache their own results using reactive computed values, so text is only remeasured when font properties or content change.

The `FontManager` computes each shape's font faces once and caches them until the shape's props or meta change. Concurrent requests for the same font share one loading promise, and `requestFonts` batches requests into a single microtask.

The measurement element sets `overflow-wrap: break-word` so long words can break, `width` and `max-width` to control wrapping, and `dir="auto"` for mixed LTR/RTL content. Line height is resolved to a whole pixel with [`resolveLineHeightPx`](/reference/editor/resolveLineHeightPx) so measurement, on-canvas rendering, and export agree across browsers, which otherwise disagree on fractional line boxes. Use the same helper anywhere you render text from a custom shape.

## Related examples

- [Speech bubble](/examples/shapes/tools/speech-bubble) - A custom shape that measures its text with `editor.textMeasure` to grow to fit.
- [Rich text with font options](/examples/shapes/tools/rich-text-font-extensions) - Extend the TipTap text editor with font-family and font-size options.

--------

# Text shape

The text shape displays formatted text on the canvas. It has two modes: auto-size, where the shape grows to fit its content, and fixed-width, where text wraps at a set width. The text tool creates text shapes. See [`TextShapeUtil`](/reference/tldraw/TextShapeUtil) and [`TLTextShape`](/reference/tlschema/TLTextShape).

## Auto-size vs fixed-width

Text shapes operate in two modes controlled by the `autoSize` property:

| Mode        | Behavior                                                         | Use case                                  |
| ----------- | ---------------------------------------------------------------- | ----------------------------------------- |
| Auto-size   | Shape width expands to fit content; text never wraps             | Labels, titles, short annotations         |
| Fixed-width | Text wraps at the shape's width boundary; height grows as needed | Paragraphs, longer descriptions, callouts |

### Auto-size mode

When `autoSize` is true (the default), the shape grows to fit its text. The shape widens as you type, and text never wraps unless you press Enter.

```tsx
import { toRichText } from 'tldraw'

editor.createShape({
	type: 'text',
	x: 100,
	y: 100,
	props: {
		richText: toRichText('This text will never wrap'),
		autoSize: true,
	},
})
```

Which edge stays put as an auto-sized shape grows depends on `textAlign`: with `start` the left edge stays fixed and the shape grows to the right, with `middle` the center stays fixed, and with `end` the right edge stays fixed.

### Fixed-width mode

When `autoSize` is false, the shape uses a fixed width specified by the `w` property. Text wraps when it reaches this boundary, and the shape grows vertically to accommodate additional lines.

```tsx
editor.createShape({
	type: 'text',
	x: 100,
	y: 100,
	props: {
		richText: toRichText('This text will wrap when it reaches the specified width'),
		autoSize: false,
		w: 200, // Width in pixels
	},
})
```

To convert an auto-sized shape to fixed-width, drag its left or right edge handle. The shape switches to fixed-width mode and keeps that width as you type.

## Text alignment

The `textAlign` property controls horizontal text alignment:

| Value    | Description                                    |
| -------- | ---------------------------------------------- |
| `start`  | Left-aligned (or right-aligned in RTL locales) |
| `middle` | Center-aligned                                 |
| `end`    | Right-aligned (or left-aligned in RTL locales) |

```tsx
editor.createShape({
	type: 'text',
	x: 100,
	y: 100,
	props: {
		richText: toRichText('Centered text'),
		textAlign: 'middle',
		autoSize: false,
		w: 300,
	},
})
```

Text shapes always align vertically to the middle of the shape's geometry.

## Creating text with the text tool

The text tool (`T` key) creates text shapes in two ways. Double-clicking empty canvas with the select tool also creates an auto-sized text shape.

### Click to create auto-sized text

Click anywhere on the canvas to create an auto-sized text shape. The shape appears centered at your click position and immediately enters edit mode. Start typing to add content.

### Drag to create fixed-width text

Hold and drag horizontally to create a fixed-width text shape. Once the pointer has been down for at least 150ms and the horizontal drag exceeds about six times the base drag distance (larger for coarse pointers, scaled by zoom), the tool creates a fixed-width shape at that width and hands off to the select tool's resize state. Keep dragging to adjust the width, then release to start editing. Quick, short drags create auto-sized shapes instead.

### Tool shortcuts

| Action                     | Result                                       |
| -------------------------- | -------------------------------------------- |
| **Click**                  | Create auto-sized text at click position     |
| **Drag horizontally**      | Create fixed-width text with dragged width   |
| **Enter** (shape selected) | Switch to the select tool and edit the shape |
| **Escape**                 | Exit text tool, return to select tool        |
| **Cmd/Ctrl+Enter**         | Confirm text and exit edit mode              |

## Editing text

Double-click a text shape or press Enter while it's selected to enter edit mode. The shape displays a cursor and you can type, select, and format text using the rich text editor.

Text shapes use the same [rich text](/sdk-features/rich-text) system as notes, geo shapes, and arrow labels. You get bold, italic, code, highlighting, and more through keyboard shortcuts or the rich text toolbar.

### Empty text deletion

When editing ends, the shape deletes itself if its text is empty or only trailing whitespace. This keeps invisible shapes off the canvas.

## Scaling and resize

Text shapes support two resize behaviors:

### Aspect-ratio locked scaling

Dragging any handle other than the left or right edges scales the whole shape proportionally. The `scale` property tracks this multiplier.

```tsx
// A text shape at 2x scale
editor.createShape({
	type: 'text',
	props: {
		richText: toRichText('Scaled up'),
		scale: 2,
	},
})
```

### Width adjustment

Dragging the left or right edge handles adjusts only the width. For auto-sized shapes, this converts them to fixed-width mode. For already fixed-width shapes, this changes where text wraps.

## Dynamic resize mode

When `editor.user.getIsDynamicResizeMode()` is true, new text shapes are created with a scale inversely proportional to the current zoom level. At 200% zoom, new shapes get `scale: 0.5`; at 50% zoom, they get `scale: 2`. This keeps text visually consistent regardless of your zoom level when creating it. Use [`Editor.getResizeScaleFactor`](/reference/editor/Editor#getResizeScaleFactor) to get the same value:

```tsx
const scale = editor.getResizeScaleFactor()
```

## Arrow bindings

Arrows can bind to text shapes just like other shapes. When an arrow with no arrowhead binds to a text shape, the shape's geometry is widened by `extraArrowHorizontalPadding` on each side (10 by default) so the bare line ends short of the glyphs. Arrows with arrowheads bind to the unpadded box. See [Configuration](#configuration) to change the padding.

## Text outline

Text shapes display an outline in the canvas background color, which keeps text readable when it overlaps other shapes. The outline uses CSS `text-shadow` and is on by default. Safari skips it because `text-shadow` performs poorly there. Turn it off with the `showTextOutline` option (see [Configuration](#configuration)).

## Properties

| Property    | Type                      | Default   | Description                                     |
| ----------- | ------------------------- | --------- | ----------------------------------------------- |
| `richText`  | `TLRichText`              | empty     | Text content with formatting                    |
| `color`     | `TLDefaultColorStyle`     | `'black'` | Text color                                      |
| `size`      | `TLDefaultSizeStyle`      | `'m'`     | Font size preset (`s`, `m`, `l`, `xl`)          |
| `font`      | `TLDefaultFontStyle`      | `'draw'`  | Font family (`draw`, `sans`, `serif`, `mono`)   |
| `textAlign` | `TLDefaultTextAlignStyle` | `'start'` | Horizontal alignment (`start`, `middle`, `end`) |
| `autoSize`  | `boolean`                 | `true`    | When true, shape resizes to fit content         |
| `w`         | `number`                  | `8`       | Width when autoSize is false                    |
| `scale`     | `number`                  | `1`       | Scale factor applied to the shape               |

## Configuration

| Option                        | Type      | Default | Description                                                              |
| ----------------------------- | --------- | ------- | ------------------------------------------------------------------------ |
| `extraArrowHorizontalPadding` | `number`  | `10`    | Extra horizontal padding when an arrow without an arrowhead binds        |
| `showTextOutline`             | `boolean` | `true`  | Display text outline for readability (skipped on Safari for performance) |

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

const ConfiguredTextUtil = TextShapeUtil.configure({
	extraArrowHorizontalPadding: 20,
	showTextOutline: false,
})

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

## Grid snapping

When grid mode is enabled (`editor.getInstanceState().isGridMode`), the text tool snaps new text shapes to the grid.

## Programmatic text formatting

To create text with formatting, construct the rich text JSON structure directly:

```tsx
editor.createShape({
	type: 'text',
	x: 100,
	y: 100,
	props: {
		richText: {
			type: 'doc',
			content: [
				{
					type: 'paragraph',
					content: [
						{ type: 'text', text: 'Regular and ' },
						{ type: 'text', text: 'bold', marks: [{ type: 'bold' }] },
						{ type: 'text', text: ' text' },
					],
				},
			],
		},
		autoSize: true,
	},
})
```

Marks include `bold`, `italic`, `strike`, `underline`, `code`, `link`, and `highlight`. See [Rich text](/sdk-features/rich-text) for the formatting system.

## Related articles

- [Rich text](/sdk-features/rich-text) — Text formatting system and TipTap integration
- [Default shapes](/sdk-features/default-shapes) — Overview of all built-in shapes
- [Tools](/sdk-features/tools) — How tools handle user input
- [Styles](/sdk-features/styles) — Working with shape styles like color and size

## Related examples

- [Programmatic text shape creation](/examples/shapes/tools/text-shape-configuration) — Creating text shapes with various configurations
- [Outlined text with TipTap mark](/examples/shapes/tools/outlined-text) — Adding text outline styling via a custom TipTap mark extension

--------

# Themes

Themes control the color palette used to render shapes in tldraw. A theme definition bundles color palettes for both light and dark modes alongside shared properties like font size and stroke width. The editor automatically selects the right color mode based on the user's preference.

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

export default function App() {
	return (
		<Tldraw
			onMount={(editor) => {
				// Read the current theme and resolve colors for the active mode
				const theme = editor.getCurrentTheme()
				const colors = theme.colors[editor.getColorMode()]
				console.log(colors.red.solid) // '#e03131'
			}}
		/>
	)
}
```

## Theme structure

A theme definition is a [`TLTheme`](/reference/tlschema/TLTheme) object with an `id`, color palettes ([`TLThemeColors`](/reference/tlschema/TLThemeColors)) for both light and dark modes, font definitions, and shared `fontSize`, `lineHeight`, and `strokeWidth` values. [`DEFAULT_THEME`](/reference/editor/DEFAULT_THEME) is the built-in theme:

```typescript
import { DEFAULT_THEME, TLTheme } from 'tldraw'

const myTheme: TLTheme = {
	id: 'custom',
	fontSize: 16,
	lineHeight: 1.35,
	strokeWidth: 2,
	fonts: DEFAULT_THEME.fonts,
	colors: {
		light: {
			text: '#000000',
			background: '#f8f8f8',
			negativeSpace: '#f8f8f8',
			solid: '#fcfcfc',
			cursor: '#000000',
			noteBorder: '#e8e8e8',
			// ... other UI colors (selection, brush, snap, laser)
			black: {
				solid: '#1d1d1d',
				semi: '#e8e8e8',
				pattern: '#494949',
				fill: '#1d1d1d',
				linedFill: '#e8e8e8',
				frameHeadingStroke: '#1d1d1d',
				frameHeadingFill: '#f5f5f5',
				frameStroke: '#e2e2e2',
				frameFill: '#fcfcfc',
				frameText: '#1d1d1d',
				noteFill: '#fddd00',
				noteText: '#000000',
				highlightSrgb: '#fddd00',
				highlightP3: 'color(display-p3 0.972 0.8705 0.05)',
			},
			blue: {
				solid: '#4263eb',
				// ... other variants
			},
			// ... other colors
		},
		dark: {
			// ... dark mode equivalents
		},
	},
}
```

Each [`TLTheme`](/reference/tlschema/TLTheme) has a unique `id` used as the key in the theme registry, and always contains both `light` and `dark` palettes under `colors`. To get the palette for the current color mode, index into `theme.colors` with the result of [`Editor.getColorMode`](/reference/editor/Editor#getColorMode).

Each color in the palette is a [`TLDefaultColor`](/reference/tlschema/TLDefaultColor) with variants for different contexts:

| Variant              | Purpose                                        |
| -------------------- | ---------------------------------------------- |
| `solid`              | Full-opacity color for strokes and solid fills |
| `semi`               | Muted color for the semi fill style            |
| `pattern`            | Color used in pattern/hatch fills              |
| `fill`               | Explicit fill color (usually same as solid)    |
| `linedFill`          | Slightly lighter fill for lined patterns       |
| `frameHeadingStroke` | Stroke color for frame headings                |
| `frameHeadingFill`   | Fill color for frame headings                  |
| `frameStroke`        | Stroke color for frame borders                 |
| `frameFill`          | Fill color for frame backgrounds               |
| `frameText`          | Text color inside frames                       |
| `noteFill`           | Fill color for note shapes                     |
| `noteText`           | Text color inside note shapes                  |
| `highlightSrgb`      | Highlighter color in sRGB color space          |
| `highlightP3`        | Highlighter color in Display P3 color space    |

The palette also includes thirteen UI colors ([`TLThemeUiColorKeys`](/reference/tlschema/TLThemeUiColorKeys)) that every theme must define:

| Property                           | Purpose                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------ |
| `text`                             | Default text color                                                                         |
| `background`                       | Canvas background color used in SVG exports                                                |
| `negativeSpace`                    | Areas that "cut through" to the background, e.g. frame heading knockouts and text outlines |
| `solid`                            | Default solid surface color                                                                |
| `cursor`                           | Cursor color                                                                               |
| `noteBorder`                       | Note shape borders                                                                         |
| `selectionStroke`, `selectionFill` | Selection box                                                                              |
| `selectedContrast`                 | Indicators drawn on top of selected shapes                                                 |
| `brushStroke`, `brushFill`         | Selection-brush rectangle                                                                  |
| `snap`                             | Snap guides                                                                                |
| `laser`                            | Laser pointer                                                                              |

In the default theme, `background` and `negativeSpace` have the same value, but custom themes can set them independently.

> The `background` property is used for SVG exports and the fill of selection handles, not for the canvas itself. The visible canvas background comes from the `--tl-color-background` CSS variable. If you customize `background` in your theme, set the CSS variable to match, otherwise exports use a different background than the canvas.

In addition to colors, each theme has a `fontSize` (default `16`), `lineHeight` (default `1.35`), and `strokeWidth` (default `2`). All default shape font sizes are derived by multiplying the base `fontSize` by a per-shape-type multiplier, and stroke widths work the same way with `strokeWidth`, so changing these base values scales text and strokes proportionally. Because these are shared across light and dark modes, you only set them once per theme definition.

## Reading the current theme

Use [`Editor.getCurrentTheme`](/reference/editor/Editor#getCurrentTheme) to get the resolved theme. This is reactive: components that read it will re-render when the theme changes.

```tsx
function MyComponent() {
	const editor = useEditor()
	const theme = editor.getCurrentTheme()
	const colors = theme.colors[editor.getColorMode()]

	return <div style={{ color: colors.blue.solid }}>Blue text</div>
}
```

Inside a shape util, access the theme through `this.editor`:

```typescript
class MyShapeUtil extends ShapeUtil<MyShape> {
	component(shape: MyShape) {
		const theme = this.editor.getCurrentTheme()
		// ...
	}
}
```

Use [`getColorValue`](/reference/editor/getColorValue) to resolve a color style name to its actual color value:

```typescript
import { getColorValue } from 'tldraw'

const theme = editor.getCurrentTheme()
const colors = theme.colors[editor.getColorMode()]
const color = getColorValue(colors, 'red', 'solid') // '#e03131'
```

## Color mode

The editor selects `'light'` or `'dark'` colors based on its `colorScheme` setting. Set the initial color scheme via the `colorScheme` prop:

```tsx
<Tldraw colorScheme="dark" />
```

The `colorScheme` prop accepts `'light'` (default), `'dark'`, or `'system'` (follows the OS preference).

Use [`Editor.getColorMode`](/reference/editor/Editor#getColorMode) to read the resolved mode at runtime:

```typescript
const colorMode = editor.getColorMode() // 'light' or 'dark'
```

Users can also override the color scheme via their preferences:

```typescript
editor.user.updateUserPreferences({ colorScheme: 'dark' })
```

When set, the user preference takes priority over the `colorScheme` prop. See [User preferences](/sdk-features/user-preferences) for more.

The [`useColorMode`](/reference/editor/useColorMode) hook provides a reactive color mode for use in React components:

```tsx
function MyComponent() {
	const colorMode = useColorMode() // reactive, re-renders on change
	return <div>Current mode: {colorMode}</div>
}
```

## Customizing colors

Use [`Editor.updateTheme`](/reference/editor/Editor#updateTheme) to override specific colors in a theme. Get the theme, modify it, and pass it back:

```typescript
const theme = editor.getTheme('default')!
editor.updateTheme({
	...theme,
	colors: {
		...theme.colors,
		light: { ...theme.colors.light, black: { ...theme.colors.light.black, solid: 'navy' } },
	},
})
```

You can also override other properties:

```typescript
const theme = editor.getTheme('default')!
editor.updateTheme({ ...theme, fontSize: 18, strokeWidth: 3 })
```

You can also pass theme definitions as the `themes` prop on the [`Tldraw`](/reference/tldraw/Tldraw) or [`TldrawEditor`](/reference/editor/TldrawEditor) component, typed as `Partial<`[`TLThemes`](/reference/tlschema/TLThemes)`>`. The prop is reactive: when it changes, the editor's themes update automatically. Use the `initialTheme` prop or [`Editor.setCurrentTheme`](/reference/editor/Editor#setCurrentTheme) to pick which registered theme is active; see the [multiple themes example](/examples/ui/multiple-themes).

```tsx
import { DEFAULT_THEME, TLThemes } from 'tldraw'

const themes: Partial<TLThemes> = {
	default: {
		id: 'default',
		fontSize: 16,
		lineHeight: 1.35,
		strokeWidth: 2,
		fonts: DEFAULT_THEME.fonts,
		colors: {
			light: { /* ... */ },
			dark: { /* ... */ },
		},
	},
}

<Tldraw themes={themes} />
```

## Adding custom colors

You can add new colors beyond the built-in palette. Extend the [`TLThemeDefaultColors`](/reference/tlschema/TLThemeDefaultColors) interface with module augmentation and include the color in your theme definitions:

```typescript
import { TLDefaultColor } from 'tldraw'

declare module '@tldraw/tlschema' {
	interface TLThemeDefaultColors {
		pink: TLDefaultColor
	}
}
```

The augmentation is type-only; your theme definitions supply the runtime values:

```tsx
import { DEFAULT_THEME, TLThemes } from 'tldraw'

const themes: Partial<TLThemes> = {
	default: {
		...DEFAULT_THEME,
		colors: {
			light: {
				...DEFAULT_THEME.colors.light,
				pink: {
					solid: '#e91e8c',
					semi: '#fce4f2',
					pattern: '#f06baf',
					fill: '#e91e8c',
					linedFill: '#fce4f2',
					frameHeadingStroke: '#e91e8c',
					frameHeadingFill: '#fce4f2',
					frameStroke: '#e91e8c',
					frameFill: '#fce4f2',
					frameText: '#e91e8c',
					noteFill: '#fce4f2',
					noteText: '#e91e8c',
					highlightSrgb: '#e91e8c',
					highlightP3: '#e91e8c',
				},
			},
			dark: {
				...DEFAULT_THEME.colors.dark,
				pink: {
					solid: '#f06baf',
					semi: '#3d1a2e',
					// ... other variants
				},
			},
		},
	},
}

<Tldraw themes={themes} />
```

tldraw validates shape properties (including colors) when data enters the store, for example when loading from IndexedDB or syncing from a server. Passing `themes` tells tldraw about your custom colors _before_ data is loaded, so they pass validation. If you create your own store, pass the same `themes` to [`createTLStore`](/reference/editor/createTLStore) so the colors are registered before the store loads data.

Every theme should include an entry for every custom color in both light and dark palettes. If a shape uses a color that doesn't exist in the active theme, it won't render correctly.

See the [Custom theme](/examples/ui/custom-theme) example for a complete demo.

## Removing colors

To remove built-in palette colors, augment the [`TLRemovedDefaultThemeColors`](/reference/tlschema/TLRemovedDefaultThemeColors) interface. Any key you add is omitted from [`TLThemeColors`](/reference/tlschema/TLThemeColors), so TypeScript no longer expects it in theme definitions:

```typescript
declare module '@tldraw/tlschema' {
	interface TLRemovedDefaultThemeColors {
		'light-violet': true
		'light-blue': true
		'light-green': true
		'light-red': true
	}
}
```

Then omit those colors when building your theme object:

```typescript
const {
	'light-violet': _,
	'light-blue': __,
	'light-green': ___,
	'light-red': ____,
	...kept
} = DEFAULT_THEME.colors.light
```

Colors that are absent from every registered theme are removed from the color style and won't appear in the style panel. The UI colors listed in [`TLThemeUiColorKeys`](/reference/tlschema/TLThemeUiColorKeys) cannot be removed.

## Using themes in shape utils

For built-in shapes, override how theme colors are applied using `getCustomDisplayValues` on a configured shape util. The `theme` and `colorMode` parameters provide the theme definition and active color mode for the current context (which may differ from the editor's active theme during SVG export):

```typescript
import { GeoShapeUtil, type GeoShapeUtilDisplayValues } from 'tldraw'

const CustomGeoShapeUtil = GeoShapeUtil.configure({
	getCustomDisplayValues(_editor, shape, theme, colorMode): Partial<GeoShapeUtilDisplayValues> {
		if (shape.isLocked) {
			return { fillColor: theme.colors[colorMode].red.solid }
		}

		return {}
	},
})
```

Frame, note, and highlight shapes read their colors from the theme's color palette. To customize them, override the relevant color variants in your theme definition:

```typescript
import { DEFAULT_THEME, TLTheme } from 'tldraw'

const myTheme: TLTheme = {
	...DEFAULT_THEME,
	id: 'custom',
	colors: {
		light: {
			...DEFAULT_THEME.colors.light,
			noteBorder: '#A5D6A7',
			black: {
				...DEFAULT_THEME.colors.light.black,
				noteFill: '#E8F5E9', // green-tinted notes
				noteText: '#1B5E20',
			},
			blue: {
				...DEFAULT_THEME.colors.light.blue,
				noteFill: '#E3F2FD',
				noteText: '#0D47A1',
			},
			// ... other colors
		},
		dark: DEFAULT_THEME.colors.dark,
	},
}
```

The same approach works for frame colors (`frameFill`, `frameStroke`, `frameHeadingFill`, `frameHeadingStroke`, `frameText`) and highlight colors (`highlightSrgb`, `highlightP3`).

For custom shapes, call `this.editor.getCurrentTheme()` or `useEditor().getCurrentTheme()` directly in your `component` and `indicator` methods:

```tsx
class MyShapeUtil extends ShapeUtil<MyShape> {
	component(shape: MyShape) {
		const theme = this.editor.getCurrentTheme()
		const colors = theme.colors[this.editor.getColorMode()]
		const color = getColorValue(colors, shape.props.color, 'solid')

		return (
			<HTMLContainer>
				<div style={{ color }}>Hello</div>
			</HTMLContainer>
		)
	}
}
```

## Editor API reference

| Method                        | Description                                       |
| ----------------------------- | ------------------------------------------------- |
| [`Editor.getCurrentTheme`](/reference/editor/Editor#getCurrentTheme)   | Get the current theme definition                  |
| [`Editor.getCurrentThemeId`](/reference/editor/Editor#getCurrentThemeId) | Get the id of the current theme                   |
| [`Editor.setCurrentTheme`](/reference/editor/Editor#setCurrentTheme)   | Set the current theme by id                       |
| [`Editor.getThemes`](/reference/editor/Editor#getThemes)         | Get all registered themes                         |
| [`Editor.getTheme`](/reference/editor/Editor#getTheme)          | Get a theme by id                                 |
| [`Editor.updateTheme`](/reference/editor/Editor#updateTheme)       | Register or update a theme (keyed by `id`)        |
| [`Editor.updateThemes`](/reference/editor/Editor#updateThemes)      | Replace all themes or update via callback         |
| [`Editor.getColorMode`](/reference/editor/Editor#getColorMode)      | Get the active color mode (`'light'` or `'dark'`) |
| [`Editor.setColorMode`](/reference/editor/Editor#setColorMode)      | Set the color mode (`'light'` or `'dark'`)        |

These methods delegate to an internal [`ThemeManager`](/reference/editor/ThemeManager).

## Related examples

- [Custom theme](/examples/ui/custom-theme) - Add a custom color, and adjust theme values with sliders.
- [Changing default colors](/examples/ui/changing-default-colors) - Customize the default theme's color palette.
- [Multiple themes](/examples/ui/multiple-themes) - Register several themes and switch between them.
- [Display options](/examples/configuration/display-options) - Override how built-in shapes render using `getCustomDisplayValues`.

--------

# Ticks

The tick system provides a frame-synchronized update loop for the editor. On every animation frame the editor emits a `frame` event and then a `tick` event, each with the elapsed time in milliseconds since the last frame.

While pointer and keyboard events fire in response to user input, tick events fire continuously. Use them when you need updates that run every frame regardless of user interaction.

> The editor emits `frame` first so its own bookkeeping (pointer velocity, following a collaborator) runs before `tick` handlers. Use `tick` in application code.

## Subscribing to tick events

The most common way to use ticks is by subscribing to the `tick` event on the editor. The callback receives the elapsed time in milliseconds since the last frame:

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

export default function TickExample() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					const handleTick = (elapsed: number) => {
						// elapsed is typically ~16ms at 60fps
						updateAnimation(elapsed)
					}

					editor.on('tick', handleTick)

					// Clean up when done
					return () => editor.off('tick', handleTick)
				}}
			/>
		</div>
	)
}
```

Remember to unsubscribe when your component unmounts or when you no longer need tick updates. Scale movement by `elapsed` rather than assuming a fixed framerate. For one-off work on the next frame, use `editor.timers.requestAnimationFrame`, which is cleaned up when the editor is disposed.

## Tick events in tools

When building custom tools using the state machine pattern, you can handle tick events by implementing the `onTick` method on your [`StateNode`](/reference/editor/StateNode). The editor dispatches tick events through the state tree after flushing any pending pointer events for that frame, so your active tool states receive them automatically:

```typescript
import { StateNode, TLTickEventInfo } from 'tldraw'

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

	override onTick({ elapsed }: TLTickEventInfo) {
		// Update something every frame while this state is active
		this.updateDragPosition(elapsed)
	}

	private updateDragPosition(elapsed: number) {
		// Your frame-based logic here
	}
}
```

[`TLTickEventInfo`](/reference/editor/TLTickEventInfo) contains the elapsed time in milliseconds.

## Edge scrolling example

The most common use of `onTick` in tools is edge scrolling during drag operations. When you drag near the edge of the viewport, the canvas scrolls automatically. Here's how tldraw's built-in `Translating` state handles it:

```typescript
import { StateNode, TLTickEventInfo } from 'tldraw'

export class Translating extends StateNode {
	static override id = 'translating'

	override onTick({ elapsed }: TLTickEventInfo) {
		const { editor } = this
		if (!editor.inputs.getIsDragging() || editor.inputs.getIsPanning()) return
		editor.edgeScrollManager.updateEdgeScrolling(elapsed)
	}
}
```

The [`EdgeScrollManager`](/reference/editor/EdgeScrollManager) accumulates elapsed time to create a smooth acceleration effect. After a short delay, scrolling begins slowly and speeds up the longer you hold near the edge.

For more details on edge scrolling, see the [edge scrolling](/sdk-features/edge-scrolling) documentation.

## How the editor uses ticks internally

The editor uses tick and frame events for several internal features.

The [`ScribbleManager`](/reference/editor/ScribbleManager) animates the trails you see while erasing, using the laser pointer, or scribble-selecting. On each tick it adds new points to active scribbles and shrinks them from the tail, so the trail fades.

The [`InputsManager`](/reference/editor/InputsManager) computes pointer velocity on each `frame` event. Read it with `editor.inputs.getPointerVelocity()`; the select tool uses it to decide when to snap or drop into a container.

Camera methods like `editor.zoomIn()` and `editor.zoomToFit()` animate when you pass an `animation` option. The animation subscribes to `tick` for its duration and unsubscribes when complete.

## When to use tick events

Tick events are appropriate when you need continuous updates that run every frame:

- Animations and interpolation that should run regardless of user input
- Edge scrolling during drag operations
- Physics simulations or particle systems
- Debouncing based on frame counts rather than timeouts

Don't use tick events for responding to user input. Pointer, keyboard, and wheel events are better for that since they fire immediately when the user acts. Tick events add a frame of latency.

## Related

- [Events](/sdk-features/events) - Overview of all editor events including tick
- [Edge scrolling](/sdk-features/edge-scrolling) - Detailed documentation on edge scrolling behavior
- [Snowstorm example](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/use-cases/snowstorm) - Uses tick events to animate falling snowflakes

--------

# Tools

Tools in tldraw define how the editor responds to user input. Each tool handles one interaction mode: selecting shapes, drawing, panning the canvas. The editor has a single active tool at any time and routes all input events through it. When you click the hand icon in the toolbar, the editor transitions from the select tool to the hand tool, and the canvas starts responding to drags by panning.

You implement tools as state machines using the [`StateNode`](/reference/editor/StateNode) class. Multi-step interactions map onto child states: when you resize a shape with the select tool, the tool moves through `idle`, `pointing_resize_handle`, and `resizing`. Each state handles different events and can transition to other states.

## How it works

Tools are organized in a hierarchical state machine where each node can handle events and contain child states. The editor creates a root state that contains all tools as children. When an input event occurs, it flows down from the root through the currently active tool and its active child state.

Each state node has an id, optional children, and methods for handling events. State nodes come in three types: root nodes that contain tools, branch nodes that have child states, and leaf nodes that perform actual work. Tools themselves are typically branch nodes with child states representing different phases of an interaction.

When a state becomes active, its `onEnter` method runs. When it becomes inactive, its `onExit` method runs. Between these lifecycle events, the state handles input through event methods like `onPointerDown`, `onPointerMove`, and `onKeyDown`. A state that doesn't implement a handler skips the event, and the event still continues down to the active child state, so a parent and its child can both respond.

You trigger transitions between states explicitly through [`StateNode.transition`](/reference/editor/StateNode#transition). When the select tool's idle state detects a pointer down on a shape, it calls `this.parent.transition('pointing_shape', info)` to move to the pointing state. The transition runs the old state's `onExit` and the new state's `onEnter`.

## Key concepts

### State hierarchy

Tools exist in a tree structure starting from a root node. The root contains all available tools like select, hand, eraser, and draw. Each tool can contain child states for different phases of its interaction. For example, the select tool has children including `idle`, `pointing_shape`, `translating`, `resizing`, and `rotating`. When the select tool is active and the user starts dragging a shape, the active path becomes `select.translating`.

The hierarchy lets a tool share behavior across its child states. The select tool's `onEnter` and `onExit` set up and tear down state that every child uses, while the child states handle pointer and keyboard interactions.

### Event handling

State nodes implement event handler methods that match input event types. The handlers receive an info object containing event details like pointer position, keyboard modifiers, and the event target. The full set is `onPointerDown`, `onPointerMove`, `onPointerUp`, `onLongPress`, `onDoubleClick`, `onRightClick`, `onMiddleClick`, `onKeyDown`, `onKeyUp`, `onKeyRepeat`, `onWheel`, `onCancel`, `onComplete`, `onInterrupt`, and `onTick` for animation frame updates.

The hand tool's dragging state implements `onPointerMove` to update the camera position as the user drags.

### State transitions

You can transition to a direct child using just its id, or to deeper descendants using dot notation like `'crop.pointing_crop_handle'`.

Transitions carry information through their second parameter. When transitioning from idle to pointing, the pointer event info passes along so the pointing state knows where the interaction started. This data is available in both the exit handler of the old state and the enter handler of the new state.

### Tool registration

Tools are registered with the editor through the root state. The `@tldraw/editor` package provides only the root state with no tools. The `tldraw` package adds its full suite of tools. Custom tools are added through the `tools` prop, described below.

[`Editor.setCurrentTool`](/reference/editor/Editor#setCurrentTool) transitions the root state to a different tool by id. [`Editor.getCurrentTool`](/reference/editor/Editor#getCurrentTool) returns the active tool state node, and [`Editor.getCurrentToolId`](/reference/editor/Editor#getCurrentToolId) returns its id.

### Event targets

Event info objects include a `target` property indicating what the user interacted with: `canvas`, `shape`, `handle`, `selection`, or `overlay`. The canvas dispatches every pointer event with `target: 'canvas'`. The select tool's idle state hit-tests the pointer position and re-dispatches the event to itself with a more specific target, then transitions to the matching child state: `pointing_shape` for a shape, `pointing_canvas` for empty canvas.

Custom tools that need to know what's under the pointer do their own hit testing with methods like [`Editor.getShapeAtPoint`](/reference/editor/Editor#getShapeAtPoint).

### Tool lock

Tool lock keeps the current tool active after completing an action. Normally, tools like geo, arrow, or note return to the select tool after creating a shape. With tool lock enabled, the tool stays active so you can create multiple shapes without reselecting the tool each time.

Tool lock is stored in instance state:

```ts
// Check if tool lock is enabled
editor.getInstanceState().isToolLocked

// Enable tool lock
editor.updateInstanceState({ isToolLocked: true })

// Toggle tool lock
const current = editor.getInstanceState().isToolLocked
editor.updateInstanceState({ isToolLocked: !current })
```

Tool lock is not enforced by the state machine. Custom tools check `isToolLocked` themselves when deciding where to go after completing their action:

```ts
if (this.editor.getInstanceState().isToolLocked) {
	this.parent.transition('idle')
} else {
	this.editor.setCurrentTool('select')
}
```

## Creating custom tools

To create a custom tool, extend the [`StateNode`](/reference/editor/StateNode) class and implement the static properties and event handlers you need. The simplest tool has no child states and handles events directly. Register it with the `tools` prop:

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

class MeasureTool extends StateNode {
	static override id = 'measure'

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

	override onPointerDown(info: TLPointerEventInfo) {
		const start = this.editor.inputs.getCurrentPagePoint()
		// Start measuring from this point
	}

	override onPointerUp(info: TLPointerEventInfo) {
		// Finalize measurement and return to select tool
		this.editor.setCurrentTool('select')
	}
}

const customTools = [MeasureTool]

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

Define the tools array once, outside the component or in a `useMemo`, so the editor isn't recreated on each render.

The `StateNode` class has these static properties:

| Property             | Description                                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | Required. The unique identifier for this state                                                                                                        |
| `initial`            | The id of the initial child state (required if the tool has children)                                                                                 |
| `children()`         | A function returning an array of child state constructors                                                                                             |
| `isLockable`         | Whether the toolbar shows the tool-lock toggle while this tool is active (default: `true`). The tool itself still has to check `isToolLocked`.        |
| `useCoalescedEvents` | Whether to receive the browser's coalesced pointer move events for higher-fidelity input, as the draw tool does (default: `false`; always off on iOS) |

Tools with multiple phases use child states. A tool with children sets `initial` and `children()`:

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

export class StampTool extends StateNode {
	static override id = 'stamp'
	static override initial = 'idle'
	static override children() {
		return [StampIdle, StampPointing]
	}
}
```

Child states follow the same pattern but focus on specific phases of the interaction. A drawing tool might have idle, pointing, and drawing states. The pointing state waits to see if the user is clicking or starting a drag, then transitions accordingly:

```typescript
export class DrawingPointing extends StateNode {
	static override id = 'pointing'

	override onPointerMove(info: TLPointerEventInfo) {
		if (this.editor.inputs.getIsDragging()) {
			this.parent.transition('drawing', info)
		}
	}

	override onPointerUp(info: TLPointerEventInfo) {
		this.parent.transition('idle', info)
	}
}
```

Access the editor through `this.editor` to read input state, manipulate shapes, or transition tools. Access the parent state through `this.parent` to transition between sibling states.

## Overriding default tools

You can remove tools from the UI, add custom tools to it, or register and unregister tools at runtime.

### Removing tools from the toolbar

Use the `overrides` prop ([`TLUiOverrides`](/reference/tldraw/TLUiOverrides)) to modify which tools appear in the UI. The `tools` function receives the current tools object and returns a modified version:

```typescript
import { Tldraw, TLUiOverrides } from 'tldraw'

const overrides: TLUiOverrides = {
	tools(editor, tools, helpers) {
		// Remove the text tool from the toolbar
		delete tools.text
		return tools
	},
}

function App() {
	return <Tldraw overrides={overrides} />
}
```

This removes the tool from the toolbar, its keyboard shortcut, and the menus, since all of them read from the same tools object. It doesn't remove the tool from the editor's state machine: `editor.setCurrentTool('text')` still works.

### Adding custom tools to the toolbar

When you create a custom tool, you need to add it both to the editor's state machine and to the UI. The `tools` prop registers the tool with the state machine, while `overrides.tools` adds a [`TLUiToolItem`](/reference/tldraw/TLUiToolItem) to the UI context. The `kbd` you set here is what registers the keyboard shortcut:

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

class MyTool extends StateNode {
	static override id = 'my-tool'
	// ... implementation
}

const overrides: TLUiOverrides = {
	tools(editor, tools, helpers) {
		tools['my-tool'] = {
			id: 'my-tool',
			icon: 'my-icon',
			label: 'My Tool',
			kbd: 'm',
			onSelect: () => editor.setCurrentTool('my-tool'),
		}
		return tools
	},
}

function App() {
	return <Tldraw tools={[MyTool]} overrides={overrides} />
}
```

The `icon` is a key into the UI's asset URLs; a custom icon needs an `assetUrls` override, or you can reuse a built-in icon name. To make the tool appear in the toolbar, override the `Toolbar` component and include your tool item. See the [add a tool to the toolbar example](/examples/ui/add-tool-to-toolbar) for the complete implementation.

### Dynamic tool registration

Tools can be added or removed at runtime using [`Editor.setTool`](/reference/editor/Editor#setTool) and [`Editor.removeTool`](/reference/editor/Editor#removeTool). This is useful when tool availability depends on user permissions, feature flags, or application state.

```tsx
import { useState } from 'react'
import { Editor, StateNode, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

class HeartTool extends StateNode {
	static override id = 'heart'
	override onPointerDown() {
		// Create a heart shape at click position
	}
}

function App() {
	const [editor, setEditor] = useState<Editor | null>(null)
	const [isEnabled, setIsEnabled] = useState(false)

	const toggleTool = () => {
		if (!editor) return
		if (isEnabled) {
			// Switch away first if currently using the tool
			if (editor.getCurrentToolId() === 'heart') {
				editor.setCurrentTool('select')
			}
			editor.removeTool(HeartTool)
		} else {
			editor.setTool(HeartTool)
		}
		setIsEnabled(!isEnabled)
	}

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw onMount={setEditor} />
			<button style={{ position: 'absolute', top: 64, left: 8, zIndex: 1000 }} onClick={toggleTool}>
				{isEnabled ? 'Remove heart tool' : 'Add heart tool'}
			</button>
		</div>
	)
}
```

When removing a tool, check whether the user is currently using it. If so, transition to a different tool like select to avoid leaving the editor in an invalid state. `setTool` throws if a tool with the same id is already registered.

## Related examples

- [Custom tool (sticker)](/examples/shapes/tools/custom-tool) - A tool that adds a heart sticker to the canvas when you click.
- [Custom tool with child states](/examples/shapes/tools/tool-with-child-states) - The sticker tool rebuilt with idle, pointing, and dragging child states.
- [Screenshot tool](/examples/shapes/tools/screenshot-tool) - Drag a box on the canvas and export it as an image.
- [Lasso select tool](/examples/editor-api/lasso-select-tool) - A freehand selection tool built with reactive atoms and overlays.
- [Add a tool to the toolbar](/examples/ui/add-tool-to-toolbar) - Put a custom tool in the toolbar and keyboard shortcuts dialog with custom assets.
- [Remove a tool from the toolbar](/examples/ui/remove-tool) - Remove a default tool with UI overrides.
- [Dynamic tools with setTool and removeTool](/examples/editor-api/dynamic-tools) - Add and remove tools from the state chart after initialization.

--------

# UI components

The `tldraw` package includes a complete React-based UI: the menus, toolbars, panels, and dialogs that users interact with when creating and editing content. The UI is composed of named component slots that you can override or hide one at a time.

The UI connects to the editor through React hooks and context providers. Components update automatically when editor state changes, so you can replace individual parts of the interface without reimplementing the logic that connects UI actions to editor operations.

## How it works

### Component slot architecture

The UI divides the screen into distinct layout zones:

```
┌─────────────────────────────────────────────────────────┐
│                    Top Panel                             │
├────────────┬──────────────────────────┬─────────────────┤
│   Left     │         Canvas           │     Right       │
│   Panel    │                          │     Panel       │
├────────────┴──────────────────────────┴─────────────────┤
│                   Bottom Panel                           │
└─────────────────────────────────────────────────────────┘
```

The top zone contains the main menu, helper buttons (like "Back to content"), an empty top panel slot, and the share and style panels. The bottom zone houses navigation controls, the main toolbar with drawing tools, and the help menu (if you provide one). On desktop, the style panel appears in the top-right zone; on mobile it moves into a popover opened from the toolbar.

Each zone can host multiple components. The toolbar includes the tool selector, tool-specific options, and the tool lock button.

### Context providers and state management

The UI establishes a hierarchy of React context providers. At the root, [`TldrawUiContextProvider`](/reference/tldraw/TldrawUiContextProvider) coordinates the other providers and applies your overrides. Specialized providers handle translations, tooltips, dialogs, toasts, UI events, accessibility announcements, breakpoints for responsive behavior, and the component registry.

The actions and tools providers turn editor methods into UI actions with labels, icons, and keyboard shortcuts. When you click a toolbar button, the component calls an action from context, which invokes the editor method. The same action can be triggered from the toolbar, a menu, or a keyboard shortcut. See [Actions](/sdk-features/actions) for details.

### Reactive UI updates

UI components read editor state through hooks like [`useEditor`](/reference/editor/useEditor) and [`useValue`](/reference/state-react/useValue). These hooks use the editor's reactive signal system to re-render when relevant state changes. The style panel uses [`useRelevantStyles`](/reference/tldraw/useRelevantStyles) to decide which style controls to show for the current selection: select a different shape and the panel updates.

## Key components

### Component slots

The UI defines several component slots you can override or hide. The `Toolbar` holds the tool buttons. The `TopPanel` is an empty top-center slot with no default component; use it for your own UI like a document title or sync status. The `StylePanel` shows style controls for the selected shapes. The `MenuPanel` (top-left) groups the main menu, the page menu, and quick actions. The `NavigationPanel` (bottom-left) provides zoom controls and the minimap toggle. `HelperButtons` appear based on editor state, such as "Back to content" when the camera is far from shapes.

Each slot is optional. Pass `null` to hide a component, or pass your own React component to replace the default. A few slots have no default: `TopPanel` and `HelpMenu` are `null` unless you provide a component (use [`DefaultHelpMenu`](/reference/tldraw/DefaultHelpMenu) to opt in to the built-in help menu), and `SharePanel` and `CursorChatBubble` only render when collaboration UI is enabled.

### Slot props

The UI portion of the `components` prop is shaped by [`TLUiComponents`](/reference/tldraw/TLUiComponents). Every key is optional: use `null` to hide that slot, or pass a React component. When a slot has a documented props type in the table below, import that type from `tldraw` and type your replacement as `React.ComponentType<…>` (or implement the matching props). When the props column says **none**, the SDK does not declare extra props for that slot beyond what a plain `ComponentType` allows.

| Slot                      | Props (import from `tldraw`)                                                  |
| ------------------------- | ----------------------------------------------------------------------------- |
| `ContextMenu`             | [`TLUiContextMenuProps`](/reference/tldraw/TLUiContextMenuProps)                                                     |
| `ActionsMenu`             | [`TLUiActionsMenuProps`](/reference/tldraw/TLUiActionsMenuProps)                                                     |
| `HelpMenu`                | [`TLUiHelpMenuProps`](/reference/tldraw/TLUiHelpMenuProps)                                                        |
| `ZoomMenu`                | [`TLUiZoomMenuProps`](/reference/tldraw/TLUiZoomMenuProps)                                                        |
| `MainMenu`                | [`TLUiMainMenuProps`](/reference/tldraw/TLUiMainMenuProps)                                                        |
| `Minimap`                 | none                                                                          |
| `StylePanel`              | [`TLUiStylePanelProps`](/reference/tldraw/TLUiStylePanelProps)                                                      |
| `PageMenu`                | none                                                                          |
| `NavigationPanel`         | none                                                                          |
| `Toolbar`                 | none                                                                          |
| `RichTextToolbar`         | [`TLUiRichTextToolbarProps`](/reference/tldraw/TLUiRichTextToolbarProps)                                                 |
| `ImageToolbar`            | none                                                                          |
| `VideoToolbar`            | none                                                                          |
| `KeyboardShortcutsDialog` | [`TLUiKeyboardShortcutsDialogProps`](/reference/tldraw/TLUiKeyboardShortcutsDialogProps)                                         |
| `QuickActions`            | [`TLUiQuickActionsProps`](/reference/tldraw/TLUiQuickActionsProps)                                                    |
| `HelperButtons`           | [`TLUiHelperButtonsProps`](/reference/tldraw/TLUiHelperButtonsProps)                                                   |
| `DebugPanel`              | none                                                                          |
| `DebugMenu`               | none                                                                          |
| `MenuPanel`               | none                                                                          |
| `TopPanel`                | none                                                                          |
| `SharePanel`              | none                                                                          |
| `CursorChatBubble`        | none                                                                          |
| `Dialogs`                 | none                                                                          |
| `Toasts`                  | none                                                                          |
| `A11y`                    | none                                                                          |
| `FollowingIndicator`      | none                                                                          |
| `PeopleMenu`              | none (default component: optional `children` via [`DefaultPeopleMenuProps`](/reference/tldraw/DefaultPeopleMenuProps)) |
| `PeopleMenuAvatar`        | [`TLUiPeopleMenuAvatarProps`](/reference/tldraw/TLUiPeopleMenuAvatarProps)                                                |
| `PeopleMenuFacePile`      | [`TLUiPeopleMenuFacePileProps`](/reference/tldraw/TLUiPeopleMenuFacePileProps)                                              |
| `PeopleMenuItem`          | [`TLUiPeopleMenuItemProps`](/reference/tldraw/TLUiPeopleMenuItemProps)                                                  |
| `UserPresenceEditor`      | none                                                                          |

This table is an index; the authoritative list and types remain [`TLUiComponents`](/reference/tldraw/TLUiComponents) in the API reference and in the package typings.

### UI hooks

Components access editor functionality through specialized hooks.

[`useEditor`](/reference/editor/useEditor) returns the editor instance, with direct access to all editor methods and state.

[`useActions`](/reference/tldraw/useActions) returns the UI actions (copy, paste, delete, and so on) with their labels, icons, and keyboard shortcuts. Call an action's `onSelect` from your custom UI.

[`useTools`](/reference/tldraw/useTools) returns the available tools with their metadata. The toolbar uses this to render tool buttons.

[`useRelevantStyles`](/reference/tldraw/useRelevantStyles) returns the styles relevant to the current selection and their values. It powers the style panel.

[`useBreakpoint`](/reference/tldraw/useBreakpoint) returns a numeric breakpoint index (0-7) matching the [`PORTRAIT_BREAKPOINT`](/reference/tldraw/PORTRAIT_BREAKPOINT) constants. Compare against values like `PORTRAIT_BREAKPOINT.MOBILE` or `PORTRAIT_BREAKPOINT.TABLET_SM` to adapt layout for different screen sizes.

## Hiding the UI

You can hide the default tldraw user interface entirely using the `hideUi` prop. This hides the visual UI only: keyboard shortcuts and clipboard handling keep working.

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

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

With the UI hidden, you can still control the editor programmatically through [`Editor`](/reference/editor/Editor) methods. Open the console and try:

```ts
editor.setCurrentTool('draw')
```

All of tldraw's user interface works by controlling the editor via its methods. If you hide the user interface, you can still use these same methods to control the editor. See the [custom user interface example](/examples/ui/custom-ui) for this in action.

## Extension points

### Overriding components

Override individual components by passing them to the `components` prop:

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

function CustomToolbar() {
	const editor = useEditor()
	const tools = useTools()

	return (
		<div className="my-toolbar">
			{Object.values(tools).map((tool) => (
				<button key={tool.id} onClick={() => editor.setCurrentTool(tool.id)}>
					{tool.label}
				</button>
			))}
		</div>
	)
}

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

The `useTools` hook returns an object mapping tool IDs to [`TLUiToolItem`](/reference/tldraw/TLUiToolItem) objects. Each tool item contains metadata like `id`, `label`, `icon`, and `kbd` (keyboard shortcut).

### Hiding components

Pass `null` to hide a component entirely. This is useful for focused experiences that don't need the full default UI:

```tsx
<Tldraw
	components={{
		PageMenu: null,
		DebugMenu: null,
		NavigationPanel: null,
	}}
/>
```

See the [UI components hidden example](/examples/ui/ui-components-hidden) for a complete list of hideable components.

## Overrides

Control tldraw's actions, tools, and translations with the `overrides` prop. This prop accepts a [`TLUiOverrides`](/reference/tldraw/TLUiOverrides) object, which has methods for `actions` and `tools`, and a `translations` property.

### Actions

The user interface has a set of shared actions used in the menus and keyboard shortcuts. Override these by providing an `actions` method that receives the editor, the [default actions](https://github.com/tldraw/tldraw/blob/main/packages/tldraw/src/lib/ui/context/actions.tsx), and a helpers object, then returns a mutated actions object. See [Actions](/sdk-features/actions) for the full story.

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

const myOverrides: TLUiOverrides = {
	actions(editor, actions, helpers) {
		// Delete an action (remember to also delete any menu items that reference it)
		delete actions['insert-embed']

		// Create a new action or replace an existing one
		actions['my-new-action'] = {
			id: 'my-new-action',
			label: 'My new action',
			readonlyOk: true,
			kbd: 'cmd+shift+u,ctrl+shift+u',
			onSelect(source) {
				window.alert('My new action just happened!')
			},
		}
		return actions
	},
}

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

The `actions` object is a map of [`TLUiActionItem`](/reference/tldraw/TLUiActionItem)s, keyed by their `id`. See the [action overrides example](/examples/ui/action-overrides) for more.

### Tools

Override tools the same way you override actions. Provide a `tools` method that accepts the editor, the [default tools object](https://github.com/tldraw/tldraw/blob/main/packages/tldraw/src/lib/ui/hooks/useTools.tsx), and a helpers object, then returns a mutated version.

```tsx
const myOverrides: TLUiOverrides = {
	tools(editor, tools, helpers) {
		// Create a tool item in the UI's context
		tools.card = {
			id: 'card',
			icon: 'geo-rectangle',
			label: 'tools.card',
			kbd: 'c',
			onSelect: () => {
				editor.setCurrentTool('card')
			},
		}
		return tools
	},
}
```

The `tools` object is a map of [`TLUiToolItem`](/reference/tldraw/TLUiToolItem)s, keyed by their `id`. See the [add tool to toolbar example](/examples/ui/add-tool-to-toolbar) for a complete implementation.

### Translations

The `translations` property accepts a table of new translations. If you add a tool with `label: 'tools.card'`, you need to provide an English translation for that key:

```tsx
const myOverrides: TLUiOverrides = {
	translations: {
		en: {
			'tools.card': 'Card',
		},
	},
}
```

See [internationalization](/sdk-features/internationalization) for more about tldraw's translation system.

## UI events

The [`Tldraw`](/reference/tldraw/Tldraw) component has an `onUiEvent` prop that fires when users interact with the UI:

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

export default function App() {
	const handleUiEvent: TLUiEventHandler = (name, data) => {
		console.log('UI event:', name, data)
	}

	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw onUiEvent={handleUiEvent} />
		</div>
	)
}
```

The callback receives the event name as a string and an object with the event's `source` (e.g. `menu` or `context-menu`) and other data specific to each event, such as the `operation` in an `align-shapes` event.

Note that `onUiEvent` only fires for UI interactions. Calling [`Editor.alignShapes`](/reference/editor/Editor#alignShapes) directly won't trigger this callback. See the [UI events example](/examples/events/ui-events) for more.

## Related articles

- [UI primitives](/sdk-features/ui-primitives) - Use tldraw's button, menu, dialog, and other UI components in your custom interfaces
- [Overlay utils](/sdk-features/overlay-utils) - Customize canvas overlays like brushes, indicators, snaps, scribbles, and collaborator cursors
- [Internationalization](/sdk-features/internationalization) - Customize translations and add new languages
- [Tools](/sdk-features/tools) - Learn how tools work and create your own

## Related examples

- [Replace the entire UI](/examples/ui/custom-ui) - Build a completely custom toolbar UI while using the editor's functionality
- [Custom canvas components](/examples/ui/custom-components) - Override individual canvas components like the background and grid
- [Hide the entire UI](/examples/ui/hide-ui) - Use hideUi to hide the entire default interface
- [Hide UI components](/examples/ui/ui-components-hidden) - Selectively hide specific UI components
- [Changing menus](/examples/ui/custom-menus) - Create custom menus using tldraw's menu system
- [Vertical toolbar](/examples/ui/vertical-toolbar) - Switch to a vertical toolbar layout
- [Add tool to toolbar](/examples/ui/add-tool-to-toolbar) - Add a custom tool to the toolbar
- [UI events](/examples/events/ui-events) - Listen to UI events like tool selection and menu interactions

--------

# UI primitives

The `tldraw` package exports a set of UI primitive components that you can use when building custom interfaces. These components match the look and feel of tldraw's default UI and integrate with the editor's theming, translations, and accessibility features.

Use these primitives when you want your custom UI to feel like a natural part of tldraw rather than something bolted on. See the [UI primitives example](/examples/ui/ui-primitives) for all of them in one place.

## Buttons

The button system consists of [`TldrawUiButton`](/reference/tldraw/TldrawUiButton) and its companion components for icons, labels, and check indicators.

### TldrawUiButton

The base button component with several visual variants:

```tsx
import { TldrawUiButton, TldrawUiButtonIcon, TldrawUiButtonLabel } from 'tldraw'

function MyButtons() {
	return (
		<>
			<TldrawUiButton type="normal" onClick={() => console.log('clicked')}>
				<TldrawUiButtonLabel>Normal</TldrawUiButtonLabel>
			</TldrawUiButton>

			<TldrawUiButton type="primary" onClick={() => console.log('clicked')}>
				<TldrawUiButtonLabel>Primary</TldrawUiButtonLabel>
			</TldrawUiButton>

			<TldrawUiButton type="danger" onClick={() => console.log('clicked')}>
				<TldrawUiButtonLabel>Danger</TldrawUiButtonLabel>
			</TldrawUiButton>

			<TldrawUiButton type="icon" onClick={() => console.log('clicked')}>
				<TldrawUiButtonIcon icon="plus" />
			</TldrawUiButton>
		</>
	)
}
```

The `type` prop controls the button's appearance:

| Type      | Description                              |
| --------- | ---------------------------------------- |
| `normal`  | Standard button for general actions      |
| `primary` | Emphasized button for primary actions    |
| `danger`  | Red button for destructive actions       |
| `low`     | Subtle button with minimal visual weight |
| `icon`    | Square button sized for a single icon    |
| `tool`    | Tool button style used in the toolbar    |
| `menu`    | Button style used inside menus           |
| `help`    | Style used for help/info buttons         |

Use `isActive` to indicate a selected or active state, and `tooltip` to show a tooltip on hover:

```tsx
<TldrawUiButton type="tool" isActive={true} tooltip="Draw">
	<TldrawUiButtonIcon icon="tool-pencil" />
</TldrawUiButton>
```

### Button sub-components

Build up button contents using these components:

```tsx
import { TldrawUiButton, TldrawUiButtonIcon, TldrawUiButtonLabel, TldrawUiButtonCheck } from 'tldraw'

// Icon button
<TldrawUiButton type="icon">
	<TldrawUiButtonIcon icon="trash" />
</TldrawUiButton>

// Button with icon and label
<TldrawUiButton type="menu">
	<TldrawUiButtonIcon icon="plus" />
	<TldrawUiButtonLabel>Add item</TldrawUiButtonLabel>
</TldrawUiButton>

// Button with checkmark (for toggles in menus)
<TldrawUiButton type="menu">
	<TldrawUiButtonCheck checked={true} />
	<TldrawUiButtonLabel>Show grid</TldrawUiButtonLabel>
</TldrawUiButton>
```

## Icons

[`TldrawUiIcon`](/reference/tldraw/TldrawUiIcon) renders icons from tldraw's icon set. Icons are SVG masks filled with the current text color.

```tsx
import { TldrawUiIcon } from 'tldraw'

<TldrawUiIcon icon="tool-pencil" label="Draw tool" />
<TldrawUiIcon icon="arrow-left" label="Go back" small />
<TldrawUiIcon icon="check" label="Complete" color="green" />
```

The `label` prop is required for accessibility—it becomes the icon's `aria-label`. Use `small` for a smaller icon size.

You can also pass a custom React element instead of an icon name:

```tsx
<TldrawUiIcon icon={<div className="my-custom-icon">★</div>} label="Favorite" />
```

## Menu primitives

When adding items to tldraw's menus, use these components to match the default menu styling and behavior. Menu primitives read a menu context to decide how to render, so they must be placed inside one of tldraw's menus (for example a custom `MainMenu` or `ContextMenu` component) or wrapped in a [`TldrawUiMenuContextProvider`](/reference/tldraw/TldrawUiMenuContextProvider). See the [custom menus example](/examples/ui/custom-menus).

### TldrawUiMenuItem

[`TldrawUiMenuItem`](/reference/tldraw/TldrawUiMenuItem) is the main component for menu items. It adapts its rendering to the menu it's in (dropdown, context menu, toolbar, and so on):

```tsx
import { TldrawUiMenuGroup, TldrawUiMenuItem } from 'tldraw'

function MyMenuGroup() {
	return (
		<TldrawUiMenuGroup id="my-actions">
			<TldrawUiMenuItem
				id="my-action"
				label="Do something"
				iconLeft="plus"
				kbd="cmd+shift+d"
				onSelect={() => {
					console.log('action triggered')
				}}
			/>
		</TldrawUiMenuGroup>
	)
}
```

The props are:

| Prop         | Description                                                                     |
| ------------ | ------------------------------------------------------------------------------- |
| `id`         | Unique identifier for the menu item                                             |
| `label`      | Display text (supports translation keys)                                        |
| `icon`       | Icon for icon-style menus and toolbars (not shown in dropdown or context menus) |
| `iconLeft`   | Icon shown on the left in dropdown and context menus                            |
| `kbd`        | Keyboard shortcut to display                                                    |
| `onSelect`   | Called when the item is clicked                                                 |
| `disabled`   | Whether the item is disabled                                                    |
| `readonlyOk` | If true, item is shown even in readonly mode                                    |
| `isSelected` | Whether the item shows as selected (for toolbar items)                          |
| `spinner`    | Show a loading spinner                                                          |
| `noClose`    | Prevent the menu from closing when clicked                                      |

### TldrawUiMenuGroup

[`TldrawUiMenuGroup`](/reference/tldraw/TldrawUiMenuGroup) groups related menu items together. In dropdown menus, groups are separated by dividers:

```tsx
<TldrawUiMenuGroup id="clipboard">
	<TldrawUiMenuItem id="cut" label="Cut" kbd="cmd+x" onSelect={handleCut} />
	<TldrawUiMenuItem id="copy" label="Copy" kbd="cmd+c" onSelect={handleCopy} />
	<TldrawUiMenuItem id="paste" label="Paste" kbd="cmd+v" onSelect={handlePaste} />
</TldrawUiMenuGroup>
```

### TldrawUiMenuSubmenu

[`TldrawUiMenuSubmenu`](/reference/tldraw/TldrawUiMenuSubmenu) creates a nested submenu:

```tsx
<TldrawUiMenuSubmenu id="export" label="Export as...">
	<TldrawUiMenuGroup id="formats">
		<TldrawUiMenuItem id="png" label="PNG" onSelect={exportPng} />
		<TldrawUiMenuItem id="svg" label="SVG" onSelect={exportSvg} />
		<TldrawUiMenuItem id="json" label="JSON" onSelect={exportJson} />
	</TldrawUiMenuGroup>
</TldrawUiMenuSubmenu>
```

### TldrawUiMenuCheckboxItem

[`TldrawUiMenuCheckboxItem`](/reference/tldraw/TldrawUiMenuCheckboxItem) is a menu item with a checkbox:

```tsx
<TldrawUiMenuCheckboxItem
	id="snap-to-grid"
	label="Snap to grid"
	checked={snapEnabled}
	onSelect={() => {
		setSnapEnabled(!snapEnabled)
	}}
/>
```

The `onSelect` callback receives a `source` parameter, a [`TLUiEventSource`](/reference/tldraw/TLUiEventSource) such as `'main-menu'` or `'context-menu'`, taken from the surrounding menu context. Ignore it if you don't need to tell sources apart.

To put an existing action or tool in a menu, use [`TldrawUiMenuActionItem`](/reference/tldraw/TldrawUiMenuActionItem) or [`TldrawUiMenuToolItem`](/reference/tldraw/TldrawUiMenuToolItem) with the action or tool id; they fill in the label, icon, and shortcut for you.

## Dialogs

Build modal dialogs using tldraw's dialog primitives ([`TldrawUiDialogHeader`](/reference/tldraw/TldrawUiDialogHeader), [`TldrawUiDialogTitle`](/reference/tldraw/TldrawUiDialogTitle), [`TldrawUiDialogCloseButton`](/reference/tldraw/TldrawUiDialogCloseButton), [`TldrawUiDialogBody`](/reference/tldraw/TldrawUiDialogBody), and [`TldrawUiDialogFooter`](/reference/tldraw/TldrawUiDialogFooter)) and open them with [`useDialogs`](/reference/tldraw/useDialogs). These components handle accessibility, focus management, and styling.

```tsx
import {
	TldrawUiDialogHeader,
	TldrawUiDialogTitle,
	TldrawUiDialogCloseButton,
	TldrawUiDialogBody,
	TldrawUiDialogFooter,
	TldrawUiButton,
	TldrawUiButtonLabel,
	useDialogs,
} from 'tldraw'

function MyDialog({ onClose }: { onClose(): void }) {
	return (
		<>
			<TldrawUiDialogHeader>
				<TldrawUiDialogTitle>Confirm deletion</TldrawUiDialogTitle>
				<TldrawUiDialogCloseButton />
			</TldrawUiDialogHeader>
			<TldrawUiDialogBody style={{ maxWidth: 350 }}>
				Are you sure you want to delete this item? This action cannot be undone.
			</TldrawUiDialogBody>
			<TldrawUiDialogFooter className="tlui-dialog__footer__actions">
				<TldrawUiButton type="normal" onClick={onClose}>
					<TldrawUiButtonLabel>Cancel</TldrawUiButtonLabel>
				</TldrawUiButton>
				<TldrawUiButton
					type="danger"
					onClick={() => {
						deleteItem()
						onClose()
					}}
				>
					<TldrawUiButtonLabel>Delete</TldrawUiButtonLabel>
				</TldrawUiButton>
			</TldrawUiDialogFooter>
		</>
	)
}

// Show the dialog using the useDialogs hook
function MyComponent() {
	const { addDialog } = useDialogs()

	return <button onClick={() => addDialog({ component: MyDialog })}>Delete item</button>
}
```

The `onClose` function is passed to your dialog component automatically. Call it to dismiss the dialog.

## Input

[`TldrawUiInput`](/reference/tldraw/TldrawUiInput) is a styled text input with built-in handling for Enter (confirm) and Escape (cancel):

```tsx
<TldrawUiInput
	label="Name"
	defaultValue="Untitled"
	onComplete={(value) => {
		// Called when user presses Enter
		saveName(value)
	}}
	onCancel={(value) => {
		// Called when user presses Escape
		// Value is reset to initial value
	}}
	onValueChange={(value) => {
		// Called on every keystroke
	}}
	autoSelect // Select all text on focus
	autoFocus
/>
```

Add icons to the input using `iconLeft` (left side) or `icon` (right side):

```tsx
<TldrawUiInput iconLeft="zoom-in" placeholder="Search shapes..." onValueChange={setSearchQuery} />
<TldrawUiInput icon="check" placeholder="Confirmed value" />
```

## Layout

[`TldrawUiRow`](/reference/tldraw/TldrawUiRow), [`TldrawUiColumn`](/reference/tldraw/TldrawUiColumn), and [`TldrawUiGrid`](/reference/tldraw/TldrawUiGrid) organize UI controls with proper spacing and orientation-aware tooltips.

```tsx
import { TldrawUiRow, TldrawUiColumn, TldrawUiGrid } from 'tldraw'

// Horizontal row of buttons
<TldrawUiRow>
	<TldrawUiButton type="icon"><TldrawUiButtonIcon icon="align-left" /></TldrawUiButton>
	<TldrawUiButton type="icon"><TldrawUiButtonIcon icon="align-center-horizontal" /></TldrawUiButton>
	<TldrawUiButton type="icon"><TldrawUiButtonIcon icon="align-right" /></TldrawUiButton>
</TldrawUiRow>

// Vertical column
<TldrawUiColumn>
	<TldrawUiButton type="menu"><TldrawUiButtonLabel>Option 1</TldrawUiButtonLabel></TldrawUiButton>
	<TldrawUiButton type="menu"><TldrawUiButtonLabel>Option 2</TldrawUiButtonLabel></TldrawUiButton>
</TldrawUiColumn>

// 4-column grid (useful for color pickers, shape selectors, etc.)
<TldrawUiGrid>
	{colors.map(color => (
		<TldrawUiButton key={color} type="icon" onClick={() => setColor(color)}>
			<div style={{ background: color, width: 16, height: 16 }} />
		</TldrawUiButton>
	))}
</TldrawUiGrid>
```

These components set up an orientation context. By default, tooltips appear below items in rows and to the right of items in columns; nested layouts inherit the side until the orientation changes. Pass `tooltipSide` to override it.

## Other primitives

### TldrawUiKbd

[`TldrawUiKbd`](/reference/tldraw/TldrawUiKbd) displays a keyboard shortcut using platform-specific symbols. It is hidden on small mobile breakpoints unless you pass `visibleOnMobileLayout`:

```tsx
<TldrawUiKbd>cmd+shift+d</TldrawUiKbd>
```

### TldrawUiSlider

[`TldrawUiSlider`](/reference/tldraw/TldrawUiSlider) is a slider control with discrete integer steps rather than a continuous range:

```tsx
<TldrawUiSlider
	title="Opacity"
	label="style-panel.opacity"
	value={5}
	steps={10}
	onValueChange={(value) => console.log(value)}
/>
```

The props are:

| Prop            | Description                                                          |
| --------------- | -------------------------------------------------------------------- |
| `title`         | Title text, combined with the label for the tooltip and `aria-label` |
| `label`         | Translation key for the label                                        |
| `value`         | Current value (`min` to `steps`), or `null`                          |
| `steps`         | Maximum value                                                        |
| `min`           | Optional minimum value (defaults to 0)                               |
| `onValueChange` | Called with the new value when it changes                            |
| `onHistoryMark` | Called on pointer down so you can mark a history stopping point      |

### TldrawUiPopover

[`TldrawUiPopover`](/reference/tldraw/TldrawUiPopover) shows content next to a trigger element:

```tsx
<TldrawUiPopover id="my-popover">
	<TldrawUiPopoverTrigger>
		<TldrawUiButton type="icon">
			<TldrawUiButtonIcon icon="dots-vertical" />
		</TldrawUiButton>
	</TldrawUiPopoverTrigger>
	<TldrawUiPopoverContent side="bottom">
		<div style={{ padding: 8 }}>Popover content here</div>
	</TldrawUiPopoverContent>
</TldrawUiPopover>
```

The `id` prop is required and used to track the popover's open state. The `side` prop on `TldrawUiPopoverContent` controls which side of the trigger the popover appears on.

### TldrawUiDropdownMenu

[`TldrawUiDropdownMenuRoot`](/reference/tldraw/TldrawUiDropdownMenuRoot) and its companions build a dropdown menu on Radix UI:

```tsx
<TldrawUiDropdownMenuRoot id="my-dropdown">
	<TldrawUiDropdownMenuTrigger>
		<TldrawUiButton type="normal">
			<TldrawUiButtonLabel>Options</TldrawUiButtonLabel>
		</TldrawUiButton>
	</TldrawUiDropdownMenuTrigger>
	<TldrawUiDropdownMenuContent>
		<TldrawUiDropdownMenuGroup>
			<TldrawUiDropdownMenuItem>
				<TldrawUiButton type="menu" onClick={handleEdit}>
					<TldrawUiButtonLabel>Edit</TldrawUiButtonLabel>
				</TldrawUiButton>
			</TldrawUiDropdownMenuItem>
			<TldrawUiDropdownMenuItem>
				<TldrawUiButton type="menu" onClick={handleDuplicate}>
					<TldrawUiButtonLabel>Duplicate</TldrawUiButtonLabel>
				</TldrawUiButton>
			</TldrawUiDropdownMenuItem>
			<TldrawUiDropdownMenuItem>
				<TldrawUiButton type="menu" onClick={handleDelete}>
					<TldrawUiButtonLabel>Delete</TldrawUiButtonLabel>
				</TldrawUiButton>
			</TldrawUiDropdownMenuItem>
		</TldrawUiDropdownMenuGroup>
	</TldrawUiDropdownMenuContent>
</TldrawUiDropdownMenuRoot>
```

The `id` prop is required on `TldrawUiDropdownMenuRoot`. Each `TldrawUiDropdownMenuItem` wraps a child element (typically a button) and handles the dropdown behavior.

Other exported primitives include [`TldrawUiToolbar`](/reference/tldraw/TldrawUiToolbar) and [`TldrawUiToolbarButton`](/reference/tldraw/TldrawUiToolbarButton), [`TldrawUiTooltip`](/reference/tldraw/TldrawUiTooltip), [`TldrawUiSelect`](/reference/tldraw/TldrawUiSelect), [`TldrawUiContextualToolbar`](/reference/tldraw/TldrawUiContextualToolbar), and the dropdown submenu and checkbox item components.

## Related examples

- [UI primitives](/examples/ui/ui-primitives) - A showcase of the UI primitive components
- [Custom menus](/examples/ui/custom-menus) - Add items to tldraw's menus using menu primitives
- [Toasts and dialogs](/examples/ui/toasts-and-dialogs) - Show toasts and custom dialogs
- [Custom UI](/examples/ui/custom-ui) - Build a completely custom interface

--------

# User following

User following lets you track a collaborator's viewport. When you follow someone, your [camera](/sdk-features/camera) moves to match their view, including page changes and zoom level. The editor handles follow chains (A follows B who follows C) and interpolates your viewport toward the target on each frame.

Following works with the [collaboration](/docs/collaboration) presence system, so it needs a collaborative store. User ids are branded [`TLUserId`](/reference/tlschema/TLUserId) values: take them from presence records, or create one with [`createUserId`](/reference/tlschema/createUserId). The default People menu already exposes this: clicking a collaborator zooms to them, and the follow button beside their name starts or stops following. The API below is what it calls.

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

const userId = createUserId('user-abc-123')

editor.startFollowingUser(userId)
editor.stopFollowingUser()
editor.zoomToUser(userId)
```

Following stops when you interact with the canvas or when the followed user disconnects.

## How it works

### Follow mechanism

When you call [`Editor.startFollowingUser`](/reference/editor/Editor#startFollowingUser), the editor stores the target user ID in `followingUserId` on the instance state and sets up two reactive processes: one watches for page changes and switches pages when the followed user navigates, and another runs on every frame to interpolate your camera toward their viewport.

The frame handler calculates the difference between your current viewport and the target, then interpolates using your animation speed preference. The camera moves quickly at first and slows as it approaches. Once the viewport difference drops below the `followChaseViewportSnap` threshold (default 2 pixels), the editor locks onto the target and mirrors their viewport exactly instead of interpolating. If the animation speed preference is 0, it locks on immediately.

### Viewport calculation

The editor reads the followed user's camera state and screen bounds from their presence record, constructs their viewport in page space, then resizes your viewport to contain theirs while maintaining your screen's aspect ratio. You can see everything the followed user sees, regardless of screen size.

The interpolation uses `lerp` on viewport bounds rather than camera values directly, which produces more natural movement when zoom levels differ. The interpolation factor clamps between 0.1 and 0.8 based on the animation speed preference, so following is never sluggish or aggressive.

### Page synchronization

Page changes happen separately from camera movement. A reactive effect watches the followed user's `currentPageId` and immediately switches [pages](/sdk-features/pages) when it changes. The page switch uses a direct store update rather than `setCurrentPage()` to avoid triggering the automatic follow-stopping behavior that occurs on manual page changes.

When switching pages to follow a user, the editor pauses camera interpolation until the page switch completes. This avoids jarring camera movements during page transitions.

## API methods

### startFollowingUser

Start following a user's viewport. Pass a user ID to set up frame handlers that track their camera and page.

```ts
editor.startFollowingUser(userId)
```

The editor automatically stops following any previously followed user before starting the new follow. If it can't find the target user's presence, the method returns early without starting follow mode.

### stopFollowingUser

[`Editor.stopFollowingUser`](/reference/editor/Editor#stopFollowingUser) stops following and returns control to the local user. This commits the current camera position to the store, clears `followingUserId` from instance state, and emits the editor's `stop-following` event.

```ts
editor.stopFollowingUser()
```

Following stops automatically when you pan or zoom the canvas. Manual page changes also stop following unless the follow system itself initiated the page change.

### zoomToUser

[`Editor.zoomToUser`](/reference/editor/Editor#zoomToUser) animates the camera to a user's cursor position without entering follow mode. Use this for one-time navigation to a collaborator's location.

```ts
editor.zoomToUser(userId)
editor.zoomToUser(userId, { animation: { duration: 200 } })
```

If you're already following someone, `zoomToUser()` stops following first. The method switches pages if necessary, centers the camera on the user's cursor, and briefly highlights their cursor. The highlight clears after `collaboratorIdleTimeoutMs` (default 3 seconds). If the user is on a different page, the camera jumps without animating.

## Follow chains

When user A follows user B who is following user C, user A follows user C directly rather than B's view of C. The editor traverses the follow chain until it finds a user who isn't following anyone else.

The traversal maintains a visited set to prevent infinite loops if users create a circular follow chain. If a cycle is detected, it returns the last valid presence before the cycle.

```ts
// A follows B follows C
// A's camera tracks C's viewport, not B's viewport
editor.startFollowingUser(userB)
// Internally resolves to C's presence if B is following C
```

The follow chain resolution runs on every frame, so changes in the chain (like B stopping following C) immediately affect A's target viewport without requiring A to restart following.

## UI integration

### FollowingIndicator

The [`DefaultFollowingIndicator`](/reference/tldraw/DefaultFollowingIndicator) component displays a colored border around the canvas when you're following someone. It reads `followingUserId` from instance state and fetches the corresponding presence record to get the user's color.

```tsx
import { TLUserId, useEditor, usePresence, useValue } from 'tldraw'

export function DefaultFollowingIndicator() {
	const editor = useEditor()
	const followingUserId = useValue('follow', () => editor.getInstanceState().followingUserId, [
		editor,
	])
	if (!followingUserId) return null
	return <FollowingIndicatorInner userId={followingUserId} />
}

function FollowingIndicatorInner({ userId }: { userId: TLUserId }) {
	const presence = usePresence(userId)
	if (!presence) return null
	return <div className="tlui-following-indicator" style={{ borderColor: presence.color }} />
}
```

You can override it through the `FollowingIndicator` slot of [`TLUiComponents`](/reference/tldraw/TLUiComponents) to change its appearance or add the followed user's name. See [UI components](/sdk-features/ui-components).

### Follow state detection

Check `editor.getInstanceState().followingUserId` to detect when a user is following someone. Use this to show UI elements like a "Stop following" button or status indicators.

```ts
const followingUserId = editor.getInstanceState().followingUserId
if (followingUserId) {
	// Show stop following button
}
```

The presence records from [`Editor.getCollaborators`](/reference/editor/Editor#getCollaborators) include each user's `followingUserId`, so you can visualize the entire follow graph and show which users are following whom.

## Related articles

- [Camera](/sdk-features/camera) - Viewport and camera control
- [Collaboration](/docs/collaboration) - Set up multiplayer presence and sync
- [Pages](/sdk-features/pages) - Page management
- [UI components](/sdk-features/ui-components) - Customize UI elements like the following indicator

--------

# User preferences

User preferences store per-user settings that persist across sessions and synchronize across browser tabs. Access them through `editor.user`, a [`UserPreferencesManager`](/reference/editor/UserPreferencesManager):

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

function PreferencesPanel() {
	const editor = useEditor()

	// Read preferences reactively
	const isDark = useValue('isDarkMode', () => editor.user.getIsDarkMode(), [editor])

	// Update preferences
	const toggleDarkMode = () => {
		editor.user.updateUserPreferences({
			colorScheme: isDark ? 'light' : 'dark',
		})
	}

	return <button onClick={toggleDarkMode}>Toggle theme</button>
}

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

Preferences cover visual settings (color scheme, animation speed), interaction settings (snap mode, edge scroll speed), and identity (user name, color, locale). By default the editor stores them in localStorage and syncs them across tabs with a BroadcastChannel.

To supply preferences from your own auth or state instead, pass a `user` created with [`useTldrawCurrentUser`](/reference/editor/useTldrawCurrentUser) (or [`createTLCurrentUser`](/reference/editor/createTLCurrentUser)) to the `Tldraw` component. Preferences you provide this way are yours to persist and sync. See [Collaboration](/sdk-features/collaboration#integrating-with-usetldrawcurrentuser) for a full example.

## Reading preferences

The `UserPreferencesManager` exposes each preference as a computed value. These are reactive [signals](/sdk-features/signals): read them inside `useValue` (or another reactive context) and your component re-renders when the value changes.

```tsx
// Individual preferences
const isDark = editor.user.getIsDarkMode()
const speed = editor.user.getAnimationSpeed()
const locale = editor.user.getLocale()
const userName = editor.user.getName()
const userColor = editor.user.getColor()
const isSnapMode = editor.user.getIsSnapMode()

// The user's id as a `user:` prefixed record id, for presence and attribution
const userId = editor.user.getRecordId()

// All preferences as an object, with defaults resolved
const allPrefs = editor.user.getUserPreferences()
```

The tables below list the getter for each preference. Every preference in [`TLUserPreferences`](/reference/editor/TLUserPreferences) is optional; `null` or `undefined` means "use the default".

## Updating preferences

Use [`UserPreferencesManager.updateUserPreferences`](/reference/editor/UserPreferencesManager#updateUserPreferences) to change one or more preferences at once:

```tsx
editor.user.updateUserPreferences({
	colorScheme: 'dark',
	animationSpeed: 0.5,
	isSnapMode: true,
})
```

Changes apply immediately, save to localStorage, and broadcast to other tabs.

## Available preferences

### Visual preferences

| Preference         | Getter                | Type                            | Default                                        | Description                          |
| ------------------ | --------------------- | ------------------------------- | ---------------------------------------------- | ------------------------------------ |
| `colorScheme`      | `getIsDarkMode`       | `'light' \| 'dark' \| 'system'` | `'light'`                                      | Theme mode                           |
| `animationSpeed`   | `getAnimationSpeed`   | `number`                        | `1`, or `0` if the user prefers reduced motion | Multiplier for animation durations   |
| `enhancedA11yMode` | `getEnhancedA11yMode` | `boolean`                       | `false`                                        | Additional UI labels and visual aids |

### Interaction preferences

| Preference                    | Getter                           | Type                            | Default | Description                                                                    |
| ----------------------------- | -------------------------------- | ------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `isSnapMode`                  | `getIsSnapMode`                  | `boolean`                       | `false` | Snap shapes to other shapes and guides                                         |
| `isWrapMode`                  | `getIsWrapMode`                  | `boolean`                       | `false` | Brush selection only selects shapes fully inside the brush ("Select on wrap")  |
| `isDynamicSizeMode`           | `getIsDynamicResizeMode`         | `boolean`                       | `false` | Scale new shapes with the zoom level so they stay the same size on screen      |
| `isPasteAtCursorMode`         | `getIsPasteAtCursorMode`         | `boolean`                       | `false` | Paste at cursor instead of original location                                   |
| `edgeScrollSpeed`             | `getEdgeScrollSpeed`             | `number`                        | `1`     | Speed multiplier for edge scrolling during drag                                |
| `areKeyboardShortcutsEnabled` | `getAreKeyboardShortcutsEnabled` | `boolean`                       | `true`  | Enable or disable keyboard shortcuts                                           |
| `inputMode`                   | `getInputMode`                   | `'trackpad' \| 'mouse' \| null` | `null`  | Optimize behavior for input device                                             |
| `isZoomDirectionInverted`     | `getIsZoomDirectionInverted`     | `boolean`                       | `false` | Invert scroll-wheel zoom direction. Only applies when `inputMode` is `'mouse'` |

### Identity properties

| Preference | Getter                         | Type     | Default                          | Description                                                      |
| ---------- | ------------------------------ | -------- | -------------------------------- | ---------------------------------------------------------------- |
| `id`       | `getExternalId`, `getRecordId` | `string` | Auto-generated                   | Unique user identifier. `getRecordId` returns it as a `TLUserId` |
| `name`     | `getName`                      | `string` | `''`                             | Display name shown to collaborators                              |
| `color`    | `getColor`                     | `string` | Random from the built-in palette | User color for cursor and selections                             |
| `locale`   | `getLocale`                    | `string` | Browser locale                   | Language code (e.g., `'en'`, `'fr'`)                             |

The user color is picked at random from `USER_COLORS`, a palette of 12 colors. The `id` is what [attribution](/sdk-features/attribution) and presence records use to identify the user.

## Dark mode

The `getIsDarkMode()` method resolves the color scheme to a boolean. When `colorScheme` is `'system'`, it tracks the operating system's preference through a media query listener:

```tsx
const isDark = editor.user.getIsDarkMode()
// true if colorScheme is 'dark', or 'system' with OS in dark mode
```

The editor-level `colorScheme` prop sets the default color scheme. When a user preference is set, it takes priority over the prop. See [Themes](/sdk-features/themes#color-mode) for more.

## Persistence and synchronization

The default user persists preferences to localStorage under the key `TLDRAW_USER_DATA_v3`. Each save includes a version number, and the editor migrates older data on load so preferences stay compatible across tldraw releases. It validates the loaded data with [`userTypeValidator`](/reference/editor/userTypeValidator) and falls back to fresh preferences if the data is invalid.

The editor also broadcasts preference changes to other tabs over a BroadcastChannel. When you change a preference in one tab, all other tabs update automatically.

## Related examples

- [Toggle dark mode](/examples/ui/dark-mode-toggle) - Toggle between light and dark mode by changing `colorScheme`.

--------

# Validation

The `@tldraw/validate` package handles validation across tldraw's schemas, record types, and shape props. Validators enforce runtime type safety and provide structured errors when data is malformed. The `T` namespace is re-exported from `tldraw`, so `import { T } from 'tldraw'` works too.

## Where validation runs

Validation runs whenever a record is written to the [store](/sdk-features/store):

- Shape and binding props via [`RecordProps`](/reference/tlschema/RecordProps)
- Shape, binding, and user `meta` via the `meta` field on their schema config
- Custom record types via [`CustomRecordInfo`](/reference/tlschema/CustomRecordInfo)
- Any record type in a store via [`createRecordType`](/reference/store/createRecordType) and [`StoreSchema`](/reference/store/StoreSchema)

If validation fails, the write throws and nothing is stored.

## Core validators

Use `T` validators to describe data shapes and validate unknown input:

```typescript
import { T } from '@tldraw/validate'

const userValidator = T.object({
	id: T.string,
	name: T.string.optional(),
	age: T.number.optional(),
})

const user = userValidator.validate(input)
```

Every validator has three key methods:

- `validate(value)` validates unknown input and returns a typed result
- `isValid(value)` returns true if valid, false otherwise (useful as a type guard)
- `validateUsingKnownGoodVersion(knownGood, newValue)` reuses previously validated data to skip unchanged parts. The store calls this automatically when updating an existing record.

## Validator catalog

| Category     | Validators                                                                                                                             |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Primitives   | `T.unknown`, `T.any`, `T.string`, `T.number`, `T.boolean`, `T.bigint`                                                                  |
| Numbers      | `T.positiveNumber`, `T.nonZeroNumber`, `T.nonZeroFiniteNumber`, `T.unitInterval`, `T.integer`, `T.positiveInteger`, `T.nonZeroInteger` |
| Collections  | `T.array`, `T.arrayOf`, `T.object`, `T.unknownObject`, `T.dict`, `T.jsonDict`, `T.jsonValue`                                           |
| Unions       | `T.literal`, `T.literalEnum`, `T.setEnum`, `T.union`, `T.numberUnion`, `T.or`                                                          |
| URLs and IDs | `T.linkUrl`, `T.srcUrl`, `T.httpUrl`, `T.indexKey`                                                                                     |
| Modifiers    | `.optional()`, `.nullable()`, `.refine()`, `.check()`, `T.optional()`, `T.nullable()`, `T.model()`                                     |

Object validators also have `.extend()` to add fields and `.allowUnknownProperties()` to tolerate extra keys.

## Common validator patterns

```typescript
import { T } from '@tldraw/validate'

const configValidator = T.object({
	id: T.string,
	mode: T.literalEnum('view', 'edit'),
	tags: T.arrayOf(T.string).optional(),
	meta: T.object({ note: T.string }).nullable(),
})

const evenNumber = T.number.check('even', (value) => {
	if (value % 2 !== 0) throw new T.ValidationError('Expected even number')
})
```

## Record props validation

Shapes and bindings use [`RecordProps`](/reference/tlschema/RecordProps) to validate their `props` at runtime. Each key maps to a validator, and the store rejects any write whose props don't pass:

```typescript
import { DefaultColorStyle, RecordProps, T, TLBaseShape, TLDefaultColorStyle } from 'tldraw'

type CardShape = TLBaseShape<'card', { color: TLDefaultColorStyle; text: string }>

const cardShapeProps: RecordProps<CardShape> = {
	color: DefaultColorStyle,
	text: T.string,
}
```

Assign this object to `static override props` on your `ShapeUtil`. See the [custom shape example](/examples/shapes/tools/custom-shape) for the full util.

## Store validation and recovery

The store validates records on write. When you build your own [`StoreSchema`](/reference/store/StoreSchema) you can pass `onValidationFailure` to recover or sanitize data instead of throwing:

```typescript
import { BaseRecord, RecordId, StoreSchema, createRecordType } from '@tldraw/store'
import { T, idValidator } from 'tldraw'

interface Book extends BaseRecord<'book', RecordId<Book>> {
	title: string
}

const Book = createRecordType<Book>('book', {
	scope: 'document',
	validator: T.object({
		id: idValidator<RecordId<Book>>('book'),
		typeName: T.literal('book'),
		title: T.string,
	}),
})

const schema = StoreSchema.create(
	{ book: Book },
	{
		onValidationFailure: (failure) => failure.record,
	}
)
```

The handler must return a valid record, or rethrow to abort the write. The `failure` object is a [`StoreValidationFailure`](/reference/store/StoreValidationFailure):

| Property       | Description                                                                              |
| -------------- | ---------------------------------------------------------------------------------------- |
| `error`        | The error that was thrown                                                                |
| `store`        | The store instance where validation failed                                               |
| `record`       | The invalid record                                                                       |
| `phase`        | When validation failed: `'initialize'`, `'createRecord'`, `'updateRecord'`, or `'tests'` |
| `recordBefore` | The previous record state (null for new records)                                         |

tldraw's own schema from [`createTLSchema`](/reference/tlschema/createTLSchema) (and so [`createTLStore`](/reference/editor/createTLStore) and the `Tldraw` component) uses a built-in handler that reports the error and rethrows. You can't override it there; if you need recovery, build the `StoreSchema` yourself.

## Error handling

`T.ValidationError` carries structured information about what went wrong:

```typescript
import { T } from '@tldraw/validate'

const userValidator = T.object({
	name: T.string,
	settings: T.object({ theme: T.literalEnum('light', 'dark') }),
})

try {
	userValidator.validate({ name: 'Alice', settings: { theme: 'invalid' } })
} catch (error) {
	if (error instanceof T.ValidationError) {
		console.log(error.message) // 'At settings.theme: Expected "light" or "dark", got invalid'
		console.log(error.rawMessage) // 'Expected "light" or "dark", got invalid'
		console.log(error.path) // ['settings', 'theme']
	}
}
```

`rawMessage` is the message without path information, and `path` is an array showing where in the data structure validation failed (for example `['items', 0, 'name']`). The full `message` combines them.

Validators must be pure and must not mutate input values.

## Related examples

- [Custom shape](/examples/shapes/tools/custom-shape) - Define shape props with validators using RecordProps.
- [Custom validators for shape props](/examples/shapes/tools/custom-validators) - Add constraints with `.check()` and `.refine()`.

--------

# Visibility

The editor's visibility system determines which shapes are rendered on screen. It handles two separate concerns: culling, which hides off-screen shapes for performance, and hidden shapes, which your application hides explicitly.

## Culling

Culling is a performance optimization. Shapes outside the viewport stay in the store and can still be selected, updated, or queried, but the editor sets `display: none` on their DOM elements. Selected shapes and the shape being edited are never culled. Return `false` from [`ShapeUtil.canCull`](/reference/editor/ShapeUtil#canCull) to opt a shape out.

You can get the set of culled shape IDs with [`Editor.getCulledShapes`](/reference/editor/Editor#getCulledShapes):

```ts
const culledIds = editor.getCulledShapes()
```

See [Culling](/sdk-features/culling) for how the spatial index decides what to cull and for the full set of culling methods.

## Hidden shapes

Hidden shapes are shapes your application explicitly hides using the `getShapeVisibility` option. Unlike culled shapes, hidden shapes are excluded from hit tests, exports, and rendering.

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				getShapeVisibility={(shape) => {
					if (shape.meta.hidden) return 'hidden'
					return 'inherit'
				}}
			/>
		</div>
	)
}
```

The function can return:

| Return value                        | Behavior                                                |
| ----------------------------------- | ------------------------------------------------------- |
| `'inherit'`, `undefined`, or `null` | Shape is visible unless its parent is hidden (default). |
| `'hidden'`                          | Shape is always hidden.                                 |
| `'visible'`                         | Shape is always visible, even if parent is hidden.      |

The same prop is available on [`TldrawEditor`](/reference/editor/TldrawEditor) and as an [`Editor`](/reference/editor/Editor) constructor option. The editor caches the result per shape, so keep the callback pure.

Hidden shapes are still in the store. They're just excluded from:

- Canvas rendering
- Hit tests ([`Editor.getShapeAtPoint`](/reference/editor/Editor#getShapeAtPoint), [`Editor.getShapesAtPoint`](/reference/editor/Editor#getShapesAtPoint))
- [`Editor.getRenderingShapes`](/reference/editor/Editor#getRenderingShapes) and [`Editor.getCurrentPageRenderingShapesSorted`](/reference/editor/Editor#getCurrentPageRenderingShapesSorted)
- Image exports and printing
- [`Editor.getCurrentPageBounds`](/reference/editor/Editor#getCurrentPageBounds) and [`Editor.zoomToFit`](/reference/editor/Editor#zoomToFit)
- Drop targets and automatic parenting of new shapes

You can check if a shape is hidden with [`Editor.isShapeHidden`](/reference/editor/Editor#isShapeHidden):

```ts
if (editor.isShapeHidden(shapeId)) {
	// shape won't render
}
```

### Preventing hidden shapes from being selected

Hidden shapes can still be selected via keyboard shortcuts like select-all. If you want to prevent this, filter the [selection](/sdk-features/selection) when it changes:

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

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				getShapeVisibility={(shape) => (shape.meta.hidden ? 'hidden' : 'inherit')}
				onMount={(editor) => {
					return react('filter hidden from selection', () => {
						const selectedIds = editor.getSelectedShapeIds()
						const visibleIds = selectedIds.filter((id) => !editor.isShapeHidden(id))
						if (selectedIds.length !== visibleIds.length) {
							editor.setSelectedShapes(visibleIds)
						}
					})
				}}
			/>
		</div>
	)
}
```

For examples using hidden shapes, see the [collaboration private content example](/examples/collaboration/sync-private-content) and the [layer panel example](/examples/ui/layer-panel).

## Opacity

Each shape has an `opacity` property (0 to 1) that controls its transparency. When shapes are nested, opacity multiplies down the hierarchy: a shape at 0.5 opacity inside a parent at 0.5 opacity renders at 0.25 opacity.

The editor calculates the cumulative opacity for each shape and passes it to the rendering layer. You can access the computed opacity through [`Editor.getRenderingShapes`](/reference/editor/Editor#getRenderingShapes):

```ts
const renderingShapes = editor.getRenderingShapes()
for (const { shape, opacity } of renderingShapes) {
	console.log(shape.id, opacity) // cumulative opacity
}
```

### Erasing feedback

When shapes are being erased (the user is mid-gesture with the eraser tool), they render at 32% of their normal opacity. This gives visual feedback that the shapes will be deleted when the gesture completes. The editor handles this automatically—you don't need to implement anything for erasing feedback to work.

## Rendering shapes

[`Editor.getRenderingShapes`](/reference/editor/Editor#getRenderingShapes) returns the shapes that should be rendered, along with their computed properties:

```ts
interface TLRenderingShape {
	id: TLShapeId
	shape: TLShape
	util: ShapeUtil
	index: number // z-index for the shape layer
	backgroundIndex: number // z-index for the background layer
	opacity: number // cumulative opacity
}
```

The `index` and `backgroundIndex` values control z-ordering. The editor uses CSS z-index rather than DOM ordering to position shapes visually. This keeps the DOM stable (shapes stay in ID order) and avoids expensive reflows when z-order changes.

For most use cases, you won't need to work with rendering shapes directly; the editor's canvas handles this. Use it if you're building custom rendering or need to know which shapes are visible at what opacity.

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

# tldraw SDK releases

--------

# v5.4.0

[View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v5.4.0)

This release adds a `center` operation to `Editor.alignShapes`, a `tleditors` registry of mounted editors, `iterateGraphemes` to `@tldraw/utils`, and two new reactive methods on `AtomMap`. It also deprecates `useViewportHeight`, speeds up the signals and store layers, and lands a broad reliability pass across the SDK, with over a hundred fixes to undo history, selection and tool interactions, cropping, arrows, the signals and store layers, sync, and local persistence.

## API changes

- 🔜 **`useViewportHeight()`** is deprecated. Read `window.visualViewport` directly instead. The hook returns only the visible viewport's bottom edge, and keeping a panel clear of the software keyboard generally needs the whole visible rectangle. ([#9826](https://github.com/tldraw/tldraw/pull/9826))
- Add `'center'` as an `Editor.alignShapes` operation. It applies the existing `'center-horizontal'` and `'center-vertical'` operations together, so shapes center on both axes in one command. ([#9074](https://github.com/tldraw/tldraw/pull/9074))
- Add `tleditors`, a reactive global registry of currently mounted editors. Use it to reach live editors from outside the React tree, for example from sidebar chrome or a keyboard shortcut handler. ([#9904](https://github.com/tldraw/tldraw/pull/9904))

  ```tsx
  import { tleditors, useValue } from 'tldraw'

  const mounted = useValue('mounted editors', () => tleditors.getMounted(), [])
  ```

- Add `getOrInsert(key, defaultValue)` and `getOrInsertComputed(key, callback)` to `AtomMap`, matching the `Map` methods added in newer JavaScript runtimes. Both are reactive, and the callback only runs when the key is absent. ([#9752](https://github.com/tldraw/tldraw/pull/9752))
- Add `isPage(record)` to `@tldraw/tlschema`, a type guard that narrows an unknown record to `TLPage`, matching the guards already exported for the other record types. ([#9774](https://github.com/tldraw/tldraw/pull/9774))
- Add `iterateGraphemes(str)` to `@tldraw/utils`. It iterates a string's grapheme clusters, using `Intl.Segmenter` when it's available and falling back to code-point iteration when it isn't. ([#9896](https://github.com/tldraw/tldraw/pull/9896))
- `EmojiPickerProps.onSelect` now receives the originating event as an optional second argument. Custom reaction palettes can forward it to opt into shift multi-select. ([#9999](https://github.com/tldraw/tldraw/pull/9999))

## Improvements

- Shift-click an emoji in a comment's reaction palette to add several reactions without the palette closing. A plain click still applies the reaction and closes the palette. ([#9999](https://github.com/tldraw/tldraw/pull/9999))
- Keyboard input now counts as collaborator presence activity, so peers no longer fade out and disappear while someone is typing. ([#9929](https://github.com/tldraw/tldraw/pull/9929))
- Reduce per-pointer-event allocations in `Group2d` and `Editor` hit-testing. ([#8600](https://github.com/tldraw/tldraw/pull/8600))
- Speed up signal reads in `@tldraw/state`. Capturing a parent used to scan the capturing signal's parent set twice, once to check for the parent and again to add it. ([#9690](https://github.com/tldraw/tldraw/pull/9690))
- Reduce per-signal memory use and per-flush allocations in `@tldraw/state`. ([#10155](https://github.com/tldraw/tldraw/pull/10155))
- Speed up editor hot paths: set lookups replace array scans in the selection side effect and the erasing check, `getCollaborators` makes a single pass over the presence records, and `getShapeUtil` only builds its assert message when the lookup fails. ([#10358](https://github.com/tldraw/tldraw/pull/10358))
- Reduce the work and allocations in `@tldraw/store` history bookkeeping, so squashing record diffs and filtering query history no longer build intermediate copies on every tick. ([#9689](https://github.com/tldraw/tldraw/pull/9689), [#9869](https://github.com/tldraw/tldraw/pull/9869))
- Move the `exportBackground` default (`true`) into the `TLInstance` record type in `@tldraw/tlschema`, so every code path that creates the instance record gets the same value. ([#10534](https://github.com/tldraw/tldraw/pull/10534))

## Bug fixes

### Crashes

- Fix the editor failing to load on older browsers that lack `Intl.Segmenter`, such as Firefox before 125. ([#9896](https://github.com/tldraw/tldraw/pull/9896))
- Fix the frame loop stopping permanently when a `tick` or `frame` listener threw, which silently disabled camera animations, edge scrolling, and other frame-driven behavior for the rest of the session. ([#9946](https://github.com/tldraw/tldraw/pull/9946))
- Fix a crash when computing a frame's geometry if its heading text couldn't be measured yet. ([#9496](https://github.com/tldraw/tldraw/pull/9496))
- Fix a crash in hit testing when a custom frame-like shape uses a plain, non-group geometry. ([#10328](https://github.com/tldraw/tldraw/pull/10328))
- Fix a crash when pressing Enter with a frame, video, or embed selected while the geo, arrow, or text tool is active. ([#10195](https://github.com/tldraw/tldraw/pull/10195))
- Fix default UI components such as `DefaultToolbar` crashing when mounted outside the `Tldraw` component. ([#10007](https://github.com/tldraw/tldraw/pull/10007))

### Undo and history

- Fix undo after a cut also reverting the change made before it. ([#9920](https://github.com/tldraw/tldraw/pull/9920))
- Fix several actions merging into the previous undo step instead of creating their own: **Unlock all**, changing an arrowhead, keyboard changes to the opacity and image zoom sliders, alt+double-clicking a rectangle into a check-box, saving alt text, and dropping a file or url onto the canvas. ([#10468](https://github.com/tldraw/tldraw/pull/10468), [#10469](https://github.com/tldraw/tldraw/pull/10469), [#10470](https://github.com/tldraw/tldraw/pull/10470), [#10473](https://github.com/tldraw/tldraw/pull/10473), [#10474](https://github.com/tldraw/tldraw/pull/10474), [#10478](https://github.com/tldraw/tldraw/pull/10478))
- Fix exiting an empty text shape leaving a phantom undo entry: document changes made by `onEditEnd` are now recorded in history. ([#10369](https://github.com/tldraw/tldraw/pull/10369))
- Fix undo after `bailToMark` removing records that were not part of the undone change. ([#10207](https://github.com/tldraw/tldraw/pull/10207))
- Fix undo/redo not removing an optional record property that the change had deleted. ([#10215](https://github.com/tldraw/tldraw/pull/10215))
- Fix collaboration-mode readonly syncs ending up in the user's undo history. ([#10372](https://github.com/tldraw/tldraw/pull/10372))
- Fix changes made by `operationComplete` handlers after a remote merge being attributed to the remote source. ([#10229](https://github.com/tldraw/tldraw/pull/10229))

### Selection and tools

- Fix Escape being ignored while pressing on the canvas with the select tool. ([#10175](https://github.com/tldraw/tldraw/pull/10175))
- Fix Escape during a scribble selection dropping the prior selection. ([#10489](https://github.com/tldraw/tldraw/pull/10489))
- Fix Space+arrow and Alt+arrow also nudging the selected shapes. ([#10453](https://github.com/tldraw/tldraw/pull/10453))
- Fix Alt not suppressing Shift/Ctrl additive selection when releasing the pointer over a selected shape. ([#10510](https://github.com/tldraw/tldraw/pull/10510))
- Fix bookmarks and other non-resizable shapes being left behind when resizing a multi-selection. ([#10491](https://github.com/tldraw/tldraw/pull/10491))
- Fix alt-cloning mid-drag reparenting the original shape instead of the clone when dropping into a frame. ([#10186](https://github.com/tldraw/tldraw/pull/10186))
- Fix the cursor staying as a resize or rotate arrow when Ctrl/Cmd+dragging a selection handle to brush-select. ([#10487](https://github.com/tldraw/tldraw/pull/10487))
- Fix handle snapping on rotated shapes landing off the snap target. ([#10168](https://github.com/tldraw/tldraw/pull/10168))
- Fix an interrupted press with the geo, frame, or note tool (undo, opening a menu, or changing page before releasing) creating a default-size shape. ([#10506](https://github.com/tldraw/tldraw/pull/10506))
- Fix an invisible empty text shape being left behind when switching tools while dragging out a text box. ([#10457](https://github.com/tldraw/tldraw/pull/10457))
- Fix the text tool undoing earlier work when cancelling a pointer-down after a drag-created text shape. ([#10194](https://github.com/tldraw/tldraw/pull/10194))
- Fix shift-click with the draw, highlight, and line tools editing a shape on the previous page after a page change. ([#10455](https://github.com/tldraw/tldraw/pull/10455))
- Fix the draw tool's shift segment threshold depending on the zoom level. ([#10240](https://github.com/tldraw/tldraw/pull/10240))
- Fix the first point of a pen stroke losing its pressure value. ([#10243](https://github.com/tldraw/tldraw/pull/10243))
- Fix small, slowly drawn loops sometimes failing to close, because dense input sampling made the stroke measure shorter than it was. ([#9930](https://github.com/tldraw/tldraw/pull/9930))
- Fix the eraser dropping a frame it was pressed on once the drag begins. ([#10507](https://github.com/tldraw/tldraw/pull/10507))
- Fix a camera jump when a second finger touches down during a one-finger zoom with the hand tool. ([#10178](https://github.com/tldraw/tldraw/pull/10178))
- Fix Escape ending a spacebar pan while Space is still held. ([#10504](https://github.com/tldraw/tldraw/pull/10504))
- Fix tools whose `onEnter` transitions to a child state ending up with two active children. ([#10354](https://github.com/tldraw/tldraw/pull/10354))
- Fix double clicks being cancelled by small pointer movements when the editor container is offset from the page origin. ([#10349](https://github.com/tldraw/tldraw/pull/10349))
- Fix modifier keys (Shift, Alt, Ctrl, Cmd) briefly being treated as held at the start of a new click or drag right after being released, which could momentarily affect snapping and other modifier-dependent behavior. ([#9523](https://github.com/tldraw/tldraw/pull/9523))
- Fix held keys, including Space panning, staying active after the window loses focus. ([#10500](https://github.com/tldraw/tldraw/pull/10500))

### Cropping

- Fix stale crop state after leaving crop mode by switching tools. ([#10167](https://github.com/tldraw/tldraw/pull/10167))
- Fix Escape during a crop drag reverting the whole crop session instead of only the drag in progress. ([#10462](https://github.com/tldraw/tldraw/pull/10462))
- Fix Escape in image crop mode clearing the selection. ([#10463](https://github.com/tldraw/tldraw/pull/10463))
- Fix crop mode staying active when the cropping shape is deleted. ([#10370](https://github.com/tldraw/tldraw/pull/10370))
- Fix pressing Enter on a selected image entering crop mode in a readonly editor. ([#10492](https://github.com/tldraw/tldraw/pull/10492))

### Arrows and shapes

- Fix arrows bound to custom shapes with non-standard `size` values rendering as `NaN`. ([#10214](https://github.com/tldraw/tldraw/pull/10214))
- Fix elbow arrows with a free terminal sometimes routing through the bound shape. ([#10219](https://github.com/tldraw/tldraw/pull/10219))
- Fix arrow geometry ignoring a custom stroke width from `getCustomDisplayValues`. ([#10230](https://github.com/tldraw/tldraw/pull/10230))
- Fix the arrow binding target highlight staying visible after clicking an arrow handle without dragging. ([#10191](https://github.com/tldraw/tldraw/pull/10191))
- Fix a stub arrow being left on the canvas when switching tools during an arrow press. ([#10461](https://github.com/tldraw/tldraw/pull/10461))
- Fix arrow label drag reverting when a menu opens or undo is pressed mid-drag. ([#10493](https://github.com/tldraw/tldraw/pull/10493))
- Fix Cmd+Enter / Tab on a note creating a duplicate on top of an existing neighbour. ([#10199](https://github.com/tldraw/tldraw/pull/10199))
- Fix adjacent-note snapping under a scaled, grown note. ([#10204](https://github.com/tldraw/tldraw/pull/10204))
- Fix the note tool not snapping a new note beside the note it just created when tool lock is on. ([#10484](https://github.com/tldraw/tldraw/pull/10484))
- Fix attributed notes losing their font in exports. ([#10249](https://github.com/tldraw/tldraw/pull/10249))
- Fix shift-extending a line inside a rotated frame placing the point incorrectly. ([#10238](https://github.com/tldraw/tldraw/pull/10238))
- Fix the second diagonal of an x-box shape being treated as an outer edge. ([#10245](https://github.com/tldraw/tldraw/pull/10245))
- Fix a replaced image being zoomed when the original had an explicit default crop. ([#10234](https://github.com/tldraw/tldraw/pull/10234))
- Fix video shapes showing a floating spinner with no bounding box while their asset uploads or loads. They now show the same loading plate as image shapes. ([#9994](https://github.com/tldraw/tldraw/pull/9994))
- Fix **Flatten to image** producing different groupings depending on selection order, and not merging clusters that were only connected through a bridging shape. ([#8661](https://github.com/tldraw/tldraw/pull/8661))

### Editor

- Fix dragging a frame out of its parent when grabbed over a nested child, and restore a child's original z-order when dragged back into a frame. ([#10329](https://github.com/tldraw/tldraw/pull/10329))
- Fix camera constraints for bounds away from the page origin, and clamp padding against the correct viewport axis. ([#10337](https://github.com/tldraw/tldraw/pull/10337))
- Fix `setCameraOptions({ zoomSteps: undefined })` breaking every later camera move. ([#10387](https://github.com/tldraw/tldraw/pull/10387))
- Fix `slideCamera` zoom momentum driving the zoom to zero on a long frame. ([#10388](https://github.com/tldraw/tldraw/pull/10388))
- Fix malformed viewport deep links moving the camera to the origin instead of falling back to fitting the page content. ([#10508](https://github.com/tldraw/tldraw/pull/10508))
- Fix following a user whose own leader has left or has no presence yet. ([#10389](https://github.com/tldraw/tldraw/pull/10389))
- Fix `getSelectionRotatedScreenBounds` going stale when the editor container moves. ([#10390](https://github.com/tldraw/tldraw/pull/10390))
- Fix `duplicateShapes` throwing on unknown ids and offsetting nested duplicates twice. ([#10355](https://github.com/tldraw/tldraw/pull/10355))
- Fix `packShapes` packing shapes of different heights into a single column. ([#10381](https://github.com/tldraw/tldraw/pull/10381))
- Fix `stackShapes` reordering shapes when a gap is given. ([#10383](https://github.com/tldraw/tldraw/pull/10383))
- Fix nested 270° shapes being dropped from axis-aligned shape clustering. ([#10384](https://github.com/tldraw/tldraw/pull/10384))
- Fix `putContentOntoCurrentPage` mutating the content passed to it. ([#10367](https://github.com/tldraw/tldraw/pull/10367))
- Fix `setErasingShapes` mutating its input array, so it accepts store-owned (frozen) arrays. ([#10371](https://github.com/tldraw/tldraw/pull/10371))
- Fix the teardown returned by the `createTLStore` `onMount` option never running when the editor unmounts. ([#10375](https://github.com/tldraw/tldraw/pull/10375))
- Fix drop events inside the canvas never reaching React drop handlers, and keep Safari gesture suppression working with multiple editors on a page. ([#10360](https://github.com/tldraw/tldraw/pull/10360))
- Fix object URLs for locally persisted assets leaking across remounts. ([#10361](https://github.com/tldraw/tldraw/pull/10361))
- Fix the click-capture overlay staying over the canvas after right-click panning with a menu open. ([#10359](https://github.com/tldraw/tldraw/pull/10359))
- Fix hiding and showing menus by context id, and tolerate corrupt user-preference data in localStorage. ([#10344](https://github.com/tldraw/tldraw/pull/10344))
- Fix `Vec.Slope`, `Vec.cross`, and `areAnglesCompatible` for negative angles, `rotateSelectionHandle` for negative rotations, and dotted dash arrays for very short paths. ([#10352](https://github.com/tldraw/tldraw/pull/10352))
- Fix laser trails staying visible after changing page. ([#10509](https://github.com/tldraw/tldraw/pull/10509))
- Fix locking a mixed selection of locked and unlocked shapes leaving the shapes selected. ([#10480](https://github.com/tldraw/tldraw/pull/10480))
- Fix wheel event normalization passing through non-finite delta values. ([#9586](https://github.com/tldraw/tldraw/pull/9586))

### UI

- Fix the **Frame selection** shortcut (Ctrl+Alt+G) not working on Windows and Linux. ([#10481](https://github.com/tldraw/tldraw/pull/10481))
- Fix pasted text shapes and bookmarks not being selected after paste. ([#10485](https://github.com/tldraw/tldraw/pull/10485))
- Fix context-menu paste landing under the pointer instead of at the right-click point. ([#10488](https://github.com/tldraw/tldraw/pull/10488))
- Fix file drops and pastes silently doing nothing when one of the files is an image that can't be decoded. The bad file is now skipped with an error toast and the other files are placed. ([#10495](https://github.com/tldraw/tldraw/pull/10495))
- Fix the **Edit link** dialog staying open as an empty panel when its shape is deleted or deselected. ([#10496](https://github.com/tldraw/tldraw/pull/10496))
- Fix wheel and trackpad scrolling over the minimap moving the camera at double rate. ([#10499](https://github.com/tldraw/tldraw/pull/10499))
- Fix the actions menu button appearing, and opening empty, in readonly mode with the hand and zoom tools. ([#10503](https://github.com/tldraw/tldraw/pull/10503))
- Fix closing a stacked dialog by touch also closing the dialog beneath it. ([#10002](https://github.com/tldraw/tldraw/pull/10002))
- Fix the loading screen not honoring the system theme on a dark OS, and the reduce motion preference not following the OS setting until a reload. ([#10528](https://github.com/tldraw/tldraw/pull/10528))
- Fix the storage read-failure alert promising a reload that never happened. ([#10530](https://github.com/tldraw/tldraw/pull/10530))
- Fix the casing of the error fallback's refresh button. ([#10362](https://github.com/tldraw/tldraw/pull/10362))
- Fix pasted links showing a broken preview image when the linked page has no Open Graph image. ([#9909](https://github.com/tldraw/tldraw/pull/9909))
- Fix the counterclockwise rotation tooltip not showing its comma key. ([#9772](https://github.com/tldraw/tldraw/pull/9772))
- Fix the spacing around the cursor chat item in the context menu. ([#9921](https://github.com/tldraw/tldraw/pull/9921))
- Fix the people menu's collaborator rows not lining up with your own row above them: the follow icon sat too close to the right edge, and collaborator names sat slightly left of your own. ([#9900](https://github.com/tldraw/tldraw/pull/9900))
- Fix the comment thread popover briefly rendering with a doubled shadow the first time a thread is opened. ([#9886](https://github.com/tldraw/tldraw/pull/9886))

### Persistence and sync

- Fix edits made in the last 350 ms before closing or reloading a tab being lost from local persistence. ([#10526](https://github.com/tldraw/tldraw/pull/10526))
- Fix background tabs repeatedly dropping and re-establishing their sync connection when the browser throttles timers. ([#9964](https://github.com/tldraw/tldraw/pull/9964))
- Fix `useSyncDemo` creating assets for uploads the server rejected. ([#10109](https://github.com/tldraw/tldraw/pull/10109))
- Fix `loadSnapshot` failing on better-sqlite3, and `NodeSqliteWrapper` getting stuck in a transaction when `COMMIT` fails. ([#10111](https://github.com/tldraw/tldraw/pull/10111), [#10113](https://github.com/tldraw/tldraw/pull/10113))

### Signals and store

- Fix computeds returning stale values when read inside a transaction during an effect, from a deferred effect, or after a reactor restarts. ([#10145](https://github.com/tldraw/tldraw/pull/10145))
- Fix effects with no signal dependencies re-running on every `start()`. ([#10148](https://github.com/tldraw/tldraw/pull/10148))
- Fix nested transactions inside effects not rolling back with their parent. ([#10149](https://github.com/tldraw/tldraw/pull/10149))
- Fix effects observing half-restored state when a `deferAsyncEffects` call throws. ([#10150](https://github.com/tldraw/tldraw/pull/10150))
- Fix `@computed` on a subclass override that calls `super`, and `@computed()` with no arguments. ([#10151](https://github.com/tldraw/tldraw/pull/10151))
- Fix computeds re-running their compute function on every read after their first derive throws. ([#10152](https://github.com/tldraw/tldraw/pull/10152))
- Fix computeds read inside an atom's `computeDiff` never seeing that change, and an explicit `null` diff passed to `atom.set()` or returned from `withDiff()` clearing history. ([#10153](https://github.com/tldraw/tldraw/pull/10153))
- Fix `localStorageAtom` throwing outside the browser. ([#10154](https://github.com/tldraw/tldraw/pull/10154))
- Fix a stack overflow in `ImmutableMap` and `AtomMap` for keys named after `Object.prototype` members, and make `NaN` and `-0` key equality match native `Map`. ([#10202](https://github.com/tldraw/tldraw/pull/10202))
- Fix `AtomMap` throwing when an entry is deleted mid-iteration. ([#10209](https://github.com/tldraw/tldraw/pull/10209))
- Fix `StoreSchema.create` reporting a redundant migration dependency as circular. ([#10213](https://github.com/tldraw/tldraw/pull/10213))
- Fix the `store.query.ids()` query creator being called with a computed's `(previousValue, epoch)` arguments. ([#10218](https://github.com/tldraw/tldraw/pull/10218))
- Fix `CollectionDiff`s from `store.query.ids()` and `index()` containing an empty `added` or `removed` set after an add/remove round trip. ([#10221](https://github.com/tldraw/tldraw/pull/10221))

--------

# Migration skill

The `tldraw-migrate` skill is an agent skill that helps you migrate a project to a newer version of the tldraw SDK. You point your coding agent at it, and it detects the previous version, fetches the release notes for everything between then and now, upgrades the packages, and works through any TypeScript errors using the migration guides published in our release notes.

<Callout type="info">
	This skill is experimental. It is designed to guide your migration, not to run it unattended.
	Treat its output as a starting point. Review the diff, run your own tests, and watch for changes
	the skill missed or got wrong.
</Callout>

## What it does

The skill packages our migration workflow into a single command so an agent can apply it to your codebase:

- Detects the tldraw version your project is migrating from and the target you're migrating to.
- Fetches the public release notes between those two versions and caches them next to the skill, along with the full SDK docs for ad-hoc lookup.
- Inspects your project to figure out the package manager, which tldraw packages are installed, which import style you use, and how your typecheck and build scripts are configured.
- Upgrades every tldraw package already in `package.json` to the resolved target.
- Categorizes the resulting TypeScript errors by code, then fixes them in order of impact: React types first, then custom shape and binding registration, then API renames and removals, then TipTap, then anything left over.
- Sweeps the project for `@deprecated` API usage and applies the recommended replacements.
- Verifies with the project's typecheck and build, and audits the diff for new `as` casts or unsafe module augmentations.

The version-specific recipes come from the `<details><summary>Migration guide</summary>` blocks in our release notes. The skill doesn't carry its own copy of these recipes; it reads the release notes at run time, so a single skill works across releases.

## Adding the skill to your project

The easiest way to install the skill is to ask your agent:

```
Using the instructions in the README file at https://github.com/tldraw/tldraw/blob/main/skills/tldraw-migrate/README.md upgrade my project to the latest version of tldraw using the migration skill
```

For more control, see the [manual installation](#manual-installation) options below.

## How to use it

Once the skill is installed, ask your agent to migrate your project. It auto-detects your current version, reviews the SDK changes between then and the target, and proposes updates.

## Manual installation

Copy the entire `tldraw-migrate/` folder into one of the locations the skill probes, relative to your project root. The skill checks them in this order and uses the first one it finds:

| Path                             | Harness                              |
| -------------------------------- | ------------------------------------ |
| `.claude/skills/tldraw-migrate/` | Claude Code                          |
| `.agents/skills/tldraw-migrate/` | Generic / open agent-skills spec     |
| `.codex/skills/tldraw-migrate/`  | OpenAI Codex                         |
| `.cursor/skills/tldraw-migrate/` | Cursor                               |
| `skills/tldraw-migrate/`         | Fallback / vendored alongside source |

If multiple harnesses share a project, install once and symlink the others to the same folder.

### One-shot install from GitHub

```sh
DEST=.claude/skills/tldraw-migrate   # or .agents/skills/..., .codex/skills/..., .cursor/skills/..., etc.
mkdir -p "$DEST"
curl -fsSL https://github.com/tldraw/tldraw/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=3 -C "$DEST" tldraw-main/skills/tldraw-migrate
```

To install from a local checkout of the tldraw monorepo, copy `skills/tldraw-migrate/` into one of the paths above directly.

### Updating an installed copy

Re-run the one-shot install above to overwrite `SKILL.md` and the helper scripts. The skill's content (release notes and docs) is auto-refreshed on every invocation, so you only need to update `SKILL.md` when the workflow changes.

### Custom install location

If you keep the skill somewhere outside the probed paths, export `SKILL_DIR` before invocation:

```sh
SKILL_DIR=/abs/path/to/tldraw-migrate
```

The auto-fetch blocks and internal grep examples in `SKILL.md` honor this variable.

## Where to find it

The canonical source is [`skills/tldraw-migrate/`](https://github.com/tldraw/tldraw/tree/main/skills/tldraw-migrate) in the [tldraw](https://github.com/tldraw/tldraw) monorepo. The folder is self-contained:

- `SKILL.md` — the workflow the agent follows.
- `detect-versions.mjs` — resolves the "from" version.
- `detect-target.mjs` — resolves the "to" version (defaults to `latest` but can take a tag like `canary`/`next`/`beta`, or a pre-release version).
- `fetch-release-notes.mjs` — pulls release notes from the docs markdown files in the tldraw repo.
- `references/` — auto-populated cache of fetched release notes and docs (created on first run; safe to gitignore).

GitHub is the deliberate source of truth: sourcing release notes from `main` rather than from a deployed docs site means migration recipes for unreleased versions are available to the skill the moment they land.

## Requirements

| Requirement    | Purpose                                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Node ≥ 20      | Required for the helper scripts. They are zero-dependency ES modules.                                                  |
| `curl`         | Required for the docs fetch.                                                                                           |
| `git`          | Optional. Improves from-version detection (the skill compares `main`, `HEAD~1`, and the working tree).                 |
| `GITHUB_TOKEN` | Optional. Raises GitHub's unauthenticated API rate limit (60/hr) so re-runs and long version ranges don't hit the cap. |

--------

# v5.3.0

[View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v5.3.0)

This release adds commenting: a set of new packages for anchored comment threads on the canvas, backed by comment records in the schema and sync support for non-document data. Commenting is the first piece of our new collaboration package, a separately licensed section of the SDK for premium collaboration features. The release also adds flipping for geo shapes, snapping and symmetric resizing while cropping images, an `assets` prop for `TldrawImage`, and a reactive `Editor.getIsMounted()` with a new `unmount` event. Viewport culling is faster on large pages, and there's a batch of fixes for crashes and interaction bugs across arrows, groups, and text.

## What's new

### Commenting ([#9471](https://github.com/tldraw/tldraw/pull/9471), [#9782](https://github.com/tldraw/tldraw/pull/9782), [#9850](https://github.com/tldraw/tldraw/pull/9850))

Comments are now a first-class primitive in the SDK. `@tldraw/commenting` ships a batteries-included canvas comments layer: threads anchor to a point, a shape (precisely or imprecisely), a text range, a region, or the page. You can reply, edit, react, resolve, and delete comments. The pins drag to re-anchor, and `?comment=<id>` deep links open a thread and bring the camera to its pin. Comment pins cluster together as you zoom out and separate back out as you zoom in.

Comment records live in `@tldraw/tlschema` as `TLCommentThread`, `TLComment`, and `TLCommentReaction`, and sync over a new generic object store in `@tldraw/sync-core`, so they ride alongside the document rather than inside it. On the server, `@tldraw/sync-collaboration` enforces write authorization, with a `canModifyComment` rule that lets a host widen the default owner-only permission. That way a workspace admin can moderate comments they don't own without granting anything beyond edit, delete, and resolve.

One rollout note: the comment record types ship with guard migrations, so once your server registers them, clients on an older SDK are rejected as too old and prompted to refresh. Roll out the upgraded client before or alongside the server change.

The layer is built to be taken apart. `ThreadRow` and `ThreadActions` are component slots, `CommentListItem` and `sortSidebarRows` are exported so a hand-built list can match the built-in one, and a host that supplies `getThreadHref` gets copy-link in the thread menu. On phones, the composer and the open thread stay above the software keyboard.

<details>
<summary>New packages</summary>

| Package                      | What it provides                                                         |
| ---------------------------- | ------------------------------------------------------------------------ |
| `@tldraw/commenting`         | Canvas comments layer, comment UI components, and the comment tool       |
| `@tldraw/mentions`           | @-mention picker and TipTap node, shared by comments and shape rich text |
| `@tldraw/collaboration`      | Umbrella package for the collaboration pieces                            |
| `@tldraw/sync-collaboration` | Server-side write authorization for collaboration features               |

</details>

See the [commenting docs](https://tldraw.dev/docs/commenting) for setup.

## API changes

- 💥 Remove `usePassThroughMouseOverEvents` from `@tldraw/editor`. It re-dispatched `mouseover` at `.tl-canvas` so shapes under a floating panel stayed hovered, but the canvas only wires `onPointerEnter`, so the re-dispatched event arrived at an element with no listener for it. ([#9782](https://github.com/tldraw/tldraw/pull/9782))
- Add `TLCommentThread`, `TLComment`, and `TLCommentReaction` records to `@tldraw/tlschema`, with `createCommentThread` and `createComment` helpers, id helpers, validators, and `commentSchemaRecords` for registering them. ([#9471](https://github.com/tldraw/tldraw/pull/9471), [#9782](https://github.com/tldraw/tldraw/pull/9782))
- Add a generic object store to `@tldraw/sync-core` for syncing non-document records: `objectTypes` on the room and storage constructors, per-session `TLObjectStoreAccess`, `getObjectsSnapshot()`, `onCommittedChanges`, and an optional `TLSyncStorage.getObjectsByIds(ids)` for callers that need a few object-lane records rather than the whole lane. ([#9471](https://github.com/tldraw/tldraw/pull/9471), [#9782](https://github.com/tldraw/tldraw/pull/9782))
- Add `objectAccess` to the `synced-remote` member of `RemoteTLStoreWithStatus`, so a store from `useSync` reports whether the session can write object-lane records such as comments. If you construct that type yourself, in test mocks for example, you now need to supply `objectAccess`. ([#9471](https://github.com/tldraw/tldraw/pull/9471))
- Add `EditorPortal`, `EditorPortalProps`, and `useEditorPortalHost` to `@tldraw/editor`, for portalling canvas-anchored content into a host the editor renders last so its DOM order doesn't depend on mount timing. ([#9782](https://github.com/tldraw/tldraw/pull/9782))
- Add `renderHtmlFromRichTextWithExtensions(richText, extensions)` for rendering rich text outside a shape's editor config. `renderHtmlFromRichText` now fills _every_ empty paragraph with a `<br />` and keeps the paragraph's attributes, so an empty paragraph renders as `<p dir="auto"><br /></p>` — worth knowing if you snapshot that output. ([#9782](https://github.com/tldraw/tldraw/pull/9782))
- Add `flipX` and `flipY` to `TLGeoShapeProps`, with an `AddFlipProps` migration defaulting both to `false`, and add `PathBuilder.transform(mat)` for producing a transformed copy of a path. ([#9530](https://github.com/tldraw/tldraw/pull/9530))
- Add an optional `sizeToContentAspectRatio` to `EmbedDefinition` and a public `EmbedShapeUtil.resolveAspectRatio(shape)`. When set, an embed corrects its size after creation to its content's real aspect ratio, resolved from the URL's OpenGraph metadata via the editor's url asset handler. Existing custom embed definitions are unaffected. ([#9613](https://github.com/tldraw/tldraw/pull/9613))
- Add `ExportAsMenuGroup`, mirroring `CopyAsMenuGroup`, for the "Export as" submenu. ([#9589](https://github.com/tldraw/tldraw/pull/9589))
- Add `EditorManager`, a public abstract base class for editor managers that own a subscription or resource, so they share one teardown contract. `InputsManager`, `TickManager`, `FocusManager`, and `TextManager` now extend it. ([#9204](https://github.com/tldraw/tldraw/pull/9204))
- Populate `TLBaseExternalContent.sources` for file pastes, where it was previously always undefined, so custom `files` handlers and `onBeforePasteFromClipboard` can inspect the text, HTML, and url content that came alongside the files. ([#9763](https://github.com/tldraw/tldraw/pull/9763))
- Add an `assets` prop to `TldrawImage`, so a snapshot's images render from a custom asset store the same way they do in `Tldraw`. Previously `TldrawImage` always used the inline base64 asset store, so images kept anywhere else were missing. ([#9697](https://github.com/tldraw/tldraw/pull/9697)) (based on an implementation by [@jon-dez](https://github.com/jon-dez))

  ```tsx
  <TldrawImage snapshot={snapshot} assets={assetStore} />
  ```

- Add an `unmount` event to `TLEventMap` and make `Editor.getIsMounted()` a reactive value that tracks whether the editor's component is currently mounted. ([#9472](https://github.com/tldraw/tldraw/pull/9472), [#9483](https://github.com/tldraw/tldraw/pull/9483))
- Make the shape hit-test margin pointer-aware and add a `coarseHitTestMargin` option: fine pointers (mouse and trackpad) use a tighter 3px default, coarse pointers (touch and pen) use 4px. ([#9492](https://github.com/tldraw/tldraw/pull/9492))
- Add a `ShapeUtil.onDuplicate(source, duplicate)` callback, invoked by `Editor.duplicateShapes` and `Editor.putContentOntoCurrentPage`, so a shape can adjust its props when it is copied. Sticky notes now use it to attribute duplicated or pasted text to the current user instead of carrying over the original author. ([#9566](https://github.com/tldraw/tldraw/pull/9566))

## Improvements

- Geo shapes now flip. Previously flipping a selection left directional shapes such as the rhombus, trapezoid, and arrow geo shapes looking exactly the same on the other side of the mirror. `TLGeoShape` gains `flipX` and `flipY` props, matching the image shape, and a flip mirrors the shape's generated path. Geometry, hit-testing, the selection indicator, the canvas render, and SVG export all read from that path, so they stay in agreement. ([#9530](https://github.com/tldraw/tldraw/pull/9530))
- When cropping an image, crop edges now snap to other shapes and the grid, with the usual snapping guidelines. Holding Alt resizes the crop region symmetrically from its center. ([#9424](https://github.com/tldraw/tldraw/pull/9424))
- Size embeds from providers that report their content's dimensions (currently Vimeo) to that content's real aspect ratio, so a video is no longer letterboxed inside a 16:9 box. The corrected embed keeps the area of the original box, so a portrait video doesn't balloon over whatever sits above and below it. ([#9613](https://github.com/tldraw/tldraw/pull/9613), [#9756](https://github.com/tldraw/tldraw/pull/9756))
- Hide the "Copy as", "Export as", and "Export file" submenus, and the main menu's export group, when a consumer has removed all of their actions through `overrides`, instead of leaving an empty submenu trigger behind. ([#9589](https://github.com/tldraw/tldraw/pull/9589))
- Improve viewport culling performance on large pages: the spatial index now rechecks only the shapes affected by a change instead of every shape on the page. Custom shapes whose geometry depends on unrelated shapes (outside parent/child and binding relationships) are no longer automatically rechecked for culling when those shapes change; built-in shapes and standard patterns are unaffected. ([#9093](https://github.com/tldraw/tldraw/pull/9093))
- Improve performance when deleting many shapes at once by batching page state cleanup. ([#9456](https://github.com/tldraw/tldraw/pull/9456))
- Make long toast and dialog content wrap instead of overflowing, so long strings like URLs stay within the toast or dialog. ([#9546](https://github.com/tldraw/tldraw/pull/9546))
- Delay the appearance of the "back to content" button by about a second so it no longer flickers during normal panning and zooming. Hiding stays immediate. ([#9448](https://github.com/tldraw/tldraw/pull/9448))
- Remove the unnecessary ellipsis from the "Keyboard shortcuts" menu item. ([#9570](https://github.com/tldraw/tldraw/pull/9570))

## Bug fixes

- Fix zooming and panning not working while the cursor is over a non-scrollable UI overlay. The wheel pass-through guard treated any element whose content overflowed as scrollable, and a hover transform on a small overlay was enough to trigger that. Overlays now count as scrollable only when their computed `overflow` says so. ([#9698](https://github.com/tldraw/tldraw/pull/9698))
- Fix a crash when dragging content from another browser tab whose URL isn't a valid link, which happens when an ad blocker rewrites the dragged URL to something like `about:blank#blocked`. Dropping one now shows an error toast instead of failing validation on the bookmark shape. ([#9598](https://github.com/tldraw/tldraw/pull/9598))
- Fix the "URL" label wrapping onto two lines in the edit link and embed dialogs. ([#9663](https://github.com/tldraw/tldraw/pull/9663))
- Fix rich text headings (H1–H6) rendering with their line-height too tight, causing overlapping lines. ([#9543](https://github.com/tldraw/tldraw/pull/9543))
- Fix the style panel not highlighting the active fill correctly when the current fill lives in the overflow dropdown. ([#9509](https://github.com/tldraw/tldraw/pull/9509))
- Fix the style panel Shape, Line, and spline dropdown popovers so they open with the same gap as the other dropdowns. ([#9491](https://github.com/tldraw/tldraw/pull/9491))
- Fix double-clicking a shape inside an unfocused group immediately editing it; a double-click now drills one level into the group. ([#9488](https://github.com/tldraw/tldraw/pull/9488))
- Fix selected clipped arrows so they can be dragged when their geometry extends outside a clipping parent. ([#9479](https://github.com/tldraw/tldraw/pull/9479))
- Fix arrows bound to frames so they duplicate and delete with the frame without being clipped. ([#9470](https://github.com/tldraw/tldraw/pull/9470))
- Fix a shape dragged from the toolbar to a frame beneath the toolbar not being parented to the frame. ([#9458](https://github.com/tldraw/tldraw/pull/9458))
- Fix a missing `onChildrenChange` call when creating a shape directly within a parent shape. ([#9455](https://github.com/tldraw/tldraw/pull/9455))
- Fix the reactive Meta (Cmd) key state not clearing on keyup until a pointer event on macOS, which affected `getMetaKey()` and `getAccelKey()`. ([#9404](https://github.com/tldraw/tldraw/pull/9404))
- Fix a crash when dragging a handle on a line whose point keys differed from their indices. ([#9299](https://github.com/tldraw/tldraw/pull/9299))
- Fix arrow bindings floating outside a geo shape after changing its geo type; precise bindings now re-snap to the nearest point on the new shape. ([#9281](https://github.com/tldraw/tldraw/pull/9281))
- Fix an occasional crash in text measurement by iterating over grapheme clusters instead of individual characters, keeping emoji, flags, and accented characters intact. ([#9266](https://github.com/tldraw/tldraw/pull/9266))
- Fix a crash ("Shape not found") when dragging a tool from the toolbar in a read-only room. ([#9225](https://github.com/tldraw/tldraw/pull/9225))
- Fix sync clients not recovering from a malformed WebSocket message; they now restart the connection so a corrupt frame can no longer silently leave the client out of sync. ([#9380](https://github.com/tldraw/tldraw/pull/9380))
- Fix uploaded asset handling for invalid R2 object names. ([#9495](https://github.com/tldraw/tldraw/pull/9495))
- Fix a crash when a custom font failed to load after its editor had been disposed. ([#9494](https://github.com/tldraw/tldraw/pull/9494))
- Fix license expiry being evaluated in local time, which could deactivate a license a calendar day early for users west of UTC; the expiry date is now treated as the last fully usable day in UTC. ([#9475](https://github.com/tldraw/tldraw/pull/9475))

---

## Patch releases

### v5.3.1

- Fix touches in part of the canvas being ignored on iOS when the editor was inset from the edge of the page, such as beside a sidebar. ([#9989](https://github.com/tldraw/tldraw/pull/9989))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v5.3.1)

### v5.3.2

- Fix default UI components, such as `DefaultToolbar` and `DefaultQuickActionsContent`, crashing when mounted outside the `Tldraw` component. ([#10007](https://github.com/tldraw/tldraw/pull/10007))
- Fix license validation treating native apps served from custom protocols as development environments. ([#10021](https://github.com/tldraw/tldraw/pull/10021))
- Fix wildcard license host matching so `*.example.com` matches only that domain's subdomains. ([#10053](https://github.com/tldraw/tldraw/pull/10053))
- Add product metadata to each published package's `package.json`, so which product or feature a package implements is clearer, and ship the missing `LICENSE.md` files. ([#9977](https://github.com/tldraw/tldraw/pull/9977))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v5.3.2)

--------

# v5.2.0

[View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v5.2.0)

This release brings in performance improvements across tldraw. The freehand ink algorithm now computes strokes 2–3x faster, shape resizing is quicker, and editor load time is reduced. Multi-click handling was simplified to double-click only to support improved mobile gestures. Plus it's easier to add shapes to frames, and dozens of bugs were fixed.

## What's new

### Faster freehand ink ([#9154](https://github.com/tldraw/tldraw/pull/9154))

We rewrote the freehand ink algorithm. Draw and highlighter strokes now compute about 2x faster (up to 3x for long strokes) and produce 57% smaller SVG path data, with no visible change to how strokes look. The rewrite removes two rarely-used stroke APIs; see the breaking changes in [API changes](#api-changes).

### Frame selection ([#8151](https://github.com/tldraw/tldraw/pull/8151))

A new "Frame selection" action wraps the selected shapes in a frame with `cmd+shift+f`. When a frame is selected, the same shortcut removes it.

## API changes

- 💥 Simplify multi-click handling to double-click only. `ClickManager` no longer tracks triple or quadruple clicks: the `triple_click` and `quadruple_click` events and the `onTripleClick` / `onQuadrupleClick` handlers have been removed, and `TLClickEventName` is now just `'double_click'`. ([#8897](https://github.com/tldraw/tldraw/pull/8897))
- 💥 Move `ShapeIndicatorOverlayUtil` and `TLShapeIndicatorOverlay` from `@tldraw/editor` to `tldraw`. Both are still exported from `tldraw`; update any imports of these symbols that came directly from `@tldraw/editor`. ([#9018](https://github.com/tldraw/tldraw/pull/9018))
- 💥 Drop support for the EOL Node 20. The minimum supported Node is now `>=22.12.0`, the first version with native `require()` of ES modules, so tldraw can depend on ESM-only packages. ([#9098](https://github.com/tldraw/tldraw/pull/9098))
- 💥 Type the collaborator user-id APIs as `TLUserId` instead of `string`. `TLInstancePresence.userId` / `followingUserId`, `TLInstance.followingUserId` / `highlightedUserIds`, `Editor.startFollowingUser()`, `Editor.zoomToUser()`, `usePresence()`, `usePeerIds()`, and the people-menu prop types now use `TLUserId`. Runtime behavior is unchanged: `TLUserId` is a branded string, so cast plain strings at the call site, for example `editor.startFollowingUser(userId as TLUserId)`. ([#9002](https://github.com/tldraw/tldraw/pull/9002))
- 💥 Remove `StrokePoint.vector` and `setStrokePointRadii` from the freehand stroke pipeline. The vector is derivable from consecutive points and radius/taper computation now happens inside `getStroke` and `svgInk`; nothing in the SDK consumed these outside the pipeline itself. ([#9154](https://github.com/tldraw/tldraw/pull/9154))
- 💥 Remove the obsolete selection-background slot from `@tldraw/editor`: `DefaultSelectionBackground`, `TLSelectionBackgroundProps`, `TLEditorComponents.SelectionBackground`, and the `useTransform` helper. These were unused and have no replacement; remove any references to them. ([#9362](https://github.com/tldraw/tldraw/pull/9362))
- Add an `embedConfig` option to `EmbedShapeUtil` for passing per-embed configuration such as API keys. The default Google Maps embed no longer reads `process.env.NEXT_PUBLIC_GC_API_KEY` — pass the key explicitly instead. ([#9068](https://github.com/tldraw/tldraw/pull/9068))

  ```ts
  EmbedShapeUtil.configure({
  	embedConfig: { google_maps: { apiKey: '...' } },
  })
  ```

- Add an `allowVideoAutoplay` option to `TldrawOptions`. When set to `false`, no video shape autoplays regardless of its per-shape `autoplay` prop — including pasted and restored shapes. Defaults to `true`. ([#8943](https://github.com/tldraw/tldraw/pull/8943))
- Add `ShapeUtil.getContentElement` and `ShapeUtil.onReleaseContentElement`, an app-owned content element lifecycle that lets stateful shape content (such as cross-origin iframes) survive unmounting the editor. ([#9167](https://github.com/tldraw/tldraw/pull/9167))

## Improvements

- Open the context menu with a right-click from any tool, not just the select tool, and with a touch long-press while using the select tool. Long-pressing on a shape-creation tool no longer leaves a stray shape behind. ([#8948](https://github.com/tldraw/tldraw/pull/8948))
- Add a `shift+q` shortcut that copies the styles of the hovered shape and applies them to the next shapes you create. ([#9028](https://github.com/tldraw/tldraw/pull/9028))
- Add a double-tap-and-drag zoom gesture for touch devices. ([#7858](https://github.com/tldraw/tldraw/pull/7858))
- As you drag out a frame, the frame tool now highlights the shapes it will enclose. ([#9102](https://github.com/tldraw/tldraw/pull/9102))
- Pasted bookmarks now show an immediate loading placeholder with a spinner at the paste location, instead of waiting for metadata before appearing. ([#8663](https://github.com/tldraw/tldraw/pull/8663))
- Add the missing keyboard shortcuts (copy as PNG, print, insert embed, highlight tool, frame selection, flatten, toggle locked, distribute horizontally/vertically) to the keyboard shortcuts dialog. ([#9285](https://github.com/tldraw/tldraw/pull/9285))
- Make the selection corner rotate handles easier to grab. ([#9374](https://github.com/tldraw/tldraw/pull/9374))
- Reduce the default indentation on rich-text lists so nested lists take up less horizontal space. ([#9287](https://github.com/tldraw/tldraw/pull/9287))
- Hide the "back to content" button during the animation that pans back to the canvas when focusing it. ([#9278](https://github.com/tldraw/tldraw/pull/9278))
- Remove the extraneous `title` tooltips on menu items. ([#9315](https://github.com/tldraw/tldraw/pull/9315))
- `@tldraw/mermaid` now loads its ESM-only `mermaid` dependency lazily, so the package is requirable from CommonJS and mermaid only loads when a diagram is created. ([#9100](https://github.com/tldraw/tldraw/pull/9100))
- Keep sync at full speed when the same multiplayer room is open in multiple tabs, windows, or devices — previously a room with no other users throttled network sync to once per second. ([#8988](https://github.com/tldraw/tldraw/pull/8988))
- Include `DOCS.md` documentation in published npm packages, and a generated docs and release notes rollup in the `tldraw` package, so documentation is available when browsing package artifacts. ([#8503](https://github.com/tldraw/tldraw/pull/8503))
- Shrink stored draw shape data for mouse, trackpad, and finger input by ~33% by omitting the redundant constant-pressure value from the encoded path. ([#8963](https://github.com/tldraw/tldraw/pull/8963))
- Improve performance when resizing many shapes at once. ([#9153](https://github.com/tldraw/tldraw/pull/9153))
- Improve change tracking and sync performance when many shapes change at once. ([#9151](https://github.com/tldraw/tldraw/pull/9151), [#9152](https://github.com/tldraw/tldraw/pull/9152))
- Improve validation performance during high-frequency updates. ([#9150](https://github.com/tldraw/tldraw/pull/9150))
- Speed up editor load by caching generated pattern fill defs and deduplicating icon preloads, so neither is rebuilt on every editor mount. ([#9345](https://github.com/tldraw/tldraw/pull/9345), [#9351](https://github.com/tldraw/tldraw/pull/9351))
- Remove the `jittered-fractional-indexing` dependency and speed up index key generation and validation; newly generated index keys are slightly shorter. ([#9352](https://github.com/tldraw/tldraw/pull/9352))
- Improve minimap rendering performance on large documents. ([#9355](https://github.com/tldraw/tldraw/pull/9355))

## Bug fixes

- Fix the fill style dropdown trigger showing a misleading tooltip for the currently selected fill. ([#9023](https://github.com/tldraw/tldraw/pull/9023))
- Fix a two-finger pinch unintentionally changing the selection on touch devices. ([#9006](https://github.com/tldraw/tldraw/pull/9006))
- Pasting content while dragging, translating, resizing, or rotating no longer steals selection from the shape being manipulated. ([#8976](https://github.com/tldraw/tldraw/pull/8976))
- Fix a bug where pressing `Tab` while editing a list inside a note shape created a new note instead of indenting the list item. ([#8958](https://github.com/tldraw/tldraw/pull/8958))
- Fix the viewport shifting slightly when zooming past the minimum or maximum zoom level. ([#8957](https://github.com/tldraw/tldraw/pull/8957))
- Improve the contrast of disabled buttons and menu items in dark mode. ([#8931](https://github.com/tldraw/tldraw/pull/8931))
- Fix `debounce(...).cancel()` leaving an awaited call hanging forever; it now rejects the pending promise. ([#8683](https://github.com/tldraw/tldraw/pull/8683))
- Fix arrows jumping to incorrect positions after undoing or redoing shape deletions involving bindings. ([#8283](https://github.com/tldraw/tldraw/pull/8283))
- Fix touch long-press on shape-creation tools so the context menu opens without leaving a stray shape behind. ([#8946](https://github.com/tldraw/tldraw/pull/8946))
- Fix text labels drifting vertically between browsers (e.g. Chrome vs Safari) in multiplayer by snapping line-height to whole pixels. ([#8981](https://github.com/tldraw/tldraw/pull/8981))
- Fix collaborators not appearing until they interact with the board, idle following peers not being hidden, the "following you" indicator not showing in the people menu, and a phantom cursor for your own other browser sessions. ([#9088](https://github.com/tldraw/tldraw/pull/9088), [#9002](https://github.com/tldraw/tldraw/pull/9002))
- Fix releasing a modifier while still holding a shortcut key triggering the adjacent non-modifier shortcut. ([#9099](https://github.com/tldraw/tldraw/pull/9099))
- Fix redo (`cmd+shift+z`) not firing after an undo (`cmd+z`) on macOS when cmd is kept held. ([#9139](https://github.com/tldraw/tldraw/pull/9139))
- Fix releasing a fast right-click pan zooming the camera to the maximum zoom level. ([#9140](https://github.com/tldraw/tldraw/pull/9140))
- Fix selection handles disappearing when pressing (but not yet dragging) a resize edge, resize corner, or rotate handle, and keep selection chrome consistent while pointing. ([#9179](https://github.com/tldraw/tldraw/pull/9179), [#9184](https://github.com/tldraw/tldraw/pull/9184))
- Fix double-clicking an arrow handle no longer toggling the arrowhead on that end. ([#9180](https://github.com/tldraw/tldraw/pull/9180))
- Fix the camera jumping when a one-finger hand-tool pan transitions into a two-finger pinch zoom. ([#9182](https://github.com/tldraw/tldraw/pull/9182))
- Fix arrows becoming partially un-hoverable and un-clickable when bindings were created or updated without a shape change (e.g. `createBindings` after `createShapes`). ([#9183](https://github.com/tldraw/tldraw/pull/9183))
- Fix camera state getting stuck at `moving` when the editor is disposed during camera movement (e.g. React strict mode with a shared store). ([#9201](https://github.com/tldraw/tldraw/pull/9201))
- Fix the following indicator border being hidden beneath UI panels. ([#9210](https://github.com/tldraw/tldraw/pull/9210))
- Fix the sync version-mismatch handshake reporting `CLIENT_TOO_OLD` when the server is the one running an older version; it now correctly reports `SERVER_TOO_OLD`. ([#9212](https://github.com/tldraw/tldraw/pull/9212))
- Fix ctrl+click on macOS not selecting locked shapes or opening the context menu; it now behaves like a right-click. ([#9234](https://github.com/tldraw/tldraw/pull/9234))
- Fix a crash that could occur when undo or redo restored an editing state for a shape that no longer exists. ([#9260](https://github.com/tldraw/tldraw/pull/9260))
- Fix the line tool's minimum bend distance so it's measured in screen pixels. Shift-click now behaves the same at every zoom level. ([#9275](https://github.com/tldraw/tldraw/pull/9275))
- Fix style scrubbing selecting the wrong option when you release the pointer over a different style section. ([#9280](https://github.com/tldraw/tldraw/pull/9280))
- Fix empty rich text (an empty array) not being treated as an empty label. ([#9295](https://github.com/tldraw/tldraw/pull/9295))
- Fix desktop graphics tablets (e.g. Wacom) incorrectly switching the editor into pen mode. Pen mode now auto-enables only for direct-display stylus input such as Apple Pencil on iPad or Surface Pen on a touchscreen. ([#9316](https://github.com/tldraw/tldraw/pull/9316))
- Fix inconsistent easing when clicking the minimap to move the camera. ([#9355](https://github.com/tldraw/tldraw/pull/9355))
- Fix sync clients crashing when a malformed WebSocket message is received. ([#9356](https://github.com/tldraw/tldraw/pull/9356))
- Fix a crash when measuring viewport bounds after the editor document body is unavailable. ([#9357](https://github.com/tldraw/tldraw/pull/9357))
- Fix highlighted rich text showing an outline in dark mode. ([#9358](https://github.com/tldraw/tldraw/pull/9358))
- Fix text in exported images sometimes being sized with a fallback font when the export ran before the document's fonts had finished loading. ([#9372](https://github.com/tldraw/tldraw/pull/9372))
- Fix a crash when a shape is deleted mid-click (e.g. by a remote user or an undo) while clicking on it. ([#9376](https://github.com/tldraw/tldraw/pull/9376))
- Fix the license manager treating loopback hosts other than `localhost` (such as `127.0.0.1` and `::1`) as production environments. ([#9384](https://github.com/tldraw/tldraw/pull/9384))
- Fix the crop of a grouped, cropped image shifting when the group is flipped by dragging a resize handle. ([#9395](https://github.com/tldraw/tldraw/pull/9395))

--------

# v5.1.0

[View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v5.1.0)

This release redesigns the page menu around inline interaction, adds a keyboard shortcut to copy styles from a hovered shape, and adds a `selectLockedShapes` option for inspecting locked shapes, along with new public translation APIs, canvas performance improvements, and various rendering and UI bug fixes.

## What's new

### Page menu redesign ([#8836](https://github.com/tldraw/tldraw/pull/8836))

The page menu no longer has an explicit edit mode. Reorder pages by dragging a row directly, rename inline by double-clicking the label or pressing Enter, and drag the new resize handle at the bottom of the popover to adjust the list height — the height is persisted across sessions and a double-click on the handle resets it to the default. The current page is now indicated by a subtle background pill, the row submenu trigger reveals on hover, and the "Create new page" button is pinned to the footer of the popover.

## API changes

- Add a `selectLockedShapes` option to `TldrawOptions`. When enabled, locked shapes can be selected by left click or by brush/scribble selection while remaining protected from edits, moves, and deletes. ([#8860](https://github.com/tldraw/tldraw/pull/8860))
- Export `TldrawUiTranslationProvider`, `AssetUrlsProvider`, and `useAssetUrls` as public API so components like `TldrawSelectionForeground` can be rendered without the full `TldrawUiContextProvider`. ([#8909](https://github.com/tldraw/tldraw/pull/8909))
- Add `FontManager.dispose()`, `OverlayManager.dispose()`, and `OverlayUtil.dispose()` for cleaning up manager state across editor lifecycles. ([#8896](https://github.com/tldraw/tldraw/pull/8896))

## Improvements

- Improve performance on busy canvases — `getRenderingShapes()` now skips its sort step when only shape props, not the set of shape ids, have changed. ([#8784](https://github.com/tldraw/tldraw/pull/8784))
- Improve drawing performance on pages with many shapes by skipping spatial index and culling recomputation when only shape props change. ([#8799](https://github.com/tldraw/tldraw/pull/8799), [#8804](https://github.com/tldraw/tldraw/pull/8804))

## Bug fixes

- Fix a misleading "license expired" console warning for perpetual licenses on covered versions. ([#8791](https://github.com/tldraw/tldraw/pull/8791))
- Fix inconsistent tooltip behavior on the video toolbar by using `TldrawUiToolbarButton` for the replace and download buttons. ([#8794](https://github.com/tldraw/tldraw/pull/8794))
- Fix the missing open-state hint on the page menu and zoom menu triggers when rendered outside the main toolbar. ([#8813](https://github.com/tldraw/tldraw/pull/8813))
- Mark the tldraw UI layer with `role="document"` so toolbars, menus, and dialogs stay reachable to mobile screen readers like VoiceOver and TalkBack, which do not announce the outer canvas `role="application"`. ([#8901](https://github.com/tldraw/tldraw/pull/8901))
- Fix selection edge resize handles overlapping corner handles, which made corners hard to grab on small shapes. ([#8926](https://github.com/tldraw/tldraw/pull/8926))
- Fix a bug where deleting a shape inside a group could move the group to a different z-index. ([#8925](https://github.com/tldraw/tldraw/pull/8925))
- Avoid console errors from calling `preventDefault` on non-cancelable events. ([#8910](https://github.com/tldraw/tldraw/pull/8910))
- Only log the missing-translation warning once per session instead of once per `useTranslation` consumer. ([#8909](https://github.com/tldraw/tldraw/pull/8909))
- Catch `image.decode()` rejections from the icon preload effect so they no longer surface as uncaught promise errors in the console. ([#8824](https://github.com/tldraw/tldraw/pull/8824))

--------

# v5.0.0

This major release introduces a first-class theme system with display values, a new `OverlayUtil` system for canvas overlays, and extensibility APIs for custom record types, asset types, geo shapes, and frame-like shapes. Two new packages ship alongside it: `@tldraw/driver` for imperative editor control and `@tldraw/mermaid` for converting Mermaid diagrams into native shapes. It also adds a shape attribution system with the `TLUserStore` provider, clipboard and performance-measurement hooks, WebSocket hibernation in tlsync, RTL support, cross-window embedding, and various other improvements and bug fixes.

## What's new

### 💥 Custom themes with display values ([#8410](https://github.com/tldraw/tldraw/pull/8410))

A new first-class theme system replaces the previous approach where colors were hardcoded and resolved inline. Themes are named, registered objects that shape utils consume via a structured display values pipeline.

Register custom themes via `TLThemes` module augmentation for type-safe IDs, add or remove palette colors via `TLThemeDefaultColors` and `TLRemovedDefaultThemeColors`, and pass themes to the editor via the `themes` and `initialTheme` props:

```tsx
<Tldraw themes={{ corporate: myCorporateTheme }} initialTheme="corporate" />
```

Each default shape util defines `getDefaultDisplayValues` to resolve visual properties (colors, stroke widths, font sizes) from the current theme and color mode. Override display values for a default shape with `getCustomDisplayValues`:

```tsx
const MyDrawShapeUtil = DrawShapeUtil.configure({
	getCustomDisplayValues(_editor, _shape, _theme, _colorMode) {
		return { strokeWidth: 10 }
	},
})
```

<details>
<summary>Migration guide</summary>

The `inferDarkMode` prop has been renamed to `colorScheme` and changed from `boolean` to `'light' | 'dark' | 'system'`:

```tsx
// Before
<Tldraw inferDarkMode />

// After
<Tldraw colorScheme="system" />
```

`useIsDarkMode()` has been renamed to `useColorMode()` and returns `'dark' | 'light'` instead of `boolean`.

`getDefaultColorTheme()` and `DefaultColorThemePalette` have been removed. Use `editor.getCurrentTheme().colors[colorMode]` instead:

```tsx
// Before
const theme = getDefaultColorTheme({ isDarkMode })

// After
const theme = editor.getCurrentTheme()
const colors = theme.colors[editor.getColorMode()]
```

`useDefaultColorTheme()` has been removed. Use `editor.getCurrentTheme()` and `useColorMode()` instead.

`FONT_FAMILIES`, `FONT_SIZES`, `LABEL_FONT_SIZES`, `STROKE_SIZES`, `TEXT_PROPS`, and `ARROW_LABEL_FONT_SIZES` have been removed — these are now resolved via display values.

`SvgExportContext.themeId` has been renamed to `SvgExportContext.colorMode` and changed from `string` to `'light' | 'dark'`.

`getColorValue()` now takes `TLThemeColors` as its first argument instead of `TLDefaultColorTheme`.

</details>

### 💥 Custom overlays ([#8469](https://github.com/tldraw/tldraw/pull/8469))

A new `OverlayUtil` system unifies canvas overlays. Built-in brushes, handles, scribbles, snap indicators, selection foreground, collaborator cursors, and arrow hints are now implemented as overlay utils and can be customized or extended via the `overlayUtils` prop.

Overlays now render in front of indicators in a unified `CanvasOverlays` layer, and the legacy default component implementations and their CSS have been removed.

<details>
<summary>Migration guide</summary>

The legacy overlay components have been removed from `TLEditorComponents`. Canvas overlays are now rendered directly to a 2D canvas context by `OverlayUtil` classes, and customization happens by subclassing the default util rather than swapping a React component.

**Customizing a built-in overlay:** extend the default util and give it the same `static type`; it replaces the built-in when passed via `overlayUtils`:

```tsx
// Before
const components: TLEditorComponents = {
	Brush: MyBrushComponent,
}

<Tldraw components={components} />

// After
import { Tldraw, BrushOverlayUtil, type TLBrushOverlay } from 'tldraw'

class MyBrushOverlayUtil extends BrushOverlayUtil {
	override render(ctx: CanvasRenderingContext2D, overlays: TLBrushOverlay[]) {
		const overlay = overlays[0]
		if (!overlay) return
		const { x, y, w, h } = overlay.props
		const zoom = this.editor.getEfficientZoomLevel()
		ctx.fillStyle = 'rgba(0, 0, 255, 0.1)'
		ctx.strokeStyle = 'blue'
		ctx.lineWidth = 1 / zoom
		ctx.beginPath()
		ctx.rect(x, y, w, h)
		ctx.fill()
		ctx.stroke()
	}
}

<Tldraw overlayUtils={[MyBrushOverlayUtil]} />
```

The following slots have been removed from `TLEditorComponents`. Subclass the matching default overlay util instead:

- `Brush`, `ZoomBrush` → `BrushOverlayUtil`, `ZoomBrushOverlayUtil`
- `Scribble` → `ScribbleOverlayUtil`
- `SnapIndicator` → `SnapIndicatorOverlayUtil`
- `Handle`, `Handles` → `ShapeHandleOverlayUtil`
- `SelectionForeground`, `SelectionBackground` → `SelectionForegroundOverlayUtil`
- `CollaboratorHint` → `CollaboratorHintOverlayUtil` (collaborator cursors/brushes/scribbles have their own utils too)

The corresponding `Default*` exports and `LiveCollaborators` have also been removed.

**`ShapeUtil.indicator()` → `ShapeUtil.getIndicatorPath()`.** The shape util method that draws a shape's selection indicator no longer returns JSX. It now returns a `Path2D` (or a `TLIndicatorPath`) and is composited onto the canvas overlay layer. Every custom `ShapeUtil` that overrides `indicator` needs to migrate:

```tsx
// Before
override indicator(shape: MyShape) {
	return <rect width={shape.props.w} height={shape.props.h} />
}

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

For shapes whose indicator should match the shape's geometry, return `path` built from the same primitives. For placeholder shapes (e.g. an `ErrorShape`), return an empty `new Path2D()` and declare the return type explicitly so TypeScript doesn't infer `never`.

The React component slots `ShapeIndicator`, `ShapeIndicators`, and `ShapeIndicatorErrorFallback` are also removed from `TLEditorComponents` — there is no replacement React slot, since indicators now render through `getIndicatorPath()`.

Overlays cannot render React; they draw into a 2D canvas context. For React-based overlays, render an HTML layer above the canvas via a regular `TLEditorComponents` slot like `InFrontOfTheCanvas`.

Overlay colors come from `TLTheme`, not CSS variables. Read them inside `render()` via `this.editor.getCurrentTheme().colors[this.editor.getColorMode()]` so overlays follow light/dark mode automatically.

These CSS variables have been removed: `--tl-color-snap`, `--tl-color-brush-fill`, `--tl-color-brush-stroke`, `--tl-color-laser`, `--tl-layer-overlays-custom`.

Overriding them (or the removed selectors `.tl-brush`, `.tl-scribble`, `.tl-snap-indicator`, `.tl-handle*`, `.tl-selection__fg__outline`, `.tl-corner-handle`, `.tl-text-handle`, `.tl-corner-crop-handle`, `.tl-mobile-rotate__*`) no longer has any effect. Port these to `TLTheme` entries or to the overlay util's `render()`.

</details>

### 💥 Tldraw component options

Several `<Tldraw>` props that previously lived at the top level have been consolidated under the `options` prop, and a few extension points moved off the component entirely.

<details>
<summary>Migration guide</summary>

**`cameraOptions`, `textOptions`, and `deepLinks` props moved into `options`:**

```tsx
// Before
<Tldraw cameraOptions={camOpts} textOptions={txtOpts} deepLinks />

// After
<Tldraw options={{ camera: camOpts, text: txtOpts, deepLinks: true }} />
```

**`embeds` prop removed; configure embed definitions on `EmbedShapeUtil`:**

```tsx
// Before
<Tldraw embeds={[...DEFAULT_EMBED_DEFINITIONS, customEmbed]} />

// After
import { EmbedShapeUtil } from 'tldraw'
const ConfiguredEmbedShapeUtil = EmbedShapeUtil.configure({
	embedDefinitions: [...DEFAULT_EMBED_DEFINITIONS, customEmbed],
})
<Tldraw shapeUtils={[ConfiguredEmbedShapeUtil]} />
```

This silently compiles in some setups (the prop is unknown but JSX won't always reject it), so this is the kind of change that the typecheck won't always catch — search the source for `embeds=` and migrate any matches.

**`setDefaultEditorAssetUrls()` and `setDefaultUiAssetUrls()` are no longer part of the public API.** They still exist at runtime for now, but they're marked `@internal` and should not be relied on. Pass `assetUrls` to each `<Tldraw>` instead:

```tsx
// Before
import { setDefaultEditorAssetUrls, setDefaultUiAssetUrls } from 'tldraw'
setDefaultEditorAssetUrls(assetUrls)
setDefaultUiAssetUrls(assetUrls)

<Tldraw />

// After
<Tldraw assetUrls={assetUrls} />
```

Do not reach for module augmentation to re-expose the old globals — find each `<Tldraw>` mount point and pass `assetUrls` directly.

</details>

### Custom record types ([#8213](https://github.com/tldraw/tldraw/pull/8213))

You can now register custom record types in the tldraw store for persisting and synchronizing domain-specific data that doesn't fit into shapes, bindings, or assets. Custom records support scoping (document/session/presence), validation, migrations, and default properties.

```tsx
import { createTLSchema, createCustomRecordId } from 'tldraw'

const schema = createTLSchema({
	records: [
		{
			typeName: 'marker',
			scope: 'document',
			validator: markerValidator,
		},
	],
})
```

TypeScript module augmentation via `TLGlobalRecordPropsMap` lets custom record types participate in the `TLRecord` union.

### Extensible geo shapes ([#8543](https://github.com/tldraw/tldraw/pull/8543))

`GeoShapeUtil` now supports custom geo types via a `customGeoTypes` option on `configure()`. Previously, adding a new geo type required forking or monkey-patching `GeoShapeUtil`; now custom types plug into the existing system and inherit labels, resizing, fill/dash/color styling, SVG export, and hyperlink support — while supplying their own path geometry, snap behavior, creation size, and style panel icon.

```tsx
import { GeoShapeUtil, PathBuilder } from 'tldraw'

const MyGeoShapeUtil = GeoShapeUtil.configure({
	customGeoTypes: {
		'rounded-rect': {
			getPath: (w, h, shape) => {
				const r = Math.min(w, h) * 0.2
				return new PathBuilder()
					.moveTo(r, 0, { geometry: { isFilled: shape.props.fill !== 'none' } })
					.lineTo(w - r, 0)
					.circularArcTo(r, false, true, w, r)
					.lineTo(w, h - r)
					.circularArcTo(r, false, true, w - r, h)
					.lineTo(r, h)
					.circularArcTo(r, false, true, 0, h - r)
					.lineTo(0, r)
					.circularArcTo(r, false, true, r, 0)
					.close()
			},
			snapType: 'polygon',
			icon: 'geo-rectangle',
			defaultSize: { w: 200, h: 150 },
		},
	},
})

<Tldraw shapeUtils={[MyGeoShapeUtil]} />
```

Each definition supplies `getPath`, `snapType` (`'polygon'` for vertex + center snaps, `'blobby'` for center-only), and an `icon` for the style panel, plus optional `defaultSize` and `onDoubleClick` handler. Custom types appear alongside the built-ins in the geo picker.

### 💥 Extensible asset types ([#8031](https://github.com/tldraw/tldraw/pull/8031))

A new `AssetUtil` base class follows the `ShapeUtil` / `BindingUtil` pattern, making the asset system extensible. Previously, assets were a hardcoded union of image, video, and bookmark types. Now you can register custom asset types with their own MIME type handling, file-to-asset conversion, and shape creation logic.

```tsx
import { AssetUtil } from '@tldraw/editor'

class AudioAssetUtil extends AssetUtil<TLAudioAsset> {
	static override type = 'audio' as const
	override getSupportedMimeTypes() {
		return ['audio/mpeg', 'audio/wav']
	}
	override async getAssetFromFile(editor, file) {
		/* ... */
	}
}

;<Tldraw assetUtils={[AudioAssetUtil]} />
```

`TLAssetStore` keeps `upload`/`resolve`/`remove` as cross-cutting concerns, while `AssetUtil` handles type-specific behavior: MIME types, file-to-asset metadata, and asset-to-shape creation.

<details>
<summary>Migration guide</summary>

`assetValidator` has been removed. Use `imageAssetValidator`, `videoAssetValidator`, or `bookmarkAssetValidator` instead.

`getMediaAssetInfoPartial` has been removed. Use `AssetUtil.getAssetFromFile` instead.

`notifyIfFileNotAllowed` signature changed from `(file, options)` to `(editor, file, options)`.

`getAssetInfo` signature changed from `(file, options, assetId?)` to `(editor, file, assetId?)` and now returns `TLAsset | null` instead of throwing.

</details>

### Frame-like custom shapes ([#8331](https://github.com/tldraw/tldraw/pull/8331))

Custom shapes can now opt into frame-like behavior: clipping children, acting as a parent on paste and drag-in, blocking erasure from inside, and supporting full-brush selection. Previously, frame behavior was hardcoded to the built-in `frame` type; the editor and tools now route frame checks through `editor.getShapeUtil(shape).isFrameLike(shape)`.

The easiest way to build one is to extend the new `BaseFrameLikeShapeUtil` abstract class, which provides sensible defaults for `isFrameLike`, `providesBackgroundForChildren`, `canReceiveNewChildrenOfType`, `canRemoveChildrenOfType`, `getClipPath`, `onDragShapesIn`, and `onDragShapesOut`:

```tsx
import { BaseFrameLikeShapeUtil, SVGContainer } from '@tldraw/editor'

class MyContainerUtil extends BaseFrameLikeShapeUtil<MyContainerShape> {
	static override type = 'my-container' as const
	static override props = myContainerShapeProps

	override getDefaultProps() {
		return { w: 300, h: 200 }
	}

	override component(shape: MyContainerShape) {
		return <SVGContainer>...</SVGContainer>
	}

	override indicator(shape: MyContainerShape) {
		return <rect width={shape.props.w} height={shape.props.h} />
	}
}
```

Shapes that need frame behavior without inheriting from `BaseFrameLikeShapeUtil` can override `isFrameLike()` directly on any `ShapeUtil`. `FrameShapeUtil` now extends `BaseFrameLikeShapeUtil`, so existing frames are unaffected.

### Shape attribution and TLUserStore ([#8147](https://github.com/tldraw/tldraw/pull/8147))

A new shape attribution system tracks who created and last edited shapes. The `TLUserStore` provider interface connects tldraw to your auth system with reactive `Signal`-based methods: `getCurrentUser()` returns the active user for presence and attribution, while `resolve(userId)` resolves any user ID to display info.

```tsx
<Tldraw
	users={{
		getCurrentUser: () => currentUserSignal,
		resolve: (userId) => resolvedUserSignal(userId),
	}}
/>
```

User records are now document-scoped via the unified `TLUser` record type. SDK users can extend user records with custom validated metadata through `createTLSchema`:

```tsx
const schema = createTLSchema({
	user: {
		meta: {
			isAdmin: T.boolean,
			department: T.string,
		},
	},
})
```

Note shapes now track and display a "first edited by" attribution label in the bottom-right corner, showing who first added text to the note.

<details>
<summary>Migration guide</summary>

**`useTldrawUser` has been removed.** Previously it bundled user _preferences_ (color, color scheme) and user _identity_ (id, name) into a single object. These are now separate concerns:

- **Preferences** (color, color scheme, snap mode, etc.) are managed via `TLUserPreferences`. Set them with the editor's user-preferences API directly.
- **Identity** for attribution comes from a `TLUserStore` provider passed to the new `users` prop on `<Tldraw>`.

```tsx
// Before
const user = useTldrawUser({ userPreferences, setUserPreferences })
<Tldraw user={user} />

// After
<Tldraw
	users={{
		getCurrentUser: () => currentUserSignal,
		resolve: (userId) => resolvedUserSignal(userId),
	}}
	colorScheme={userPreferences.colorScheme}
/>
```

If you only need preferences (no custom identity), pass `colorScheme` directly and seed preferences imperatively after mount; if you only need identity, pass `users`. Most apps want both.

</details>

### @tldraw/driver ([#7952](https://github.com/tldraw/tldraw/pull/7952))

A new `@tldraw/driver` package provides an imperative API for driving the tldraw editor programmatically. `Driver` wraps an `Editor` instance and exposes event dispatch, selection transforms, clipboard operations, and shape queries with fluent chaining.

```tsx
import { Driver } from '@tldraw/driver'

const driver = new Driver(editor)
driver.pointerMove(100, 100).pointerDown().pointerMove(200, 200).pointerUp()
```

This is useful for scripting, automation, agent workflows, and REPL-style interaction. The release includes a Scripter example that demonstrates the package.

### @tldraw/mermaid ([#8194](https://github.com/tldraw/tldraw/pull/8194), [#8285](https://github.com/tldraw/tldraw/pull/8285), [#8322](https://github.com/tldraw/tldraw/pull/8322))

A new `@tldraw/mermaid` package converts Mermaid diagram syntax into native tldraw shapes. Paste Mermaid text to create flowcharts, sequence diagrams, state diagrams, and mind maps as editable shapes on the canvas.

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

await createMermaidDiagram(
	editor,
	`
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`
)
```

The package parses Mermaid syntax, extracts layout from the rendered SVG, and produces a diagram-agnostic blueprint that gets rendered into geo shapes, arrows, and groups.

Node creation is extensible: pass `mapNodeToRenderSpec` per diagram type to map diagram nodes to different shapes, or use `createShape` in `BlueprintRenderingOptions` to take full control of how nodes are created on the canvas.

### Arbitrary iframe embeds ([#8306](https://github.com/tldraw/tldraw/pull/8306))

Paste any `<iframe>` embed code onto the canvas to create an embed shape. Previously only URLs matching known providers (YouTube, Google Maps, etc.) worked. Now any valid iframe with an HTTP(S) source creates an embed directly. It works with services like OpenStreetMap, SoundCloud, Loom, and more.

### Clipboard hooks ([#8290](https://github.com/tldraw/tldraw/pull/8290))

New `TldrawOptions` hooks let you intercept and customize clipboard copy, cut, and paste. `onBeforeCopyToClipboard` filters or transforms serialized content before it hits the clipboard, `onBeforePasteFromClipboard` filters parsed paste payloads before shapes are created, and `onClipboardPasteRaw` handles raw clipboard data before tldraw's default paste pipeline.

```tsx
const options: Partial<TldrawOptions> = {
	onBeforeCopyToClipboard(info, content) {
		// filter shapes or transform content before copy/cut
		return content
	},
	onBeforePasteFromClipboard(info, content) {
		// filter or transform parsed paste content
		return content
	},
	onClipboardPasteRaw(info) {
		// handle raw clipboard data yourself; return false to cancel tldraw handling
		return false
	},
}
```

### Cross-window embedding support ([#8196](https://github.com/tldraw/tldraw/pull/8196))

Tldraw now works correctly when embedded in iframes, Electron pop-out windows, and Obsidian plugins where the global `document` and `window` differ from the ones tldraw is mounted in. All bare `document` and `window` references have been replaced with container-aware alternatives.

New helpers `getOwnerDocument()` and `getOwnerWindow()` are exported from `@tldraw/editor`, along with `Editor.getContainerDocument()` and `Editor.getContainerWindow()` convenience methods.

### Performance measurement hooks ([#8421](https://github.com/tldraw/tldraw/pull/8421))

A new `editor.performance` API lets SDK users subscribe to editor performance events: interaction frame times (translating, resizing, drawing), camera pan/zoom sessions, shape create/update/delete operations, and undo/redo timings. Events aggregate frame-time percentiles (avg / median / p95 / p99) and, on Chromium, attach Long Animation Frame data with per-script attribution for diagnosing jank.

```tsx
const unsubscribe = editor.performance.on('interaction-end', (event) => {
	// forward to analytics
	const { frameTimes, longAnimationFrames, ...metrics } = event
	track('editor.interaction', metrics)
})
```

The manager is zero-overhead when no listeners are attached. Custom tools opt in to interaction tracking via `static trackPerformance = true` on the `StateNode`. A `PerformanceApiAdapter` is also available for piping events into the browser Performance API for DevTools timelines.

### RTL support ([#8033](https://github.com/tldraw/tldraw/pull/8033))

The tldraw UI now supports right-to-left languages like Arabic. A new `useDirection()` hook returns `'ltr'` or `'rtl'` from the current translation context, and all Radix UI components and CSS have been updated to respect text direction. The `dir` attribute is set on `.tl-container`, and CSS uses logical properties (`margin-inline-start`, `inset-inline-end`, etc.) instead of physical ones.

### WebSocket hibernation in tlsync ([#8070](https://github.com/tldraw/tldraw/pull/8070))

`TLSocketRoom` now supports session resume and snapshot APIs for WebSocket hibernation environments like Cloudflare Durable Objects. Sessions can be suspended and restored without losing state, and the `sync-cloudflare` template has been updated to use the WebSocket Hibernation API.

New APIs include `handleSocketResume()` for restoring sessions from snapshots, `getSessionSnapshot()` for capturing session state, and an `onSessionSnapshot` callback for persisting snapshots to WebSocket attachments.

## API changes

- 💥 Remove `defaultColorNames`, `DefaultColorThemePalette`, `DefaultLabelColorStyle`, `TLDefaultColorTheme` type, and `getDefaultColorTheme()` from `@tldraw/tlschema`. Use `editor.getCurrentTheme().colors` instead. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- 💥 Remove `ARROW_LABEL_FONT_SIZES`, `FONT_FAMILIES`, `FONT_SIZES`, `LABEL_FONT_SIZES`, `STROKE_SIZES`, `TEXT_PROPS`, and `useDefaultColorTheme()` from `@tldraw/tldraw`. These are now resolved via display values. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- 💥 Rename `inferDarkMode` prop to `colorScheme` (`boolean` → `'light' | 'dark' | 'system'`). Rename `useIsDarkMode()` to `useColorMode()` (returns `'dark' | 'light'` instead of `boolean`). ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- 💥 Rename `SvgExportContext.themeId` to `SvgExportContext.colorMode` (`string` → `'light' | 'dark'`). ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- 💥 Change `getColorValue()` first argument from `TLDefaultColorTheme` to `TLThemeColors`. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- 💥 Change `PlainTextLabelProps` and `RichTextLabelProps`: `font` → `fontFamily`, `align` → `textAlign`, `fill` removed. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- 💥 Remove `Brush`, `ZoomBrush`, `Scribble`, `SnapIndicator`, `Handle`, `Handles`, `SelectionForeground`, `SelectionBackground`, `CollaboratorHint`, `ShapeIndicator`, `ShapeIndicators`, and `ShapeIndicatorErrorFallback` from `TLEditorComponents`, along with the corresponding `Default*` component exports and `LiveCollaborators`. Migrate custom overlay components to `OverlayUtil`; indicator customization moves to `ShapeUtil.getIndicatorPath()`. ([#8469](https://github.com/tldraw/tldraw/pull/8469))
- 💥 Remove the CSS variables `--tl-color-snap`, `--tl-color-brush-fill`, `--tl-color-brush-stroke`, `--tl-color-laser`, and `--tl-layer-overlays-custom`, along with the overlay class selectors (`.tl-brush`, `.tl-scribble`, `.tl-snap-indicator`, `.tl-handle*`, `.tl-selection__fg__outline`, `.tl-corner-handle`, `.tl-text-handle`, `.tl-corner-crop-handle`, `.tl-mobile-rotate__*`). Overlay colors now come from `TLTheme`. ([#8469](https://github.com/tldraw/tldraw/pull/8469))
- 💥 Remove `assetValidator`. Use `imageAssetValidator`, `videoAssetValidator`, or `bookmarkAssetValidator` instead. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
- 💥 Remove `getMediaAssetInfoPartial`. Use `AssetUtil.getAssetFromFile` instead. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
- 💥 Change `notifyIfFileNotAllowed` signature from `(file, options)` to `(editor, file, options)`. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
- 💥 Change `getAssetInfo` signature from `(file, options, assetId?)` to `(editor, file, assetId?)` and return `TLAsset | null` instead of throwing. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
- 💥 Move the `Cmd+Shift+C` / `Ctrl+Shift+C` shortcut from "Copy as SVG" to "Copy as PNG". ([#8532](https://github.com/tldraw/tldraw/pull/8532))
- 💥 Replace `ShapeUtil.indicator()` (returned JSX) with `ShapeUtil.getIndicatorPath()` (returns `Path2D | TLIndicatorPath | undefined`). Indicators now render to the canvas overlay layer instead of as React elements. ([#8469](https://github.com/tldraw/tldraw/pull/8469))
- 💥 Move `cameraOptions`, `textOptions`, and `deepLinks` from top-level `<Tldraw>` props into the `options` prop (e.g. `options={{ camera, text, deepLinks }}`).
- 💥 Remove the `embeds` prop from `<Tldraw>`. Configure embed definitions via `EmbedShapeUtil.configure({ embedDefinitions })` and pass the configured util through `shapeUtils`.
- 💥 Demote `setDefaultEditorAssetUrls()` and `setDefaultUiAssetUrls()` to `@internal`. Pass `assetUrls` to each `<Tldraw>` instead.
- 💥 Remove `useTldrawUser`. Use the new `users` prop (`TLUserStore`) for identity and `TLUserPreferences` for preferences.
- 💥 Replace `TLDrawShapeSegment.points` with the helper `getPointsFromDrawSegment(segment, scaleX, scaleY)` so segment points respect the shape's current scale.
- 💥 Change `BindingUtil` hook params: `fromShapeType`/`toShapeType` are removed in favor of full `fromShape`/`toShape` records (read `fromShape.type` / `toShape.type` directly).
- 💥 Add `'middle-legacy'` (and other legacy values) to the `align` union resolved by `PlainTextLabel`/`RichTextLabel`. If your code maps `align` into `PlainTextLabel.textAlign`, narrow legacy values to one of `'start' | 'center' | 'end'` before passing them through.
- Add `TLTheme`, `TLThemeId`, `TLThemes`, `TLThemeDefaultColors`, `TLThemeColors`, `TLRemovedDefaultThemeColors`, `ThemeManager`, `getDisplayValues()`, `getColorValue()`, and `DEFAULT_THEME` for the new theme system. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- Add `themes` and `initialTheme` props to `<Tldraw>` and `<TldrawEditor>`. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- Add `getCurrentTheme()`, `setCurrentTheme()`, `getThemes()`, `getTheme()`, `updateTheme()`, `updateThemes()`, and `getColorMode()` to the editor. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- Add `getDefaultDisplayValues` and `getCustomDisplayValues` to shape util options for theme-aware visual properties. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
- Add `OverlayUtil`, `TLOverlay`, `OverlayManager`, `Editor.overlays`, `defaultOverlayUtils`, and the `overlayUtils` prop on `<Tldraw>` / `<TldrawEditor>` for registering and managing canvas overlays. ([#8469](https://github.com/tldraw/tldraw/pull/8469))
- Add per-overlay utils: `BrushOverlayUtil`, `ZoomBrushOverlayUtil`, `ScribbleOverlayUtil`, `SnapIndicatorOverlayUtil`, `ShapeHandleOverlayUtil`, `SelectionForegroundOverlayUtil`, `ArrowHintOverlayUtil`, `CollaboratorBrushOverlayUtil`, `CollaboratorScribbleOverlayUtil`, `CollaboratorHintOverlayUtil`, and `CollaboratorCursorOverlayUtil`. ([#8469](https://github.com/tldraw/tldraw/pull/8469))
- Add overlay-related colors to `TLTheme`. ([#8469](https://github.com/tldraw/tldraw/pull/8469))
- Add `BaseFrameLikeShapeUtil` abstract class and `ShapeUtil.isFrameLike()` so custom shapes can opt into frame-like behaviors (paste parenting, full-brush selection, blocking erasure from inside, clipping children). `FrameShapeUtil` now extends `BaseFrameLikeShapeUtil`. ([#8331](https://github.com/tldraw/tldraw/pull/8331))
- Add extensibility API for custom geo shape types via `GeoShapeUtil.configure({ customGeoTypes })`. Add `GeoTypeDefinition` interface for defining path geometry, snap behavior, creation size, style panel icon, and double-click handler while inheriting standard geo shape behavior. ([#8543](https://github.com/tldraw/tldraw/pull/8543))
- Add `AssetUtil` base class with `configure()`, `getDefaultProps()`, `getSupportedMimeTypes()`, `getAssetFromFile()`, and `createShape()`. Add `assetUtils` prop to `<Tldraw>`. Add `Editor.getAssetUtil()`, `Editor.hasAssetUtil()`, and `Editor.getAssetUtilForMimeType()`. Add `TLGlobalAssetPropsMap` for type-safe custom asset registration. Add `createAssetRecordType()`, `defaultAssetSchemas`, and `assets` parameter to `createTLSchema()`. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
- Add `CustomRecordInfo` interface, `createCustomRecordId()`, `createCustomRecordMigrationIds()`, `createCustomRecordMigrationSequence()`, `isCustomRecord()`, `isCustomRecordId()` for custom record types. `createTLSchema()` and `createTLStore()` now accept a `records` option. ([#8213](https://github.com/tldraw/tldraw/pull/8213))
- Add `TLUserStore` interface with `getCurrentUser()` and `resolve()` for connecting tldraw to auth systems. Add unified `TLUser` record type, `UserRecordType`, `createUserId`, `isUserId`, `userIdValidator`, and `createUserRecordType()` for extensible user schemas. Add `user` parameter to `createTLSchema()`. Add `Editor.getAttributionUser()`, `Editor.getAttributionUserId()`, and `Editor.getAttributionDisplayName()`. Add `textFirstEditedBy` prop to `TLNoteShapeProps`. ([#8147](https://github.com/tldraw/tldraw/pull/8147))
- Add `@tldraw/driver` package with `Driver` class for imperative editor control. ([#7952](https://github.com/tldraw/tldraw/pull/7952))
- Add `@tldraw/mermaid` package with `createMermaidDiagram()`, `renderBlueprint()`, and `MermaidDiagramError` for converting Mermaid syntax to tldraw shapes. ([#8194](https://github.com/tldraw/tldraw/pull/8194))
- Add `mapNodeToRenderSpec` per-diagram-type option and `createShape` override to `@tldraw/mermaid` for customizing how diagram nodes are rendered as shapes. ([#8322](https://github.com/tldraw/tldraw/pull/8322))
- Add `onBeforeCopyToClipboard`, `onBeforePasteFromClipboard`, and `onClipboardPasteRaw` hooks to `TldrawOptions` for intercepting clipboard operations. Add `TLClipboardWriteInfo` and `TLClipboardPasteRawInfo` types. Export `handleNativeOrMenuCopy` from `@tldraw/tldraw`. ([#8290](https://github.com/tldraw/tldraw/pull/8290))
- Add `Cmd+Shift+V` / `Ctrl+Shift+V` shortcut to paste clipboard content as plain text. `Cmd+Shift+V` no longer toggles paste-at-cursor positioning. ([#8347](https://github.com/tldraw/tldraw/pull/8347))
- Add support for pasting arbitrary `<iframe>` embed codes to create embed shapes from any service. ([#8306](https://github.com/tldraw/tldraw/pull/8306))
- Add Canva to `DEFAULT_EMBED_DEFINITIONS` so Canva design URLs paste as iframe embeds. ([#8459](https://github.com/tldraw/tldraw/pull/8459))
- Add `TldrawOptions.rightClickPanning` (default `true`) to gate the new right-click drag-to-pan behavior. Add `InputsManager.getIsRightPointing()` / `setIsRightPointing()`. ([#8501](https://github.com/tldraw/tldraw/pull/8501))
- Add `Editor.performance` (`PerformanceManager`) with `on()`, `once()`, and `dispose()` for subscribing to interaction, camera, shape-operation, frame, and undo/redo performance events. Add `PerformanceApiAdapter` for piping events into the browser Performance API. Add `StateNode.trackPerformance` static field so custom tools can opt into interaction tracking. Add `TLPerfFrameTimeStats`, `TLPerfEventMap`, `TLInteractionStartPerfEvent`, `TLInteractionEndPerfEvent`, `TLCameraStartPerfEvent`, `TLCameraEndPerfEvent`, `TLShapeOperationPerfEvent`, `TLFramePerfEvent`, `TLUndoRedoPerfEvent`, `TLPerfLongAnimationFrame`, and `TLPerfLongAnimationFrameScript`. ([#8421](https://github.com/tldraw/tldraw/pull/8421))
- Add `Editor.getContainerDocument()` and `Editor.getContainerWindow()` methods, and `getOwnerDocument()` / `getOwnerWindow()` helpers for cross-window embedding. ([#8196](https://github.com/tldraw/tldraw/pull/8196))
- Add `handleSocketResume()`, `getSessionSnapshot()`, and `onSessionSnapshot` to `TLSocketRoom` for WebSocket hibernation support. Add `clientTimeout` option to `TLSyncRoom`. ([#8070](https://github.com/tldraw/tldraw/pull/8070))
- Add `useDirection()` hook for RTL support. ([#8033](https://github.com/tldraw/tldraw/pull/8033))
- Expose `PeopleMenu`, `PeopleMenuItem`, `PeopleMenuFacePile`, and `UserPresenceEditor` through `TldrawUiComponents` so the share panel sub-components can be overridden via the `<Tldraw />` `components` prop. ([#8346](https://github.com/tldraw/tldraw/pull/8346))
- Add `'none'` to `TLDefaultDashStyle` for hiding shape borders while preserving fills. The option is not exposed in the style panel — it can only be set programmatically. Add `NonePathBuilderOpts`; `PathBuilder.toSvg()` now returns `null` for the `'none'` style. ([#8453](https://github.com/tldraw/tldraw/pull/8453))
- Export `defaultHandleExternalFileReplaceContent`, which was previously referenced in docs but missing from the package's public exports. ([#8579](https://github.com/tldraw/tldraw/pull/8579))
- Change `TLSvgExportOptions.padding` to accept `number | 'auto'`. The `'auto'` mode (now default) renders with padding then trims to visual content bounds. ([#8202](https://github.com/tldraw/tldraw/pull/8202))
- Add `TextManager.measureHtmlBatch()` for batched DOM text measurement. ([#7949](https://github.com/tldraw/tldraw/pull/7949))
- Add `'json'` to `TLCopyType` for copying shapes as JSON in debug mode. ([#8206](https://github.com/tldraw/tldraw/pull/8206))
- Add `Vec.IsFinite()` for checking whether a vector has finite coordinates. ([#8176](https://github.com/tldraw/tldraw/pull/8176))
- Change `Vec.PointsBetween()` to accept an optional `ease` parameter. ([#7977](https://github.com/tldraw/tldraw/pull/7977))

## Improvements

- Optimize geometry hot paths for hit testing: reduce allocations and function call overhead in `Vec`, `Edge2d`, `Circle2d`, `Arc2d`, `Polyline2d`, and intersection routines. Circle hit testing is up to 19x faster, polyline nearest-point is 6.8x faster. ([#8210](https://github.com/tldraw/tldraw/pull/8210))
- Improve resize performance for multiple geo shapes with text labels by batching DOM measurements into a single pass per frame. ([#7949](https://github.com/tldraw/tldraw/pull/7949))
- Exports now automatically trim to visual content bounds, capturing overflow like thick strokes and arrowheads without extra whitespace. ([#8202](https://github.com/tldraw/tldraw/pull/8202))
- Add `Cmd+Shift+V` / `Ctrl+Shift+V` shortcut to paste clipboard content as plain text, stripping HTML and rich formatting. `Cmd+Shift+V` no longer toggles paste-at-cursor positioning — the "Paste at cursor" preference covers that use case. ([#8347](https://github.com/tldraw/tldraw/pull/8347))
- Change `Cmd+Shift+C` / `Ctrl+Shift+C` to copy selected shapes as PNG instead of SVG, matching the default in most apps. The SVG copy path is still available from the Copy-as menu. ([#8532](https://github.com/tldraw/tldraw/pull/8532))
- Right-click and drag now pans the camera, matching tools like Figma. A static right-click still opens the context menu on release. Gate via `TldrawOptions.rightClickPanning` (defaults to `true`). ([#8501](https://github.com/tldraw/tldraw/pull/8501))
- Allow Cmd+click / Ctrl+click on style panel items to apply style changes only to selected shapes without updating defaults for future shapes. ([#8452](https://github.com/tldraw/tldraw/pull/8452))
- Hide selection overlay when nudging shapes with arrow keys. ([#8447](https://github.com/tldraw/tldraw/pull/8447))
- Move the debug mode toggle into the preferences submenu. ([#8259](https://github.com/tldraw/tldraw/pull/8259))
- Tighten iframe referrer policy for embeds to send only the origin instead of the full URL to third-party embed providers. ([#8412](https://github.com/tldraw/tldraw/pull/8412))
- Replace the `@use-gesture/react` dependency with custom gesture handling. Bundle size is smaller and a stale dependency is gone. ([#8392](https://github.com/tldraw/tldraw/pull/8392))

## Bug fixes

- Fix `bailToMark` silently discarding pending history changes when the target mark doesn't exist. ([#8260](https://github.com/tldraw/tldraw/pull/8260))
- Fix `FocusManager.dispose()` not actually removing document event listeners due to `.bind()` creating new function references. ([#8232](https://github.com/tldraw/tldraw/pull/8232))
- Fix camera state getting stuck at `'moving'` when the editor is disposed mid-transition (e.g. deep links under React strict mode), which blocked all pointer interactions on the canvas. ([#8396](https://github.com/tldraw/tldraw/pull/8396))
- Fix leaked camera animations, following subscriptions, and stale menu state when the editor is disposed during active operations. ([#8422](https://github.com/tldraw/tldraw/pull/8422))
- Fix a memory leak where disposed `Editor` instances were retained through a shared throttled `updateHoveredShapeId` closure. ([#8439](https://github.com/tldraw/tldraw/pull/8439))
- Fix a memory leak where disposed `Editor` instances were retained through the `window.__tldraw__hardReset` global. ([#8476](https://github.com/tldraw/tldraw/pull/8476))
- Fix crash when isolating curved arrows with degenerate binding geometry. ([#8176](https://github.com/tldraw/tldraw/pull/8176))
- Fix all shapes disappearing when a labeled arrow has zero length (both endpoints overlapping), which previously propagated NaN values through the spatial index. ([#8329](https://github.com/tldraw/tldraw/pull/8329))
- Fix crash from duplicate fractional index keys in `kickoutOccludedShapes` during multiplayer sync. ([#8448](https://github.com/tldraw/tldraw/pull/8448))
- Fix crash in browsers without `OffscreenCanvas` support (e.g. older Safari) when preloading image alpha data. ([#8582](https://github.com/tldraw/tldraw/pull/8582))
- Fix over-softened corners and end artifacts when shift-clicking to draw straight line segments. ([#7977](https://github.com/tldraw/tldraw/pull/7977))
- Fix eraser not erasing shapes when starting a drag from inside a group's bounds. ([#8054](https://github.com/tldraw/tldraw/pull/8054))
- Fix draw-shape loop-closing sensitivity so closing works more consistently across zoom levels. ([#8293](https://github.com/tldraw/tldraw/pull/8293))
- Fix shadow artifact and oversized caret on notes and geo shapes at high zoom in dynamic size mode. ([#8378](https://github.com/tldraw/tldraw/pull/8378))
- Fix pattern fill not scaling correctly with dynamic size mode. ([#8441](https://github.com/tldraw/tldraw/pull/8441))
- Fix arrow labels rendered at incorrect size when editing at high zoom in dynamic size mode. ([#8451](https://github.com/tldraw/tldraw/pull/8451))
- Fix rotation performance regression where CSS `transform: scale()` was applied to shape labels even when dynamic size was inactive, forcing an unnecessary compositing layer on every shape. ([#8570](https://github.com/tldraw/tldraw/pull/8570))
- Fix spiky artifacts on draw-style geometric shapes by using a circular random offset distribution instead of a square one. ([#8466](https://github.com/tldraw/tldraw/pull/8466))
- Fix pasting into editable text shapes when the clipboard contains tldraw data. ([#8192](https://github.com/tldraw/tldraw/pull/8192))
- Fix slight positioning drift when pasting text onto the canvas. ([#8345](https://github.com/tldraw/tldraw/pull/8345))
- Fix right-clicking inside a multi-selection over a filled background shape changing the selection. ([#8434](https://github.com/tldraw/tldraw/pull/8434))
- Fix context menu briefly flashing when right-clicking to dismiss an already-open context menu. ([#8498](https://github.com/tldraw/tldraw/pull/8498))
- Fix context menu items accidentally being selected when right-clicking and quickly moving the mouse. ([#8499](https://github.com/tldraw/tldraw/pull/8499))
- Fix opacity slider drag not working on Safari due to `stopPropagation` blocking pointer events. ([#8519](https://github.com/tldraw/tldraw/pull/8519))
- Fix quick zoom mode (Z + Shift) cursor anchor and brush misalignment when the tldraw container is offset from the top-left of the window. ([#8520](https://github.com/tldraw/tldraw/pull/8520))
- Fix `Cmd+Shift+V` doing nothing when the clipboard contains an image; the shortcut now falls back to the regular paste flow when there is no plain-text payload. ([#8490](https://github.com/tldraw/tldraw/pull/8490))
- Fix keyboard shortcuts that change styles not marking the change as a style update, causing subsequent shapes to use the wrong defaults. ([#8599](https://github.com/tldraw/tldraw/pull/8599)) (contributed by [@danieljamesross](https://github.com/danieljamesross))
- Fix "back to content" button flickering when both it and the "move focus to canvas" button are visible. ([#8334](https://github.com/tldraw/tldraw/pull/8334))
- Fix intermittent `ResizeObserver loop` browser warnings when hovering over toolbar buttons. ([#8574](https://github.com/tldraw/tldraw/pull/8574))
- Fix missing sandbox attribute on GitHub Gist embeds. ([#8403](https://github.com/tldraw/tldraw/pull/8403))
- Restrict sandbox permissions for unknown/arbitrary embeds to mitigate security risks from untrusted content. ([#8404](https://github.com/tldraw/tldraw/pull/8404))
- Fix duplicate presence cursors appearing after login or logout in multiplayer sessions by filtering a session's own stale record from the connect handshake response. ([#8542](https://github.com/tldraw/tldraw/pull/8542))
- Fix sticky notes preserving stale attribution when cloned via a nib. ([#8614](https://github.com/tldraw/tldraw/pull/8614))
- Fix `Cmd+V` paste of tldraw-copied PNGs on Chrome 147 stable, where the custom-format clipboard entry returned a 0-byte blob. ([#8615](https://github.com/tldraw/tldraw/pull/8615))
- Fix note author attribution overflowing the sticky note width in SVG and PNG exports. ([#8664](https://github.com/tldraw/tldraw/pull/8664))
- Fix keyboard shortcuts not matching on alternative Latin keyboard layouts (Dvorak, Colemak, AZERTY) by replacing the `hotkeys-js` library with a small layout-aware native event matcher. ([#8669](https://github.com/tldraw/tldraw/pull/8669))
- Fix TypeScript signature mismatch on `ShapeUtil` base-class methods so overrides that need a `shape` parameter can declare it without errors. ([#8521](https://github.com/tldraw/tldraw/pull/8521))

--------

# v4.5.0

[View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.5.0)

This release adds click-through on transparent image pixels, SVG sanitization for pasted and dropped content, configurable embed definitions via `EmbedShapeUtil.configure()`, and correct high-DPI image sizing across platforms. It also includes a new `Editor.resizeToBounds()` method, TypeScript enum-to-const refactoring for Node strip-types compatibility, and various other improvements and bug fixes.

## What's new

### Click-through on transparent image pixels ([#7942](https://github.com/tldraw/tldraw/pull/7942))

Clicking on transparent areas of PNG, WebP, GIF, and AVIF images now selects shapes behind the image instead of the image itself. This works with cropped, flipped, and circle-cropped images.

This is powered by a new `Geometry2d.ignoreHit(point)` method that allows geometries to reject successful hit tests.

### 🔜 Configurable embed definitions ([#8034](https://github.com/tldraw/tldraw/pull/8034))

Embed definitions are now configured through `EmbedShapeUtil.configure()` instead of the static `setEmbedDefinitions()` method, which has been deprecated. The `embeds` prop on `Tldraw` is deprecated in favor of this approach.

```tsx
import { EmbedShapeUtil, DEFAULT_EMBED_DEFINITIONS } from 'tldraw'

const shapeUtils = [
	EmbedShapeUtil.configure({
		embedDefinitions: [...DEFAULT_EMBED_DEFINITIONS, myCustomEmbed],
	}),
]
```

<details>
<summary>Migration guide</summary>

Before:

```ts
EmbedShapeUtil.setEmbedDefinitions([...DEFAULT_EMBED_DEFINITIONS, myEmbed])
```

After:

```ts
const shapeUtils = [
	EmbedShapeUtil.configure({
		embedDefinitions: [...DEFAULT_EMBED_DEFINITIONS, myEmbed],
	}),
]
```

The `embeds` prop on `Tldraw` still works but is deprecated. Use `EmbedShapeUtil.configure()` instead.

</details>

### SVG sanitization ([#7896](https://github.com/tldraw/tldraw/pull/7896), [#8087](https://github.com/tldraw/tldraw/pull/8087))

Pasted and dropped SVG content is now sanitized against XSS and data exfiltration. The sanitizer uses an allowlist-based approach that blocks script injection, event handlers, dangerous URI schemes, and external resource loading while preserving tldraw's own SVG output (including `<foreignObject>` text rendering and CSS font references).

The sanitizer is also available as a public export for custom content handling:

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

const cleanSvg = sanitizeSvg(untrustedSvgText)
```

## API changes

- 🔜 **`EmbedShapeUtil.setEmbedDefinitions()`** deprecated. Use `EmbedShapeUtil.configure({ embedDefinitions: [...] })` instead. ([#8034](https://github.com/tldraw/tldraw/pull/8034))
- 🔜 **`Tldraw` `embeds` prop** is deprecated. Configure embed definitions via `EmbedShapeUtil.configure()`. ([#8034](https://github.com/tldraw/tldraw/pull/8034))
- Add `Geometry2d.ignoreHit(point)` for rejecting hit tests on transparent pixels. ([#7942](https://github.com/tldraw/tldraw/pull/7942))
- Add `Editor.resizeToBounds(shapes, bounds)` for resizing shapes to fit target bounds. ([#8120](https://github.com/tldraw/tldraw/pull/8120))
- Add `Editor.getResizeScaleFactor()` for computing the dynamic size scale factor at the current zoom level. ([#8042](https://github.com/tldraw/tldraw/pull/8042))
- Add `sanitizeSvg(svgText: string)` export for sanitizing SVG content against XSS and data exfiltration. ([#7896](https://github.com/tldraw/tldraw/pull/7896))
- Add experimental `experimental__onDropOnCanvas` option to intercept canvas drop events. Return `true` from the callback to prevent the editor's default drop behavior. ([#7911](https://github.com/tldraw/tldraw/pull/7911))

  ```tsx
  <Tldraw
  	options={{
  		experimental__onDropOnCanvas: (point, event) => {
  			// Handle drop at page-space point
  			return true // prevent default
  		},
  	}}
  />
  ```

- Add optional `pixelRatio` property to `TLImageAsset` for correct high-DPI image sizing. Detected automatically from PNG metadata. ([#8163](https://github.com/tldraw/tldraw/pull/8163))
- Replace TypeScript enums (`MigrationFailureReason`, `PORTRAIT_BREAKPOINT`) with `const` object + type alias pattern for compatibility with Node's built-in TypeScript support (strip-types). Values are unchanged. ([#8084](https://github.com/tldraw/tldraw/pull/8084))

## Improvements

- Improve arrow component rendering performance with finer-grained reactivity. ([#8167](https://github.com/tldraw/tldraw/pull/8167))
- Simplify paste-parent selection to use `canReceiveNewChildrenOfType` instead of frame-specific checks. Prevent edge-only overlap from auto-reparenting pasted shapes into adjacent frames. ([#8057](https://github.com/tldraw/tldraw/pull/8057))
- Save link and alt-text values when clicking outside the editor instead of discarding changes. ([#8037](https://github.com/tldraw/tldraw/pull/8037))
- Add SVG sanitization on paste and file drop to prevent XSS and data exfiltration. ([#7896](https://github.com/tldraw/tldraw/pull/7896))
- Fix circular dependencies across `@tldraw/state`, `@tldraw/editor`, and `@tldraw/tldraw` packages to improve compatibility with Jest mocking and tree-shaking. ([#7935](https://github.com/tldraw/tldraw/pull/7935))
- Fix high-DPI image sizing to work correctly across macOS and Windows by detecting the source DPI baseline from PNG metadata. ([#8163](https://github.com/tldraw/tldraw/pull/8163))

## Bug fixes

- Fix shapes pasted with Ctrl+V not being parented to a frame when they land inside one. ([#7938](https://github.com/tldraw/tldraw/pull/7938))
- Fix a crash when cropping custom shapes that don't include `isCircle` in their crop schema. ([#7931](https://github.com/tldraw/tldraw/pull/7931))
- Fix a crash when loading session state without a `currentPageId` (e.g. when using deep links). ([#7994](https://github.com/tldraw/tldraw/pull/7994))
- Fix U+2028/U+2029 line separators breaking chunked sync messages. ([#7918](https://github.com/tldraw/tldraw/pull/7918))
- Fix "Download original" not triggering a download for cross-origin assets. ([#8090](https://github.com/tldraw/tldraw/pull/8090))
- Fix arrow endpoints terminating at invisible clipped shape boundaries instead of at the frame edge. ([#7932](https://github.com/tldraw/tldraw/pull/7932))
- Fix sticky notes having a hard shadow instead of a soft drop shadow when exported as SVG. ([#7934](https://github.com/tldraw/tldraw/pull/7934))
- Fix rich text toolbar staying open when the editing shape is deleted by another user. ([#8050](https://github.com/tldraw/tldraw/pull/8050))
- Fix SVG sanitizer stripping embedded SVG data URIs on `<image>` elements. Nested SVGs are now recursively sanitized instead of blocked. ([#8087](https://github.com/tldraw/tldraw/pull/8087))
- Fix `TldrawSelectionForeground` crashing when used without `TldrawUiContextProvider`. ([#8011](https://github.com/tldraw/tldraw/pull/8011))
- Fix dynamic-size shapes losing shadows and dashes too early when zoomed out. ([#8040](https://github.com/tldraw/tldraw/pull/8040))
- Fix a crash when resizing draw or highlight shapes to zero width or height. ([#8067](https://github.com/tldraw/tldraw/pull/8067))
- Fix crash when enabling Debug SVG with shapes on the canvas. ([#8101](https://github.com/tldraw/tldraw/pull/8101))
- Fix `localOffset` mutation bug in `stretchShapes` when shapes have parent transforms. ([#8120](https://github.com/tldraw/tldraw/pull/8120))
- Fix arrow SVG export producing invalid negative `<foreignObject>` dimensions when arrows have no text label. ([#8137](https://github.com/tldraw/tldraw/pull/8137))
- Fix arrow endpoint flickering when anchors are at exact shape boundaries. ([#8130](https://github.com/tldraw/tldraw/pull/8130))
- Fix shapes dragged from the toolbar not respecting dynamic size mode. ([#8042](https://github.com/tldraw/tldraw/pull/8042))
- Fix dragging unselected shapes that have an `onClick` handler. ([#7936](https://github.com/tldraw/tldraw/pull/7936))
- Fix false positive "multiple instances" warning in Next.js dev mode. ([#7933](https://github.com/tldraw/tldraw/pull/7933))
- Fix missing alt text on rendered image shapes in some cases. ([#8158](https://github.com/tldraw/tldraw/pull/8158))
- Fix drawing on tablets that report zero pen pressure. ([#5693](https://github.com/tldraw/tldraw/pull/5693))
- Fix `create-tldraw` CLI to always create a subdirectory from the project name. ([#8161](https://github.com/tldraw/tldraw/pull/8161))

---

## Patch releases

### v4.5.3

- Fix dynamic import file extension handling. ([#8278](https://github.com/tldraw/tldraw/pull/8278))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.5.3)

### v4.5.4

- Fix all shapes disappearing when a labeled arrow has zero length due to NaN propagation through the spatial index. ([#8351](https://github.com/tldraw/tldraw/pull/8351))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.5.4)

### v4.5.5

- Fix camera state getting permanently stuck at 'moving' when the editor is disposed mid-camera-transition. ([#8396](https://github.com/tldraw/tldraw/pull/8396))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.5.5)

### v4.5.6

- Fix crash when isolating curved arrows with degenerate binding geometry. ([#8390](https://github.com/tldraw/tldraw/pull/8390))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.5.6)

--------

# v4.4.0

[View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.4.0)

This release adds a consolidated `options` prop, quick zoom navigation, a fill styles dropdown, a new `TldrawUiSelect` component, and shape-aware binding checks. It also includes 2D canvas rendering for shape indicators, R-tree spatial indexing, telestrator-style laser behavior, significant performance improvements for large canvases, and various bug fixes.

## What's new

### 2D canvas rendering for shape indicators ([#7708](https://github.com/tldraw/tldraw/pull/7708))

Shape indicators (selection outlines, hover states) now render using a 2D canvas instead of SVG elements. This significantly improves performance when selecting or hovering over many shapes, with up to 25x faster rendering in some scenarios.

Custom shapes can opt into canvas indicators by implementing the new `getIndicatorPath()` method on their ShapeUtil, and marking `useLegactIndicator` to return false:

```tsx
class MyShapeUtil extends ShapeUtil<MyShape> {
	getIndicatorPath(shape: MyShape): TLIndicatorPath | undefined {
		return {
			path: new Path2D(),
			// optional clip path for complex shapes like arrows with labels
		}
	}

	// Return false to use the new canvas indicators (default is true for backwards compatibility)
	useLegacyIndicator(): boolean {
		return false
	}
}
```

### Quick zoom navigation ([#7801](https://github.com/tldraw/tldraw/pull/7801), [#7836](https://github.com/tldraw/tldraw/pull/7836))

Press `z` then hold Shift to zoom out and see the whole canvas ("eagle eye" view). A viewport brush appears showing where you'll zoom to. Move the cursor to pick a location and release Shift to zoom there. Press Escape to cancel and return to the original view.

### Fill styles dropdown ([#7885](https://github.com/tldraw/tldraw/pull/7885))

The style panel now exposes additional fill styles (pattern, fill, lined-fill) through a dropdown picker after the solid button. The first three fill options (none, semi, solid) remain as inline buttons.

### User preference: Invert mouse wheel zoom direction ([#7732](https://github.com/tldraw/tldraw/pull/7732))

Added a new user preference to invert mouse wheel zoom direction. Some users prefer "natural" scrolling behavior where scrolling down zooms out, which this option now enables.

Access it via Menu → Preferences → Input device → Invert mouse zoom.

### Performance improvements ([#7676](https://github.com/tldraw/tldraw/pull/7676), [#7826](https://github.com/tldraw/tldraw/pull/7826), [#7840](https://github.com/tldraw/tldraw/pull/7840), [#7657](https://github.com/tldraw/tldraw/pull/7657))

This release includes several performance improvements for large canvases:

- **R-tree spatial indexing**: Shape queries now use an R-tree (RBush) for O(log n) lookups instead of O(n) iteration, significantly improving brushing, scribble selection, and erasing with many shapes on the canvas. The spatial index is maintained internally and accessed through existing methods like `editor.getShapesAtPoint()` and `editor.getShapeAtPoint()`.
- **Faster panning**: Hover hit-testing is now skipped during camera movement, reducing work while panning through large documents.
- **Reduced allocations**: Optimized Set comparisons, reduced memory allocations, and added string hash caching for better performance in large canvases and multiplayer rooms.
- **Smarter network scheduling**: Solo-mode network traffic is reduced by throttling to 1 FPS when no collaborators are present.

### Re-designed laser pointer ([#7681](https://github.com/tldraw/tldraw/pull/7681))

The laser pointer now behaves like a telestrator: all strokes remain visible while you're drawing and fade together when you stop. Previously, each stroke segment would fade independently, creating a trailing effect.

This is powered by a new generic session system on `ScribbleManager`. Sessions group multiple scribbles together and control how they fade:

```tsx
// Start a grouped session (used internally by the laser tool)
const sessionId = editor.scribbles.startSession({
	fadeMode: 'grouped',
	idleTimeoutMs: 1200,
	fadeDurationMs: 500,
})

// Add scribbles and points to a session
editor.scribbles.addScribbleToSession(sessionId, { color: 'laser' })
editor.scribbles.addPointToSession(sessionId, scribbleId, x, y)

// Stop or clear a session
editor.scribbles.stopSession(sessionId)
editor.scribbles.clearSession(sessionId)
```

New option in `TldrawOptions`:

- `laserFadeoutMs` (default: 500ms) - How long to fade all laser scribbles after the session ends

### Image pipeline starter template ([#7863](https://github.com/tldraw/tldraw/pull/7863))

A new "Image pipeline" starter template is available via `npx create-tldraw`. It provides a visual node-based canvas for building AI image generation workflows, with custom node shapes, typed port connections, pipeline regions with play/stop controls, and a DAG-based execution engine backed by a Cloudflare Worker API.

### Agent starter template improvements ([#7640](https://github.com/tldraw/tldraw/pull/7640))

The agent starter template has been restructured around a manager-based architecture for better modularity and extensibility. It now includes a mode system for controlling agent capabilities per mode, action schema registries, prompt part definitions, canvas linting, and user action tracking. The template also renames "SimpleShape" to "FocusedShape" for clarity.

### TldrawUiSelect component ([#7566](https://github.com/tldraw/tldraw/pull/7566))

New select dropdown primitive wrapping Radix UI's Select, following existing tldraw UI patterns.

### 🔜 Consolidated options prop ([#7888](https://github.com/tldraw/tldraw/pull/7888))

The `cameraOptions`, `textOptions`, and `deepLinks` props on `Tldraw`, `TldrawEditor`, and `TldrawImage` are now consolidated into the `options` prop. The standalone props are deprecated but still work for backward compatibility.

```tsx
// Before
<Tldraw cameraOptions={{ isLocked: true }} deepLinks textOptions={{ ... }} />

// After
<Tldraw options={{ camera: { isLocked: true }, deepLinks: true, text: { ... } }} />
```

<details>
<summary>Migration guide</summary>

Replace standalone props with equivalent `options` fields:

- `cameraOptions={...}` → `options={{ camera: { ... } }}`
- `textOptions={...}` → `options={{ text: { ... } }}`
- `deepLinks` or `deepLinks={...}` → `options={{ deepLinks: true }}` or `options={{ deepLinks: { ... } }}`

The deprecated props still work. When both the deprecated prop and the `options` field are provided, the `options` value takes precedence.

</details>

## API changes

- 🔜 **`TldrawEditorBaseProps.cameraOptions`**, **`TldrawEditorBaseProps.textOptions`**, **`TldrawEditorBaseProps.deepLinks`** deprecated in favor of `options.camera`, `options.text`, `options.deepLinks`. ([#7888](https://github.com/tldraw/tldraw/pull/7888))
- 🔜 **`TLShapeUtilCanBindOpts.fromShapeType`** and **`toShapeType`** replaced with `fromShape` and `toShape` accepting `TLShape | { type }`. ([#7821](https://github.com/tldraw/tldraw/pull/7821))
- Remove `editor.spatialIndex` from public API. The spatial index is now internal; use `editor.getShapesAtPoint()` and `editor.getShapeAtPoint()` for shape queries. ([#7699](https://github.com/tldraw/tldraw/pull/7699))
- Add `TldrawOptions.camera`, `TldrawOptions.text`, and `TldrawOptions.deepLinks` fields to the `options` prop. ([#7888](https://github.com/tldraw/tldraw/pull/7888))
- Add `TldrawUiSelect`, `TldrawUiSelectTrigger`, `TldrawUiSelectValue`, `TldrawUiSelectContent`, `TldrawUiSelectItem` components and associated prop types. Add `iconTypes` export for enumerating available icons. ([#7566](https://github.com/tldraw/tldraw/pull/7566))
- Add `useCanApplySelectionAction()` hook for checking if selection actions should be enabled. ([#7811](https://github.com/tldraw/tldraw/pull/7811))
- Add `TLInstance.cameraState: 'idle' | 'moving'` for tracking camera movement state. ([#7826](https://github.com/tldraw/tldraw/pull/7826))
- Add `quickZoomPreservesScreenBounds` to `TldrawOptions`. ([#7836](https://github.com/tldraw/tldraw/pull/7836))
- Add `fillExtra` to `STYLES` object for additional fill style options. ([#7885](https://github.com/tldraw/tldraw/pull/7885))
- Make `Editor.getShapeIdsInsideBounds()` public. ([#7863](https://github.com/tldraw/tldraw/pull/7863))
- Add `ShapeUtil.getIndicatorPath()` method and `TLIndicatorPath` type for canvas-based indicator rendering. Add `ShapeUtil.useLegacyIndicator()` to control whether shapes use SVG or canvas indicators. ([#7708](https://github.com/tldraw/tldraw/pull/7708))
- Add `isZoomDirectionInverted` to `TLUserPreferences` interface and `UserPreferencesManager.getIsZoomDirectionInverted()` method. Add `ToggleInvertZoomItem` component export and `toggle-invert-zoom` action. ([#7732](https://github.com/tldraw/tldraw/pull/7732))
- Add `complete` to `TL_SCRIBBLE_STATES` enum and `ScribbleManager.complete(id)` method for marking scribbles as complete before fading. ([#7760](https://github.com/tldraw/tldraw/pull/7760))
- Add scribble session system: `ScribbleManager.startSession()`, `stopSession()`, `clearSession()`, `extendSession()`, `isSessionActive()`, `addScribbleToSession()`, `addPointToSession()`, and `ScribbleSessionOptions` type. Add `LaserTool.getSessionId()`. Add `laserFadeoutMs` to `TldrawOptions`. ([#7681](https://github.com/tldraw/tldraw/pull/7681))
- Add `FpsScheduler` class to create FPS-throttled function queues with configurable target rates. ([#7418](https://github.com/tldraw/tldraw/pull/7418))

## Improvements

- Improve performance in large canvases and multiplayer rooms by optimizing Set comparisons, reducing memory allocations, and caching string hashes. ([#7840](https://github.com/tldraw/tldraw/pull/7840))
- Improve panning performance in large documents by skipping hover hit-testing during camera movement. ([#7826](https://github.com/tldraw/tldraw/pull/7826))
- Improve performance when translating arrows together with bound shapes by skipping unnecessary reparenting. ([#7733](https://github.com/tldraw/tldraw/pull/7733))
- Add R-tree spatial indexing for O(log n) shape queries, improving performance of brushing, selection, and erasing with many shapes. ([#7676](https://github.com/tldraw/tldraw/pull/7676))
- Improve laser pointer to keep all strokes visible during a session (telestrator pattern), with strokes fading together when drawing stops. ([#7681](https://github.com/tldraw/tldraw/pull/7681))
- Improve laser pointer strokes with proper taper when lifting the pointer by adding a 'complete' state to the scribble lifecycle. ([#7760](https://github.com/tldraw/tldraw/pull/7760))
- Improve quick zoom to use zoom-to-fit instead of fixed 5%, add "quick peek" behavior, and add edge scrolling. ([#7836](https://github.com/tldraw/tldraw/pull/7836))
- Remove `core-js` polyfill dependency from `@tldraw/editor`. ([#7769](https://github.com/tldraw/tldraw/pull/7769))
- Reduce network traffic by squashing pending push requests before sending, so rapid edits result in fewer network calls. ([#7724](https://github.com/tldraw/tldraw/pull/7724))
- Reduce solo-mode network traffic by using a dedicated FPS-based scheduler that throttles to 1 FPS when no collaborators are present. ([#7657](https://github.com/tldraw/tldraw/pull/7657))
- Improve performance by separating UI and network scheduling into independent queues with configurable target FPS. ([#7418](https://github.com/tldraw/tldraw/pull/7418))
- Improve frame label sizing on smaller viewports and when zoomed out. ([#7746](https://github.com/tldraw/tldraw/pull/7746))
- Add image pipeline starter template with visual node-based AI image generation workflows. ([#7863](https://github.com/tldraw/tldraw/pull/7863))
- Restructure agent starter template with manager-based architecture and mode system. ([#7640](https://github.com/tldraw/tldraw/pull/7640))

## Bug fixes

- Fix geo shapes with text not being resizable to a smaller size. ([#7878](https://github.com/tldraw/tldraw/pull/7878))
- Fix shapes exploding when resizing unaligned arrows. ([#7855](https://github.com/tldraw/tldraw/pull/7855))
- Fix Safari pinch zoom resetting selection to previous shapes. ([#7777](https://github.com/tldraw/tldraw/pull/7777))
- Fix toggle-lock action firing when no shapes are selected. ([#7815](https://github.com/tldraw/tldraw/pull/7815))
- Fix menu items (zoom to selection, cut, copy, delete) being enabled when not in select tool. ([#7811](https://github.com/tldraw/tldraw/pull/7811))
- Fix excessive tab indentation in text shapes (now 2 spaces instead of 8). ([#7796](https://github.com/tldraw/tldraw/pull/7796))
- Fix canvas-in-front elements (cursors, following indicators) appearing in front of UI panels instead of behind them. ([#7865](https://github.com/tldraw/tldraw/pull/7865))
- Fix license console message colors for warnings and errors. ([#7850](https://github.com/tldraw/tldraw/pull/7850))
- Fix asset resolution being delayed by 500ms when updating an image shape's asset. ([#7612](https://github.com/tldraw/tldraw/pull/7612))
- Fix Durable Object SQLite migration in the multiplayer Cloudflare template. ([#7829](https://github.com/tldraw/tldraw/pull/7829), [#7832](https://github.com/tldraw/tldraw/pull/7832), [#7834](https://github.com/tldraw/tldraw/pull/7834), [#7835](https://github.com/tldraw/tldraw/pull/7835))
- Fix `zoomToFit` and `getCurrentPageBounds` to ignore hidden shapes when computing bounds. ([#7770](https://github.com/tldraw/tldraw/pull/7770))
- Fix collaborator shape indicators not rendering after the canvas indicator change. ([#7759](https://github.com/tldraw/tldraw/pull/7759))
- Fix rich text content not updating correctly with message squashing due to reference comparison. ([#7758](https://github.com/tldraw/tldraw/pull/7758))
- Fix keyboard shortcut menu item labels to use consistent ellipsis formatting. ([#7757](https://github.com/tldraw/tldraw/pull/7757))
- Fix spatial index not removing shapes when moved to a different page. ([#7700](https://github.com/tldraw/tldraw/pull/7700))
- Fix tldraw failing to load in CJS environments (tsx, ts-node, Jest) due to ESM-only rbush dependency. ([#7905](https://github.com/tldraw/tldraw/pull/7905))

---

## Patch releases

### v4.4.1

- Fix tooltip positioning when tldraw is rendered inside a container with CSS transforms. ([#8171](https://github.com/tldraw/tldraw/pull/8171))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.4.1)

--------

# v4.3.0

[View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.3.0)

This release introduces several significant changes: a new pattern for defining custom shape/binding typings, pluggable storage for `TLSocketRoom` with a new SQLite option, reactive `editor.inputs`, and optimized draw shape encoding. It also adds various other API improvements, performance optimizations, and bug fixes, including better support for React 19.

---

### 💥 New pattern for defining custom shape/binding types ([#7091](https://github.com/tldraw/tldraw/pull/7091))

We've improved the developer experience of working with custom shape and binding types. There's now less boilerplate and fewer gotchas when using tldraw APIs in a type-safe manner.

This is a minor breaking change at the type level—your code will still run, but you'll get TypeScript errors until you migrate.

<details>
<summary>Migration guide</summary>

When _declaring_ types for custom shapes, you can now use TypeScript's module augmentation feature to provide more specific types for the custom shape.

Before:

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

// Shapes were defined by using the helper TLBaseShape type
type MyShape = TLBaseShape`<'my-shape', { w: number; h: number; text: string }>`
```

After:

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

const MY_SHAPE = 'my-shape'

// We now use TypeScript's module augmentation feature to allow
// extending the builtin TLShape type.
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_SHAPE]: { w: number; h: number; text: string }
	}
}

type MyShape = TLShape`<typeof MY_SHAPE>`
```

The benefit of this new system is that Editor APIs such as `createShape` now know about your custom shapes automatically:

```ts
// Just works - TypeScript validates props and provides autocomplete
editor.createShape({ type: 'my-shape', props: { w: 100, h: 100, text: 'Hello' } })

// Will cause a TypeScript error for `text`
editor.createShape({ type: 'my-shape', props: { w: 100, h: 100, text: 123 } })
```

The same pattern applies to custom bindings — augment `TLGlobalBindingPropsMap` and use `TLBinding<'binding-name'>`:

```ts
declare module 'tldraw' {
	export interface TLGlobalBindingPropsMap {
		'my-binding': { offset: number }
	}
}

type MyBinding = TLBinding`<'my-binding'>`
```

See the [Custom Shapes Guide](https://tldraw.dev/docs/shapes#custom-shapes) and the [Pin Bindings example](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/shapes/tools/pin-bindings) for details.

**After registering, remove the `TLBaseShape` import** — it's no longer used and will trip lint rules that flag unused imports.

**Shape type names are global.** `TLGlobalShapePropsMap` is a single shared registry, so two custom shapes that previously used the same type name in different files now collide. Pick a unique name for each, and remember the rename ripples beyond the type alias:

- `static override type = '...'` on the `ShapeUtil` subclass
- Every `editor.createShape({ type: '...' })` and `editor.updateShape({ type: '...' })` call site
- The `TLGlobalShapePropsMap` entry itself
- Any persisted snapshot or migration JSON that references the old name

**Use `as const` on the static `type` field.** TypeScript may widen `static override type = 'my-shape'` to `string`, which fails the new constraint. Add `as const` to keep it a string literal:

```ts
class MyShapeUtil extends (ShapeUtil`<MyShape>`) {
	static override type = 'my-shape' as const
	// ...
}
```

The same fix applies to `BaseBoxShapeTool` (and other tool) subclasses, which expose `static override shapeType = '...'`. If you see TS2416 on a tool's `shapeType`, add `as const` there too. The two fields are easy to confuse — check both.

**Heterogeneous `createShapes`/`updateShapes` arrays may need a cast.** Because `TLShape` is now a discriminated union over the global props map, a mapped array of mixed shape types no longer narrows automatically. For homogeneous arrays where every item shares one shape type, `as const` on the `type` field in the mapped object literal is enough. For genuinely heterogeneous arrays, go straight to `as TLShapePartial[]` (or `as TLCreateShapePartial[]` for `createShapes`):

```ts
// Heterogeneous update — the union doesn't narrow
editor.updateShapes(
	shapes.map((s) => ({ id: s.id, type: s.type, x: s.x + 10 })) as TLShapePartial[]
)
```

Don't reach for `satisfies TLShapePartial` here — `TLShapePartial` is distributive over the `TLShape` union, so `satisfies` enforces a literal-per-variant constraint that mapped-over heterogeneous shapes can't meet. The cast is the right tool for this specific shape of code.

</details>

(contributed by [@Andarist](https://github.com/Andarist))

---

### Pluggable storage for TLSocketRoom + SQLite support ([#7320](https://github.com/tldraw/tldraw/pull/7320), [#7123](https://github.com/tldraw/tldraw/pull/7123))

We've refactored the `TLSocketRoom` API to support a pluggable storage layer. We're providing two implementations:

- **`SQLiteSyncStorage`** – Automatically persists room state to SQLite. Recommended for production.
- **`InMemorySyncStorage`** – Keeps state in memory with manual persistence via callbacks (previous built-in behavior).

**We recommend switching to `SQLiteSyncStorage` if your environment supports SQLite** (Cloudflare Durable Objects, Node.js, Bun, Deno). It provides automatic persistence, lower memory usage, and faster startup times.

<details>
<summary>Why SQLite?</summary>

- **Automatic persistence**: Data survives process restarts without manual snapshot handling
- **Lower memory usage**: No need to keep entire documents in memory
- **Faster startup**: No need to load the document into memory before accepting socket connections
- **Simpler code**: No more `onChange` callbacks and manual persistence logic

</details>

<details>
<summary>Platform support</summary>

| Platform                   | Wrapper                          | SQLite Library                    |
| -------------------------- | -------------------------------- | --------------------------------- |
| Cloudflare Durable Objects | `DurableObjectSqliteSyncWrapper` | Built-in `ctx.storage`            |
| Node.js/Deno               | `NodeSqliteWrapper`              | `better-sqlite3` or `node:sqlite` |

See the [Cloudflare template](https://github.com/tldraw/tldraw-sync-cloudflare) and the [Node server example](https://github.com/tldraw/tldraw/tree/main/templates/simple-server-example) respectively. Bun support should be straightforward to add.

</details>

<details>
<summary>Migration guide</summary>

Existing code continues to work, however we have deprecated the following `TLSocketRoom` options:

- `initialSnapshot`
- `onDataChange`

These are replaced by the new `storage` option. We've also deprecated the `TLSocketRoom.updateStore` method, which has been supplanted by `storage.transaction`.

Before:

```ts
const existingSnapshot = loadExistingSnapshot()

const room = new TLSocketRoom({
	initialSnapshot: existingSnapshot,
	onDataChange: () => {
		persistSnapshot(room.getCurrentSnapshot())
	},
})
```

If you want to keep the same behavior with in-memory document storage and manual persistence:

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

const room = new TLSocketRoom({
	storage: new InMemorySyncStorage({
		snapshot: existingSnapshot,
		onChange() {
			saveToDatabase(storage.getSnapshot())
		},
	}),
})
```

However, we recommend switching to SQLite. Users of our Cloudflare template should follow the migration guide on the [sync docs page](https://tldraw.dev/docs/sync).

If you're using `TLSocketRoom` on Node, creating the room should end up looking something like this:

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

async function createRoom(roomId: string) {
	const db = new Database(`path/to/${roomId}.db`)
	const sql = new NodeSqliteWrapper(db)
	let snapshot: RoomSnapshot | undefined = undefined
	if (!SQLiteSyncStorage.hasBeenInitialized(sql)) {
		// This db hasn't been used before, so if it's a pre-existing
		// document, load the legacy room snapshot
		snapshot = await loadExistingSnapshot()
	}

	const storage = new SQLiteSyncStorage({ sql, snapshot })
	return new TLSocketRoom({
		storage,
		onSessionRemoved(room, args) {
			if (args.numSessionsRemaining === 0) {
				room.close()
				db.close()
			}
		},
	})
}
```

</details>

---

### Optimized draw shape encoding ([#7364](https://github.com/tldraw/tldraw/pull/7364), [#7710](https://github.com/tldraw/tldraw/pull/7710))

Draw and highlight shape point data is now stored using a compact delta-encoded binary format instead of JSON arrays. This reduces storage size by approximately 80% while preserving stroke fidelity.

<details>
<summary>Breaking change details</summary>

If you were reading or writing draw shape data programmatically you might need to update your code to use the new format.

- `TLDrawShapeSegment.points` renamed to `.path` and changed from `VecModel[]` to `string` (base64-encoded)
- Added `scaleX` and `scaleY` properties to draw and highlight shapes
- New exports: `b64Vecs` encoding utilities, e.g. `getPointsFromDrawSegment` helper. Use this if you need to manually read/write point data.

Existing documents are automatically migrated.

</details>

---

### Reactive inputs ([#7312](https://github.com/tldraw/tldraw/pull/7312))

Refactored `editor.inputs` to use reactive atoms via the new `InputsManager` class. All input state is now accessed via getter methods (e.g., `editor.inputs.getCurrentPagePoint()`, `editor.inputs.getShiftKey()`). Direct property access is deprecated but still supported for backwards compatibility.

## API changes

- 💥 **`DefaultTopPanel`** export removed from `tldraw`. The top panel component for displaying the offline indicator is now handled internally by `PeopleMenu`. ([#7568](https://github.com/tldraw/tldraw/pull/7568))
- 💥 **`TextDirection`** export removed from `tldraw`. Use TipTap's native `TextDirection` extension instead. The `richTextValidator` now includes an optional `attrs` property - a migration may be necessary for older clients/custom shapes. ([#7304](https://github.com/tldraw/tldraw/pull/7304))
- Add `tlenvReactive` atom to `@tldraw/editor` for reactive environment state tracking, including coarse pointer detection that updates when users switch between mouse and touch input. ([#7296](https://github.com/tldraw/tldraw/pull/7296))
- Add `hideAllTooltips()` helper function for programmatically dismissing tooltips. ([#7288](https://github.com/tldraw/tldraw/pull/7288))
- Add `zoomToFitPadding` option to `TldrawOptions` to customize the default padding used by zoom-to-fit operations. ([#7602](https://github.com/tldraw/tldraw/pull/7602))
- Add `snapThreshold` option to `TldrawOptions` for configuring the snap distance, defaulting to 8 screen pixels. ([#7543](https://github.com/tldraw/tldraw/pull/7543))
- Add `resizeChildren` configuration option to `FrameShapeUtil` to allow frame children to be resized proportionally when the frame is resized. ([#7526](https://github.com/tldraw/tldraw/pull/7526))
- Add `Editor.canEditShape()` and `Editor.canCropShape()` methods to centralize shape permission checks. Add `ShapeUtil.canEditWhileLocked()` for shapes that remain editable when locked. ([#7361](https://github.com/tldraw/tldraw/pull/7361))
- Add `editor.getDebouncedZoomLevel()` and `editor.getEfficientZoomLevel()` methods for improved zoom performance on dense canvases. Add `debouncedZoom` and `debouncedZoomThreshold` options. ([#7235](https://github.com/tldraw/tldraw/pull/7235))
- Add configurable `showTextOutline` option to `TextShapeUtil`, `ArrowShapeUtil`, and `GeoShapeUtil` via `.configure()` pattern. ([#7314](https://github.com/tldraw/tldraw/pull/7314))
- Export freehand stroke utilities: `getStroke`, `getStrokeOutlinePoints`, and `setStrokePointRadii`. ([#7400](https://github.com/tldraw/tldraw/pull/7400)) (contributed by [@VimHax](https://github.com/VimHax))
- Add `Box.isValid()` method to check for finite coordinates. ([#7532](https://github.com/tldraw/tldraw/pull/7532))
- Add `spacebarPanning` option to control whether spacebar activates pan mode. ([#7312](https://github.com/tldraw/tldraw/pull/7312))
- Introduce pluggable `TLSyncStorage` API for `TLSocketRoom`. The `initialSnapshot` and `onDataChange` options are now deprecated in favor of the new `storage` option. ([#7123](https://github.com/tldraw/tldraw/pull/7123))
- Export `DefaultLabelColorStyle` which is necessary for rich text in custom shapes. ([#7114](https://github.com/tldraw/tldraw/pull/7114))

### Improvements

- Improve coarse pointer detection by replacing CSS media queries with a reactive `data-coarse` attribute that updates when users switch between mouse and touch input. ([#7404](https://github.com/tldraw/tldraw/pull/7404))
- Add CSS containment to main toolbar and text measurement element for improved rendering performance. ([#7406](https://github.com/tldraw/tldraw/pull/7406)) ([#7407](https://github.com/tldraw/tldraw/pull/7407))
- Improve cross-realm support by scoping canvas event listeners to the editor container's ownerDocument. ([#7113](https://github.com/tldraw/tldraw/pull/7113))
- Simplify ImmutableMap implementation for better code clarity. ([#7431](https://github.com/tldraw/tldraw/pull/7431))
- Improve code readability in number validator by using `Number.isFinite()` instead of arithmetic trick. ([#7374](https://github.com/tldraw/tldraw/pull/7374))
- Upgrade to React 19 with all necessary type and configuration changes for compatibility. ([#7317](https://github.com/tldraw/tldraw/pull/7317))
- Improve signal graph traversal performance by eliminating per-recursion closure allocations. ([#7430](https://github.com/tldraw/tldraw/pull/7430))
- Optimize object utility functions. ([#7432](https://github.com/tldraw/tldraw/pull/7432))
- Use in-place sorting in parentsToChildren derivation. ([#7433](https://github.com/tldraw/tldraw/pull/7433))
- Optimize notVisibleShapes derivation with inlined bounds checks. ([#7429](https://github.com/tldraw/tldraw/pull/7429))
- Cache label size measurements with WeakCache for improved geo shape performance. ([#7412](https://github.com/tldraw/tldraw/pull/7412))
- Optimize validators with fast paths and production inlining. ([#7373](https://github.com/tldraw/tldraw/pull/7373))

### Bug fixes

- Fix migrations for draw and highlight shapes to be idempotent, preventing errors when migrations run multiple times. ([#7389](https://github.com/tldraw/tldraw/pull/7389))
- Fix dot detection in draw and highlight shapes after the point compression change. ([#7365](https://github.com/tldraw/tldraw/pull/7365))
- Fix clicking a shape's text label while editing to re-focus the input and select all text. ([#7342](https://github.com/tldraw/tldraw/pull/7342))
- Fix pasting at cursor to correctly account for frames and parent containers. ([#7277](https://github.com/tldraw/tldraw/pull/7277))
- Fix editing mode to exit when dragging causes the text input to blur. ([#7291](https://github.com/tldraw/tldraw/pull/7291))
- Fix CommonJS build issues with TipTap imports in rich text module. ([#7282](https://github.com/tldraw/tldraw/pull/7282))
- Fix iOS automatically zooming in on input fields by ensuring 16px minimum font size. ([#7118](https://github.com/tldraw/tldraw/pull/7118))
- Fix `distanceToLineSegment` returning squared distance instead of actual distance, causing hit testing (eraser, scribble select) to be too strict. ([#7610](https://github.com/tldraw/tldraw/pull/7610)) (contributed by [@arpit-goblins](https://github.com/arpit-goblins))
- Fix `zoomToSelection` to toggle between 100% zoom and zoom-to-fit behavior. ([#7536](https://github.com/tldraw/tldraw/pull/7536))
- Fix export of SVG markers by handling fragment-only URLs correctly. ([#7506](https://github.com/tldraw/tldraw/pull/7506)) (contributed by [@PidgeyBE](https://github.com/PidgeyBE))
- Restore wheel and pinch canvas event emission. ([#6834](https://github.com/tldraw/tldraw/pull/6834)) (contributed by [@swdev33](https://github.com/swdev33))
- Fix context menu submenu flickering when hovered. ([#6837](https://github.com/tldraw/tldraw/pull/6837)) (contributed by [@swdev33](https://github.com/swdev33))
- Fix rotated shape positions not being restored after flipping twice. ([#7359](https://github.com/tldraw/tldraw/pull/7359))
- Fix keyboard shortcuts and clipboard events not working when `hideUi` is true. ([#7367](https://github.com/tldraw/tldraw/pull/7367))
- Fix elbow arrows routing incorrectly when using dynamic sizing at high zoom levels. ([#7424](https://github.com/tldraw/tldraw/pull/7424))
- Allow fullscreen for embed shapes. ([#7417](https://github.com/tldraw/tldraw/pull/7417))
- Move mobile rotate handle to bottom for image and video shapes to accommodate the contextual toolbar. ([#6727](https://github.com/tldraw/tldraw/pull/6727))
- Fix dropdown menu items incorrectly displaying an icon on the right side. ([#7533](https://github.com/tldraw/tldraw/pull/7533))
- Fix zoom menu showing debounced zoom level for canvases with many shapes. ([#7626](https://github.com/tldraw/tldraw/pull/7626))
- Fix extra line appearing after bullet and ordered lists in text shapes. ([#7643](https://github.com/tldraw/tldraw/pull/7643)) (contributed by [@sahiee-dev](https://github.com/sahiee-dev))
- Fix "Back to content" button not appearing when selected shapes are off-screen. ([#7649](https://github.com/tldraw/tldraw/pull/7649))
- Fix dotted freehand lines becoming invisible at minimum zoom on Chrome. ([#7650](https://github.com/tldraw/tldraw/pull/7650))
- Fix menu bar stretching to full width on mobile viewports instead of fitting content. ([#7568](https://github.com/tldraw/tldraw/pull/7568))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.3.0)

---

## Patch releases

### v4.3.1

- Fix draw shape precision issues at high canvas coordinates by switching to delta encoding with a Float32 anchor point. ([#7710](https://github.com/tldraw/tldraw/pull/7710))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.3.1)

### v4.3.2

- Fix crash when cropping custom shapes that don't include `isCircle` in their crop schema. ([#7931](https://github.com/tldraw/tldraw/pull/7931))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.3.2)

--------

# v4.2.0

This month's release includes many bug fixes and small API additions, along with a major version bump of our TipTap rich text editor.

## What's new

### 💥 TipTap v3 ([#5717](https://github.com/tldraw/tldraw/pull/5717))

We've upgraded TipTap from v2 to v3. If you've done any customization to our standard TipTap kit, please refer to TipTap's guide [How to upgrade Tiptap v2 to v3](https://tiptap.dev/docs/guides/upgrade-tiptap-v2) for breaking changes you might experience.

<details>
<summary>Migration guide</summary>

Starting in v4.2, tldraw bundles TipTap v3 as a transitive dependency. If your project pins `@tiptap/*` v2 packages directly, upgrade them to v3 _before_ trying to fix any code-level errors — leaving v2 in place produces a dual install that surfaces as confusing type errors.

**Dual-install symptom.** Deeply-nested errors like _"Property 'getCharacterCount' is missing in type 'Editor' but required in type 'Editor'"_, with the two `Editor` types resolving to different paths (one under `node_modules/@tiptap/core`, the other under `node_modules/@tldraw/editor/node_modules/@tiptap/core`), are not API changes — they are the v2/v3 dual install. The `Editor` classes are structurally similar but nominally different. Finishing the v3 upgrade collapses the duplicate and these errors disappear without code changes.

**Code-level changes that affect tldraw users:**

- **Default → named exports.** Several extensions changed from default to named exports:

  ```ts
  // Before
  import StarterKit from '@tiptap/starter-kit'

  // After
  import { StarterKit } from '@tiptap/starter-kit'
  ```

- **`TextStyle` → `TextStyleKit`, and `FontFamily` moved.** The `FontFamily` extension is no longer in `@tiptap/extension-font-family`; it's part of `TextStyleKit` in `@tiptap/extension-text-style`. The `setFontFamily` and `setFontSize` chain commands only exist on `TextStyleKit`, not on bare `TextStyle`.

- **Transaction handler types.** Inline parameter type annotations on TipTap event handlers no longer work. Import the proper event-map type:

  ```ts
  import { EditorEvents } from '@tiptap/core'
  // ...
  onTransaction: (props: EditorEvents['transaction']) => {
  	/* ... */
  }
  ```

- **Custom chained commands** still register via `declare module '@tiptap/core'` augmentation in v3 — the augmentation target is the same.

</details>

## API changes

- Add `Editor.setTool`/`Editor.removeTool` for dynamically altering the editor's tool state chart. ([#6909](https://github.com/tldraw/tldraw/pull/6909)) ([#7134](https://github.com/tldraw/tldraw/pull/7134))
- Allow using custom socket implementations with `useSync` via a new `connect` option. ([#6859](https://github.com/tldraw/tldraw/pull/6859)) (contributed by [@Digital39999](https://github.com/Digital39999))
- Add support for nested property queries in the store. ([#6981](https://github.com/tldraw/tldraw/pull/6981))
- Add `createBookmarkFromUrl` helper for easier bookmark shape creation. ([#6894](https://github.com/tldraw/tldraw/pull/6894))
- Add custom reference points for handle angle snapping. ([#6987](https://github.com/tldraw/tldraw/pull/6987)) (contributed by [@naaa760](https://github.com/naaa760))
- Add new "lined-fill" style, accessible via Option+Shift+F. ([#7034](https://github.com/tldraw/tldraw/pull/7034))
- Add `onInteractionEnd` callback option. ([#6919](https://github.com/tldraw/tldraw/pull/6919))
- Add `allowReferrer` option for window opening functions. ([#7004](https://github.com/tldraw/tldraw/pull/7004))
- Remove defunct Excalidraw embed definition. ([#6897](https://github.com/tldraw/tldraw/pull/6897))

## Improvements

- Use window.prompt for renaming frames on mobile. ([#6838](https://github.com/tldraw/tldraw/pull/6838))
- Optimize string append operations in sync protocol. ([#7007](https://github.com/tldraw/tldraw/pull/7007)) (contributed by [@quasor](https://github.com/quasor))

## Bug fixes

- Fix Replit embed URL handling. ([#6892](https://github.com/tldraw/tldraw/pull/6892))
- Fix accessibility issue that caused a misleading warning in the console. ([#6904](https://github.com/tldraw/tldraw/pull/6904))
- Fix convert-to-bookmark action. ([#6894](https://github.com/tldraw/tldraw/pull/6894))
- Fix dropdown menu pointer handling. ([#7021](https://github.com/tldraw/tldraw/pull/7021))
- Fix iOS Safari image uploads. ([#7037](https://github.com/tldraw/tldraw/pull/7037))
- Fix Alt+Tab conflict on Windows. ([#7005](https://github.com/tldraw/tldraw/pull/7005))
- Fix text focus issues. ([#7043](https://github.com/tldraw/tldraw/pull/7043))
- Fix `TldrawEditor` usability without `TldrawUiContextProvider`. ([#7053](https://github.com/tldraw/tldraw/pull/7053))
- Fix cross-realm clipboard functionality. ([#7026](https://github.com/tldraw/tldraw/pull/7026))
- Fix iOS ink rendering via coalesced events. ([#6917](https://github.com/tldraw/tldraw/pull/6917))
- Fix menu-open dragging behavior. ([#6918](https://github.com/tldraw/tldraw/pull/6918))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.2.0)

---

## Patch releases

### v4.2.1

- Fix CommonJS/cjs builds that were broken in v4.2.0. ([#7282](https://github.com/tldraw/tldraw/pull/7282))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.2.1)

--------

# v4.1.0

This month's release introduces a new shader starter kit for WebGL integration, along with API additions for embed control, minimap filtering, and localStorage-backed atoms.

## What's new

### Shader starter kit ([#6847](https://github.com/tldraw/tldraw/pull/6847))

A new template demonstrating WebGL shader integration with tldraw for dynamic, interactive backgrounds that respond to canvas interactions. Includes four complete examples:

- **Fluid simulation** - Navier-Stokes dynamics
- **Rainbow** - Animated gradients
- **Shadows** - Raymarching and signed distance fields
- **Minimal** - Bare-bones template for custom shaders

Features configurable parameters, localStorage persistence, and full TypeScript support.

## API changes

- Add `embedOnPaste` option to `EmbedDefinition` for opting out of automatic embed-on-paste behavior. ([#6874](https://github.com/tldraw/tldraw/pull/6874))
- Add `hideInMinimap` option to `ShapeUtil` for excluding shapes from the minimap. ([#6327](https://github.com/tldraw/tldraw/pull/6327))
- Add `snapType?: 'point' | 'align'` to `TLHandle` for finer control over handle snapping. The `canSnap` property is now deprecated. ([#6883](https://github.com/tldraw/tldraw/pull/6883))
- Expose `Editor#getShapePageBounds` and `isRecordsDiffEmpty` as public methods. ([#6871](https://github.com/tldraw/tldraw/pull/6871))
- Add `localStorageAtom` to `@tldraw/state` for atoms backed by localStorage with cross-tab syncing. ([#6876](https://github.com/tldraw/tldraw/pull/6876))
- Add inline style picker component variants. ([#6920](https://github.com/tldraw/tldraw/pull/6920))

## Improvements

- Make bookmark titles clickable. ([#6326](https://github.com/tldraw/tldraw/pull/6326))
- Optimize mobile top bar rendering. ([#6895](https://github.com/tldraw/tldraw/pull/6895))
- Add numpad Enter support for entering edit mode. ([#6830](https://github.com/tldraw/tldraw/pull/6830))
- Consolidate preferences menu items. ([#6802](https://github.com/tldraw/tldraw/pull/6802))

## Bug fixes

- Fix accessibility shortcut typo. ([#6811](https://github.com/tldraw/tldraw/pull/6811))
- Fix focus mode action missing. ([#6812](https://github.com/tldraw/tldraw/pull/6812))
- Fix arrow rendering edge case. ([#6799](https://github.com/tldraw/tldraw/pull/6799))
- Fix empty window opening on anchor click. ([#6817](https://github.com/tldraw/tldraw/pull/6817))
- Fix missing translation key. ([#6826](https://github.com/tldraw/tldraw/pull/6826))
- Fix shape index race condition. ([#6884](https://github.com/tldraw/tldraw/pull/6884))
- Fix zero geometry vertices edge case. ([#6885](https://github.com/tldraw/tldraw/pull/6885))
- Fix style panel button overflow. ([#6920](https://github.com/tldraw/tldraw/pull/6920))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.1.0)

---

## Patch releases

### v4.1.1

- Update the formatting of the `npm create tldraw` command in the CLI output.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.1.1)

### v4.1.2

- Move `InFrontOfTheCanvas` component back out of the `.tl-canvas` element. ([#7021](https://github.com/tldraw/tldraw/pull/7021))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.1.2)

--------

# v4.0.0

This major release introduces new starter kits, a CLI tool, WCAG 2.2 Level AA accessibility compliance, and significant API enhancements for building custom canvas applications.

## What's new

### npm create tldraw ([#6753](https://github.com/tldraw/tldraw/pull/6753))

A new CLI tool for quickly scaffolding tldraw projects. Run `npm create tldraw` to initialize projects using templates and starter kits.

### Starter kits

Five new MIT-licensed starter kits demonstrate different applications of tldraw's canvas:

- **[agent](https://tldraw.dev/starter-kits/agent)** - Cursor-style chatbot interface where conversations occur on the canvas with AI assistance
- **[workflow](https://tldraw.dev/starter-kits/workflow)** - Node-and-wire visual programming interface for automation workflows and state machines
- **[branching-chat](https://tldraw.dev/starter-kits/branching-chat)** - Multi-path conversation explorer for managing conversation branches
- **[chat](https://tldraw.dev/starter-kits/chat)** - Canvas-based image annotation with integrated chatbot
- **[multiplayer](https://tldraw.dev/starter-kits/multiplayer)** - Collaborative whiteboard foundation built on tldraw sync

### Licensing ([#6707](https://github.com/tldraw/tldraw/pull/6707))

Production deployments now require a license key. Development and localhost environments remain exempt. Available licenses include:

- Free 100-day trial license
- Commercial license for commercial projects
- Hobby license for non-commercial use

### Accessibility ([#6695](https://github.com/tldraw/tldraw/pull/6695))

Achieves WCAG 2.2 Level AA compliance with an accessibility mode, improved keyboard shortcuts, comprehensive aria-labels, and scrollable menus.

### Drag from toolbar ([#6681](https://github.com/tldraw/tldraw/pull/6681))

Create shapes by dragging directly from the toolbar, eliminating the click-then-draw workflow.

### Custom shape clipping ([#6649](https://github.com/tldraw/tldraw/pull/6649))

Shapes can now clip their children, enabling complex visual hierarchies and container-style shapes.

### Vertical toolbar support ([#6623](https://github.com/tldraw/tldraw/pull/6623))

The toolbar supports vertical orientation for alternative layout configurations.

### Rich text arrows ([#6594](https://github.com/tldraw/tldraw/pull/6594))

Arrow labels support rich text formatting including bold, italic, and text styling.

## API changes

- 💥 **CSS variables** now start with `--tl-` prefix. Update custom CSS: `--color-background` → `--tl-color-background`, `--space-4` → `--tl-space-4`. ([#6712](https://github.com/tldraw/tldraw/pull/6712))
- 💥 **`Geometry2D.isLabel`** replaced with `excludeFromShapeBounds` flag. ([#6668](https://github.com/tldraw/tldraw/pull/6668))
- 💥 **`open-url` event** now uses `destinationUrl` instead of `url`. ([#6641](https://github.com/tldraw/tldraw/pull/6641))
- 💥 **Arrow shapes** now use `richText` instead of `text` property. Data migrates automatically, but direct access to `arrow.props.text` must update to `arrow.props.richText`. ([#6594](https://github.com/tldraw/tldraw/pull/6594))
- 💥 **`@tldraw/ai` module** removed. Use the [agent starter kit](https://tldraw.dev/starter-kits/agent) instead.
- 💥 **Event propagation behavior** changed. Use `editor.markEventAsHandled()` for custom event handling. ([#6592](https://github.com/tldraw/tldraw/pull/6592))
- 💥 **Style panel** redesigned with legacy picker components removed. ([#6573](https://github.com/tldraw/tldraw/pull/6573))
- 💥 **Toolbar CSS class names** updated for consistency. ([#6551](https://github.com/tldraw/tldraw/pull/6551))
- Add custom messages in `TLSocketRoom` via `sendCustomMessage()` and `onCustomMessageReceived`. ([#6614](https://github.com/tldraw/tldraw/pull/6614)) (contributed by [@mootari](https://github.com/mootari))
- Add `Editor.getShapesAtPoint()` with flexible margin options for precise hit testing. ([#6724](https://github.com/tldraw/tldraw/pull/6724))
- Add `editor.toImageDataUrl()` for generating image data URLs directly from shapes. ([#6658](https://github.com/tldraw/tldraw/pull/6658))
- Add `ShapeUtil.isExportBoundsContainer` and `canCull` methods for controlling export behavior and rendering optimization. ([#6649](https://github.com/tldraw/tldraw/pull/6649))
- Add `EditorAtom` for managing UI state outside React components. ([#6687](https://github.com/tldraw/tldraw/pull/6687))
- Add enhanced handle drag callbacks with timing events for custom drag interactions. ([#6702](https://github.com/tldraw/tldraw/pull/6702))

## Bug fixes

- Fix arrow labels being cut off in exports. ([#6783](https://github.com/tldraw/tldraw/pull/6783))
- Fix PNG physical pixel dimensions parsing. ([#6771](https://github.com/tldraw/tldraw/pull/6771))
- Fix pointer events on mobile firing inconsistently. ([#6738](https://github.com/tldraw/tldraw/pull/6738))
- Fix Chrome embed positioning at non-100% zoom levels. ([#6724](https://github.com/tldraw/tldraw/pull/6724))
- Fix hollow shapes not being properly bound-to by arrows. ([#6705](https://github.com/tldraw/tldraw/pull/6705))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.0.0)

---

## Patch releases

### v4.0.1

- Fix template exports. ([#6804](https://github.com/tldraw/tldraw/pull/6804))
- Fix documentation. ([#6805](https://github.com/tldraw/tldraw/pull/6805))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.0.1)

### v4.0.2

- Fix focus mode SDK issue that caused problems when using focus mode in the SDK. ([#6815](https://github.com/tldraw/tldraw/pull/6815))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.0.2)

### v4.0.3

- Add Claude 4.5 Sonnet to agent starter kit. ([#6852](https://github.com/tldraw/tldraw/pull/6852))
- Ensure templates don't use internal functions. ([#6871](https://github.com/tldraw/tldraw/pull/6871))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.0.3)

### v4.0.4

- Fix shape index jitter for the first shape created, preventing potential index collisions. ([#6884](https://github.com/tldraw/tldraw/pull/6884))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.0.4)

--------

# v3.15.0

This release introduces `npm create tldraw` for bootstrapping new projects, along with API additions, accessibility improvements, and performance optimizations.

## What's new

### npm create tldraw

Developers can now initialize new tldraw projects by running `npm create tldraw` in their terminal, selecting from available starter templates.

## API changes

- Add handle interaction callbacks: `onHandleDragStart`, `onHandleDragEnd`, and cancellation callbacks (`onTranslateCancel`, `onResizeCancel`, `onRotateCancel`, `onHandleDragCancel`).
- Add JSX icon support for custom icons in tool overrides, action overrides, buttons, and menu items.
- Add `StateNode.addChild` method enabling dynamic tool functionality additions.
- Convert `DefaultSpinner` component to SVG format, now accepts standard SVG properties.
- Export `HeartToolbarItem` component.

## Improvements

- Enhance "Select All" functionality to intelligently select within a shape's common parent context (e.g., selecting shapes within a frame without selecting the frame itself).
- Add user preference option to disable keyboard shortcuts.
- Prevent frame drops.
- Optimize the `useValue` and `useReactor` hooks.
- Enhance frame rendering efficiency.
- Expand `aria-hidden` application.
- Improve keyboard navigation.
- Add proper `role="radiogroup"` assignment for toggle groups.
- Correct aria slider values.

## Bug fixes

- Fix HTML entity escaping in pasted content.
- Fix text measurement accuracy.
- Fix arrow rendering between circles.
- Fix SVG text outline rendering.
- Fix image toolbar camera movement interactions.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.15.0)

---

## Patch releases

### v3.15.1

- Fix room change event handling in the sync core library. ([#6543](https://github.com/tldraw/tldraw/pull/6543))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.15.1)

### v3.15.2

- Fix editor remounting in a loop when given custom assetUrls. ([#6605](https://github.com/tldraw/tldraw/pull/6605))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.15.2)

### v3.15.3

- Enhance callback functionality for shape utilities. ([#6634](https://github.com/tldraw/tldraw/pull/6634))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.15.3)

### v3.15.4

- Fix potential bug in TLSyncClient. ([#6660](https://github.com/tldraw/tldraw/pull/6660))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.15.4)

### v3.15.5

- Show license flags message as a warning. ([#6843](https://github.com/tldraw/tldraw/pull/6843))
- Fix expired internal license verification. ([#6843](https://github.com/tldraw/tldraw/pull/6843))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.15.5)

--------

# v3.14.0

This release introduces contextual toolbars for image and video shapes, enhanced cropping options, and a new PathBuilder API.

## API changes

- 💥 **`Editor#getShapePageGeometry`** removed.
- 💥 **`Editor#getShapesAtPoint`** now returns shapes in descending index order.
- 💥 **Locked shapes** cannot be duplicated; pasting locked shapes unlocks them.
- 💥 **`ShapeUtil.canDropShapes`** removed—drag-and-drop participation now requires implementing handlers.
- Add `TldrawUiContextualToolbar` component enabling developers to create floating toolbars.
- Add `PathBuilder` API for constructing tldraw-style inky and dashed SVGs.
- Add arrow binding configuration for controlling when arrows should be exact and/or bind.
- Add `measureScrollWidth` option for text measurement.
- Add `defaultAutoplay` boolean property for `VideoShapeUtil`.

## Improvements

- Add image and video contextual toolbar with floating controls for enhanced interaction.
- Add download functionality for image and video shapes to download original files.
- Add advanced image cropping options.
- Improve context menu keyboard support.
- Improve style panel keyboard navigation.
- Improve focus management.
- Optimize copy operations.
- Optimize arrow rendering with labels.
- Optimize shape resizing.
- Optimize keyboard interactions.
- Optimize arrow dragging.
- Improve text measurement caching.

## Bug fixes

- Fix page menu scrolling behavior.
- Fix undo functionality for sticky creation.
- Fix bookmark hyperlink handling.
- Fix SVG output and vector calculations.
- Fix frame resizing with multiple selections.
- Fix HTML copy-paste positioning.
- Fix keyboard shortcuts and text overflow issues.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.14.0)

---

## Patch releases

### v3.14.1

- Fix text measurement bug where styles could leak from one measurement to the next. ([#6388](https://github.com/tldraw/tldraw/pull/6388))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.14.1)

### v3.14.2

- Fix HTML entities being escaped in clipboard operations. ([#6396](https://github.com/tldraw/tldraw/pull/6396))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.14.2)

--------

# v3.13.0

This release introduces elbow arrows for technical diagramming and continues accessibility improvements toward WCAG compliance.

## What's new

### Elbow arrows

The arrow shape now supports a new elbow connector style. These arrows travel between points using straight lines joined at right angles rather than curved paths, making them ideal for technical diagrams. Access this option through the arrow tool's line style settings.

## API changes

- 💥 **`ShapeUtil.canEditInReadOnly`** renamed to `ShapeUtil.canEditInReadonly` (note capitalization change).
- 💥 **Arrow target highlights** migrated from `setHintingShapes` to a custom `TldrawOverlays` component; users of `<TldrawEditor />` must pass this component to the `Overlays` slot.
- Add text measurement API that accepts arbitrary style parameters.
- Add new `Overlays` component for camera-following canvas overlays.
- Add `hasCustomTabBehavior` prop to `RichTextLabel` for custom tab logic.

## Improvements

- Auto-select link text when editing shape links.
- Snap pasted text and embeds to grid when enabled.
- Allow Figma embeds to work with selection links.
- Show visual block indicating label placement when editing arrow labels.
- Include background color in single frame exports.
- Allow frames to be double-click resized to fit contents.
- Allow style panel to focus with keyboard shortcut.
- Add proper labels to more UI icons and handles.
- Add container navigation shortcuts for moving selections in/out of frames and groups.
- Make embed shapes keyboard-tabbable.
- Add keyboard navigation to toolbars throughout the application.
- Show rich text editing shortcuts in the help menu.
- Improve performance of programmatic rotation of selected shapes.
- Improve performance of multi-shape dragging operations.
- Optimize selection evaluation to prevent unnecessary re-evaluations.

## Bug fixes

- Fix flattened shape backgrounds.
- Fix screenreader behavior.
- Fix tool consistency.
- Fix text rendering.
- Fix selection accuracy.
- Fix arrow flickering during rotation.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.13.0)

---

## Patch releases

### v3.13.1

- Show elbow arrow outline indicator on hover when creating elbow arrows. ([#6099](https://github.com/tldraw/tldraw/pull/6099))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.13.1)

### v3.13.2

- Fix LoadingScreen context bug where custom asset URL configuration was ignored. ([#6283](https://github.com/tldraw/tldraw/pull/6283))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.13.2)

### v3.13.3

- Fix overriding builtin tools not working. ([#6330](https://github.com/tldraw/tldraw/pull/6330))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.13.3)

### v3.13.4

- Fix cross-realm functionality issues. ([#6338](https://github.com/tldraw/tldraw/pull/6338))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.13.4)

--------

# v3.12.0

This release focuses on accessibility improvements and API enhancements, with no breaking changes.

## API changes

- Add new `getShapeVisibility` prop replacing the deprecated `isShapeHidden`, allowing hidden children to override parent visibility states.
- Allow frames to display colorful borders and labels by configuring `FrameShapeUtil` with `showColors: true`.
- Add `Geometry2d` helper methods including `intersectLineSegment`, `intersectCircle`, `transform`, and filtering options.
- Export two Tiptap extensions individually for rich text customization.

## Improvements

- Add keyboard-based selection movement between shapes using Tab and Cmd/Ctrl+Arrow keys.
- Add screen reader announcements for tool and shape selection changes.
- Add keyboard resizing capability via Cmd/Ctrl+Alt+Shift with +/- keys.
- Improve semantic HTML5 tags and proper ARIA roles throughout the UI.
- Simplify keyboard shortcut syntax (e.g., `'?!l'` becomes `'alt+shift+l'`).
- Add atomic `Store.mergeRemoteChanges` with correct scope-triggered side effects.
- Add smoother drawing on slower CPUs via `getCoalescedEvents`.
- Add YouTube embed support for time/loop parameters.
- Add optional asset URL overrides for unused Embed shape icons.

## Bug fixes

- Fix Firefox SVG pasting.
- Fix TailwindCSS text export styling.
- Fix image pasting efficiency.
- Fix Miro shape compatibility.
- Fix Safari trackpad zoom.
- Fix performance regressions in rich text and iPad drawing.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.12.0)

---

## Patch releases

### v3.12.1

- Fix group bounds containing text shapes. ([#5911](https://github.com/tldraw/tldraw/pull/5911))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.12.1)

### v3.12.2

- Restore DPR constrained shape dimensions. ([#6034](https://github.com/tldraw/tldraw/pull/6034))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.12.2)

--------

# v3.11.0

This release addresses rich text issues following v3.10, adds zoom improvements, and introduces accessibility enhancements.

## API changes

- 💥 **`editor.user.getName()`** no longer returns "New user" when unnamed; returns empty string instead.
- 💥 **`defaultUserPreferences.name`** changed from "New user" to empty string.
- Export `RichTextSVG` from the package.

## Improvements

- Add a new minimum zoom step at 5%.
- Add keyboard shortcuts (Shift +/Shift -) for zooming toward your cursor.
- Add option to hit Enter to continue editing after selection in the style panel.
- Improve rich text rendering performance with many shapes.
- Improve hiding/showing shape indicators on large projects.
- Add page navigation shortcuts (option + arrows).
- Add support for satellite mode in Google Map embeds.
- Add focus rings for accessibility.
- Add nonce support for the editor security.

## Bug fixes

- Fix rich text numbered list geometry bounds.
- Fix React 19 StrictMode compatibility.
- Fix export styling issues.
- Fix missing internationalization strings for rich text elements.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.11.0)

---

## Patch releases

### v3.11.1

- Fix application of zoomSpeed setting to pinch gestures. ([#5696](https://github.com/tldraw/tldraw/pull/5696))
- Fix unexpected borders in exports from Tailwind CSS pages. ([#5696](https://github.com/tldraw/tldraw/pull/5696))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.11.1)

### v3.11.2

- Fix sync core bug. ([#6667](https://github.com/tldraw/tldraw/pull/6667))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.11.2)

--------

# v3.10.0

This release introduces rich text as a first-class primitive within the Editor, alongside various performance improvements and bug fixes.

## What's new

### Rich text support

The SDK now offers rich text as a first-class primitive. The implementation utilizes TipTap with its StarterKit extension plus additional customizations. Developers can configure this functionality through a `textOptions` property to customize TipTap and modify extensions.

## API changes

- 💥 **`text` property** on most shapes replaced with `richText`. When setting values, use `richText: toRichText('some string')` instead of `text: 'some string'`. When retrieving values, use `renderPlaintextFromRichText(props.text)` rather than `props.text`.
- Add asset rehydration for .tldr files containing embedded base64 data.
- Add `BrokenAssetIcon` display on file upload failures.
- Add public collaboration hooks (`usePeerIds`, `usePresence`).
- Add `userId` parameter to collaboration components.

## Bug fixes

- Fix performance regression affecting document loading.
- Fix Firefox export/style embedding for foreignObjects.
- Fix shape reparenting order preservation.
- Fix resize functionality.
- Fix Safari file pasting issues.
- Fix SSR environment compatibility (core-js import removal).
- Fix IME text duplication in Chrome.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.10.0)

---

## Patch releases

### v3.10.1

- Fix API reference links in state packages. ([#5610](https://github.com/tldraw/tldraw/pull/5610))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.10.1)

### v3.10.2

- Add `textOptions` to `<TldrawImage />` component. ([#5650](https://github.com/tldraw/tldraw/pull/5650))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.10.2)

### v3.10.3

- Fix Inter font being embedded in exports. ([#5676](https://github.com/tldraw/tldraw/pull/5676))
- Reduce excessive styling in exported content. ([#5676](https://github.com/tldraw/tldraw/pull/5676))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.10.3)

--------

# v3.9.0

This release focuses on bug fixes and performance enhancements, laying groundwork for v3.10 features.

## API changes

- 💥 **`store.createSelectedComputedCache`** removed; use `store.createCache` with custom selector `computed` instead.
- 💥 **`createComputerCache` API** modified: third argument now accepts options object with `areRecordsEqual` and `areResultsEqual` properties instead of single equality function.

## Improvements

- Improve layout operations including align, distribute, flip, and stack with better compatibility for arrows and overlapping shapes.
- Add new `AtomMap` class to accelerate shape, binding, and record creation/deletion, available as a utility for building custom reactive maps.
- Add horizontal padding to text-bound arrows for improved visual appearance.

## Bug fixes

- Fix pasted image size calculations.
- Remove `canvas-size` dependency resolving bundler compatibility issues.
- Fix SVG copy mimetype.
- Fix text shape cloning crash.
- Fix temporary image preview display during uploads.
- Recognize `https://localhost` as development environment for licensing.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.9.0)

--------

# v3.8.0

This release delivers performance enhancements, UI improvements, and developer experience upgrades alongside bug fixes.

## API changes

- 💥 **`maxDrawShapePoints`** moved to `DrawShapeUtil.configure({ maxPoints })`.
- 💥 **Asset upload** now returns `{ src, meta? }` object instead of string.
- 💥 **JSON export option** removed; `useImageOrVideoAssetUrl` requires width parameter.
- 💥 **`TldrawUiToasts` and `TldrawUiDialogs`** renamed to `DefaultToasts` and `DefaultDialogs`.
- Add new `Editor.toImage` method for refined export functionality.
- Add custom content handlers for pasted tldraw and excalidraw content.
- Add "before-event" listener for custom input event handling.
- Add `onCrop` method for shape-specific cropping customization.

## Improvements

- Add `ShapeUtil.configure` utility for passing options to shape utilities.
- Allow note shapes to resize by scale.
- Add geometric tool shortcut (`g` key) for quick selection.
- Add URL drag-and-drop to create bookmark shapes on canvas.
- Expand support to 40+ languages via i18n enhancements.
- Add React 19 compatibility.
- Improve frame performance through computation relocation.

## Bug fixes

- Fix dialog and edit menu glitches.
- Fix mousewheel scrolling on elements.
- Fix image export width.
- Fix text paste behavior via keyboard shortcuts.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.8.0)

---

## Patch releases

### v3.8.1

- Fix `TldrawImage` not functioning properly with `format=png`. ([#5429](https://github.com/tldraw/tldraw/pull/5429))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.8.1)

--------

# v3.7.0

This release delivers bug fixes and performance enhancements, including customization options for presence data synchronization.

## What's new

### Presence sync customization ([#5149](https://github.com/tldraw/tldraw/pull/5149))

Developers can now customize what presence data is synced between clients, or disable presence syncing entirely. This enables optimization for high-latency connections and privacy-focused applications.

## API changes

- Allow `expandSelectionOutlinePx` to return a `Box` object to enable asymmetric expansion across different sides.
- Modify behavior when using `editor.updateShape` to properly handle undefined values.

## Bug fixes

- Fix React Strict Mode listener bug affecting `store.listen`.
- Fix image rotation and cropping functionality issues.
- Fix CSS import failures during export/print operations.
- Fix text measurement div leakage during development hot reloads.
- Fix popover menu viewport overflow problems.
- Fix GitHub Gist URL validation.
- Fix image dimension limits for pasted content.
- Fix pages menu and quick actions rendering.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.7.0)

---

## Patch releases

### v3.7.1

- Pass custom migrations to `useLocalStore`. ([#5204](https://github.com/tldraw/tldraw/pull/5204))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.7.1)

### v3.7.2

- Fix pasting files copied from the local filesystem with cmd-v. ([#5225](https://github.com/tldraw/tldraw/pull/5225))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.7.2)

--------

# v3.6.0

This release focuses on developer experience improvements with expanded helper functions and various bug fixes across the editor, embed system, and export functionality.

## What's new

### Expanded helper functions ([#5041](https://github.com/tldraw/tldraw/pull/5041))

Actions and toasts overrides now have access to a wider range of helper functions, including clipboard interactions, toast notifications, export utilities, printing, and more. This makes it easier to create custom actions and tools that integrate deeply with tldraw's functionality.

## API changes

- 💥 **`setEmbedDefinitions`** changed from an instance method to a static method on the `EmbedShapeUtil` class. Update your embed definitions to use `EmbedShapeUtil.setEmbedDefinitions()` instead of calling it on an instance. ([#5027](https://github.com/tldraw/tldraw/pull/5027))
- 💥 **`ExtractOptionalKeys` and `ExtractRequiredKeys`** utility types removed. Use the new utility type for creating optional properties instead. ([#5055](https://github.com/tldraw/tldraw/pull/5055))

## Improvements

- Add utility type for making undefined properties optional, simplifying type definitions for shape props and other optional configurations. ([#5055](https://github.com/tldraw/tldraw/pull/5055))
- Make notes properly snap to the grid after their position is updated, improving alignment consistency. ([#5010](https://github.com/tldraw/tldraw/pull/5010))
- Add incremental derivation example demonstrating advanced computed value patterns. ([#5038](https://github.com/tldraw/tldraw/pull/5038))

## Bug fixes

- Fix asset resolution when copying and pasting multiple items, including proper handling of video assets. ([#5061](https://github.com/tldraw/tldraw/pull/5061))
- Fix text clipping in scaled frames during export, ensuring all text content is visible in exported images. ([#5022](https://github.com/tldraw/tldraw/pull/5022))
- Fix concurrent export operations interfering with each other's font loading. ([#5022](https://github.com/tldraw/tldraw/pull/5022))
- Fix long-press point accuracy to ensure touch interactions register at the correct coordinates. ([#5032](https://github.com/tldraw/tldraw/pull/5032))
- Fix export naming for single unnamed frames, which now receive appropriate default names. ([#4918](https://github.com/tldraw/tldraw/pull/4918))
- Fix custom embeds not rendering correctly on initial mount. ([#5027](https://github.com/tldraw/tldraw/pull/5027))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.6.0)

---

## Patch releases

### v3.6.1

- Fix bugs in the editor, state-react, and tldraw packages. ([#5132](https://github.com/tldraw/tldraw/pull/5132))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.6.1)

--------

# v3.5.0

This release introduces enhancements to grid snapping during shape creation, improves layering mechanics, and provides better control over export functionality.

## What's new

### Grid snapping for shape creation ([#4894](https://github.com/tldraw/tldraw/pull/4894))

Shapes now automatically align to the grid when drawn in grid mode. The new `maybeSnapToGrid` function enables snapping for both click-created and drag-created shapes.

### Improved layering actions ([#4898](https://github.com/tldraw/tldraw/pull/4898))

The "bring forward" and "send backward" actions now only consider nearby overlapping shapes, making layer management more intuitive when working with complex canvases.

## API changes

- Add `scale` and `pixelRatio` parameters to export utilities for more precise control over export dimensions and quality.
- Expose font size and stroke size APIs.
- Add socket close reason for rate limiting.
- Add option to toggle double-click text creation.

## Improvements

- Improve panning performance for note-heavy canvases and zoomed-out views.
- Improve page menu hover interaction.
- Add custom React provider support in SVG exports.
- Switch default theme to light mode.
- Improve frame heading right-click behavior.

## Bug fixes

- Fix off-screen shape zoom-to-edit.
- Fix erasing state stickiness.
- Fix frame heading drag interactions.
- Fix Safari sleep-related crashes.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.5.0)

---

## Patch releases

### v3.5.1

- Fix long press on inset canvases. ([#5037](https://github.com/tldraw/tldraw/pull/5037))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.5.1)

--------

# v3.4.0

This release addresses UI bugs, enhances image/video performance, and improves Excalidraw content compatibility.

## API changes

- 💥 **`id` DOM attribute** on shapes removed in favor of a `data-shape-id` attribute on shape wrappers.
- Add `labelColor` property to note shapes.
- Add `useUniqueSafeId` and `useSharedSafeId` utilities for managing DOM IDs in tldraw components.

## Improvements

- Improve tooltip wording in the style panel.
- Prevent arrow label indicators from displaying behind labels.
- Limit page name length in the move-to-page menu.
- Improve image and video rendering performance.

## Bug fixes

- Fix re-render loops caused by inline `options` in the Tldraw component.
- Fix toolbar button outline border-radius alignment.
- Fix color preservation when pasting Excalidraw content.
- Fix unhighlighted menu triggers.
- Fix drag event type handling.
- Fix duplicate image creation on canvas drops.
- Fix link indicator visibility on sticky notes.
- Fix URL parsing in embed dialogs.
- Fix cross-instance rendering conflicts.
- Fix menu options in read-only mode.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.4.0)

---

## Patch releases

### v3.4.1

- Fix arrows being clipped incorrectly when multiple tldraw instances or exports are present in the DOM. ([#4819](https://github.com/tldraw/tldraw/pull/4819))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.4.1)

--------

# v3.3.0

This release introduces sync improvements, readonly mode support, and various performance enhancements.

## What's new

### Readonly mode

Servers can now restrict client editing while preserving presence updates using the new "readonly" mode. This enables use cases like view-only sharing and presentation modes where users can see each other's cursors but cannot modify the document.

### Sync server enhancements

New `TLSocketRoom` methods (`closeSession`, `getRecord`, and `getSessions`) provide finer control over sync connections and room state management.

## API changes

- Add editor option for quick action shortcut placement.
- Add `editor.getIsReadonly()` helper method.

## Improvements

- Pass wheel events through toolbar elements for improved scrolling/zooming.
- Allow Command/Control modifier keys to enable multi-select (previously shift-only).
- Allow text tool to be locked.
- Improve draw shape rendering performance during zoom interactions.

## Bug fixes

- Fix Safari arrow rendering.
- Fix image drop navigation errors.
- Fix watermark layering.
- Fix geometry calculations.
- Fix readonly mode label editing prevention.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.3.0)

---

## Patch releases

### v3.3.1

- Fix meta key incorrectly triggering the shift key. ([#4703](https://github.com/tldraw/tldraw/pull/4703))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.3.1)

### v3.3.2

- Fix dropped images being created twice. ([#4727](https://github.com/tldraw/tldraw/pull/4727))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.3.2)

### v3.3.3

- Fix image duplication when dropping onto the canvas. ([#4789](https://github.com/tldraw/tldraw/pull/4789))
- Fix additional keyboard modifier issues. ([#4789](https://github.com/tldraw/tldraw/pull/4789))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.3.3)

--------

# v3.2.0

This release contains no code changes. It was published to align version numbers across packages. See the [v3.1.0 release notes](/releases/v3.1.0) for information about changes since v3.0.x.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.2.0)

--------

# v3.1.0

This release introduces shape visibility control and server-side data manipulation capabilities, alongside API enhancements and bug fixes.

## What's new

### Shape visibility control ([#4570](https://github.com/tldraw/tldraw/pull/4570))

The new `isShapeHidden` predicate option prevents shapes from being rendered or reacting to pointer events. This is useful for implementing permission systems in collaborative applications where certain shapes should be invisible to specific users.

### Server-side document manipulation ([#4581](https://github.com/tldraw/tldraw/pull/4581))

The tldraw sync server now supports server-side document manipulation through the `updateShapes` method, enabling integration with third-party services and automated document updates.

## API changes

- Add option to `Editor.rotateShapesBy` specifying rotation center point.
- Add `useAsset` hook for resolving responsive asset versions.

## Bug fixes

- Fix arrow label text measurement calculations.
- Fix arrow collaborator indicators overlapping labels.
- Fix binding processing error handling.
- Fix watermark opacity and animation behavior.

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.1.0)

--------

# v3.0.0

This release introduces a revised licensing model alongside deep links, enhanced image export, custom embeds, and a new text search API.

## What's new

### Licensing

The most significant change involves updated licenses permitting use in both commercial and non-commercial projects when displaying a "Made with tldraw" watermark. Users can now purchase Business Licenses to remove the watermark, with details available at [tldraw.dev](https://tldraw.dev). ([#4449](https://github.com/tldraw/tldraw/pull/4449), [#4517](https://github.com/tldraw/tldraw/pull/4517), [#4561](https://github.com/tldraw/tldraw/pull/4561))

### Deep links

New APIs enable creation of shareable URLs pointing to specific canvas locations, such as particular shapes or pages, with automatic URL updates as users navigate.

```typescript
// Create a deep link to a specific shape
const url = editor.createDeepLink({
	shapeId: 'shape-id',
	viewport: 'fit',
})

// The URL updates automatically as you navigate
editor.on('change', () => {
	const currentUrl = editor.getCurrentDeepLink()
})
```

See the [deep links guide](https://tldraw.dev/docs/editor#Deep-links) for more information. ([#4498](https://github.com/tldraw/tldraw/pull/4498))

### Enhanced image export

Custom shapes now export as images by default through HTML/CSS embedding within SVG files, eliminating the need for developers to implement custom SVG rendering methods.

```typescript
// Custom shapes automatically export as images
class MyShapeUtil extends ShapeUtil<MyShape> {
  // No need to implement toSvg() anymore
  component(shape: MyShape) {
    return <div className="my-shape">{/* ... */}</div>
  }
}
```

### Custom embeds API

Developers can now customize which external websites (YouTube, Google Maps, CodeSandbox, etc.) appear as embeddable content, or add entirely new embed types.

```typescript
// Add a custom embed type
const customEmbedDef = {
  type: 'custom',
  title: 'My Custom Embed',
  hostnames: ['mysite.com'],
  toEmbedUrl: (url: string) => `https://mysite.com/embed/${url}`,
  fromEmbedUrl: (url: string) => url.replace('/embed/', '/')
}

<Tldraw embedDefs={[customEmbedDef, ...defaultEmbedDefs]} />
```

### Text search via getText API

A new `getText` API provides reliable access to human-readable shape content, facilitating text search implementation within applications.

```typescript
// Search through all shapes for text content
const searchResults = editor.getCurrentPageShapes().filter((shape) => {
	const text = editor.getText(shape.id)
	return text?.toLowerCase().includes(searchTerm.toLowerCase())
})
```

## API changes

- 💥 **`TLRotationSnapshot`** type removed from the public API. Use `editor.getShapePageTransform(shape).rotation()` instead.
- 💥 **`onEditorMount`** callback in `createTLStore` renamed to `onMount` for consistency.
- 💥 **`Editor.mark()`** deprecated in favor of `Editor.markHistoryStoppingPoint()` for clearer intent.
- 💥 **`TLSvgOptions`** type renamed to `TLImageExportOptions` to better reflect its broader use in image export.
- 💥 **Focus event behavior**: Calling `updateInstanceState({isFocused: true})` now triggers standard focus events consistently. Use `editor.focus()` for reliable focus behavior.
- Add `editor.getText(shapeId)` method for accessing shape text content.
- Add `editor.createDeepLink(options)` for generating shareable URLs.
- Add `embedDefs` prop to Tldraw component for customizing embed types.
- Expose additional shape export utilities for custom image generation.

## Improvements

- Improve bookmark rendering for URLs without preview images. ([#4460](https://github.com/tldraw/tldraw/pull/4460))
- Improve handling of asset storage and persistence. ([#4542](https://github.com/tldraw/tldraw/pull/4542))
- Improve documentation search functionality. ([#4485](https://github.com/tldraw/tldraw/pull/4485))
- Refine watermark appearance and behavior. ([#4589](https://github.com/tldraw/tldraw/pull/4589), [#4622](https://github.com/tldraw/tldraw/pull/4622))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.0.0)

---

## Patch releases

### v3.0.1

- Fix documentation search functionality and article issues. ([#4515](https://github.com/tldraw/tldraw/pull/4515))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.0.1)

### v3.0.2

- Fix build caching issue causing "You have multiple versions of tldraw libraries installed" errors. ([#4525](https://github.com/tldraw/tldraw/pull/4525))
- Fix container null error. ([#4524](https://github.com/tldraw/tldraw/pull/4524))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.0.2)

### v3.0.3

- Fix bugs in the editor and tldraw packages. ([#4541](https://github.com/tldraw/tldraw/pull/4541))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v3.0.3)

--------

# v2.4.0

This release introduces our sync engine as a general-use library, new animation options for shapes, support for image flipping, and many bug fixes and developer experience enhancements.

## What's new

### Sync ([#4031](https://github.com/tldraw/tldraw/pull/4031))

For the first time, we're releasing our real-time collaboration engine—the one we developed for tldraw.com—as a general library. The SDK still supports any backend for collaboration, but we hope this will be the easiest option for developers. See the new `sync` package in the repository and the multiplayer-demo example.

### Interpolation ([#4162](https://github.com/tldraw/tldraw/pull/4162))

You can use `Editor.animateShapes` to animate shapes on the canvas. Previously only position and rotation would animate. Now you can implement `ShapeUtil.getInterpolatedProps` to describe how your custom shape's other properties should animate.

```ts
override getInterpolatedProps(
  startShape: Shape,
  endShape: Shape,
  t: number
): Shape['props'] {
  return {
    ...endShape.props,
    w: lerp(startShape.props.w, endShape.props.w, t),
    h: lerp(startShape.props.h, endShape.props.h, t),
  }
}
```

### Editor.run ([#4042](https://github.com/tldraw/tldraw/pull/4042))

The new `Editor.run` method runs a function within additional context. By default, the function runs inside a transaction, meaning all changes settle at once—improving performance and avoiding unnecessary renders. You can also use options to ignore history or ignore locked shapes.

```ts
editor.run(
	() => {
		editor.createShapes(myShapes)
		editor.sendToBack(myShapes)
		editor.selectNone()
	},
	{ history: 'ignore' }
)
```

### Assets

As part of our work on sync, we have a new system for handling large assets like images and videos. Provide a [`TLAssetStore`](https://tldraw.dev/reference/tlschema/TLAssetStore) to control how assets are uploaded and retrieved. Use [`Editor.uploadAsset`](https://tldraw.dev/reference/editor/Editor#uploadAsset) and [`Editor.resolveAssetURL`](https://tldraw.dev/reference/editor/Editor#resolveAssetUrl) in your shapes and tools.

## API changes

- 💥 **`editor.history.ignore(cb)`** replaced with `editor.run(cb, {history: 'ignore'})`.
- 💥 **`editor.batch`** deprecated, replaced with `editor.run`.
- 💥 **`@tldraw/state` imports**: If you're importing from `@tldraw/state` directly, the `track` function and all hooks (e.g. `useValue`) have moved to `@tldraw/state-react`. ([#4170](https://github.com/tldraw/tldraw/pull/4170))
- Add `DefaultMenuPanel` export. ([#4193](https://github.com/tldraw/tldraw/pull/4193))
- Make `fileSize` property of `TLImageAsset` and `TLVideoAsset` optional. ([#4206](https://github.com/tldraw/tldraw/pull/4206))
- Allow passing partial `TLEditorSnapshot` to `TldrawImage` and `useTLStore`. ([#4190](https://github.com/tldraw/tldraw/pull/4190))
- Make `EffectScheduler` and `useStateTracking` public. ([#4155](https://github.com/tldraw/tldraw/pull/4155))
- Add `setDefaultValue` to `StyleProp`. ([#4044](https://github.com/tldraw/tldraw/pull/4044))
- Add `ShapeUtil.getInterpolatedProps`. ([#4162](https://github.com/tldraw/tldraw/pull/4162))
- Add `Editor.run`, replacing `Editor.batch`. ([#4042](https://github.com/tldraw/tldraw/pull/4042))

## Improvements

- Add horizontal and vertical flipping for images. ([#4113](https://github.com/tldraw/tldraw/pull/4113))
- Allow custom tools to decide whether they are affected by shape lock. ([#4208](https://github.com/tldraw/tldraw/pull/4208))
- Serve icons as a single SVG instead of many individual requests. ([#4150](https://github.com/tldraw/tldraw/pull/4150))
- Make paste-at-point behavior based on a user preference. ([#4104](https://github.com/tldraw/tldraw/pull/4104))
- Show toast when uploading an unsupported file type or file that's too large. ([#4114](https://github.com/tldraw/tldraw/pull/4114))
- Show toast when pasting fails due to missing clipboard permissions. ([#4117](https://github.com/tldraw/tldraw/pull/4117))
- Add `ShapeIndicators` component for custom logic about when to display indicators. ([#4083](https://github.com/tldraw/tldraw/pull/4083))
- Animate shape opacity changes. ([#4242](https://github.com/tldraw/tldraw/pull/4242))

## Bug fixes

- Fix font style export to SVG. ([#4195](https://github.com/tldraw/tldraw/pull/4195))
- Fix `force` flag for camera methods. ([#4214](https://github.com/tldraw/tldraw/pull/4214))
- Show user's color scheme in menu by default. ([#4184](https://github.com/tldraw/tldraw/pull/4184))
- Fix padding for dynamically scaled text shapes. ([#4140](https://github.com/tldraw/tldraw/pull/4140))
- Fix `cameraOptions` via React causing editor to re-mount. ([#4089](https://github.com/tldraw/tldraw/pull/4089))
- Allow high-res images to be uploaded. ([#4198](https://github.com/tldraw/tldraw/pull/4198))
- Prevent locked shapes from being updated, grouped, or ungrouped programmatically. ([#4042](https://github.com/tldraw/tldraw/pull/4042))
- Fix `snapshots` prop in `createTLStore`. ([#4233](https://github.com/tldraw/tldraw/pull/4233))
- Fix grid backgrounds with multiple tldraw instances. ([#4132](https://github.com/tldraw/tldraw/pull/4132))
- Fix inputs staying in place while viewport-following. ([#4108](https://github.com/tldraw/tldraw/pull/4108))
- Fix bookmarks rendering across devices. ([#4118](https://github.com/tldraw/tldraw/pull/4118))
- Fix `InFrontOfTheCanvas` component stack order. ([#4024](https://github.com/tldraw/tldraw/pull/4024))
- Fix frame headers not stopping edit on focus loss. ([#4092](https://github.com/tldraw/tldraw/pull/4092))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.4.0)

---

## Patch releases

### v2.4.1

- Fix `assets` prop on `<Tldraw />` and `<TldrawEditor />` components not being respected. ([#4285](https://github.com/tldraw/tldraw/pull/4285))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.4.1)

### v2.4.2

- Fix bugs and improve the sync engine and related packages. ([#4309](https://github.com/tldraw/tldraw/pull/4309))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.4.2)

### v2.4.3

- Fix bugs in the tldraw package. ([#4328](https://github.com/tldraw/tldraw/pull/4328))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.4.3)

### v2.4.4

- Fix bugs in the editor, sync, tldraw, and tlschema packages. ([#4352](https://github.com/tldraw/tldraw/pull/4352))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.4.4)

### v2.4.5

- Fix unhandled promise rejection during strict mode in the editor. ([#4407](https://github.com/tldraw/tldraw/pull/4407))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.4.5)

### v2.4.6

- Improve rendering performance in the store and tldraw packages. ([#4434](https://github.com/tldraw/tldraw/pull/4434))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.4.6)

--------

# v2.3.0

This release focuses on image and video storage improvements, a new fonts/icons CDN, image performance optimizations, and a new flatten feature.

## What's new

### Image and video storage improvements ([#3836](https://github.com/tldraw/tldraw/pull/3836))

When using local-only storage, images and videos are now stored in a separate IndexedDB table instead of as base64-encoded blobs in the room's JSON. This significantly improves performance and reduces the size of room data.

### Fonts and icons CDN ([#3923](https://github.com/tldraw/tldraw/pull/3923))

Improved our CDN for assets (fonts and icons). We were using unpkg before, but now we're using Cloudflare directly for more fine-grained control and better performance. ([#3927](https://github.com/tldraw/tldraw/pull/3927))

### Image level-of-detail ([#3827](https://github.com/tldraw/tldraw/pull/3827))

For higher-resolution images (over a couple megabytes), the image gets transformed to an appropriate size depending on your viewport, zoom level, and network speed. This helps with bandwidth and browser memory usage when you have multiple high-res images on the board.

### Flatten ([#3933](https://github.com/tldraw/tldraw/pull/3933))

You can now select multiple shapes and flatten them into a single image. For those moments when you need to press things together.

### Security improvements ([#3884](https://github.com/tldraw/tldraw/pull/3884))

Locked down referrer network requests to make sure we weren't leaking tldraw rooms to external media/iframe requests. ([#3881](https://github.com/tldraw/tldraw/pull/3881))

## API changes

- Add fill-fill style, accessible via `Alt`+`F`. ([#3966](https://github.com/tldraw/tldraw/pull/3966))
- Make `ArrowBindingUtil` public. ([#3913](https://github.com/tldraw/tldraw/pull/3913))
- Add `getSnapshot` and `loadSnapshot` methods to `Editor` class. ([#3912](https://github.com/tldraw/tldraw/pull/3912))

## Improvements

- Allow users to use system appearance (dark/light) mode. ([#3703](https://github.com/tldraw/tldraw/pull/3703))
- Remove ability to rename document while in readonly mode. ([#3911](https://github.com/tldraw/tldraw/pull/3911))
- Add delay and easing to edge scrolling. ([#3950](https://github.com/tldraw/tldraw/pull/3950))

## Bug fixes

- Fix copy/paste for older versions of Firefox. ([#4008](https://github.com/tldraw/tldraw/pull/4008))
- Fix copy/paste in Firefox 127+. ([#4003](https://github.com/tldraw/tldraw/pull/4003))
- Fix not allowing editing locked shapes when switching edit modes. ([#4007](https://github.com/tldraw/tldraw/pull/4007))
- Fix text shape measurement in React strict mode. ([#4001](https://github.com/tldraw/tldraw/pull/4001))
- Fix border color for following user. ([#3975](https://github.com/tldraw/tldraw/pull/3975))
- Fix scale issue with new draw lines. ([#3971](https://github.com/tldraw/tldraw/pull/3971))
- Fix edge scrolling at odd browser zoom levels. ([#3973](https://github.com/tldraw/tldraw/pull/3973))
- Fix appearance of solid-style heart shapes. ([#3963](https://github.com/tldraw/tldraw/pull/3963))
- Fix position of multiple assets when pasted/dropped onto canvas. ([#3965](https://github.com/tldraw/tldraw/pull/3965))
- Fix indicator for stylus-drawn draw shapes. ([#3962](https://github.com/tldraw/tldraw/pull/3962))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.3.0)

--------

# v2.2.0

This release introduces the bindings system, camera constraints, and configurable options—major features that unlock new types of applications you can build with tldraw.

## What's new

### Bindings ([#3326](https://github.com/tldraw/tldraw/pull/3326))

Bindings allow you to create relationships between shapes. Our default arrow shapes are a great example: each end of the arrow can bind to another shape. When that shape moves, so does the arrow.

Before this change, arrows were hard-coded into the library. Now, with the bindings system, you can create arrows, constraint systems, visual programming environments, and much more.

Check out the [bindings guide](https://tldraw.dev/docs/editor#Bindings) for more information. ([#3780](https://github.com/tldraw/tldraw/pull/3780)) ([#3797](https://github.com/tldraw/tldraw/pull/3797)) ([#3800](https://github.com/tldraw/tldraw/pull/3800)) ([#3871](https://github.com/tldraw/tldraw/pull/3871))

### Camera constraints ([#3282](https://github.com/tldraw/tldraw/pull/3282))

You can now limit the camera to a fixed area of the canvas. This is useful for creating experiences that don't quite fit the "infinite canvas" paradigm: document annotators, image editors, slideshow creators, and more.

See the [camera constraints guide](https://tldraw.dev/docs/editor#Camera-options) for more information. ([#3747](https://github.com/tldraw/tldraw/pull/3747)) ([#3814](https://github.com/tldraw/tldraw/pull/3814))

### Configurable options ([#3799](https://github.com/tldraw/tldraw/pull/3799))

You can now override many options which were previously hard-coded constants. Pass an `options` prop into the tldraw component to change the maximum number of pages, grid steps, or other previously hard-coded values.

See [`TldrawOptions`](https://tldraw.dev/reference/editor/TldrawOptions) for details. ([#3900](https://github.com/tldraw/tldraw/pull/3900))

### 💥 Undo/redo changes

The history system has been significantly reworked:

1. **History options simplified**: `squashing`, `ephemeral`, and `preserveRedoStack` flags have been consolidated. Use `editor.history.ignore(fn)` or `editor.history.batch(fn, {history: 'record-preserveRedoStack'})` instead.

2. **Automatic recording**: Everything that touches the store is now recorded in undo/redo (unless part of `mergeRemoteChanges`). Use `editor.history.ignore(fn)` for changes you don't want recorded.

3. **Side effects captured**: Changes in side-effects are now captured by undo/redo. Wrap in `editor.history.ignore` for the old behavior.

## API changes

- 💥 **`canBind`** now accepts an options object instead of just the shape. See [`TLShapeUtilCanBindOpts`](https://tldraw.dev/reference/editor/TLShapeUtilCanBindOpts).
- 💥 **`editor.sideEffects.registerBatchCompleteHandler`** replaced with `editor.sideEffects.registerOperationCompleteHandler`. ([#3748](https://github.com/tldraw/tldraw/pull/3748))
- 💥 **`editor.getArrowInfo(shape)`** replaced with `getArrowInfo(editor, shape)`.
- 💥 **`editor.getArrowsBoundTo(shape)`** removed—use `editor.getBindingsToShape(shape, 'arrow')` instead.
- 💥 **Arrow shape `start` and `end` properties** are now always points. Use `getArrowBindings(editor, shape)` to check for bindings.
- 💥 **Types renamed**: `ShapeProps` → `RecordProps`, `ShapePropsType` → `RecordPropsType`, `TLShapePropsMigrations` → `TLPropsMigrations`, `SchemaShapeInfo` → `SchemaPropsInfo`.
- Add `editor.blur` method. ([#3875](https://github.com/tldraw/tldraw/pull/3875))
- Add better defaults for `createTLStore`. ([#3886](https://github.com/tldraw/tldraw/pull/3886))
- Add `getSnapshot` and `loadSnapshot` for easier document persistence. See [State Snapshots](https://tldraw.dev/docs/persistence#State-Snapshots). ([#3811](https://github.com/tldraw/tldraw/pull/3811))
- Add `select` option to `Editor.groupShapes` and `Editor.ungroupShapes`. ([#3690](https://github.com/tldraw/tldraw/pull/3690))
- `InFrontOfTheCanvas` now has access to the editor's UI context. ([#3782](https://github.com/tldraw/tldraw/pull/3782))
- `useEditor` and other context-based hooks now throw an error when used out-of-context. ([#3750](https://github.com/tldraw/tldraw/pull/3750))
- Add `defaultShapeSchemas` for custom multiplayer implementations. ([#3613](https://github.com/tldraw/tldraw/pull/3613))

## Improvements

- Add a heart shape to the geo shape set. ([#3787](https://github.com/tldraw/tldraw/pull/3787))
- Improve rendering for bookmarks without preview images. ([#3856](https://github.com/tldraw/tldraw/pull/3856))
- Improve undo/redo UX around image cropping. ([#3891](https://github.com/tldraw/tldraw/pull/3891))
- Increase default limit of shapes per page from 2000 to 4000. ([#3716](https://github.com/tldraw/tldraw/pull/3716))
- Expand accepted image types to include webp, webm, apng, and avif. ([#3730](https://github.com/tldraw/tldraw/pull/3730))
- Prune unused assets when loading `.tldr` files. ([#3689](https://github.com/tldraw/tldraw/pull/3689))
- Improve handling of mouse-type devices that support pressure (e.g., Wacom tablets). ([#3639](https://github.com/tldraw/tldraw/pull/3639))
- Change text shapes to be left-aligned by default. ([#3627](https://github.com/tldraw/tldraw/pull/3627))
- Add Desmos graph embed type. ([#3608](https://github.com/tldraw/tldraw/pull/3608))

## Bug fixes

- Fix 'insert media' undo removing other changes. ([#3910](https://github.com/tldraw/tldraw/pull/3910))
- Fix referrer being sent for bookmarks and images. ([#3881](https://github.com/tldraw/tldraw/pull/3881))
- Fix minimum drag distance being wrong when zoomed. ([#3873](https://github.com/tldraw/tldraw/pull/3873))
- Fix cropped images not exporting properly. ([#3837](https://github.com/tldraw/tldraw/pull/3837))
- Fix spacebar and middle mouse button panning. ([#3791](https://github.com/tldraw/tldraw/pull/3791)) ([#3792](https://github.com/tldraw/tldraw/pull/3792))
- Fix cursor and shapes wiggling when following someone's viewport. ([#3695](https://github.com/tldraw/tldraw/pull/3695))
- Fix cross-browser focus management issues. ([#3718](https://github.com/tldraw/tldraw/pull/3718))
- Fix imports in Astro. ([#3742](https://github.com/tldraw/tldraw/pull/3742))
- Fix copy/paste for patterned shapes as SVG/PNG. ([#3708](https://github.com/tldraw/tldraw/pull/3708))
- Fix RTL text layout for SVG exports. ([#3680](https://github.com/tldraw/tldraw/pull/3680))
- Fix clicking on minimap sometimes not changing viewport. ([#3617](https://github.com/tldraw/tldraw/pull/3617))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.2.0)

---

## Patch releases

### v2.2.1

- Improve documentation and make `ArrowBindingUtil` public. ([#3958](https://github.com/tldraw/tldraw/pull/3958))
- Add `editor.getSnapshot()` and `editor.loadSnapshot()` methods. ([#3958](https://github.com/tldraw/tldraw/pull/3958))
- Fix CSS styling for bookmark elements. ([#3958](https://github.com/tldraw/tldraw/pull/3958))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.2.1)

### v2.2.2

- Fix text measurement breaking when `Tldraw` was used with React strict mode. ([#4004](https://github.com/tldraw/tldraw/pull/4004))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.2.2)

### v2.2.3

- Fix copy/paste functionality in Firefox 127+. ([#4006](https://github.com/tldraw/tldraw/pull/4006))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.2.3)

### v2.2.4

- Fix copy/paste functionality for older versions of Firefox. ([#4011](https://github.com/tldraw/tldraw/pull/4011))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.2.4)

--------

# v2.1.0

This release includes completely redesigned sticky notes, an overhaul to our migration system, and significant performance improvements.

## What's new

### New stickies ([#3249](https://github.com/tldraw/tldraw/pull/3249))

Sticky notes have been completely redesigned with a fresh look and improved functionality.

### 💥 New migrations ([#3220](https://github.com/tldraw/tldraw/pull/3220))

The migrations system has been overhauled for better reliability and developer experience.

- The `Migrations` type is now called `LegacyMigrations`
- The serialized schema format (returned by `StoreSchema.serialize()` and `Store.getSnapshot()`) has changed
- `compareRecordVersions` and `RecordVersion` have been removed
- `compareSchemas` is gone—use `schema.getMigrationsSince(prevSchema)` instead
- `defineMigrations` has been deprecated. See [updating legacy shape migrations](https://tldraw.dev/docs/persistence#Updating-legacy-shape-migrations-defineMigrations) for upgrade instructions
- `migrate` has been removed

### 💥 Input buffering ([#3223](https://github.com/tldraw/tldraw/pull/3223))

Events are now buffered and sent to state nodes every tick, instead of immediately. This unlocks big performance improvements but could introduce subtle issues with custom tools—make sure to test any custom tools thoroughly.

### 💥 React-powered SVG exports ([#3117](https://github.com/tldraw/tldraw/pull/3117))

If any of your shapes implement `toSvg` for exports, you'll need to replace your implementation with a new version that returns JSX instead of manually constructing SVG DOM nodes.

`editor.getSvg` is deprecated. Use `editor.getSvgElement` or `editor.getSvgString` instead.

### 💥 Component-based toolbar customization ([#3067](https://github.com/tldraw/tldraw/pull/3067))

If you're using the `toolbar` callback to override toolbar items, switch to using the new `Toolbar` component override. See the [toolbar groups example](https://tldraw.dev/examples/ui/toolbar-groups) for details.

## API changes

- 💥 **`getRenderingShapes`** no longer returns `isCulled`—use `getCulledShapes` instead.
- Add `Editor.getStyleForNextShape`. ([#3039](https://github.com/tldraw/tldraw/pull/3039))
- Add `usePreloadAssets` export. ([#3545](https://github.com/tldraw/tldraw/pull/3545))

## Improvements

- Improve color contrast. ([#3486](https://github.com/tldraw/tldraw/pull/3486))
- Add long press event. ([#3275](https://github.com/tldraw/tldraw/pull/3275))
- Add severity colors and icons to toasts. ([#2988](https://github.com/tldraw/tldraw/pull/2988))
- Improve handling of broken images/videos. ([#2990](https://github.com/tldraw/tldraw/pull/2990))
- Improve performance of draw shapes. ([#3464](https://github.com/tldraw/tldraw/pull/3464))
- Use WebGL to draw the minimap. ([#3510](https://github.com/tldraw/tldraw/pull/3510))
- Improve reactivity bookkeeping performance. ([#3471](https://github.com/tldraw/tldraw/pull/3471)) ([#3487](https://github.com/tldraw/tldraw/pull/3487))
- Improve selection/erasing performance. ([#3454](https://github.com/tldraw/tldraw/pull/3454))
- Improve performance of text shapes on iOS/Safari. ([#3429](https://github.com/tldraw/tldraw/pull/3429))
- Reduce rendered DOM nodes for geo shapes and arrows. ([#3283](https://github.com/tldraw/tldraw/pull/3283))
- Improve shape rendering performance. ([#3176](https://github.com/tldraw/tldraw/pull/3176))

## Bug fixes

- Fix copy error sound in Safari. ([#3536](https://github.com/tldraw/tldraw/pull/3536))
- Fix arrow label positioning overlapping bound shapes. ([#3512](https://github.com/tldraw/tldraw/pull/3512))
- Fix cursor chat button appearing when not in select tool. ([#3485](https://github.com/tldraw/tldraw/pull/3485))
- Fix alt-duplicating shapes sometimes not working. ([#3488](https://github.com/tldraw/tldraw/pull/3488))
- Fix camera sliding after pinch. ([#3462](https://github.com/tldraw/tldraw/pull/3462))
- Fix text shapes overflowing their bounds when resized. ([#3327](https://github.com/tldraw/tldraw/pull/3327))
- Fix incorrectly rotated handles on rotated cropping images. ([#3093](https://github.com/tldraw/tldraw/pull/3093))
- Fix videos not being sized correctly. ([#3047](https://github.com/tldraw/tldraw/pull/3047))
- Fix `localStorage` crash in React Native webviews. ([#3043](https://github.com/tldraw/tldraw/pull/3043))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.1.0)

---

## Patch releases

### v2.1.1

- Fix missing export for `createShapePropsMigrationIds`, part of the new migrations API. ([#3594](https://github.com/tldraw/tldraw/pull/3594))
- Add exports for `defaultEditorAssetUrls`, `PORTRAIT_BREAKPOINT`, `useDefaultColorTheme`, and `getPerfectDashProps`. ([#3594](https://github.com/tldraw/tldraw/pull/3594))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.1.1)

### v2.1.2

- Revert a performance optimization that caused computed caches to sometimes not invalidate correctly, leading to stale data and crashes. ([#3611](https://github.com/tldraw/tldraw/pull/3611))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.1.2)

### v2.1.3

- Expose migrations, validators, and versions from tlschema. ([#3613](https://github.com/tldraw/tldraw/pull/3613))
- Add `defaultShapeSchemas` which can be passed directly to `createTLSchema`. ([#3613](https://github.com/tldraw/tldraw/pull/3613))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.1.3)

### v2.1.4

- Fix text selection flakiness when clicking into text shapes. ([#3643](https://github.com/tldraw/tldraw/pull/3643))
- Fix edit→edit not working correctly when unfilled geo shapes are on top of other shapes. ([#3643](https://github.com/tldraw/tldraw/pull/3643))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.1.4)

--------

# v2.0.0

This is the initial public release of the tldraw SDK—a TypeScript library for creating infinite canvas experiences in React. After an extensive alpha and beta period, the SDK is ready for production use.

## What's new

### The editor

At the heart of tldraw is the `Editor` class, a single object that manages all editor state and provides the API for programmatic control. The editor maintains document state through a reactive store system containing JSON-serializable records.

```tsx
import { Tldraw } from 'tldraw'

function App() {
	return (
		<Tldraw
			onMount={(editor) => {
				// Full programmatic control
				editor.createShapes([{ type: 'geo', x: 100, y: 100 }])
				editor.selectAll()
				editor.zoomToFit()
			}}
		/>
	)
}
```

### Default shapes

The SDK ships with a complete set of default shapes:

- **Geo shapes**: Rectangle, ellipse, triangle, diamond, pentagon, hexagon, octagon, star, rhombus, oval, trapezoid, arrow-shapes, cloud, and x-box
- **Draw**: Freehand drawing with pressure sensitivity support
- **Arrow**: Connectable arrows with labels, multiple arrowhead styles, and curved/straight/elbow routing
- **Text**: Rich text with font, size, and alignment options
- **Note**: Sticky notes with customizable colors
- **Image & Video**: Media embedding with cropping support
- **Frame**: Grouping containers that clip their contents
- **Line**: Multi-point lines with various spline options
- **Highlight**: Transparent highlight strokes
- **Embed**: Web content embedding (YouTube, Figma, Google Maps, and more)
- **Bookmark**: URL previews with metadata

### Default tools

A full set of tools for interacting with the canvas:

- **Select**: Selection, multi-select, resize, rotate, and transform shapes
- **Hand**: Pan the canvas
- **Draw**: Freehand drawing
- **Eraser**: Remove shapes by drawing over them
- **Arrow, Line, Geo, Text, Note, Frame, Highlight**: Shape creation tools
- **Laser**: Temporary pointer for presentations
- **Zoom**: Zoom in/out with click or marquee

### State management

The SDK uses a reactive signals system for state management. All editor state is observable, with automatic dependency tracking to prevent unnecessary re-renders.

```tsx
import { track, useEditor } from 'tldraw'

const SelectedShapeCount = track(() => {
	const editor = useEditor()
	return <div>{editor.getSelectedShapeIds().length} selected</div>
})
```

### The store

Document data lives in a `TLStore`—a reactive client-side database that supports:

- JSON-serializable records for shapes, pages, assets, and instance state
- Reactive updates via signals
- Snapshot export/import for persistence
- Schema migrations for backwards compatibility

### Tool system

Tools are implemented as hierarchical state machines using `StateNode`. Events flow through a state chart, enabling complex multi-step interactions:

```tsx
class MyTool extends StateNode {
	static id = 'my-tool'

	onPointerDown(info) {
		const point = this.editor.inputs.currentPagePoint
		this.editor.createShape({ type: 'geo', x: point.x, y: point.y })
	}
}
```

### Shape system

Every shape type has a `ShapeUtil` class defining its behavior—geometry, rendering, interactions, and more. Create custom shapes by extending `ShapeUtil`:

```tsx
class CardShapeUtil extends ShapeUtil<CardShape> {
	static type = 'card'

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

	component(shape) {
		return <div className="card">{shape.props.title}</div>
	}
}
```

### User interface

A complete, responsive UI system with:

- Toolbar with tool selection and shape-specific options
- Style panel for colors, fills, fonts, and more
- Context menus with shape actions
- Keyboard shortcuts dialog
- Page management
- Zoom controls and minimap
- Actions menu and quick actions bar
- Help menu and debug panel

All UI components can be overridden or extended via the `components` prop.

### Features

- **Multi-page documents**: Create and manage multiple pages per document
- **Undo/redo**: Full history management with marks and batching
- **Copy/paste**: Between pages, documents, and external applications
- **Export**: SVG, PNG, and JSON export
- **Zoom & pan**: Pinch, scroll, keyboard shortcuts, and programmatic control
- **Grid & snapping**: Align shapes to grid and each other
- **Grouping**: Group shapes together
- **Locking**: Prevent shape modification
- **Duplication**: Alt-drag to duplicate
- **Alignment & distribution**: Align and distribute selected shapes
- **Flip**: Horizontal and vertical flipping
- **Styles**: Color, fill, dash, size, font, and more
- **Dark mode**: Full dark mode support
- **Localization**: 30+ languages supported
- **Accessibility**: Keyboard navigation and screen reader support
- **Touch support**: Full touch and pen input support
- **Pressure sensitivity**: For supported devices

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.0.0)

---

## Patch releases

### v2.0.1

- Avoid randomness at init time, improving consistency for SSR and testing scenarios. ([#3076](https://github.com/tldraw/tldraw/pull/3076))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.0.1)

### v2.0.2

- Fix JPG export functionality. ([#3199](https://github.com/tldraw/tldraw/pull/3199))

[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v2.0.2)

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

# tldraw SDK Examples

--------

# Tldraw component

Category: Getting started

Keywords: basic, getting started, intro, simple, quick start, hello world, installation, first app, tldraw component

The simplest way to use the `Tldraw` component.

The `Tldraw` component renders the full tldraw editor as a regular React component. Put it anywhere in your React tree; it fills whatever container it's given, so the container needs a size. Here `.tldraw__editor` makes it fill the page.

Import `tldraw/tldraw.css` alongside the component. Without it, the editor's UI has no styling.

By default the editor does not persist between refreshes or sync between tabs. To keep your work after a refresh, see the [persistence key example](https://tldraw.dev/examples/persistence-key).

## App.tsx

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

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

--------

# Editor options

Category: Configuration

Keywords: options, configuration, pages, animation, camera

Override editor options like the maximum number of pages and animation duration.

The `options` prop on `Tldraw` takes a `Partial<TldrawOptions>` and overrides tldraw's defaults; anything you leave out keeps its default value. Options are read once when the editor is created, so define the object outside the component (or memoize it) rather than creating a new one on every render.

This example limits documents to 3 pages and sets `animationMediumMs` to 5 seconds. Try opening the page menu and adding pages: the "create page" button disables after the third. Then zoom in or out from the zoom menu and watch the (very) slow animation.

## App.tsx

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

const options: Partial<TldrawOptions> = {
	maxPages: 3,
	animationMediumMs: 5000,
}

export default function CustomOptionsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="custom-options-example" options={options} />
		</div>
	)
}
```

--------

# Shape options

Category: Configuration

Keywords: configure, shapeutil, shape options, noteshapeoptions, frameshapeoptions, builtin shapes, customization

Change the behavior of built-in shapes with `ShapeUtil.configure`.

Several built-in shape utils expose an `options` object. `ShapeUtil.configure(options)` returns a subclass of the util with those options overridden, and passing that subclass in the `shapeUtils` prop replaces the default one.

You can find a shape's options in the `options` property of its util, for example [`NoteShapeOptions`](https://tldraw.dev/reference/tldraw/NoteShapeOptions) and [`FrameShapeOptions`](https://tldraw.dev/reference/tldraw/FrameShapeOptions). Here notes get `resizeMode: 'scale'` so they can be resized by dragging a handle, and frames get `showColors: true` so the color style applies to them.

Try creating a note (N) and dragging a corner handle, or a frame (F) and changing its color in the style panel.

## App.tsx

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

const shapeUtils = [
	FrameShapeUtil.configure({ showColors: true }),
	NoteShapeUtil.configure({ resizeMode: 'scale' }),
]

export default function ConfigureShapeUtilExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw shapeUtils={shapeUtils} />
		</div>
	)
}
```

--------

# Camera options

Category: Configuration

Keywords: camera, cameraoptions, zoom constraints, pan constraints, camera bounds, zoom speed, pan speed, viewport, isfixed

Configure the camera's constraints, zoom steps, and wheel behavior, and change them live.

The `Tldraw` component takes its initial camera configuration from `options={{ camera: { ... } }}`, a `TLCameraOptions` object. It controls whether the camera is locked, what the mouse wheel does, pan and zoom speed, the zoom steps, and (optionally) constraints that keep the camera inside a bounded area with a chosen fit behavior, padding, and origin.

The control panel in this example changes the options at runtime with `editor.setCameraOptions()` so you can see the effect of each setting. The dashed rectangle on the canvas is the constraint bounds; the dotted rectangle in front of the canvas is the padding.

Try switching bounds between "A4 page" and "landscape", then change behavior from `contain` to `inside` or `outside` and pan around. "Reset camera" re-fits the camera to the current constraints; "Reset camera options" restores the defaults.

## App.tsx

```tsx
import { useEffect } from 'react'
import {
	BoxModel,
	TLCameraOptions,
	Tldraw,
	Vec,
	clamp,
	track,
	useEditor,
	useLocalStorageState,
} from 'tldraw'
import 'tldraw/tldraw.css'

const CAMERA_OPTIONS: TLCameraOptions = {
	isLocked: false,
	wheelBehavior: 'pan',
	panSpeed: 1,
	zoomSpeed: 1,
	zoomSteps: [0.1, 0.25, 0.5, 1, 2, 4, 8],
	constraints: {
		initialZoom: 'fit-max',
		baseZoom: 'fit-max',
		bounds: {
			x: 0,
			y: 0,
			w: 1600,
			h: 900,
		},
		behavior: { x: 'contain', y: 'contain' },
		padding: { x: 100, y: 100 },
		origin: { x: 0.5, y: 0.5 },
	},
}

const BOUNDS_SIZES: Record<string, BoxModel> = {
	a4: { x: 0, y: 0, w: 1050, h: 1485 },
	landscape: { x: 0, y: 0, w: 1600, h: 900 },
	portrait: { x: 0, y: 0, w: 900, h: 1600 },
	square: { x: 0, y: 0, w: 900, h: 900 },
}

export default function CameraOptionsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw components={components} options={{ camera: CAMERA_OPTIONS }}>
				<CameraOptionsControlPanel />
			</Tldraw>
		</div>
	)
}

const PaddingDisplay = track(() => {
	const editor = useEditor()
	const cameraOptions = editor.getCameraOptions()

	if (!cameraOptions.constraints) return null

	const {
		constraints: {
			padding: { x: px, y: py },
		},
	} = cameraOptions

	return (
		<div
			style={{
				position: 'absolute',
				top: py,
				left: px,
				width: `calc(100% - ${px * 2}px)`,
				height: `calc(100% - ${py * 2}px)`,
				border: '1px dotted var(--tl-color-text)',
				pointerEvents: 'none',
			}}
		/>
	)
})

const BoundsDisplay = track(() => {
	const editor = useEditor()
	const cameraOptions = editor.getCameraOptions()

	if (!cameraOptions.constraints) return null

	const {
		constraints: {
			bounds: { x, y, w, h },
		},
	} = cameraOptions

	const d = Vec.ToAngle({ x: w, y: h }) * (180 / Math.PI)
	const colB = '#00000002'
	const colA = '#0000001F'

	return (
		<>
			<div
				style={{
					position: 'absolute',
					top: y,
					left: x,
					width: w,
					height: h,
					border: '1px dashed var(--tl-color-text)',
				}}
			>
				{/* grey and white stripes */}
				<div
					style={{
						position: 'absolute',
						top: 0,
						left: 0,
						width: '100%',
						height: '100%',
						backgroundImage: `
						linear-gradient(0deg, ${colB} 0%, ${colA} 50%, ${colB} 50%, ${colA} 100%),
						linear-gradient(90deg, ${colB} 0%, ${colA} 50%, ${colB} 50%, ${colA} 100%),
						linear-gradient(${d}deg, ${colB} 0%, ${colA} 50%, ${colB} 50%, ${colA} 100%),
						linear-gradient(-${d}deg, ${colB} 0%, ${colA} 50%, ${colB} 50%, ${colA} 100%)`,
					}}
				></div>
			</div>
		</>
	)
})

// [1]
const components = {
	OnTheCanvas: BoundsDisplay,
	InFrontOfTheCanvas: PaddingDisplay,
}

const CameraOptionsControlPanel = track(() => {
	const editor = useEditor()

	// [2]
	const [cameraOptions, setCameraOptions] = useLocalStorageState('camera ex1', CAMERA_OPTIONS)

	// [3]
	useEffect(() => {
		editor.run(() => {
			editor.setCameraOptions(cameraOptions)
			editor.setCamera(editor.getCamera(), {
				immediate: true,
			})
		})
	}, [editor, cameraOptions])

	const { constraints } = cameraOptions

	const updateOptions = (
		options: Partial<
			Omit<TLCameraOptions, 'constraints'> & {
				constraints: Partial<TLCameraOptions['constraints']>
			}
		>
	) => {
		const { constraints } = options
		const cameraOptions = editor.getCameraOptions()
		setCameraOptions({
			...cameraOptions,
			...options,
			constraints:
				constraints === undefined
					? cameraOptions.constraints
					: {
							...(cameraOptions.constraints! ?? CAMERA_OPTIONS.constraints),
							...constraints,
						},
		})
	}

	return (
		<div
			style={{
				pointerEvents: 'all',
				position: 'absolute',
				top: 50,
				left: 0,
				padding: 4,
				background: 'white',
				zIndex: 100,
			}}
		>
			<div
				style={{
					display: 'grid',
					gridTemplateColumns: 'auto 1fr',
					columnGap: 12,
					rowGap: 4,
					marginBottom: 12,
					alignItems: 'center',
					justifyContent: 'center',
				}}
			>
				<label htmlFor="lock">Lock</label>
				<select
					name="lock"
					value={cameraOptions.isLocked ? 'true' : 'false'}
					onChange={(e) => {
						const value = e.target.value
						updateOptions({
							...CAMERA_OPTIONS,
							isLocked: value === 'true',
						})
					}}
				>
					<option value="true">true</option>
					<option value="false">false</option>
				</select>
				<label htmlFor="wheelBehavior">Wheel behavior</label>
				<select
					name="wheelBehavior"
					value={cameraOptions.wheelBehavior}
					onChange={(e) => {
						const value = e.target.value
						updateOptions({
							...CAMERA_OPTIONS,
							wheelBehavior: value as TLCameraOptions['wheelBehavior'],
						})
					}}
				>
					<option>zoom</option>
					<option>pan</option>
					<option>none</option>
				</select>
				<label htmlFor="panspeed">Pan speed</label>
				<input
					name="panspeed"
					type="number"
					step={0.1}
					value={cameraOptions.panSpeed}
					onChange={(e) => {
						const val = clamp(Number(e.target.value), 0, 2)
						updateOptions({ panSpeed: val })
					}}
				/>
				<label htmlFor="zoomspeed">Zoom speed</label>
				<input
					name="zoomspeed"
					type="number"
					step={0.1}
					value={cameraOptions.zoomSpeed}
					onChange={(e) => {
						const val = clamp(Number(e.target.value), 0, 2)
						updateOptions({ zoomSpeed: val })
					}}
				/>
				<label htmlFor="zoomsteps">Zoom steps</label>
				<input
					name="zoomsteps"
					type="text"
					defaultValue={cameraOptions.zoomSteps.join(', ')}
					onChange={(e) => {
						try {
							const val = e.target.value.split(', ').map((v) => Number(v))
							if (val.every((v) => typeof v === 'number' && Number.isFinite(v))) {
								updateOptions({ zoomSteps: val })
							}
						} catch {
							// ignore
						}
					}}
				/>
				<label htmlFor="bounds">Bounds</label>
				<select
					name="bounds"
					value={
						Object.entries(BOUNDS_SIZES).find(([_, b]) => b.w === constraints?.bounds.w)?.[0] ??
						'none'
					}
					onChange={(e) => {
						const currentConstraints = constraints ?? CAMERA_OPTIONS.constraints
						const value = e.target.value

						if (value === 'none') {
							updateOptions({
								...CAMERA_OPTIONS,
								constraints: undefined,
							})
							return
						}

						updateOptions({
							...CAMERA_OPTIONS,
							constraints: {
								...currentConstraints,
								bounds: BOUNDS_SIZES[value] ?? BOUNDS_SIZES.a4,
							},
						})
					}}
				>
					<option value="none">none</option>
					<option value="a4">A4 page</option>
					<option value="portrait">Portrait</option>
					<option value="landscape">Landscape</option>
					<option value="square">Square</option>
				</select>
				{constraints ? (
					<>
						<label htmlFor="initialZoom">Initial zoom</label>
						<select
							name="initialZoom"
							value={constraints.initialZoom}
							onChange={(e) => {
								updateOptions({
									constraints: {
										...constraints,
										initialZoom: e.target.value as any,
									},
								})
							}}
						>
							<option>fit-min</option>
							<option>fit-max</option>
							<option>fit-x</option>
							<option>fit-y</option>
							<option>fit-min-100</option>
							<option>fit-max-100</option>
							<option>fit-x-100</option>
							<option>fit-y-100</option>
							<option>default</option>
						</select>
						<label htmlFor="zoomBehavior">Base zoom</label>
						<select
							name="zoomBehavior"
							value={constraints.baseZoom}
							onChange={(e) => {
								updateOptions({
									constraints: {
										...constraints,
										baseZoom: e.target.value as any,
									},
								})
							}}
						>
							<option>fit-min</option>
							<option>fit-max</option>
							<option>fit-x</option>
							<option>fit-y</option>
							<option>fit-min-100</option>
							<option>fit-max-100</option>
							<option>fit-x-100</option>
							<option>fit-y-100</option>
							<option>default</option>
						</select>
						<label htmlFor="originX">Origin x</label>
						<input
							name="originX"
							type="number"
							step={0.1}
							value={constraints.origin.x}
							onChange={(e) => {
								const val = clamp(Number(e.target.value), 0, 1)
								updateOptions({
									constraints: {
										origin: {
											...constraints.origin,
											x: val,
										},
									},
								})
							}}
						/>
						<label htmlFor="originY">Origin y</label>
						<input
							name="originY"
							type="number"
							step={0.1}
							value={constraints.origin.y}
							onChange={(e) => {
								const val = clamp(Number(e.target.value), 0, 1)
								updateOptions({
									constraints: {
										...constraints,
										origin: {
											...constraints.origin,
											y: val,
										},
									},
								})
							}}
						/>
						<label htmlFor="paddingX">Padding x</label>
						<input
							name="paddingX"
							type="number"
							step={10}
							value={constraints.padding.x}
							onChange={(e) => {
								const val = clamp(Number(e.target.value), 0)
								updateOptions({
									constraints: {
										...constraints,
										padding: {
											...constraints.padding,
											x: val,
										},
									},
								})
							}}
						/>
						<label htmlFor="paddingY">Padding y</label>
						<input
							name="paddingY"
							type="number"
							step={10}
							value={constraints.padding.y}
							onChange={(e) => {
								const val = clamp(Number(e.target.value), 0)
								updateOptions({
									constraints: {
										padding: {
											...constraints.padding,
											y: val,
										},
									},
								})
							}}
						/>
						<label htmlFor="behaviorX">Behavior x</label>
						<select
							name="behaviorX"
							value={(constraints.behavior as { x: any; y: any }).x}
							onChange={(e) => {
								setCameraOptions({
									...cameraOptions,
									constraints: {
										...constraints,
										behavior: {
											...(constraints.behavior as { x: any; y: any }),
											x: e.target.value as any,
										},
									},
								})
							}}
						>
							<option>free</option>
							<option>contain</option>
							<option>inside</option>
							<option>outside</option>
							<option>fixed</option>
						</select>
						<label htmlFor="behaviorY">Behavior y</label>
						<select
							name="behaviorY"
							value={(constraints.behavior as { x: any; y: any }).y}
							onChange={(e) => {
								setCameraOptions({
									...cameraOptions,
									constraints: {
										...constraints,
										behavior: {
											...(constraints.behavior as { x: any; y: any }),
											y: e.target.value as any,
										},
									},
								})
							}}
						>
							<option>free</option>
							<option>contain</option>
							<option>inside</option>
							<option>outside</option>
							<option>fixed</option>
						</select>
					</>
				) : null}
			</div>
			<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
				<button
					onClick={() => {
						editor.setCamera(editor.getCamera(), { reset: true })
					}}
				>
					Reset camera
				</button>
				<button
					onClick={() => {
						updateOptions(CAMERA_OPTIONS)
					}}
				>
					Reset camera options
				</button>
			</div>
		</div>
	)
})

/*
[1]
These two components are only there to visualize the configuration: BoundsDisplay draws the
constraint bounds in page space (OnTheCanvas), and PaddingDisplay draws the padding inset in
screen space (InFrontOfTheCanvas). Neither is needed to make constraints work.

[2]
The panel's options are kept in local storage so they survive a refresh, and so the panel,
not the initial `options.camera`, is the source of truth once it has mounted.

[3]
`editor.setCameraOptions()` updates the options at runtime and re-applies the constraints to
the current camera. We follow it with `setCamera(getCamera(), { immediate: true })` so the
camera snaps to its new constrained position instead of animating there. Wrapping both in
`editor.run()` keeps them in one transaction.
*/
```

--------

# Asset options

Category: Configuration

Keywords: assets, images, videos, upload, acceptedimagetypes, acceptedvideotypes, maxassetsize, maximagesize, maximagedimension

Restrict which images and videos can be added to the canvas.

The `Tldraw` component has props that control which assets it accepts when files are dropped, pasted, or uploaded:

- `acceptedImageMimeTypes` and `acceptedVideoMimeTypes` filter by file type. Here only JPEGs are allowed and videos are turned off entirely.
- `maxAssetSize` caps the file size in bytes (1 MB here).
- `maxImageDimension` limits an image's width or height in pixels; larger images are scaled down on import. `Infinity` disables the limit.

Try dropping a PNG or a video onto the canvas: it is rejected with a toast. A JPEG under 1 MB is accepted.

## App.tsx

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

export default function AssetPropsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// only allow jpegs
				acceptedImageMimeTypes={['image/jpeg']}
				// don't allow any videos
				acceptedVideoMimeTypes={[]}
				// accept images of any dimension
				maxImageDimension={Infinity}
				// ...but only accept assets up to 1mb
				maxAssetSize={1 * 1024 * 1024}
			/>
		</div>
	)
}
```

--------

# Custom text outline

Category: Configuration

Keywords: text, outline, showTextOutline, configure, TextShapeUtil, ArrowShapeUtil, GeoShapeUtil, label, performance, styling

Disable the text outline on text, arrow, and geo shape labels.

By default tldraw draws a halo in the canvas background color around text labels so they stay legible when they overlap other shapes. Each shape util that renders text (`TextShapeUtil`, `ArrowShapeUtil`, `GeoShapeUtil`) has a `showTextOutline` option; this example sets it to `false` on all three with `ShapeUtil.configure`.

The canvas starts with three overlapping text shapes and a labeled arrow so you can see the difference. Try changing `showTextOutline` back to `true` for one of the utils and compare.

You might turn outlines off for a different visual style, or for performance: the outline is drawn with a text shadow, which can be expensive on some browsers (tldraw already skips it on Safari).

## App.tsx

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

// [1]
const shapeUtils = [
	ArrowShapeUtil.configure({ showTextOutline: false }),
	TextShapeUtil.configure({ showTextOutline: false }),
	GeoShapeUtil.configure({ showTextOutline: false }),
]

export default function CustomTextOutlineExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				persistenceKey="custom-text-outline-example"
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size > 0) return

					// [2]
					const message = toRichText('very good whiteboard')
					editor.createShapes([
						{ type: 'text', x: 100, y: 100, props: { richText: message } },
						{ type: 'text', x: 110, y: 110, props: { richText: message } },
						{ type: 'text', x: 120, y: 120, props: { richText: message } },
						{
							type: 'arrow',
							x: 0,
							y: 0,
							props: {
								richText: toRichText('hello world'),
								start: { x: 0, y: 0 },
								end: { x: 200, y: 200 },
							},
						},
					])
				}}
			/>
		</div>
	)
}

/*
[1]
Text outlines are an option on each shape util that renders text labels, so each one has to
be configured separately. Passing the configured utils in `shapeUtils` replaces the defaults.

[2]
Overlapping text shapes and an arrow with a label. With outlines on, each label would get a
halo in the background color that separates it from the text behind it; here they run together.
*/
```

--------

# Display options

Category: Configuration

Keywords: display, values, override, configure, colors, fonts, customize

Override the colors, fonts, and stroke widths a shape renders with, without changing its props.

Built-in shape utils compute a set of display values (stroke color, fill color, label font, stroke width, and so on) from a shape's style props each time the shape renders. The `getCustomDisplayValues` option lets you override any of them: return a partial object and it is merged over the defaults.

This example configures `GeoShapeUtil` so that locked shapes are filled red, ellipses use a monospace label, and every geo shape has a 10px stroke. Try locking the rectangle (select it, then use the context menu) to see the fill change, or change the size style and notice that the stroke width stays the same.

Because display values are computed at render time, they don't touch the document: unlocking the shape or opening the file elsewhere shows the normal styles.

## App.tsx

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

// [1]
const shapeUtils = [
	GeoShapeUtil.configure({
		getCustomDisplayValues(editor, shape): Partial<GeoShapeUtilDisplayValues> {
			const values: Partial<GeoShapeUtilDisplayValues> = {}

			// [2]
			if (shape.isLocked) {
				const colors = editor.getCurrentTheme().colors[editor.getColorMode()]
				values.fillColor = colors.red.solid
			}

			if (shape.props.geo === 'ellipse') {
				values.labelFontFamily = 'monospace'
			}

			values.strokeWidth = 10
			return values
		},
	}),
]

export default function DisplayOptionsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				onMount={(editor) => {
					editor.createShapes([
						{
							type: 'geo',
							x: 100,
							y: 100,
							props: {
								w: 200,
								h: 100,
								geo: 'rectangle',
								fill: 'solid',
								richText: toRichText('Rectangle'),
							},
						},
						{
							type: 'geo',
							x: 400,
							y: 100,
							props: {
								w: 200,
								h: 200,
								geo: 'ellipse',
								richText: toRichText('Ellipse'),
							},
						},
					])
					editor.zoomToFit({ animation: { duration: 0 } })
					editor.zoomOut()
				}}
			/>
		</div>
	)
}

/*
[1]
`getCustomDisplayValues` runs every time a geo shape renders, after the default display values
have been computed from the shape's style props. Whatever it returns is merged on top, so you
only need to return the values you want to change. Passing the configured util in `shapeUtils`
replaces the default GeoShapeUtil.

[2]
Display values can depend on anything about the shape, not just its props. Locked shapes get a
red fill; ellipses get a monospace label; every geo shape gets a 10px stroke regardless
of its size style.
*/
```

--------

# Edge scrolling

Category: Configuration

Keywords: scroll, edge, auto-scroll, drag, edge scroll manager, options, camera

Configure how the camera auto-scrolls when dragging near the viewport edge.

Edge scrolling automatically pans the camera when you drag a shape or selection brush close to the edge of the viewport. This example provides sliders for the four options that control it, passed through the `Tldraw` component's `options` prop:

- `edgeScrollSpeed`: base scroll speed in pixels per tick (default 25)
- `edgeScrollDelay`: how long the pointer must linger near the edge before scrolling starts (default 200ms)
- `edgeScrollEaseDuration`: how long the scroll takes to accelerate to full speed (default 200ms)
- `edgeScrollDistance`: the width of the edge zone that triggers scrolling (default 8px)

Drag one of the shapes toward a window edge to feel the current settings, then adjust the sliders and try again. The sliders commit on release because editor options are read when the editor is created: changing the `options` prop recreates the editor instance.

## App.tsx

```tsx
import { useState } from 'react'
import { Editor, TLGeoShape, Tldraw, toRichText } from 'tldraw'
import 'tldraw/tldraw.css'
import './edge-scrolling.css'

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

// [1]
interface EdgeScrollValues {
	edgeScrollSpeed: number
	edgeScrollDelay: number
	edgeScrollEaseDuration: number
	edgeScrollDistance: number
}

const DEFAULTS: EdgeScrollValues = {
	edgeScrollSpeed: 25,
	edgeScrollDelay: 200,
	edgeScrollEaseDuration: 200,
	edgeScrollDistance: 8,
}

const CONTROLS = [
	{ key: 'edgeScrollSpeed', label: 'Speed (px per tick)', min: 0, max: 100, step: 5 },
	{ key: 'edgeScrollDelay', label: 'Delay (ms)', min: 0, max: 1000, step: 50 },
	{ key: 'edgeScrollEaseDuration', label: 'Ease duration (ms)', min: 0, max: 1000, step: 50 },
	{ key: 'edgeScrollDistance', label: 'Edge zone size (px)', min: 0, max: 240, step: 8 },
] as const

// [2]
function ControlsPanel({
	values,
	onCommit,
}: {
	values: EdgeScrollValues
	onCommit(next: EdgeScrollValues): void
}) {
	const [pending, setPending] = useState(values)

	return (
		<div className="edge-scrolling__panel">
			<div className="edge-scrolling__title">Edge scrolling options</div>
			{CONTROLS.map((control) => {
				// read the slider's value from the DOM at commit time so the commit
				// can't lag behind the last change event
				const commit = (input: HTMLInputElement) =>
					onCommit({ ...pending, [control.key]: Number(input.value) })

				return (
					<label key={control.key} className="edge-scrolling__row">
						<span>
							{control.label}: <b>{pending[control.key]}</b>
						</span>
						<input
							type="range"
							min={control.min}
							max={control.max}
							step={control.step}
							value={pending[control.key]}
							onChange={(e) =>
								setPending({ ...pending, [control.key]: Number(e.currentTarget.value) })
							}
							onPointerUp={(e) => commit(e.currentTarget)}
							onKeyUp={(e) => commit(e.currentTarget)}
							onBlur={(e) => commit(e.currentTarget)}
						/>
					</label>
				)
			})}
			<button
				className="edge-scrolling__reset"
				onClick={() => {
					setPending(DEFAULTS)
					onCommit(DEFAULTS)
				}}
			>
				Reset to defaults
			</button>
		</div>
	)
}

function createDemoShapes(editor: Editor) {
	// changing the options prop recreates the editor but keeps the store, so
	// only create the demo shapes on the first mount
	if (editor.getCurrentPageShapeIds().size > 0) return

	editor.createShape({
		type: 'text',
		x: 120,
		y: 80,
		props: {
			richText: toRichText('Drag a shape toward the edge of the window to edge scroll'),
		},
	})
	const colors = ['blue', 'orange', 'green'] as const
	colors.forEach((color, i) => {
		editor.createShape<TLGeoShape>({
			type: 'geo',
			x: 150 + i * 220,
			y: 200,
			props: { w: 140, h: 140, fill: 'solid', color },
		})
	})
}

export default function EdgeScrollingExample() {
	const [values, setValues] = useState(DEFAULTS)

	return (
		<div className="tldraw__editor edge-scrolling">
			{/* [3] */}
			<Tldraw options={values} onMount={createDemoShapes} />
			<ControlsPanel values={values} onCommit={setValues} />
		</div>
	)
}

/*
[1]
Edge scrolling is configured through four editor options:

- edgeScrollSpeed: the base scroll speed in pixels per tick (default 25).
  The speed also scales with how close the pointer is to the edge, and is
  reduced on small screens.
- edgeScrollDelay: how long (ms) the pointer must stay near the edge before
  scrolling starts (default 200). Raising it prevents accidental scrolls.
- edgeScrollEaseDuration: how long (ms) the scroll takes to accelerate from
  zero to full speed once it starts (default 200).
- edgeScrollDistance: the width in pixels of the edge zone that triggers
  scrolling (default 8). Pointer positions outside the window scroll at full
  speed. Try a large zone (200+): since you grab a shape near its middle,
  scrolling then kicks in as soon as the shape itself touches the window
  edge, rather than waiting for the pointer to get there.

[2]
The sliders commit when you release them rather than while you drag.
That's because editor options are read once when the editor instance is
created: changing the options prop tears down and recreates the editor, so
we don't want to do it dozens of times per second mid-drag. Commits fire on
pointer release, key release (so keyboard adjustment works too), and blur —
re-committing an unchanged value is harmless, since the Tldraw component
shallow-compares its options.

[3]
Options are passed via the Tldraw component's options prop. Any option from
TldrawOptions can be overridden this way; unspecified options keep their
defaults.
*/
```

## edge-scrolling.css

```css
/* This panel lives outside the tldraw container, so the theme variables
   aren't inherited here — each use provides a fallback value. */
.edge-scrolling__panel {
	position: absolute;
	bottom: 80px;
	left: 8px;
	z-index: var(--tl-layer-panels, 300);
	display: flex;
	flex-direction: column;
	gap: 8px;
	width: 240px;
	padding: 12px;
	border-radius: 8px;
	background: var(--tl-color-panel, #fcfcfc);
	box-shadow: var(--tl-shadow-2, 0 1px 3px rgba(0, 0, 0, 0.2));
}

.edge-scrolling__title {
	font-size: 12px;
	font-weight: 600;
	color: var(--tl-color-text-1, #2e2e2e);
}

.edge-scrolling__row {
	display: flex;
	flex-direction: column;
	gap: 2px;
	font-size: 11px;
	color: var(--tl-color-text-1, #2e2e2e);
}

.edge-scrolling__reset {
	margin-top: 4px;
	padding: 4px 8px;
	border: 1px solid var(--tl-color-muted-1, rgba(0, 0, 0, 0.1));
	border-radius: 6px;
	background: var(--tl-color-panel, #fcfcfc);
	font-size: 11px;
	cursor: pointer;
}

.edge-scrolling__reset:hover {
	background: var(--tl-color-muted-2, rgba(0, 0, 0, 0.043));
}
```

--------

# Persistence key

Category: Configuration

Keywords: persistence, local storage, save state, persistencekey, indexeddb, session storage, auto save

Save the document in the browser and sync it between tabs with `persistenceKey`.

Pass a `persistenceKey` to the `Tldraw` component and it stores the document in IndexedDB under that key, restores it on the next load, and keeps other tabs with the same key in sync via a broadcast channel.

Draw something, refresh the page, and it's still there. Open this page in a second tab and changes appear in both. Different keys are independent documents, so use a key per document (for example a document id) rather than one per app.

If you need to persist somewhere other than the browser, see the sync and snapshot examples instead.

## App.tsx

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

export default function PersistenceKeyExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="persistence-key-example" />
		</div>
	)
}
```

--------

# Read-only

Category: Configuration

Keywords: readonly, read-only mode, isreadonly, view only, disable editing, presentation mode, locked editor

Put the editor in read-only mode so the document can be viewed but not changed.

Read-only mode is an instance state flag: `editor.updateInstanceState({ isReadonly: true })`. This example sets it in `onMount`. When it's on, editing tools disappear from the toolbar (only select, hand, and laser pointer remain), editing commands like delete and paste are ignored, and shapes can't be moved or resized. You can still pan, zoom, select, and use the laser pointer.

Because it's instance state rather than document state, it can be toggled at runtime, for example when a user's permissions change. Read it back with `editor.getIsReadonly()`.

## App.tsx

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

export default function ReadOnlyExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="readonly-example"
				onMount={(editor) => {
					editor.updateInstanceState({ isReadonly: true })
				}}
			/>
		</div>
	)
}
```

--------

# Reduced motion preferences

Category: Configuration

Keywords: accessibility, a11y, reduced motion, animation, prefers-reduced-motion, useprefersreducedmotion, animationspeed, user preferences, custom shape, css animation, vestibular

Respect the user's reduced motion preference in a custom shape with `usePrefersReducedMotion`.

`usePrefersReducedMotion()` returns `true` when the user has turned on tldraw's "reduce motion" preference (`animationSpeed: 0` in user preferences) or, if no tldraw preference is set, when the operating system reports `prefers-reduced-motion: reduce`. Use it inside a shape's React component to swap animations for static alternatives.

The pulse shapes here animate normally and fall back to a still gray circle when reduced motion is preferred. The "Toggle" button in the top panel flips the tldraw preference with `editor.user.updateUserPreferences({ animationSpeed })`, so you can watch every shape switch at once. The same setting is available to users under Preferences > Accessibility > Reduce motion in the main menu.

Reduced motion matters for users with vestibular disorders and motion sensitivity, and honoring it is cheap once the check is in one place.

## App.tsx

```tsx
import {
	Geometry2d,
	HTMLContainer,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	T,
	TLComponents,
	TLShape,
	Tldraw,
	TldrawUiButton,
	useEditor,
	usePrefersReducedMotion,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './reduced-motion.css'

const PULSE_SHAPE_TYPE = 'pulse-shape'

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

type PulseShape = TLShape<typeof PULSE_SHAPE_TYPE>

// [2]
function PulseShapeComponent() {
	const prefersReducedMotion = usePrefersReducedMotion()

	return (
		<HTMLContainer className="pulse-shape">
			<div className="pulse-shape__content">
				<div className={prefersReducedMotion ? 'pulse-indicator--static' : 'pulse-indicator'} />
				<div className="pulse-shape__label">
					{prefersReducedMotion ? 'Static mode' : 'Animated mode'}
				</div>
			</div>
		</HTMLContainer>
	)
}

// [3]
export class PulseShapeUtil extends ShapeUtil<PulseShape> {
	static override type = PULSE_SHAPE_TYPE
	static override props: RecordProps<PulseShape> = {
		w: T.number,
		h: T.number,
	}

	getDefaultProps(): PulseShape['props'] {
		return { w: 200, h: 200 }
	}

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

	component() {
		return <PulseShapeComponent />
	}

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

// [4]
function MotionToggle() {
	const editor = useEditor()
	const prefersReducedMotion = usePrefersReducedMotion()

	const toggleMotion = () => {
		const currentSpeed = editor.user.getAnimationSpeed()
		editor.user.updateUserPreferences({
			animationSpeed: currentSpeed === 0 ? 1 : 0,
		})
	}

	return (
		<div className="tlui-menu motion-toggle">
			<span className="motion-toggle__label">
				Motion: {prefersReducedMotion ? 'Reduced' : 'Normal'}
			</span>
			<TldrawUiButton type="primary" onClick={toggleMotion}>
				Toggle
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: MotionToggle,
}

const shapeUtils = [PulseShapeUtil]

export default function ReducedMotionExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				onMount={(editor) => {
					editor.createShape({ type: PULSE_SHAPE_TYPE, x: 200, y: 200 })
					editor.createShape({ type: PULSE_SHAPE_TYPE, x: 450, y: 200 })
					editor.createShape({ type: PULSE_SHAPE_TYPE, x: 325, y: 450 })
				}}
			/>
		</div>
	)
}

/*
[1]
Registering the props in TLGlobalShapePropsMap is what makes `editor.createShape({ type })`
type-check and gives `TLShape<'pulse-shape'>` its props type.

[2]
`usePrefersReducedMotion()` returns true when the user's tldraw preference has `animationSpeed`
set to 0, or (if no preference is set) when the OS reports `prefers-reduced-motion: reduce`. It
is a hook, so the shape's rendering lives in a React component that `component()` returns; the
component re-renders when the preference changes and swaps the CSS class from the pulsing
indicator to the static one.

[3]
The util itself is minimal: geometry, indicator, and the component above.

[4]
The toggle flips the tldraw preference with `editor.user.updateUserPreferences()`. Setting
`animationSpeed: 0` is what tldraw's own "reduce motion" preference does, so the hook and every
shape using it respond the same way they would to the built-in setting.
*/
```

## reduced-motion.css

```css
.pulse-shape {
	display: flex;
	align-items: center;
	justify-content: center;
	pointer-events: all;
	background-color: var(--tl-color-low);
	border: 1px solid var(--tl-color-low-border);
	border-radius: var(--tl-radius-3);
}

.pulse-shape__content {
	text-align: center;
}

.pulse-shape__label {
	font-size: 14px;
	color: var(--tl-color-text-1);
}

.pulse-indicator,
.pulse-indicator--static {
	width: 40px;
	height: 40px;
	border-radius: 50%;
	margin: 0 auto 16px;
}

.pulse-indicator {
	background-color: var(--tl-color-primary);
	animation: pulse 2s ease-in-out infinite;
}

.pulse-indicator--static {
	background-color: var(--tl-color-text-3);
}

@keyframes pulse {
	0%,
	100% {
		transform: scale(1);
		opacity: 1;
	}
	50% {
		transform: scale(1.2);
		opacity: 0.7;
	}
}

.motion-toggle {
	display: flex;
	gap: 8px;
	align-items: center;
	padding: 0 8px;
	pointer-events: all;
}

.motion-toggle__label {
	font-size: 14px;
}
```

--------

# Custom embeds

Category: Configuration

Keywords: embed, iframe, CustomEmbedDefinition, DEFAULT_EMBED_DEFINITIONS, toEmbedUrl, fromEmbedUrl, jsfiddle, url parsing

Add a custom embed provider and remove some of the built-in ones.

tldraw recognizes URLs from many services out of the box and turns them into embed shapes. This example configures `EmbedShapeUtil` with its own list of `embedDefinitions`: two of the defaults (tldraw and YouTube) plus a new `CustomEmbedDefinition` for JSFiddle.

A definition pairs `hostnames` with `toEmbedUrl` and `fromEmbedUrl` functions that convert between the page URL and the iframe URL. Custom definitions also need an `icon`, which shows in the embed dialog.

Try clicking "Insert embed" in the top panel: only tldraw, YouTube, and JSFiddle are listed. Pasting a JSFiddle URL like `https://jsfiddle.net/user/abc123/1/embedded/` onto the canvas also creates an embed.

For sandbox permissions and other per-definition options, see the embed permissions example.

## App.tsx

```tsx
import {
	CustomEmbedDefinition,
	DEFAULT_EMBED_DEFINITIONS,
	DefaultEmbedDefinitionType,
	EmbedShapeUtil,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	useActions,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
const defaultEmbedTypesToKeep: DefaultEmbedDefinitionType[] = ['tldraw', 'youtube']
const defaultEmbedsToKeep = DEFAULT_EMBED_DEFINITIONS.filter((embed) =>
	defaultEmbedTypesToKeep.includes(embed.type)
)

// [2]
const customEmbed: CustomEmbedDefinition = {
	type: 'jsfiddle',
	title: 'JSFiddle',
	hostnames: ['jsfiddle.net'],
	minWidth: 300,
	minHeight: 300,
	width: 720,
	height: 500,
	doesResize: true,
	toEmbedUrl: (url) => {
		const urlObj = new URL(url)
		const matches = urlObj.pathname.match(/\/([^/]+)\/([^/]+)\/(\d+)\/embedded/)
		if (matches) {
			return `https://jsfiddle.net/${matches[1]}/${matches[2]}/embedded/`
		}
		return
	},
	fromEmbedUrl: (url) => {
		const urlObj = new URL(url)
		const matches = urlObj.pathname.match(/\/([^/]+)\/([^/]+)\/(\d+)\/embedded/)
		if (matches) {
			return `https://jsfiddle.net/${matches[1]}/${matches[2]}/`
		}
		return
	},
	icon: 'https://jsfiddle.net/img/favicon.png',
}

// [3]
const shapeUtils = [
	EmbedShapeUtil.configure({ embedDefinitions: [...defaultEmbedsToKeep, customEmbed] }),
]

// [4]
function InsertEmbedButton() {
	const actions = useActions()
	return (
		<div className="tlui-menu" style={{ pointerEvents: 'all' }}>
			<TldrawUiButton
				type="normal"
				onClick={() => actions['insert-embed'].onSelect('helper-buttons')}
			>
				<TldrawUiButtonLabel>Insert embed</TldrawUiButtonLabel>
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: InsertEmbedButton,
}

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

/*
[1]
tldraw ships embed definitions for several popular apps in `DEFAULT_EMBED_DEFINITIONS`. Here we
keep only the 'tldraw' and 'youtube' ones; the rest will no longer be offered in the embed dialog
or recognized when a URL is pasted.

[2]
A custom definition for JSFiddle. `hostnames` decides which pasted URLs this definition handles,
`toEmbedUrl` turns a page URL into the iframe URL (returning undefined rejects the URL), and
`fromEmbedUrl` maps back for copying the link out. Custom definitions must include an `icon`,
which the embed dialog shows next to the title.

[3]
`EmbedShapeUtil.configure({ embedDefinitions })` replaces the whole list, so include any
defaults you want to keep alongside the custom one.

[4]
An "Insert embed" button in the top panel, so the dialog is one click away. It triggers the
built-in `insert-embed` action via `useActions`, the same one the main menu uses.
*/
```

--------

# Environment detection

Category: Configuration

Keywords: tlenv, tlenvreactive, platform detection, browser, iscoarsepointer, touch, mobile, adaptive ui, usevalue

Detect the platform, browser, and pointer type with `tlenv` and `tlenvReactive`.

tldraw exports two objects that describe the environment it's running in:

- `tlenv` is a plain object of flags that don't change during a session: `isDarwin`, `isIos`, `isAndroid`, `isSafari`, `isFirefox`, `isChromeForIos`, and so on. Read it directly, for example to show Cmd instead of Ctrl in shortcut hints on macOS.
- `tlenvReactive` is an atom holding values that can change while the app is open, most importantly `isCoarsePointer`. Read it with `useValue` (or inside a `track`ed component) so your UI updates when it changes.

The panel at the top shows what each one reports for your device, and a button that grows to a 48px touch target when the pointer is coarse. On a touchscreen laptop, tap the screen and then move the trackpad to watch the pointer type and button size switch.

## App.tsx

```tsx
import { Tldraw, TldrawUiButton, TldrawUiIcon, tlenv, tlenvReactive, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './environment-detection.css'

function EnvironmentInfo() {
	// [1]
	const isCoarsePointer = useValue('coarse pointer', () => tlenvReactive.get().isCoarsePointer, [])

	// [2]
	const buttonSize = isCoarsePointer ? '48px' : '32px'

	return (
		<div className="tlui-menu environment-info">
			{/* [3] */}
			<div>
				<strong>Platform (tlenv):</strong> {tlenv.isIos && 'iOS'}
				{tlenv.isDarwin && !tlenv.isIos && 'macOS'}
				{tlenv.isAndroid && 'Android'}
				{!tlenv.isDarwin && !tlenv.isIos && !tlenv.isAndroid && 'Other'}
			</div>
			<div>
				<strong>Browser:</strong> {tlenv.isSafari && 'Safari'}
				{tlenv.isFirefox && 'Firefox'}
				{tlenv.isChromeForIos && 'Chrome for iOS'}
				{!tlenv.isSafari && !tlenv.isFirefox && !tlenv.isChromeForIos && 'Other'}
			</div>
			<div>
				<strong>Modifier key:</strong> {tlenv.isDarwin ? '⌘ Cmd' : 'Ctrl'}
			</div>
			<div>
				<strong>Pointer type (tlenvReactive):</strong> {isCoarsePointer ? 'Touch' : 'Mouse'}
			</div>
			<TldrawUiButton
				type="normal"
				style={{
					width: buttonSize,
					height: buttonSize,
					border: '1px solid var(--tl-color-text-3)',
				}}
				onClick={() => alert(`Button size: ${buttonSize}`)}
			>
				<TldrawUiIcon icon="dot" label="Dot" />
			</TldrawUiButton>
		</div>
	)
}

const components = {
	TopPanel: EnvironmentInfo,
}

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

/*
[1]
`tlenvReactive` is an atom, so read it inside `useValue` to re-render when it changes. On a
touchscreen laptop `isCoarsePointer` flips as the user switches between touching the screen and
using the trackpad. `tlenv` is a plain object whose values are fixed at load time, so it can be
read directly during render.

[2]
Touch needs bigger targets than a mouse: 48px for a coarse pointer, 32px for a fine one.

[3]
`isIos` is checked before `isDarwin` because iPadOS reports itself as a Mac, so both are true on
an iPad.
*/
```

## environment-detection.css

```css
.environment-info {
	display: flex;
	flex-direction: column;
	gap: 8px;
	margin: 8px;
	padding: 12px;
}
```

--------

# Embed permissions

Category: Configuration

Keywords: embed, iframe, sandbox, permissions, aspect ratio, interactive, youtube, security

Configure embed sandbox permissions, aspect ratio locking, and visual options.

Embedded iframes in tldraw are sandboxed with deliberately conservative defaults (`embedShapePermissionDefaults`). This example configures `EmbedShapeUtil` with two embed definitions that override those defaults in opposite directions:

- A **YouTube** definition that grants `allow-presentation` (so the fullscreen button works), locks the aspect ratio to 16:9 with `isAspectRatioLocked`, sets a `backgroundColor` for the loading state, and disables `canEditWhileLocked`.
- A **read-only website** definition (showing Wikipedia's whiteboard article) that turns off scripts, forms, popups, and same-origin access entirely. This is the pattern for embedding untrusted pages as inert previews. It uses `overrideOutlineRadius` to round the shape outline, and works here because Wikipedia renders its content without JavaScript; a script-dependent site would show an empty frame in this mode.

The example also shows the embed interactivity rule: an embed's iframe ignores pointer events until you double-click the shape to enter its editing state, which is why embeds can be dragged and resized without the iframe capturing the pointer.

For adding a new embed provider from scratch, see the custom embed example.

## App.tsx

```tsx
import {
	CustomEmbedDefinition,
	DEFAULT_EMBED_DEFINITIONS,
	Editor,
	EmbedShapeUtil,
	TLEmbedDefinition,
	TLEmbedShape,
	Tldraw,
	toRichText,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

const youtube = DEFAULT_EMBED_DEFINITIONS.find((def) => def.type === 'youtube')!

// [1]
const presentationYoutube: TLEmbedDefinition = {
	...youtube,
	isAspectRatioLocked: true,
	backgroundColor: '#000000',
	canEditWhileLocked: false,
	overridePermissions: {
		'allow-presentation': true,
	},
}

// [2]
const readOnlyWebsite: CustomEmbedDefinition = {
	type: 'website',
	title: 'Website (read-only)',
	hostnames: ['wikipedia.org', '*.wikipedia.org'],
	width: 680,
	height: 1000,
	doesResize: true,
	overrideOutlineRadius: 12,
	backgroundColor: '#f8f9fa',
	overridePermissions: {
		'allow-scripts': false,
		'allow-forms': false,
		'allow-popups': false,
		'allow-same-origin': false,
	},
	toEmbedUrl: (url) => url,
	fromEmbedUrl: (url) => url,
	icon: 'https://en.wikipedia.org/static/favicon/wikipedia.ico',
}

// [3]
const shapeUtils = [
	EmbedShapeUtil.configure({ embedDefinitions: [presentationYoutube, readOnlyWebsite] }),
]

// [4]
function handleMount(editor: Editor) {
	editor.createShape({
		type: 'text',
		x: 100,
		y: 40,
		props: {
			richText: toRichText(
				'Embeds are inert until you double-click them (editing state). Try resizing each one, too.'
			),
		},
	})

	editor.createShape({
		type: 'text',
		x: 100,
		y: 100,
		props: {
			richText: toRichText('YouTube: aspect ratio locked, fullscreen allowed'),
			size: 's',
		},
	})
	editor.createShape<TLEmbedShape>({
		type: 'embed',
		x: 100,
		y: 140,
		props: {
			// "tldraw sync — multiplayer whiteboards in React" from the tldraw channel
			url: 'https://www.youtube.com/watch?v=COw7Wm9HS-g',
			w: 640,
			h: 360,
		},
	})

	editor.createShape({
		type: 'text',
		x: 820,
		y: 100,
		props: {
			richText: toRichText('Read-only website: scripts, forms, and popups disabled'),
			size: 's',
		},
	})
	editor.createShape<TLEmbedShape>({
		type: 'embed',
		x: 820,
		y: 140,
		props: {
			// what else would a whiteboard embed?
			url: 'https://en.wikipedia.org/wiki/Whiteboard',
			w: 680,
			h: 1000,
		},
	})

	editor.zoomToFit()
}

export default function EmbedPermissionsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw shapeUtils={shapeUtils} onMount={handleMount} />
		</div>
	)
}

/*
Embedded iframes are sandboxed. The defaults (embedShapePermissionDefaults
in the tldraw package) are deliberately conservative — scripts, same-origin,
forms, and popups allowed; modals, popups-to-escape-sandbox, top navigation,
and presentation disabled. Each definition can override individual
permissions. The custom embed example covers adding a provider in the first
place.

[1]
A customized YouTube definition:

- overridePermissions grants 'allow-presentation' so the player's fullscreen
  button works (a permission that's off by default because a malicious
  embed could "present" itself pretending to be the host app).
- isAspectRatioLocked keeps the player 16:9 when resized — try a corner
  handle.
- backgroundColor fills the shape behind the iframe while it loads.
- canEditWhileLocked: false means a locked shape can't enter its interactive
  editing state.

[2]
A definition pointing the other way: an intentionally locked-down website
embed, here showing Wikipedia's article on whiteboards. Everything risky is
off — no scripts, no forms, no popups, no same-origin access — the pattern
to use for embedding untrusted pages as inert, read-only previews. Note
that the page still renders because Wikipedia is server-rendered: with
allow-scripts off, a site that needs JavaScript to paint would show an
empty frame, so pick embeds for this mode accordingly.
overrideOutlineRadius rounds the shape's outline to match providers whose
embeds have their own border radius (Spotify is the in-tree example).

[3]
Definitions are passed to EmbedShapeUtil with configure(), replacing the
default list. Adding a definition with an icon (CustomEmbedDefinition) also
puts it in the insert-embed dialog.

[4]
Embed shapes are created like any shape: the util matches the url against
each definition's hostnames to pick the right definition. Note the
interactivity rule: an embed's iframe ignores pointer events until you
double-click the shape to start editing it (editor.getEditingShapeId()
controls this) — that's why you can drag embeds around without the iframe
swallowing your clicks.
*/
```

--------

# Deep links

Category: Configuration

Keywords: deep links, url, navigation, viewport, search params, createdeeplink, navigatetodeeplink, routing

Keep the camera position in the URL so links open at the same view.

Deep links are URLs that point to a specific part of a document: a viewport, a page, or a set of shapes. Try it here: create a shape, then pan or zoom. The `d` search param in the URL updates as you go, and opening that URL in a new tab returns to the same view.

## The `deepLinks` option

The simplest way to use deep links is the `deepLinks` key of the `Tldraw` component's `options` prop. It keeps `window.location` in sync with a search param that tldraw can navigate to, e.g. `https://my-app.com/document-name?d=v1234.-234.3.21`.

Setting `deepLinks: true` enables the default behavior:

1. When the editor initializes, before the initial render, it checks `window.location` for a search param called `d`. If found, it parses the value as a deep link and navigates there.
2. 500 milliseconds after each camera or page change, it updates `window.location` with the latest `d` param.

You can customize this behavior by passing an options object instead:

```tsx
<Tldraw
	options={{
		deepLinks: {
			// change the param name to `page`
			param: 'page',
			// only link to the current page
			getTarget(editor) {
				return { type: 'page', pageId: editor.getCurrentPageId() }
			},
			// log the new search params to the console instead of updating `window.location`
			onChange(url) {
				console.log('the new search params are', url.searchParams)
			},
			// set the debounce interval to 100ms instead of 500ms
			debounceMs: 100,
		},
	}}
/>
```

For full options see the [`TLDeepLinkOptions`](/reference/editor/TLDeepLinkOptions) API reference.

## Handling deep links manually

The same functionality is exposed as methods and utilities, which gives you more control if, for example, you prefer not to use search params in the URL.

### Creating a deep link

You can create an isolated deep link string using the [`createDeepLinkString`](/reference/editor/createDeepLinkString) helper which takes a [`TLDeepLink`](/reference/editor/TLDeepLink) descriptor object.

```tsx
createDeepLinkString({ type: 'page', pageId: 'page:abc123' })
// => 'pabc123'
createDeepLinkString({ type: 'shapes', shapeIds: ['shape:foo', 'shape:bar'] })
// => 'sfoo.bar'
createDeepLinkString({
	type: 'viewport',
	pageId: 'page:abc123',
	bounds: {
		x: 0,
		y: 0,
		w: 1024,
		h: 768,
	},
})
// => 'v0.0.1024.768.abc123'
```

If you do prefer to put this in a URL as a query param, you can use the [`Editor.createDeepLink`](/reference/editor/Editor#createDeepLink) method.

```tsx
editor.createDeepLink({ to: { type: 'page', pageId: 'page:abc123' } })
// => 'https://my-app.com/document-name?d=pabc123'
```

### Handling a deep link

You can parse a deep link string with [`parseDeepLinkString`](/reference/editor/parseDeepLinkString) which returns a [`TLDeepLink`](/reference/editor/TLDeepLink) descriptor object.

You can then call [`Editor.navigateToDeepLink`](/reference/editor/Editor#navigateToDeepLink) with this descriptor to navigate to the part of the document described by the deep link.

`Editor#navigateToDeepLink` also can take a plain URL if the deep link is encoded as a query param.

```tsx
editor.navigateToDeepLink(parseDeepLinkString('pabc123'))
// or pass in a url
editor.navigateToDeepLink({ url: 'https://my-app.com/document-name?d=pabc123' })
// or call without options to use the current `window.location`
editor.navigateToDeepLink()
```

### Listening for deep link changes

You can listen for deep link changes with the [`Editor.registerDeepLinkListener`](/reference/editor/Editor#registerDeepLinkListener) method, which takes the same options as the `deepLinks` option.

```tsx
useEffect(() => {
	const unlisten = editor.registerDeepLinkListener({
		param: 'page',
		getTarget(editor) {
			return { type: 'page', pageId: editor.getCurrentPageId() }
		},
		onChange(url) {
			console.log('the new search params are', url.searchParams)
		},
		debounceMs: 100,
	})
	return () => {
		unlisten()
	}
}, [editor])
```

## App.tsx

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

export default function DeepLinksExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="deep-links-example" options={{ deepLinks: true }} />
		</div>
	)
}
```

--------

# Frame colors

Category: Configuration

Keywords: frame, colors, configure, frameshapeutil, showcolors, shapeutils

Give frames a colored fill and heading with the `showColors` option.

By default frames are white with a plain heading and ignore the color style. `FrameShapeUtil.configure({ showColors: true })` makes frames use the selected color for a tinted fill and a colored heading, and adds the color picker to the style panel when a frame is selected.

Create a frame (F), then pick a color in the style panel to see it applied.

## App.tsx

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

const shapeUtils = [FrameShapeUtil.configure({ showColors: true })]

export default function FrameColorsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="frame-colors" shapeUtils={shapeUtils} />
		</div>
	)
}
```

--------

# Note resizing

Category: Configuration

Keywords: note shape, resize, sticky note, resizemode, scale, configure, shapeutil configuration, note scaling

Let users resize sticky notes with `NoteShapeUtil`'s `resizeMode` option.

Notes have a fixed size by default and can't be resized. `NoteShapeUtil.configure({ resizeMode: 'scale' })` makes them scale as a whole when a resize handle is dragged: the note, its text, and its padding all grow together, so the note keeps its proportions rather than reflowing.

Create a note (N) and drag a corner handle to try it. `resizeMode: 'none'` is the default behavior.

## App.tsx

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

const shapeUtils = [NoteShapeUtil.configure({ resizeMode: 'scale' })]

export default function ResizeNoteExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="resize-note" shapeUtils={shapeUtils} />
		</div>
	)
}
```

--------

# Precise exact arrows

Category: Configuration

Keywords: arrow, configure, isprecise, isexact, arrow behavior, arrowshapeutil, arrow tool, alt key

Make precise arrows always bind exactly, using `ArrowShapeUtil.configure`.

An arrow bound to a shape is either imprecise (it points at the shape's center) or precise (it points at a specific spot inside the shape). A precise arrow can also be exact: instead of stopping at the shape's edge, it continues into the shape all the way to the bound point.

By default an arrow becomes precise when you hover slowly over a target, and becomes exact when you also hold Alt. The `shouldBeExact` option on `ArrowShapeUtil` receives the editor and whether the current binding is precise, and returns whether it should also be exact. This example returns `isPrecise`, so every precise arrow is exact and Alt is no longer needed.

Try it: draw an arrow into a shape and pause before releasing. The arrow tip lands inside the shape instead of stopping at its edge.

## App.tsx

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

const shapeUtils = [
	ArrowShapeUtil.configure({
		shouldBeExact: (editor, isPrecise) => isPrecise,
	}),
]

export default function ArrowsPreciseExactExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw shapeUtils={shapeUtils} />
		</div>
	)
}
```

--------

# Disable pages

Category: Configuration

Keywords: maxpages, single page, options, page selector, configuration

Hide the page menu and page management UI with `maxPages: 1`.

Set the `maxPages` editor option to `1` to remove the page menu from the top-left panel and the "move to page" item from the context menu. This is what most single-canvas apps want.

The document itself still contains one page record, so shapes and the store work exactly as before.

## App.tsx

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

export default function DisablePagesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="disable-pages" options={{ maxPages: 1 }} />
		</div>
	)
}
```

--------

# Minimal

Category: Configuration

Keywords: tldraweditor, minimal, bare bones, custom ui, no ui, headless, shapeutils, tools, statenodeonly

Use `TldrawEditor` on its own with one custom shape and one custom tool, and no UI.

`TldrawEditor` is the editor without tldraw's default shapes, tools, or UI. You provide everything: here that's a single box shape (`MiniBoxShapeUtil`) and a small select tool (`MiniSelectTool`) built as a `StateNode` with idle, pointing, and dragging child states.

Double-click the canvas to create a box, double-click a box to delete it, click or shift-click to select, and drag to move. `MicroSelectTool.ts` in the same folder shows an even smaller select tool with no child states; it isn't used by the example but is a good starting point for reading.

For a fuller custom shape and tool, see the custom config example. For the pieces the `Tldraw` component adds on top of `TldrawEditor`, see the sublibraries example.

## App.tsx

```tsx
import { TldrawEditor, createShapeId } from 'tldraw'
import 'tldraw/tldraw.css'
import { MiniBoxShapeUtil } from './MiniBoxShape'
import { MiniSelectTool } from './MiniSelectTool'

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

// [1]
const tools = [MiniSelectTool]
const shapeUtils = [MiniBoxShapeUtil]

function Instructions() {
	return (
		<div style={{ position: 'absolute', transform: 'translate(16px, 16px)', width: 320 }}>
			<p>Double click to create or delete shapes.</p>
			<p>Click or shift+click to select shapes.</p>
			<p>Click and drag to move shapes.</p>
		</div>
	)
}

const components = {
	OnTheCanvas: Instructions,
}

// [2]
export default function OnlyEditorExample() {
	return (
		<div className="tldraw__editor">
			<TldrawEditor
				tools={tools}
				shapeUtils={shapeUtils}
				components={components}
				initialState="select"
				onMount={(editor) => {
					editor
						.selectAll()
						.deleteShapes(editor.getSelectedShapeIds())
						.createShapes([{ id: createShapeId(), type: 'box', x: 100, y: 100 }])
				}}
			/>
		</div>
	)
}

/*
[1]
TldrawEditor has no built-in shapes or tools, so we supply our own: a box shape util
(MiniBoxShape.tsx) and a select tool (MiniSelectTool.ts). MicroSelectTool.ts is an even smaller
select tool without child states; it isn't wired up here but is worth reading first. The custom
config example covers writing shapes and tools in more depth.

[2]
`initialState` names the tool the editor starts in; it must match a tool's `static id`. There is
no UI here, so the instructions are rendered through the `OnTheCanvas` component slot instead.
*/
```

## MicroSelectTool.ts

```ts
import { StateNode, TLClickEventInfo, TLPointerEventInfo, createShapeId } from 'tldraw'

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

// [1]
export class MicroSelectTool extends StateNode {
	static override id = 'select'
	// [2]
	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
				}

				editor.selectNone()
				break
			}
			case 'shape': {
				editor.select(info.shape.id)
				break
			}
		}
	}
	// [3]
	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.createShapes([
					{
						id: createShapeId(),
						type: 'box',
						x: currentPagePoint.x - 50,
						y: currentPagePoint.y - 50,
						props: {
							w: 100,
							h: 100,
						},
					},
				])
				break
			}
			case 'shape': {
				editor.deleteShapes([info.shape.id])
				break
			}
		}
	}
}
/*
The smallest possible "select" tool: a single StateNode with no child states. It isn't used by
the example; MiniSelectTool.ts is the version that's wired up.

[1]
A tool is a StateNode with a static `id`. If this tool were registered in place of MiniSelectTool,
the example's `initialState="select"` would start the editor in it. With no children, event
handlers go directly on the tool.

[2]
Pointer events arrive with a `target` of 'canvas' or 'shape'. Custom shapes rendered with
`pointerEvents: 'all'` report themselves as the target, but hits on the canvas can still land on
a shape (for example when the pointer is inside a hollow shape), so we re-check with
`getShapeAtPoint` and re-dispatch as a 'shape' event.

[3]
Double-click fires once per phase ('down', 'up', 'settle-down', 'settle-up'); we only act on
'up' so the shape is created or deleted once.
*/
```

## MiniBoxShape.tsx

```tsx
import { BaseBoxShapeUtil, HTMLContainer, TLShape } from 'tldraw'

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

const BOX_TYPE = 'box'

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

// [2]
export type MiniBoxShape = TLShape<typeof BOX_TYPE>

// [3]
export class MiniBoxShapeUtil extends BaseBoxShapeUtil<MiniBoxShape> {
	static override type = BOX_TYPE
	override getDefaultProps(): MiniBoxShape['props'] {
		return { w: 100, h: 100, color: '#efefef' }
	}
	// [a]
	component(shape: MiniBoxShape) {
		return (
			<HTMLContainer>
				<div
					style={{
						width: shape.props.w,
						height: shape.props.h,
						border: '1px solid black',
						backgroundColor: shape.props.color,
						pointerEvents: 'all',
					}}
				/>
			</HTMLContainer>
		)
	}
	// [b]
	getIndicatorPath(shape: MiniBoxShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}
}

/*
[1]
Registering the props in TLGlobalShapePropsMap is what makes `editor.createShapes({ type: 'box' })`
type-check and gives `TLShape<'box'>` its props type.

[2]
The shape's record type, derived from the registration above.

[3]
BaseBoxShapeUtil supplies rectangular geometry and resize behavior for any shape with `w` and `h`
props, so this util only needs to say what the box looks like.
	[a] HTMLContainer positions the shape's DOM on the canvas. `pointerEvents: 'all'` is what
		lets the select tool receive events with this shape as the target.
	[b] The indicator is the outline drawn when the shape is selected or hovered, as a Path2D in
		shape space.
*/
```

## MiniSelectTool.ts

```ts
import { StateNode, TLClickEventInfo, TLPointerEventInfo, TLShape, createShapeId } from 'tldraw'
// There's a guide at the bottom of this file!

// [1]
export class MiniSelectTool extends StateNode {
	static override id = 'select'
	static override children() {
		return [IdleState, PointingState, DraggingState]
	}
	static override initial = 'idle'
}
// [2]
class IdleState extends StateNode {
	static override id = 'idle'
	// [a]
	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
				}

				editor.selectNone()
				break
			}
			case 'shape': {
				if (editor.inputs.getShiftKey()) {
					editor.select(...editor.getSelectedShapeIds(), info.shape.id)
				} else {
					if (!editor.getSelectedShapeIds().includes(info.shape.id)) {
						editor.select(info.shape.id)
					}
					this.parent.transition('pointing', info)
				}
				break
			}
		}
	}
	// [b]
	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.createShapes([
					{
						id: createShapeId(),
						type: 'box',
						x: currentPagePoint.x - 50,
						y: currentPagePoint.y - 50,
						props: {
							w: 100,
							h: 100,
						},
					},
				])
				break
			}
			case 'shape': {
				editor.deleteShapes([info.shape.id])
				break
			}
		}
	}
}

// [3]
class PointingState extends StateNode {
	static override id = 'pointing'
	// [a]
	override onPointerUp(info: TLPointerEventInfo) {
		this.parent.transition('idle', info)
	}
	// [b]
	override onPointerMove() {
		if (this.editor.inputs.getIsDragging()) {
			this.parent.transition('dragging', { shapes: [...this.editor.getSelectedShapes()] })
		}
	}
}

// [4]
class DraggingState extends StateNode {
	static override id = 'dragging'
	private initialDraggingShapes: TLShape[] = []
	// [a]
	override onEnter(info: { shapes: TLShape[] }) {
		this.initialDraggingShapes = info.shapes
	}
	override onPointerUp(info: TLPointerEventInfo) {
		this.parent.transition('idle', info)
	}
	// [b]
	override onPointerMove() {
		const { initialDraggingShapes } = this
		const originPagePoint = this.editor.inputs.getOriginPagePoint()
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()

		this.editor.updateShapes(
			initialDraggingShapes.map((shape) => {
				return {
					...shape,
					x: shape.x + (currentPagePoint.x - originPagePoint.x),
					y: shape.y + (currentPagePoint.y - originPagePoint.y),
				}
			})
		)
	}
}

/*
Tools are nodes in the editor's state chart (https://tldraw.dev/docs/tools). This tool has
three child states, idle [2], pointing [3], and dragging [4]; exactly one is active at a time,
and events go to the active child. A child calls `this.parent.transition(id, info)` to hand
control to a sibling; the sibling's `onEnter` receives `info`, which is how data moves between
states.

[1]
The tool itself only declares its id, its children, and which child starts active.

[2]
Idle is where the tool waits for input.

	[a] Pointer events arrive with a `target` of 'canvas' or 'shape'. A hit on the canvas can
		still land on a shape (for example inside a hollow shape), so we re-check with
		`getShapeAtPoint` and re-dispatch as a 'shape' event. Pointing a shape selects it (or
		adds it with shift) and moves to pointing so a drag can begin.

	[b] Double-click fires once per phase ('down', 'up', 'settle-down', 'settle-up'); we only act
		on 'up' so the shape is created or deleted once.

[3]
Pointing exists to tell a click from a drag.

	[a] Pointer up without moving far enough: back to idle.
	[b] `editor.inputs.getIsDragging()` becomes true once the pointer has moved past the drag
		threshold. We then move to dragging and hand it the shapes to move.

[4]
Dragging moves the selected shapes.

	[a] The shapes captured on enter keep their original positions, so each move can be computed
		from the pointer's total offset since the drag started rather than accumulated deltas.
	[b] `getOriginPagePoint()` is where the pointer went down; the difference to
		`getCurrentPagePoint()` is applied to each shape's starting position with
		`editor.updateShapes()`.
*/
```

--------

# Sublibraries

Category: Configuration

Keywords: tldraweditor, tldrawui, sublibraries, modular, architecture, defaultshapeutils, defaulttools, components

Assemble the `Tldraw` component yourself from `TldrawEditor`, `TldrawUi`, and the default shapes and tools.

The `Tldraw` component is a convenience wrapper. Underneath it is `TldrawEditor` (the canvas and editor, with no shapes, tools, or UI of its own), `TldrawUi` (the default menus, toolbar, and panels), and a set of defaults: `defaultShapeUtils`, `defaultBindingUtils`, `defaultTools`, `defaultShapeTools`, and so on.

This example builds the same editor from those pieces. It behaves like the plain `Tldraw` component, but every part is now visible and replaceable: drop a shape util from the list, pass a different tool set, or leave out `TldrawUi` and supply your own interface. The only-editor example goes further and uses `TldrawEditor` with a single custom shape and tool.

## App.tsx

```tsx
import { useEffect } from 'react'
import {
	ContextMenu,
	DEFAULT_SUPPORTED_IMAGE_TYPES,
	DEFAULT_SUPPORT_VIDEO_TYPES,
	DefaultContextMenuContent,
	TldrawEditor,
	TldrawUi,
	defaultAddFontsFromNode,
	defaultAssetUtils,
	defaultBindingUtils,
	defaultEditorAssetUrls,
	defaultOverlayUtils,
	defaultShapeTools,
	defaultShapeUtils,
	defaultTools,
	registerDefaultExternalContentHandlers,
	registerDefaultSideEffects,
	tipTapDefaultExtensions,
	useEditor,
	useToasts,
	useTranslation,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

const allDefaultTools = [...defaultTools, ...defaultShapeTools]
const defaultOptions = {
	text: {
		tipTapConfig: {
			extensions: tipTapDefaultExtensions,
		},
		addFontsFromNode: defaultAddFontsFromNode,
	},
}

// [1]
export default function ExplodedExample() {
	return (
		<div className="tldraw__editor">
			<TldrawEditor
				initialState="select"
				shapeUtils={defaultShapeUtils}
				bindingUtils={defaultBindingUtils}
				assetUtils={defaultAssetUtils}
				overlayUtils={defaultOverlayUtils}
				tools={allDefaultTools}
				persistenceKey="exploded-example"
				options={defaultOptions}
				assetUrls={defaultEditorAssetUrls}
			>
				<TldrawUi>
					<InsideEditorAndUiContext />
				</TldrawUi>
			</TldrawEditor>
		</div>
	)
}

function InsideEditorAndUiContext() {
	const editor = useEditor()
	const toasts = useToasts()
	const msg = useTranslation()

	// [2]
	useEffect(() => {
		registerDefaultExternalContentHandlers(editor, {
			maxImageDimension: 5000,
			maxAssetSize: 10 * 1024 * 1024, // 10mb
			acceptedImageMimeTypes: DEFAULT_SUPPORTED_IMAGE_TYPES,
			acceptedVideoMimeTypes: DEFAULT_SUPPORT_VIDEO_TYPES,
			toasts,
			msg,
		})

		const cleanupSideEffects = registerDefaultSideEffects(editor)

		return () => {
			cleanupSideEffects()
		}
	}, [editor, msg, toasts])

	return (
		<ContextMenu>
			<DefaultContextMenuContent />
		</ContextMenu>
	)
}

/*
The `Tldraw` component is a thin wrapper that wires these pieces together. Assembling them
yourself lets you swap or omit any of them.

[1]
`TldrawEditor` is the UI-free editor. Everything the `Tldraw` component normally supplies is
passed in explicitly here: the default shape utils, binding utils, asset utils, overlay utils,
tools, asset URLs, and the rich text options. Swap any of these for your own; the custom config example shows
how to write shapes and tools. `TldrawUi` renders the default UI around it, and the context menu
is mounted as a child so it can wrap the canvas.

[2]
Two more things the `Tldraw` component does on mount that `TldrawEditor` does not: register the
default external content handlers (dropped and pasted files, URLs, embeds, SVG text) and the
default store side effects (for example, resolving an embed's aspect ratio when it is created).
Both need the toasts and translation contexts from `TldrawUi`, which is why this component is
rendered inside it.
*/
```

--------

# Controlling the canvas

Category: Editor API

Keywords: editor api, createshapes, updateshape, rotateshapesby, zoomtofit, select, useeditor, onmount, setstyle, context

Create, update, rotate, and select shapes and move the camera with the editor API.

The `Editor` instance is the entry point for everything you can do programmatically in tldraw. This example gets the editor two ways, from the `onMount` callback and from the `useEditor` hook inside a child component, then walks through a short timeline of API calls: `createShapes`, `updateShape`, `rotateShapesBy`, `zoomToFit`, `select`, and finally `setStyleForSelectedShapes` and `setStyleForNextShapes` to cycle the shape's color.

Watch the canvas after it loads: each step runs one second after the last so you can see what every call does.

## App.tsx

```tsx
import { useEffect } from 'react'
import {
	createShapeId,
	DefaultColorStyle,
	Editor,
	TLGeoShape,
	Tldraw,
	toRichText,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

const STEP_MS = 1000
const TIMELINE_MS = STEP_MS * 5

// [1]
export default function APIExample() {
	const handleMount = (editor: Editor) => {
		const id = createShapeId('hello')

		// Run each API call on its own beat so a viewer can see what each one does.
		// richText is set at creation time; adding a first label later would trigger
		// the geo shape's auto-sizing and swallow the height update in step 2.
		const steps: (() => void)[] = [
			// 1. Create the shape
			() => {
				editor.createShapes([
					{
						id,
						type: 'geo',
						x: 128 + Math.random() * 500,
						y: 128 + Math.random() * 500,
						props: {
							geo: 'rectangle',
							w: 120,
							h: 100,
							dash: 'draw',
							color: 'blue',
							size: 'm',
							richText: toRichText('hello world!'),
						},
					},
				])
			},
			// 2. Triple the shape's height
			() => {
				const shape = editor.getShape<TLGeoShape>(id)!
				editor.updateShape({
					id,
					type: 'geo',
					props: { h: shape.props.h * 3 },
				})
			},
			// 3. Rotate the shape around its center
			() => editor.rotateShapesBy([id], Math.PI / 8),
			// 4. Zoom the camera to fit the shape
			() => editor.zoomToFit(),
			// 5. Select the shape
			() => editor.select(id),
		]

		const timeouts = steps.map((step, i) => setTimeout(step, i * STEP_MS))

		return () => {
			timeouts.forEach(clearTimeout)
		}
	}

	return (
		<div className="tldraw__editor">
			<Tldraw onMount={handleMount}>
				<InsideOfEditorContext />
			</Tldraw>
		</div>
	)
}

// [2]
const InsideOfEditorContext = () => {
	const editor = useEditor()

	useEffect(() => {
		let i = 0
		let interval: ReturnType<typeof setInterval> | undefined

		// Wait for the onMount timeline to finish so the color cycle doesn't
		// interrupt the staged setup.
		const start = setTimeout(() => {
			interval = setInterval(() => {
				const selection = [...editor.getSelectedShapeIds()]
				editor.selectAll()
				editor.setStyleForSelectedShapes(DefaultColorStyle, i % 2 ? 'blue' : 'light-blue')
				editor.setStyleForNextShapes(DefaultColorStyle, i % 2 ? 'blue' : 'light-blue')
				editor.setSelectedShapes(selection)
				i++
			}, STEP_MS)
		}, TIMELINE_MS)

		return () => {
			clearTimeout(start)
			if (interval) clearInterval(interval)
		}
	}, [editor])

	return null
}

/*
Introduction:

This example shows how to use the tldraw editor instance to make changes
to the canvas. The editor is tldraw's "god object": you can use it to do just
about everything that's possible in tldraw. Internally, the canvas component
and all shapes, tools, and UI components use this instance to send events,
observe changes, and perform actions.

There are two main ways to get hold of the editor:

[1]
The Tldraw component passes its editor instance to the onMount callback prop.
We schedule each API call on its own beat so a viewer can see the effect of
every step: creating the shape, updating its height, rotating it, zooming the
camera, and selecting it. The cleanup function returned from onMount cancels
any pending steps if the editor unmounts first.

[2]
Any component rendered as a child of Tldraw can read the editor from React
context with the useEditor hook. Once the timeline above finishes, this child
component takes over and demonstrates two more API calls,
setStyleForSelectedShapes and setStyleForNextShapes, by cycling the shape's
color.

*/
```

--------

# Save and load snapshots

Category: Editor API

Keywords: snapshot, save, load, getsnapshot, loadsnapshot, persistence, export, import, document, session, localstorage

Save the editor's contents with `getSnapshot()` and restore them with `loadSnapshot()`.

`getSnapshot(editor.store)` returns a `{ document, session }` object: `document` holds the pages, shapes, and assets, and `session` holds per-user state like the current page, camera, and selection. `loadSnapshot(editor.store, snapshot)` restores either or both. The editor here starts from a bundled snapshot passed to the `snapshot` prop.

Draw something, click "Save snapshot", change the canvas, then click "Load snapshot" to restore it from localStorage.

## App.tsx

```tsx
import { useEffect, useState } from 'react'
import {
	getSnapshot,
	loadSnapshot,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TLEditorSnapshot,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import _jsonSnapshot from './snapshot.json'
import './snapshots.css'

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

const jsonSnapshot = _jsonSnapshot as any as TLEditorSnapshot

function SnapshotToolbar() {
	const editor = useEditor()
	const [showCheckMark, setShowCheckMark] = useState(false)

	const save = () => {
		// [1]
		const { document, session } = getSnapshot(editor.store)
		localStorage.setItem('snapshot', JSON.stringify({ document, session }))
		setShowCheckMark(true)
	}

	const load = () => {
		const snapshot = localStorage.getItem('snapshot')
		if (!snapshot) return
		// [2]
		loadSnapshot(editor.store, JSON.parse(snapshot))
	}

	useEffect(() => {
		if (!showCheckMark) return
		const timeout = setTimeout(() => setShowCheckMark(false), 1000)
		return () => clearTimeout(timeout)
	}, [showCheckMark])

	return (
		<div className="tlui-menu snapshot-toolbar">
			<span className="snapshot-saved" data-visible={showCheckMark}>
				Saved
			</span>
			<TldrawUiButton type="normal" onClick={save}>
				Save snapshot
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={load}>
				Load snapshot
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	SharePanel: SnapshotToolbar,
}

export default function SnapshotExample() {
	return (
		<div className="tldraw__editor">
			{/* [3] */}
			<Tldraw snapshot={jsonSnapshot} components={components} />
		</div>
	)
}

/*
[1]
`getSnapshot(editor.store)` returns `{ document, session }`. `document` is the content: pages, shapes,
assets, and so on. `session` is per-user editor state such as the current page, camera, and selection.
In a multi-user app you'd usually store these separately so each user keeps their own session. Here we
store both together in localStorage.

[2]
`loadSnapshot(editor.store, snapshot)` restores it. You can pass just `{ document }` and load
`{ session }` later on its own, or skip the session entirely.

[3]
Passing a snapshot to the `snapshot` prop loads it into the store when the editor is created, so the
editor starts with content.
*/
```

## snapshots.css

```css
.snapshot-toolbar {
	display: flex;
	align-items: center;
	gap: 4px;
	margin: 8px;
	padding: 4px;
	pointer-events: all;
}

.snapshot-saved {
	padding: 0 8px;
	font-size: 12px;
	transition:
		transform 0.2s ease,
		opacity 0.2s ease;
	transform: scale(0.5);
	opacity: 0;
}

.snapshot-saved[data-visible='true'] {
	transform: scale(1);
	opacity: 1;
}
```

--------

# Coordinate system transformations

Category: Editor API

Keywords: coordinates, screenToPage, pageToScreen, pageToViewport, getViewportScreenBounds, getViewportPageBounds, viewport, transformation, screen space, page space, dom positioning, overlay, camera

Convert between screen, page, and viewport coordinates and position DOM elements over shapes.

The editor uses three coordinate systems:

- **Screen space**: browser pixels, as reported by DOM events
- **Viewport space**: pixels relative to the editor container, used to position DOM elements over the canvas
- **Page space**: the infinite canvas that shapes live in

`editor.screenToPage(point)`, `editor.pageToScreen(point)`, and `editor.pageToViewport(point)` convert between them, and `editor.getViewportScreenBounds()` and `editor.getViewportPageBounds()` describe the visible area in screen and page space.

Move the mouse to see the pointer position in all three systems, then pan and zoom to see how screen coordinates stay put while page coordinates change. Draw and select a shape to see a DOM label positioned above it with `pageToViewport`.

## App.tsx

```tsx
import { Tldraw, TLEditorComponents, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './coordinate-system.css'

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

// [1]
function CoordinateDebugPanel() {
	const editor = useEditor()

	// [2]
	const mouse = useValue(
		'mouse',
		() => {
			const page = editor.inputs.getCurrentPagePoint()
			return {
				page,
				screen: editor.pageToScreen(page),
				viewport: editor.pageToViewport(page),
			}
		},
		[editor]
	)

	// [3]
	const viewportScreenBounds = useValue('screen bounds', () => editor.getViewportScreenBounds(), [
		editor,
	])
	const viewportPageBounds = useValue('page bounds', () => editor.getViewportPageBounds(), [editor])

	return (
		<div className="coordinate-debug-panel">
			<h3>Coordinate systems</h3>

			<div className="coordinate-section">
				<h4>Mouse position</h4>
				<div className="coordinate-row">
					<span className="coordinate-label">Screen:</span>
					<span className="coordinate-value">
						({mouse.screen.x.toFixed(0)}, {mouse.screen.y.toFixed(0)})
					</span>
				</div>
				<div className="coordinate-row">
					<span className="coordinate-label">Page:</span>
					<span className="coordinate-value">
						({mouse.page.x.toFixed(0)}, {mouse.page.y.toFixed(0)})
					</span>
				</div>
				<div className="coordinate-row">
					<span className="coordinate-label">Viewport:</span>
					<span className="coordinate-value">
						({mouse.viewport.x.toFixed(0)}, {mouse.viewport.y.toFixed(0)})
					</span>
				</div>
			</div>

			<div className="coordinate-section">
				<h4>Viewport bounds</h4>
				<div className="coordinate-row">
					<span className="coordinate-label">Screen:</span>
					<span className="coordinate-value">
						({viewportScreenBounds.x.toFixed(0)}, {viewportScreenBounds.y.toFixed(0)},{' '}
						{viewportScreenBounds.w.toFixed(0)}×{viewportScreenBounds.h.toFixed(0)})
					</span>
				</div>
				<div className="coordinate-row">
					<span className="coordinate-label">Page:</span>
					<span className="coordinate-value">
						({viewportPageBounds.x.toFixed(0)}, {viewportPageBounds.y.toFixed(0)},{' '}
						{viewportPageBounds.w.toFixed(0)}×{viewportPageBounds.h.toFixed(0)})
					</span>
				</div>
			</div>
		</div>
	)
}

// [4]
function SelectedShapeOverlay() {
	const editor = useEditor()
	const overlay = useValue(
		'selected shape overlay',
		() => {
			const selectedShapeId = editor.getOnlySelectedShapeId()
			if (!selectedShapeId) return null
			const pageBounds = editor.getShapePageBounds(selectedShapeId)
			if (!pageBounds) return null
			// [5]
			const topLeft = editor.pageToViewport(pageBounds.point)
			return { pageBounds, topLeft }
		},
		[editor]
	)

	if (!overlay) return null

	return (
		<div
			className="shape-overlay"
			style={{
				left: overlay.topLeft.x,
				top: overlay.topLeft.y - 32,
			}}
		>
			Page: ({overlay.pageBounds.x.toFixed(0)}, {overlay.pageBounds.y.toFixed(0)})
		</div>
	)
}

// [6]
const components: TLEditorComponents = {
	InFrontOfTheCanvas: () => (
		<>
			<CoordinateDebugPanel />
			<SelectedShapeOverlay />
		</>
	),
}

export default function CoordinateSystemExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="coordinate-transformations" components={components} />
		</div>
	)
}

/*
The editor works with three coordinate systems:

- Screen space: browser pixels, as reported by DOM events (`clientX`, `clientY`).
- Viewport space: pixels relative to the top-left of the editor's container. This is what
  you use to position DOM elements inside the editor.
- Page space: the infinite canvas that shapes live in. Panning and zooming change how page
  space maps to the other two.

`screenToPage`, `pageToScreen`, and `pageToViewport` convert between them.

[1]
A panel that prints the pointer position in each system, plus the viewport bounds. It's rendered
in the `InFrontOfTheCanvas` slot so it sits over the canvas but doesn't move with it.

[2]
`editor.inputs.getCurrentPagePoint()` is a reactive signal that updates on every pointer move, so
reading it inside `useValue` keeps the readout live. We convert it back to the other two spaces
with `pageToScreen` and `pageToViewport`. Going the other way, `screenToPage` turns a DOM event's
`clientX`/`clientY` into a page point.

[3]
`getViewportScreenBounds()` is the editor container's rectangle in screen space, so it only
changes when the container moves or resizes. `getViewportPageBounds()` is the region of the page
currently visible, so it changes whenever you pan or zoom.

[4]
A label positioned above the selected shape. `getOnlySelectedShapeId()` returns null unless
exactly one shape is selected.

[5]
Elements inside `InFrontOfTheCanvas` are positioned relative to the editor container, so we use
`pageToViewport`, not `pageToScreen`. `pageToScreen` includes the container's offset from the
browser origin, which would push the label off target whenever the editor isn't at (0, 0), for
example next to a sidebar.

[6]
Define `components` outside the React component so the slot component identity is stable across
renders.
*/
```

## coordinate-system.css

```css
.coordinate-debug-panel {
	position: absolute;
	top: 64px;
	left: 16px;
	width: 280px;
	background: white;
	border: 1px solid #ccc;
	padding: 12px;
	font-family: system-ui, sans-serif;
	font-size: 12px;
	z-index: 10000;
	user-select: none;
}

.coordinate-debug-panel h3 {
	margin: 0 0 8px 0;
	font-size: 13px;
	font-weight: 600;
}

.coordinate-debug-panel h4 {
	margin: 8px 0 4px 0;
	font-size: 11px;
	font-weight: 600;
	color: #666;
}

.coordinate-section {
	margin-bottom: 8px;
}

.coordinate-row {
	display: flex;
	justify-content: space-between;
	padding: 2px 0;
}

.coordinate-label {
	color: #666;
}

.coordinate-value {
	font-family: monospace;
	font-size: 11px;
}

.shape-overlay {
	position: absolute;
	pointer-events: none;
	z-index: 10000;
	background: #333;
	color: white;
	padding: 4px 8px;
	font-size: 11px;
	font-family: monospace;
	white-space: nowrap;
}
```

--------

# Create an arrow

Category: Editor API

Keywords: arrow, createShape, createBindings, binding, connection, normalizedAnchor, isPrecise, isExact, terminal, programmatic creation

Create an arrow bound to two shapes with `createShape` and `createBindings`.

Arrows attach to shapes through arrow bindings, one per terminal. This example creates two geo shapes, then creates an arrow shape and two `arrow` binding records connecting its `start` and `end` terminals to them. The `normalizedAnchor`, `isPrecise`, and `isExact` binding props control where on each shape the arrow attaches.

Try dragging either shape: the arrow stays connected because the bindings, not the arrow's own props, define where its terminals go.

## App.tsx

```tsx
import { createShapeId, Editor, TLArrowBinding, Tldraw, TLShapeId, Vec, VecLike } from 'tldraw'
import 'tldraw/tldraw.css'

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

export default function CreateArrowExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size > 0) return

					const shapeAId = createShapeId()
					const shapeBId = createShapeId()

					editor.createShapes([
						{ id: shapeAId, type: 'geo', x: 100, y: 100 },
						{ id: shapeBId, type: 'geo', x: 400, y: 400 },
					])

					createArrowBetweenShapes(editor, shapeAId, shapeBId)
				}}
			/>
		</div>
	)
}

type TerminalOptions = Partial<Omit<TLArrowBinding['props'], 'terminal'>>

function createArrowBetweenShapes(
	editor: Editor,
	startShapeId: TLShapeId,
	endShapeId: TLShapeId,
	options: { start?: TerminalOptions; end?: TerminalOptions } = {}
) {
	// [1]
	const {
		normalizedAnchor: startNormalizedAnchor = { x: 0.5, y: 0.5 },
		isExact: startIsExact = false,
		isPrecise: startIsPrecise = false,
	} = options.start ?? {}
	const {
		normalizedAnchor: endNormalizedAnchor = { x: 0.5, y: 0.5 },
		isExact: endIsExact = false,
		isPrecise: endIsPrecise = false,
	} = options.end ?? {}

	// [2]
	const startTerminalPagePosition = getAnchorInPageSpace(
		editor,
		startShapeId,
		startNormalizedAnchor
	)
	const endTerminalPagePosition = getAnchorInPageSpace(editor, endShapeId, endNormalizedAnchor)

	// [3]
	const arrowPagePoint = Vec.Min(startTerminalPagePosition, endTerminalPagePosition)

	const arrowId = createShapeId()
	editor.run(() => {
		editor.markHistoryStoppingPoint('creating_arrow')
		editor.createShape({
			id: arrowId,
			type: 'arrow',
			x: arrowPagePoint.x,
			y: arrowPagePoint.y,
			props: {
				// [4]
				start: Vec.Sub(startTerminalPagePosition, arrowPagePoint).toJson(),
				end: Vec.Sub(endTerminalPagePosition, arrowPagePoint).toJson(),
			},
		})

		// [5]
		editor.createBindings([
			{
				fromId: arrowId,
				toId: startShapeId,
				type: 'arrow',
				props: {
					terminal: 'start',
					normalizedAnchor: startNormalizedAnchor,
					isExact: startIsExact,
					isPrecise: startIsPrecise,
				},
			},
			{
				fromId: arrowId,
				toId: endShapeId,
				type: 'arrow',
				props: {
					terminal: 'end',
					normalizedAnchor: endNormalizedAnchor,
					isExact: endIsExact,
					isPrecise: endIsPrecise,
				},
			},
		])
	})
}

function getAnchorInPageSpace(editor: Editor, shapeId: TLShapeId, normalizedAnchor: VecLike) {
	const { point, size } = editor.getShapeGeometry(shapeId).bounds
	const localPoint = Vec.Add(point, Vec.MulV(normalizedAnchor, size))
	return editor.getShapePageTransform(shapeId).applyToPoint(localPoint)
}

/*
An arrow connects to other shapes through arrow bindings: one binding record per terminal
(`start` and `end`) that points from the arrow to the shape it's attached to. Once the bindings
exist, the editor keeps the arrow's terminals attached as either shape moves.

[1]
Of the binding props, `normalizedAnchor` is the point inside the bound shape that the
terminal targets, in the shape's own bounds: (0, 0) is the top left, (1, 1) the bottom right. It's
only used when `isPrecise` is true; otherwise the arrow aims at the shape's center. By default the
arrow stops at the outside of the shape's geometry; set `isExact` to true to make it end exactly on
the anchor point instead.

[2]
To place the arrow sensibly we compute where each anchor is on the page. The anchor is defined in
the shape's local bounds, so we take the geometry bounds, scale the normalized anchor by their size,
and push the result through the shape's page transform so rotation and parent groups are handled.

[3]
The arrow shape's `x`/`y` are in its parent's space, which here is the page. We put the arrow's
origin at the top-left corner of the box spanning both terminals.

[4]
An arrow's `start` and `end` props are relative to the arrow's own position. When a terminal is
bound, the editor recomputes it from the binding, so these values mostly matter for the unbound
case, but setting them keeps the arrow's transform sensible.

[5]
Create the shape and the bindings inside one `editor.run` so they land in a single history entry.
Bindings are created with `createBindings`, not by setting props on the arrow.
*/
```

--------

# Custom clipping shape

Category: Editor API

Keywords: clipping, clip path, mask, getClipPath, shouldClipChild, polygon, children, parent-child, circular

Clip child shapes to a circle with `getClipPath` and `shouldClipChild`.

Any `ShapeUtil` can clip its children by implementing `getClipPath`, which returns a polygon in the shape's local coordinates. The editor transforms it to page space, intersects it with any ancestor clip paths, and applies it to every child. Implement `shouldClipChild` to leave some children unclipped (frames use this to skip arrows).

The example defines a circle shape that clips its children to a polygon approximation of the circle. Try dragging shapes into and out of the circle, resizing it, or clicking with the "Circle clip" tool (shortcut `c`) to place new circles. The "Disable clipping" button flips a shared atom that `shouldClipChild` reads, turning clipping off for every circle at once.

## App.tsx

```tsx
import {
	createShapeId,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiMenuItem,
	TLGeoShapeProps,
	TLTextShapeProps,
	TLUiOverrides,
	toRichText,
	useEditor,
	useIsToolSelected,
	useTools,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { CircleClipShapeTool } from './CircleClipShapeTool'
import { CircleClipShapeUtil, isClippingEnabled$ } from './CircleClipShapeUtil'
import './CustomClipping.css'

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

// [1]
const shapeUtils = [CircleClipShapeUtil]
const tools = [CircleClipShapeTool]

// [2]
const customUiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		tools['circle-clip'] = {
			id: 'circle-clip',
			label: 'Circle clip',
			icon: 'color',
			kbd: 'c',
			onSelect() {
				editor.setCurrentTool('circle-clip')
			},
		}
		return tools
	},
}

// [3]
function ToggleClippingButton() {
	const editor = useEditor()

	const clippingEnabled = useValue(isClippingEnabled$)

	return (
		<div className="tlui-menu CustomClipping-toggle">
			<TldrawUiButton
				type="normal"
				onClick={() => isClippingEnabled$.update((prev) => !prev)}
				onPointerDown={editor.markEventAsHandled}
				onPointerUp={editor.markEventAsHandled}
			>
				{clippingEnabled ? '✂️ Disable clipping' : '○ Enable clipping'}
			</TldrawUiButton>
		</div>
	)
}

// [4]
function CustomToolbar() {
	const tools = useTools()
	const isCircleClipSelected = useIsToolSelected(tools['circle-clip'])

	return (
		<DefaultToolbar>
			<TldrawUiMenuItem {...tools['circle-clip']} isSelected={isCircleClipSelected} />
			<DefaultToolbarContent />
		</DefaultToolbar>
	)
}

// [5]
const components: TLComponents = {
	Toolbar: CustomToolbar,
	InFrontOfTheCanvas: ToggleClippingButton,
}

// [6]
export default function CustomClippingExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				tools={tools}
				components={components}
				overrides={customUiOverrides}
				onMount={(editor) => {
					editor.setCurrentTool('select')

					const clipShapeId = createShapeId()
					editor.createShape({
						id: clipShapeId,
						type: 'circle-clip',
						x: 200,
						y: 200,
						props: {
							w: 300,
							h: 300,
						},
					})

					editor.createShape({
						type: 'text',
						x: 0,
						y: 100,
						parentId: clipShapeId,
						props: {
							size: 'l',
							textAlign: 'middle',
							richText: toRichText('This text is clipped to the circle! ✂️'),
						} satisfies Partial<TLTextShapeProps>,
					})

					editor.createShape({
						type: 'geo',
						x: 100,
						y: 290,
						parentId: clipShapeId,
						props: {
							geo: 'rectangle',
							w: 200,
							h: 100,
							fill: 'solid',
							color: 'blue',
							richText: toRichText('Oops you found me!'),
						} satisfies Partial<TLGeoShapeProps>,
					})

					editor.zoomToFit()
				}}
			/>
		</div>
	)
}

/*
Any shape can clip its children by implementing `getClipPath` (the polygon, in local space) and
optionally `shouldClipChild` (which children it applies to). See CircleClipShapeUtil.tsx for the
shape itself; this file wires it into the editor and UI.

[1]
Define the shape util and tool arrays outside the component so they keep the same identity across
renders. A new array on each render would make the editor think its shape utils changed.

[2]
Register the tool with the UI so it has a label, icon, and keyboard shortcut. This is what
`useTools()` returns in the toolbar below.

[3]
The toggle flips a module-level atom that every circle's `shouldClipChild` reads, so one click
changes clipping for all circles. `markEventAsHandled` on pointer down/up stops the canvas from
treating the click as the start of a selection.

[4]
Add the tool to the default toolbar. `useIsToolSelected` highlights it while it's active.

[5]
Override the toolbar and add the toggle button in the `InFrontOfTheCanvas` slot.

[6]
On mount, create a circle with a text shape and a rectangle as children. Both are partly outside
the circle so the clipping is visible right away.
*/
```

## CircleClipShapeTool.tsx

```tsx
import { StateNode, TLPointerEventInfo } from 'tldraw'

export class CircleClipShapeTool extends StateNode {
	static override id = 'circle-clip'

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

	override onPointerDown(info: TLPointerEventInfo) {
		if (info.target !== 'canvas') return

		const { x, y } = this.editor.inputs.getCurrentPagePoint()
		this.editor.createShape({
			type: 'circle-clip',
			x: x - 100,
			y: y - 100,
			props: { w: 200, h: 200 },
		})
	}
}
```

## CircleClipShapeUtil.tsx

```tsx
import {
	BaseBoxShapeUtil,
	Circle2d,
	Geometry2d,
	PI2,
	RecordProps,
	SVGContainer,
	T,
	TLResizeInfo,
	TLShape,
	Vec,
	atom,
	clamp,
	resizeBox,
	toDomPrecision,
} from 'tldraw'

const CIRCLE_CLIP_TYPE = 'circle-clip'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[CIRCLE_CLIP_TYPE]: {
			w: number
			h: number
		}
	}
}

export type CircleClipShape = TLShape<typeof CIRCLE_CLIP_TYPE>

export const isClippingEnabled$ = atom('isClippingEnabled', true)

const STROKE_WIDTH = 3

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

export class CircleClipShapeUtil extends BaseBoxShapeUtil<CircleClipShape> {
	static override type = CIRCLE_CLIP_TYPE
	static override props: RecordProps<CircleClipShape> = {
		w: T.number,
		h: T.number,
	}

	override canBind() {
		return false
	}

	// [1]
	override canReceiveNewChildrenOfType(shape: CircleClipShape) {
		return !shape.isLocked
	}

	override providesBackgroundForChildren(): boolean {
		return true
	}

	override getDefaultProps(): CircleClipShape['props'] {
		return {
			w: 200,
			h: 200,
		}
	}

	override getGeometry(shape: CircleClipShape): Geometry2d {
		const radius = Math.min(shape.props.w, shape.props.h) / 2
		return new Circle2d({
			radius,
			x: shape.props.w / 2 - radius,
			y: shape.props.h / 2 - radius,
			isFilled: true,
		})
	}

	// [2]
	override getClipPath(shape: CircleClipShape): Vec[] | undefined {
		const centerX = shape.props.w / 2
		const centerY = shape.props.h / 2
		const outerRadius = Math.min(shape.props.w, shape.props.h) / 2
		// Inset by half the stroke so children clip to the stroke's inner edge, not its center line.
		const clipRadius = outerRadius - STROKE_WIDTH / 2
		// Roughly one vertex every 8px of circumference.
		const segments = clamp(Math.round((PI2 * clipRadius) / 8), 3, 360)

		const points: Vec[] = []
		for (let i = 0; i < segments; i++) {
			const angle = (i / segments) * Math.PI * 2
			const x = centerX + Math.cos(angle) * clipRadius
			const y = centerY + Math.sin(angle) * clipRadius
			points.push(new Vec(x, y))
		}

		return points
	}

	// [3]
	override shouldClipChild(_child: TLShape): boolean {
		return isClippingEnabled$.get()
	}

	// [4]
	override component(shape: CircleClipShape) {
		const radius = Math.min(shape.props.w, shape.props.h) / 2
		const centerX = shape.props.w / 2
		const centerY = shape.props.h / 2

		const clippingEnabled = isClippingEnabled$.get()

		return (
			<SVGContainer>
				<circle
					cx={toDomPrecision(centerX)}
					cy={toDomPrecision(centerY)}
					r={toDomPrecision(radius)}
					fill={clippingEnabled ? 'rgba(100, 150, 255, 0.1)' : 'rgba(150, 150, 150, 0.1)'}
					stroke={clippingEnabled ? '#4285f4' : '#999'}
					strokeWidth={STROKE_WIDTH}
					strokeDasharray={clippingEnabled ? 'none' : '5,5'}
				/>
				<text
					x={centerX}
					y={centerY + 4}
					textAnchor="middle"
					fontSize="12"
					fill={clippingEnabled ? '#4285f4' : '#999'}
				>
					{clippingEnabled ? '✂️' : '○'}
				</text>
			</SVGContainer>
		)
	}

	override getIndicatorPath(shape: CircleClipShape) {
		const radius = Math.min(shape.props.w, shape.props.h) / 2
		const centerX = shape.props.w / 2
		const centerY = shape.props.h / 2
		const path = new Path2D()
		path.arc(centerX, centerY, radius, 0, Math.PI * 2)
		return path
	}

	override onResize(shape: CircleClipShape, info: TLResizeInfo<CircleClipShape>) {
		return resizeBox(shape, info)
	}
}

/*
[1]
Allow shapes to be dropped into the circle. Dragging a shape over the circle reparents it, at
which point the clip path applies. `providesBackgroundForChildren` makes children's backgrounds
render above this shape rather than behind it.

[2]
`getClipPath` returns a polygon in the shape's local space. The editor transforms it to page
space and intersects it with any ancestor clip paths, so a circle needs to be approximated with
enough vertices to look smooth at the sizes it's used at.

[3]
`shouldClipChild` is only called when `getClipPath` returns a polygon, and lets you exclude some
children (for example arrows, which frames don't clip). Here it reads a module-level atom so a
single toggle turns clipping on and off for every circle at once.

[4]
`component` reads the same atom. Shape components are rendered inside a reactive tracking scope,
so the circle restyles itself when the atom changes without any explicit subscription.
*/
```

## CustomClipping.css

```css
.CustomClipping-toggle {
	position: absolute;
	top: 64px;
	left: 12px;
	pointer-events: all;
	z-index: 1000;
}
```

--------

# Zoom to bounds

Category: Editor API

Keywords: zoom, zoomToBounds, camera, bounds, Box, inset, animation, viewport, programmatic zoom

Move the camera to fit a page-space box in the viewport with `editor.zoomToBounds()`.

`zoomToBounds(bounds, opts)` fits a `Box` (or any `{ x, y, w, h }`) into the viewport. Two boxes are drawn on the canvas, and the buttons zoom to each one or to `Box.Common` of both. The camera keeps the viewport's aspect ratio, so the visible area may be larger than the box you pass. `inset` adds screen-space padding around the box (defaults to `options.zoomToFitPadding`), and `animation` animates the move instead of jumping.

## App.tsx

```tsx
import { Box, createShapeId, Editor, TLComponents, Tldraw, TldrawUiButton, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './zoom-to-bounds.css'

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

const zoomBox1 = new Box(50, 100, 900, 720)
const zoomBox2 = new Box(1000, 500, 500, 400)

function ZoomControls() {
	const editor = useEditor()
	return (
		<div className="tlui-menu control-panel">
			{/* [1] */}
			<TldrawUiButton type="normal" onClick={() => editor.zoomToBounds(zoomBox1, { inset: 72 })}>
				Zoom to violet box
			</TldrawUiButton>
			<TldrawUiButton
				type="normal"
				onClick={() => editor.zoomToBounds(zoomBox2, { inset: 72, animation: { duration: 200 } })}
			>
				Zoom to blue box
			</TldrawUiButton>
			<TldrawUiButton
				type="normal"
				onClick={() =>
					editor.zoomToBounds(Box.Common([zoomBox1, zoomBox2]), {
						inset: 200,
						animation: { duration: 200 },
					})
				}
			>
				Zoom to both boxes
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: ZoomControls,
}

function handleMount(editor: Editor) {
	editor.createShapes([
		{
			id: createShapeId(),
			type: 'geo',
			x: zoomBox1.x,
			y: zoomBox1.y,
			isLocked: true,
			props: { w: zoomBox1.w, h: zoomBox1.h, color: 'violet' },
		},
		{
			id: createShapeId(),
			type: 'geo',
			x: zoomBox2.x,
			y: zoomBox2.y,
			isLocked: true,
			props: { w: zoomBox2.w, h: zoomBox2.h, color: 'blue' },
		},
	])
}

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

/*
[1]
`zoomToBounds` fits the given page-space box into the viewport. The camera keeps the viewport's aspect
ratio, so the visible area is usually larger than the box you pass on one axis. `inset` is screen-space
padding around the box; when omitted the editor uses `options.zoomToFitPadding` (capped relative to the
viewport width). Pass `animation` to animate the move; without it the camera jumps.
*/
```

## zoom-to-bounds.css

```css
.control-panel {
	display: flex;
	flex-direction: row;
	flex-wrap: wrap;
	margin: 8px;
}
```

--------

# Arrow labels

Category: Editor API

Keywords: arrow, label, richText, toRichText, labelPosition, labelColor, font, annotation, text, bend, curved

Create arrows with text labels and control their position, color, and font.

Arrow labels live in the arrow shape's `richText` prop; pass `toRichText('...')` when creating the shape. The example lays out a grid of arrows showing `labelPosition` (a fraction from 0 at the start to 1 at the end), `labelColor` (independent of the arrow's `color`), each `font` option, and a label on a curved arrow made with `bend`.

Try selecting an arrow and dragging its label along the arrow, or double-click a label to edit the text.

## App.tsx

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

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

export default function ArrowLabelsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size > 0) return

					// [1]
					editor.createShapes([
						{
							id: createShapeId(),
							type: 'arrow',
							x: 100,
							y: 100,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('Default label'),
								labelPosition: 0.5,
							},
						},
						// [2]
						{
							id: createShapeId(),
							type: 'arrow',
							x: 100,
							y: 200,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('Start'),
								labelPosition: 0.2,
								color: 'blue',
								labelColor: 'red',
							},
						},
						{
							id: createShapeId(),
							type: 'arrow',
							x: 100,
							y: 300,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('Middle'),
								labelPosition: 0.5,
								color: 'blue',
								labelColor: 'violet',
							},
						},
						{
							id: createShapeId(),
							type: 'arrow',
							x: 100,
							y: 400,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('End'),
								labelPosition: 0.8,
								color: 'blue',
								labelColor: 'green',
							},
						},
						// [3]
						{
							id: createShapeId(),
							type: 'arrow',
							x: 550,
							y: 100,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('Draw font'),
								font: 'draw',
							},
						},
						{
							id: createShapeId(),
							type: 'arrow',
							x: 550,
							y: 200,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('Sans font'),
								font: 'sans',
							},
						},
						{
							id: createShapeId(),
							type: 'arrow',
							x: 550,
							y: 300,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('Serif font'),
								font: 'serif',
							},
						},
						{
							id: createShapeId(),
							type: 'arrow',
							x: 550,
							y: 400,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 300, y: 0 },
								richText: toRichText('Mono font'),
								font: 'mono',
							},
						},
						// [4]
						{
							id: createShapeId(),
							type: 'arrow',
							x: 300,
							y: 475,
							props: {
								start: { x: 0, y: 0 },
								end: { x: 400, y: 150 },
								bend: 50,
								richText: toRichText('Curved arrow'),
								labelPosition: 0.5,
								font: 'sans',
								color: 'violet',
								size: 'm',
							},
						},
					])

					editor.zoomToFit({ animation: { duration: 0 } })
				}}
			/>
		</div>
	)
}

/*
Arrow labels are stored in the arrow's `richText` prop. Use the `toRichText()` helper to
turn a plain string into that format.

[1]
The simplest labeled arrow. `labelPosition` is a fraction along the arrow from 0 (start) to
1 (end); 0.5 is the default and centers the label.

[2]
`labelColor` sets the text color independently of the arrow's `color`, which is useful for
contrast when the arrow itself is a light color.

[3]
`font` picks the label typeface: 'draw' (hand-drawn), 'sans', 'serif', or 'mono'. The `size`
prop, shared with the stroke width, controls the label's font size.

[4]
`bend` curves the arrow, and the label is positioned along the curve rather than the chord.
*/
```

--------

# Create a video shape

Category: Editor API

Keywords: video, asset, assetrecordtype, createassets, local, static, mp4, videoshape

Create a video shape from a locally hosted video by creating a video asset and a shape that references it.

Video shapes reference a `TLVideoAsset` record that holds the source URL and natural dimensions. This example creates the asset with `editor.createAssets`, then creates a `video` shape whose `assetId` points at it. The same pattern is used for images in the local-images example.

## App.tsx

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

const videoWidth = 640
const videoHeight = 360

// Video shapes work like image shapes: the shape references an asset record that holds
// the source URL and natural size, so create the asset first. See the local-images example.
function handleMount(editor: Editor) {
	const assetId = AssetRecordType.createId()
	editor.createAssets([
		{
			id: assetId,
			type: 'video',
			typeName: 'asset',
			props: {
				name: 'fluid.mp4',
				src: '/fluid.mp4',
				w: videoWidth,
				h: videoHeight,
				mimeType: 'video/mp4',
				isAnimated: true,
			},
			meta: {},
		},
	])

	const { x, y } = editor.getViewportPageBounds().center
	editor.createShape({
		type: 'video',
		x: x - videoWidth / 2,
		y: y - videoHeight / 2,
		props: {
			assetId,
			w: videoWidth,
			h: videoHeight,
		},
	})
}

export default function LocalVideosExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw onMount={handleMount} />
		</div>
	)
}
```

--------

# Create an image shape

Category: Editor API

Keywords: image, asset, assetrecordtype, createassets, local, static, png, jpg, imageshape

Create an image shape from a locally hosted image by creating an asset record and a shape that references it.

Image shapes don't store image data themselves. Each one references an asset record that holds the source URL and natural dimensions. This example creates the asset with `editor.createAssets` using `AssetRecordType.createId()` for its id, then creates an image shape with `editor.createShape` whose `assetId` points at it.

The image is served from the app's `public` folder. To let users upload their own images, see the hosted-images example.

## App.tsx

```tsx
import { AssetRecordType, Editor, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
// There's a guide at the bottom of this file!

const imageWidth = 1200
const imageHeight = 675

function handleMount(editor: Editor) {
	// [1]
	const assetId = AssetRecordType.createId()
	editor.createAssets([
		{
			id: assetId,
			type: 'image',
			typeName: 'asset',
			props: {
				name: 'tldraw.png',
				src: '/tldraw.png', // You could also use a data URL here
				w: imageWidth,
				h: imageHeight,
				mimeType: 'image/png',
				isAnimated: false,
			},
			meta: {},
		},
	])

	// [2]
	const { x, y } = editor.getViewportPageBounds().center
	editor.createShape({
		type: 'image',
		x: x - imageWidth / 2,
		y: y - imageHeight / 2,
		props: {
			assetId,
			w: imageWidth,
			h: imageHeight,
		},
	})
}

export default function LocalImagesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw onMount={handleMount} />
		</div>
	)
}

/*
An image shape doesn't hold its own pixels. It points at an asset record via `assetId`, and the asset
holds the source URL and the image's natural size. So to show an image you create the asset first [1]
and then the shape [2].

Here the image is served from this app's `public` folder. Your framework may serve static files
differently, or you might use a data URL. To let users upload their own images, see the hosted-images
example.

[1]
Create the asset record. `AssetRecordType.createId()` gives us an id we can reference from the shape.

[2]
Create the image shape, linked to the asset by `assetId`, and center it in the current viewport. The
shape starts at the image's natural size, but the user can resize it later without touching the asset.
That separation is one reason assets and shapes are different records: many shapes can share one asset.
*/
```

--------

# Custom overlay

Category: Editor API

Keywords: overlay, overlayutil, canvas, render, 2d, cursor

Draw a pointer-following ring on the canvas overlay layer with a custom `OverlayUtil`.

Overlays are the canvas-drawn UI above shapes: selection handles, the brush rectangle, snap indicators, collaborator brushes and scribbles. They render into a Canvas 2D context in page space rather than the React tree, which keeps them cheap during fast interactions.

To add one, subclass `OverlayUtil` and implement `isActive()`, `getOverlays()`, and `render()`, then pass it to `<Tldraw overlayUtils>` alongside `defaultOverlayUtils`. This example adds a pink ring that follows the pointer. Move the mouse and zoom in and out: the ring stays the same size on screen because `render()` scales by the zoom level.

## App.tsx

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

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

// [1]
const overlayUtils = [...defaultOverlayUtils, PointerRingOverlayUtil]

export default function CustomOverlayExample() {
	return (
		<div className="tldraw__editor">
			{/* [2] */}
			<Tldraw overlayUtils={overlayUtils} />
		</div>
	)
}

/*
Overlays are ephemeral UI drawn on top of the canvas — selection handles, the
brush rectangle, snap indicators, and so on. They render into a Canvas 2D
context, not the React tree, so they're cheap even during fast interactions.

To add your own, subclass `OverlayUtil` and implement three methods:

- `isActive()` — whether the overlay should render right now. Checked reactively.
- `getOverlays()` — one or more overlay instances derived from editor state.
- `render(ctx, overlays)` — draw into a page-space canvas context.

See `PointerRingOverlayUtil.ts` for a minimal implementation that draws a ring
following the cursor. `getOverlays()` reads the reactive
`editor.inputs.getCurrentPagePoint()`, so the ring redraws automatically as the
pointer moves. Because the context is in page space, `render()` divides the
ring's radius and line width by the zoom level to keep them a constant size on
screen.

[1]
Register your overlay util alongside `defaultOverlayUtils` so the built-in
overlays (selection, brush, scribble, snap, handles, collaborator brushes and
scribbles) stay intact. Passing an array without them removes those overlays. `options.zIndex`
controls paint order; higher paints on top.

[2]
Pass the array to the `overlayUtils` prop on `<Tldraw>`. Each util is
constructed once when the editor mounts, so define the array at module level.
*/
```

## PointerRingOverlayUtil.ts

```ts
import { OverlayUtil, TLOverlay } from 'tldraw'

interface TLPointerRingOverlay extends TLOverlay {
	props: {
		x: number
		y: number
	}
}

export class PointerRingOverlayUtil extends OverlayUtil<TLPointerRingOverlay> {
	static override type = 'pointer-ring'
	override options = { zIndex: 50 }

	override isActive(): boolean {
		return true
	}

	override getOverlays(): TLPointerRingOverlay[] {
		const { x, y } = this.editor.inputs.getCurrentPagePoint()
		return [{ id: 'pointer-ring', type: 'pointer-ring', props: { x, y } }]
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLPointerRingOverlay[]): void {
		const overlay = overlays[0]
		if (!overlay) return
		const { x, y } = overlay.props
		const zoom = this.editor.getZoomLevel()
		const radius = 24 / zoom

		ctx.lineWidth = 2 / zoom
		ctx.strokeStyle = 'hotpink'
		ctx.beginPath()
		ctx.arc(x, y, radius, 0, Math.PI * 2)
		ctx.stroke()
	}
}
```

--------

# Dynamic tools with setTool and removeTool

Category: Editor API

Keywords: settool, removetool, dynamic tools, runtime, conditional, permissions, feature flags, toolbar

Add and remove a tool from the editor and toolbar at runtime with `setTool` and `removeTool`.

Tools are normally passed to `<Tldraw>` once via the `tools` prop. `editor.setTool(Tool)` and `editor.removeTool(Tool)` let you add and remove tools from the state chart after the editor has mounted, which is useful for permission checks, feature flags, or plugin-style features.

The example adds a heart-stamp tool that isn't installed initially. Click "Add heart tool" to install it (it appears in the toolbar and can be selected with `y`), stamp a few hearts, then click "Remove heart tool" to take it away again. Notice that the toolbar entry is driven by a small atom rather than React state, so the `components` object stays stable.

## App.tsx

```tsx
import {
	atom,
	DefaultToolbar,
	DefaultToolbarContent,
	StateNode,
	TLComponents,
	TLTextShape,
	TLUiAssetUrlOverrides,
	TLUiOverrides,
	Tldraw,
	TldrawUiButton,
	TldrawUiMenuItem,
	toRichText,
	useEditor,
	useIsToolSelected,
	useTools,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './dynamic-tools.css'

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

const OFFSET = 12

// [1]
class HeartTool extends StateNode {
	static override id = 'heart'

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

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

// [2]
const isHeartToolEnabled$ = atom('isHeartToolEnabled', false)

// [3]
const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		tools.heart = {
			id: 'heart',
			icon: 'heart-icon',
			label: 'Heart',
			kbd: 'y',
			onSelect: () => {
				// [4]
				if (!isHeartToolEnabled$.get()) return
				editor.setCurrentTool('heart')
			},
		}
		return tools
	},
}

const customAssetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'heart-icon': '/heart-icon.svg',
	},
}

// [5]
const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isHeartSelected = useIsToolSelected(tools['heart'])
		const isHeartToolEnabled = useValue(isHeartToolEnabled$)

		return (
			<DefaultToolbar {...props}>
				{isHeartToolEnabled && (
					<TldrawUiMenuItem {...tools['heart']} isSelected={isHeartSelected} />
				)}
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	InFrontOfTheCanvas: () => {
		const editor = useEditor()
		const isHeartToolEnabled = useValue(isHeartToolEnabled$)

		const toggleHeartTool = () => {
			if (isHeartToolEnabled) {
				// [6]
				if (editor.getCurrentToolId() === 'heart') {
					editor.setCurrentTool('select')
				}
				editor.removeTool(HeartTool)
			} else {
				// [7]
				editor.setTool(HeartTool)
			}
			isHeartToolEnabled$.set(!isHeartToolEnabled)
		}

		return (
			<div className="toggle-button-container">
				<TldrawUiButton onClick={toggleHeartTool} type="normal">
					{isHeartToolEnabled ? '💔 Remove heart tool' : '💖 Add heart tool'}
				</TldrawUiButton>
			</div>
		)
	},
}

export default function DynamicToolsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				overrides={uiOverrides}
				components={components}
				assetUrls={customAssetUrls}
				// [8]
				onMount={() => {
					isHeartToolEnabled$.set(false)
				}}
			/>
		</div>
	)
}

/*
`editor.setTool` and `editor.removeTool` add and remove tools from the editor's state chart after
it has been created. Use them when a tool's availability depends on runtime conditions such as
permissions or feature flags.

[1]
A minimal tool that stamps a heart at the pointer. It is deliberately not passed to `<Tldraw>` via
the `tools` prop; it is added later with `setTool`.

[2]
Whether the tool is currently installed. Keeping this in an atom lets the toolbar and the toggle
button share it without lifting state into the example component, which would force the
`components` object to be recreated on every change.

[3]
Register the tool with the UI so the toolbar knows its label, icon, and shortcut. This entry can
exist even while the tool is absent from the state chart; the toolbar below decides whether to
show it. The shortcut is `y` because `r` already belongs to the rectangle tool.

[4]
Keyboard shortcuts are registered from the `tools` override whether or not the toolbar shows the
item, so pressing `y` while the tool is uninstalled would call `setCurrentTool` on a state that
doesn't exist and throw. Guard on the atom instead.

[5]
The toolbar reads the atom with `useValue` and only renders the heart item while the tool exists.
The toggle button lives in `InFrontOfTheCanvas` and gets the editor from `useEditor`.

[6]
Removing a tool does not exit it if it's active, so switch to select first. `removeTool` is a
no-op if the tool isn't in the state chart.

[7]
`setTool` constructs the tool and attaches it to the root state. It throws if a tool with the
same id already exists, so don't call it twice without removing first.

[8]
A fresh editor starts without the tool, so reset the flag in case the example remounts.
*/
```

## dynamic-tools.css

```css
.toggle-button-container {
	position: absolute;
	top: 16px;
	left: 50%;
	transform: translateX(-50%);
	display: flex;
	flex-direction: column;
	align-items: center;
	gap: 8px;
	pointer-events: auto;
}
```

--------

# Focus the editor

Category: Editor API

Keywords: focus, blur, autofocus, keyboard shortcuts, multiple editors, scrolling, instance state

Control the editor's focus with `focus()`, `blur()`, and `autoFocus` to gate keyboard shortcuts and scroll capture.

The editor's focus decides whether its keyboard shortcuts respond and whether wheel events pan the canvas. It is related to, but not the same as, the browser's notion of focus (the document's [active element](https://developer.mozilla.org/en-US/docs/Web/API/Document/activeElement)). The browser's focus can't be relied on for this: iframes aren't descendants of their parents, and many menus are portalled elsewhere in the document, so checking whether the active element is inside the `Tldraw` element isn't reliable.

That leaves focus management to you, especially with more than one editor on a page. This example mounts the editor with `autoFocus={false}` and drives focus with `editor.focus()` and `editor.blur()` from a checkbox that stays in sync via `editor.getIsFocused()`. Try typing in the text input while the editor is focused (shortcuts shouldn't fire), and toggle the checkbox to see scrolling switch between the page and the canvas.

## App.tsx

```tsx
import { useState } from 'react'
import { Editor, Tldraw, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './editor-focus.css'

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

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

	// [1]
	const isFocused = useValue('isFocused', () => editor?.getIsFocused() ?? false, [editor])

	return (
		<div className="editor-focus-example">
			<input type="text" placeholder="Test me" />
			<p>
				You should be able to type in this text input without triggering editor shortcuts, even when
				the editor is focused.
			</p>
			<h2>Controlled focus</h2>
			<div className="editor-focus-example__controls">
				<input
					id="focus"
					type="checkbox"
					checked={isFocused}
					onChange={(e) => {
						// [2]
						if (e.target.checked) {
							editor?.focus()
						} else {
							editor?.blur()
						}
					}}
				/>
				<label htmlFor="focus">Focus</label>
			</div>
			<p>
				The checkbox focuses and blurs the editor. Clicking on the canvas also focuses it, which is
				why the checkbox follows the editor&apos;s own focus state.
			</p>
			<p>
				When the editor is focused, its keyboard shortcuts work and scrolling over it moves the
				canvas. When it is not, shortcuts are ignored and the page scrolls instead.
			</p>
			<div className="editor-focus-example__editor">
				{/* [3] */}
				<Tldraw autoFocus={false} onMount={setEditor} />
			</div>
		</div>
	)
}

/*
[1]
`editor.getIsFocused()` is reactive, so reading it through `useValue` keeps the checkbox in sync
whether focus changed through the checkbox or by clicking the canvas.

[2]
`editor.focus()` and `editor.blur()` set the editor's focus state and, by default, also focus or
blur the container element. Pass `{ focusContainer: false }` / `{ blurContainer: false }` to
change only the editor's state.

[3]
`autoFocus={false}` stops the editor from grabbing focus when it mounts, which matters when the
canvas is one of several things on a page (or one of several editors).
*/
```

## editor-focus.css

```css
.editor-focus-example {
	padding: 32px;
	min-height: 120vh;
}

.editor-focus-example__controls {
	display: flex;
	gap: 4px;
}

.editor-focus-example__editor {
	width: 800px;
	max-width: 100%;
	height: 500px;
}

/* The editor adds this class to its container while it has focus. */
.tl-container__focused {
	outline: 1px solid var(--tl-color-primary);
}
```

--------

# Lock camera zoom

Category: Editor API

Keywords: camera, zoom, lock, setcameraoptions, zoomsteps, getzoomlevel, getcameraoptions, viewport, fixed zoom

Lock the camera at its current zoom level by collapsing `zoomSteps` to a single value.

The camera's `zoomSteps` option defines the zoom levels the camera can move between; the smallest and largest steps also bound the zoom range. Setting `zoomSteps` to a single value equal to the current zoom (`editor.setCameraOptions({ zoomSteps: [editor.getZoomLevel()] })`) means every zoom gesture, shortcut, and menu action has nowhere to go, so the zoom stays fixed while panning still works. Restoring `DEFAULT_CAMERA_OPTIONS.zoomSteps` unlocks it.

Press Shift+K to lock the camera at its current zoom, then try scrolling, pinching, or using the zoom menu. Press Shift+K again to unlock.

## App.tsx

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

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

const overrides: TLUiOverrides = {
	actions(editor, actions) {
		actions.lockCameraZoom = {
			id: 'lock-camera-zoom',
			kbd: 'shift+k',
			onSelect() {
				// [1]
				const isLocked = editor.getCameraOptions().zoomSteps.length === 1
				editor.setCameraOptions({
					zoomSteps: isLocked ? DEFAULT_CAMERA_OPTIONS.zoomSteps : [editor.getZoomLevel()],
				})
			},
		}

		return actions
	},
}

export default function LockCameraZoomExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="lock-camera-zoom-example" overrides={overrides} />
		</div>
	)
}

/*
[1]
The camera can only zoom to values in `zoomSteps` (or between the smallest and largest of them). With a
single step equal to the current zoom, every zoom gesture, shortcut, and menu action is a no-op, so the
zoom is effectively locked. Restoring the default steps unlocks it. We use `zoomSteps.length === 1` as
the "is locked" flag so the same shortcut toggles both ways.
*/
```

--------

# Search text on the canvas

Category: Editor API

Keywords: search, text search, find text, keyboard shortcut, helpers, helperButtons, filter shapes, overrides, actions, gettext

Search the text of every shape on the current page and zoom to a result.

Each shape util exposes its text through `getText(shape)`, so the search filters `editor.getCurrentPageShapes()` by that value. Results are listed in the `HelperButtons` UI slot, and clicking one selects the shape and calls `zoomToSelection` to animate the camera to it. A UI action override binds Cmd+F / Ctrl+F to open the panel.

Add some text or shapes with labels, press Cmd+F or Ctrl+F, and start typing. Press Escape to close.

## App.tsx

```tsx
import { TLComponents, TLUiOverrides, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { showSearch, TextSearchPanel } from './TextSearchPanel'
import './text-search.css'

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

// [1]
const components: TLComponents = {
	HelperButtons: TextSearchPanel,
}

// [2]
const overrides: TLUiOverrides = {
	actions(_editor, actions) {
		return {
			...actions,
			'text-search': {
				id: 'text-search',
				label: 'Search',
				kbd: 'cmd+f,ctrl+f',
				onSelect() {
					showSearch.set(true)
				},
			},
		}
	},
}

export default function TextSearchExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="text-search-example" overrides={overrides} components={components} />
		</div>
	)
}

/*
[1]
The search panel renders in the `HelperButtons` slot, which sits at the top left of the canvas under
the menu panel. See TextSearchPanel.tsx for the search itself.

[2]
Registering an action with `kbd: 'cmd+f,ctrl+f'` takes over the browser's find shortcut while the
editor is focused. The action just flips a shared `atom`; the panel reads that atom with `track` so it
shows and hides reactively.
*/
```

## TextSearchPanel.tsx

```tsx
import { useEffect, useRef, useState } from 'react'
import { atom, EASINGS, Editor, TLShape, TldrawUiButton, track, useEditor } from 'tldraw'

export const showSearch = atom('showSearch', false)

interface SearchResult {
	text: string
	shape: TLShape
}

// [1]
function getShapesWithText(editor: Editor, text: string): SearchResult[] {
	if (!text) return []
	const query = text.toLowerCase()
	const results: SearchResult[] = []
	for (const shape of editor.getCurrentPageShapes()) {
		const shapeText = editor.getShapeUtil(shape).getText(shape)
		if (shapeText?.toLowerCase().includes(query)) {
			results.push({ text: shapeText, shape })
		}
	}
	return results.sort((a, b) => a.text.localeCompare(b.text))
}

function moveToShape(editor: Editor, shape: TLShape) {
	editor.setSelectedShapes([shape.id])
	editor.zoomToSelection({
		animation: { duration: 500, easing: EASINGS.easeInOutCubic },
	})
}

function handleKeyDown(e: React.KeyboardEvent) {
	if (e.key === 'Escape') {
		showSearch.set(false)
	}
}

export const TextSearchPanel = track(() => {
	const editor = useEditor()
	const [searchText, setSearchText] = useState('')
	const inputRef = useRef<HTMLInputElement>(null)
	const isVisible = showSearch.get()

	useEffect(() => {
		if (isVisible) {
			setSearchText('')
			inputRef.current?.focus()
		}
	}, [isVisible])

	if (!isVisible) return null

	// [2]
	const results = getShapesWithText(editor, searchText)
	return (
		<div
			className="text-search-panel scroll-light"
			onPointerDown={editor.markEventAsHandled}
			onKeyDown={handleKeyDown}
		>
			<input
				className="text-search-input"
				ref={inputRef}
				onChange={(e) => setSearchText(e.target.value)}
			/>
			{results.map((result) => (
				<TldrawUiButton
					key={result.shape.id}
					type="normal"
					className="text-search-panel-button"
					onClick={() => moveToShape(editor, result.shape)}
				>
					{result.text}
				</TldrawUiButton>
			))}
		</div>
	)
})

/*
[1]
Every shape util can report its text through `getText(shape)`. It returns `undefined` for shapes with
no text, so this works across geo, text, note, arrow, and any custom shape that implements it.

[2]
The component is wrapped in `track`, so calling `getShapesWithText` during render subscribes it to the
page's shapes. Results update live as text on the canvas changes, not just when the query changes.
*/
```

## text-search.css

```css
.text-search-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);
}

.text-search-panel-button {
	border-radius: var(--tl-radius-4);
	outline-offset: -1px;
}

.text-search-input {
	border-radius: var(--tl-radius-2);
	margin: 4px;
}
```

--------

# Shape animation

Category: Editor API

Keywords: animate, animation, shape, easing, transition, movement, rotation, opacity

Animate a shape's position, rotation, and opacity with `animateShape()` and `animateShapes()`.

`editor.animateShape(partial, { animation })` interpolates a shape's `x`, `y`, `rotation`, and `opacity` from their current values to those in the partial over the given `duration`, using an easing function from `EASINGS` (or any `(t) => number`). `animateShapes()` does the same for many shapes at once. Shape props are also interpolated when the shape util implements `getInterpolatedProps`.

Select one shape and try the position, rotation, fade, and combined buttons, or use "Animate multiple shapes" to scatter everything on the page.

## App.tsx

```tsx
import {
	createShapeId,
	EASINGS,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './shape-animation.css'

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

function AnimationControls() {
	const editor = useEditor()

	// [1]
	const animatePosition = () => {
		const shape = editor.getOnlySelectedShape()
		if (!shape) return

		editor.animateShape(
			{ ...shape, x: shape.x + 200, y: shape.y + 100 },
			{ animation: { duration: 800, easing: EASINGS.easeInOutCubic } }
		)
	}

	const animateRotation = () => {
		const shape = editor.getOnlySelectedShape()
		if (!shape) return

		editor.animateShape(
			{ ...shape, rotation: shape.rotation + Math.PI * 2 },
			{ animation: { duration: 1000, easing: EASINGS.easeInOutCubic } }
		)
	}

	const animateFade = () => {
		const shape = editor.getOnlySelectedShape()
		if (!shape) return

		editor.animateShape(
			{ ...shape, opacity: shape.opacity > 0.5 ? 0.2 : 1 },
			{ animation: { duration: 600, easing: EASINGS.easeInOutQuad } }
		)
	}

	const animateAll = () => {
		const shape = editor.getOnlySelectedShape()
		if (!shape) return

		editor.animateShape(
			{
				...shape,
				x: shape.x + 150,
				y: shape.y - 100,
				rotation: shape.rotation + Math.PI,
				opacity: 0.3,
			},
			{ animation: { duration: 1200, easing: EASINGS.easeInOutCubic } }
		)
	}

	// [2]
	const animateMultiple = () => {
		const updates = editor.getCurrentPageShapes().map((shape) => ({
			...shape,
			x: shape.x + (Math.random() - 0.5) * 200,
			y: shape.y + (Math.random() - 0.5) * 200,
			rotation: shape.rotation + (Math.random() - 0.5) * Math.PI,
		}))

		editor.animateShapes(updates, { animation: { duration: 1000, easing: EASINGS.easeOutCubic } })
	}

	const hasOneSelected = useValue(
		'has one selected',
		() => editor.getSelectedShapeIds().length === 1,
		[editor]
	)

	return (
		<div className="tlui-menu animation-controls">
			<TldrawUiButton type="normal" disabled={!hasOneSelected} onClick={animatePosition}>
				Animate position
			</TldrawUiButton>
			<TldrawUiButton type="normal" disabled={!hasOneSelected} onClick={animateRotation}>
				Animate rotation
			</TldrawUiButton>
			<TldrawUiButton type="normal" disabled={!hasOneSelected} onClick={animateFade}>
				Fade in/out
			</TldrawUiButton>
			<TldrawUiButton type="normal" disabled={!hasOneSelected} onClick={animateAll}>
				Animate all
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={animateMultiple}>
				Animate multiple shapes
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: AnimationControls,
}

export default function ShapeAnimationExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				components={components}
				onMount={(editor) => {
					const id = createShapeId()
					editor.createShapes([
						{
							id,
							type: 'geo',
							x: 200,
							y: 200,
							props: {
								w: 100,
								h: 100,
								color: 'blue',
							},
						},
						{
							id: createShapeId(),
							type: 'geo',
							x: 400,
							y: 300,
							props: {
								w: 80,
								h: 80,
								color: 'red',
								geo: 'ellipse',
							},
						},
						{
							id: createShapeId(),
							type: 'geo',
							x: 600,
							y: 200,
							props: {
								w: 120,
								h: 90,
								color: 'green',
								geo: 'triangle',
							},
						},
					])
					editor.select(id)
				}}
			/>
		</div>
	)
}

/*
[1]
`animateShape()` takes a shape partial (here the whole shape spread with new values) plus animation
options, and interpolates `x`, `y`, `rotation`, and `opacity` from the shape's current values to the
targets over `duration`. `easing` accepts any function from `EASINGS`, or your own `(t) => number`.
Props are interpolated too when the shape util implements `getInterpolatedProps`.

[2]
`animateShapes()` does the same for many partials at once, sharing one duration and easing. Starting a
new animation on a shape that's already animating cancels the earlier one for that shape.
*/
```

## shape-animation.css

```css
.animation-controls {
	display: flex;
	flex-wrap: wrap;
	margin: 8px;
}
```

--------

# Z-order

Category: Editor API

Keywords: z-order, index, stacking, layers, reorder, sendToBack, bringToFront, sendBackward, bringForward

Reorder shapes with `sendToBack`, `sendBackward`, `bringForward`, and `bringToFront`.

This example shows how to use the four z-order methods to control shape stacking:

- `editor.sendToBack(ids)` — move shapes to the very bottom
- `editor.bringToFront(ids)` — move shapes to the very top
- `editor.sendBackward(ids)` — move shapes one step down (by default, only past overlapping shapes)
- `editor.bringForward(ids)` — move shapes one step up (by default, only past overlapping shapes)

Select one or more shapes and use the buttons to see the stacking order change. When multiple shapes are selected, their relative order is preserved. For `sendBackward` and `bringForward`, pass `{ considerAllShapes: true }` to move past non-overlapping shapes too.

## App.tsx

```tsx
import { createShapeId, Editor, TLComponents, Tldraw, TldrawUiButton, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './z-order.css'

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

const COLORS = ['red', 'blue', 'green', 'orange'] as const
const SHAPE_SIZE = 150
const OVERLAP = 110

function ZOrderControls() {
	const editor = useEditor()
	return (
		<div className="tlui-menu z-order-controls">
			{/* [1] */}
			<TldrawUiButton type="normal" onClick={() => editor.sendToBack(editor.getSelectedShapeIds())}>
				Send to back
			</TldrawUiButton>
			<TldrawUiButton
				type="normal"
				onClick={() => editor.sendBackward(editor.getSelectedShapeIds())}
			>
				Send backward
			</TldrawUiButton>
			<TldrawUiButton
				type="normal"
				onClick={() => editor.bringForward(editor.getSelectedShapeIds())}
			>
				Bring forward
			</TldrawUiButton>
			<TldrawUiButton
				type="normal"
				onClick={() => editor.bringToFront(editor.getSelectedShapeIds())}
			>
				Bring to front
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: ZOrderControls,
}

function handleMount(editor: Editor) {
	if (editor.getCurrentPageShapeIds().size > 0) return

	editor.createShapes(
		COLORS.map((color, i) => ({
			id: createShapeId(),
			type: 'geo' as const,
			x: 200 + i * (SHAPE_SIZE - OVERLAP),
			y: 200 + i * (SHAPE_SIZE - OVERLAP),
			props: {
				w: SHAPE_SIZE,
				h: SHAPE_SIZE,
				color,
				fill: 'solid' as const,
			},
		}))
	)

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

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

/*
[1]
`sendToBack` and `bringToFront` move shapes to the very bottom or top of their parent. `sendBackward`
and `bringForward` shift them one step, and by default only past shapes they overlap, which is what
you want from a UI button: moving past a shape on the other side of the page would look like nothing
happened. Pass `{ considerAllShapes: true }` to move exactly one position in the z-order regardless.

When several shapes are selected, their relative order is preserved, so they move as a block.
*/
```

## z-order.css

```css
.z-order-controls {
	display: flex;
	flex-direction: row;
	flex-wrap: wrap;
	margin: 8px;
}
```

--------

# Align and distribute shapes

Category: Editor API

Keywords: align, distribute, alignshapes, distributeshapes, layout, position, arrange, horizontal, vertical

Align and distribute selected shapes with `alignShapes` and `distributeShapes`.

The editor exposes the same alignment and distribution operations that the built-in context menu uses. `editor.alignShapes(ids, operation)` accepts `left`, `center-horizontal`, `right`, `top`, `center-vertical`, `bottom`, or `center`, and `editor.distributeShapes(ids, operation)` accepts `horizontal` or `vertical`.

The example creates five shapes and selects them. Try clicking the buttons in the top panel, then use "Reset positions" to put the shapes back. Align operations need at least two selected shapes, and distribute operations need at least three, so change the selection to see the buttons become no-ops.

## App.tsx

```tsx
import { createShapeId, TLComponents, Tldraw, TldrawUiButton, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './align-and-distribute-shapes.css'

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

// [1]
const ALIGN_OPERATIONS = [
	{ operation: 'left', label: 'Align left' },
	{ operation: 'center-horizontal', label: 'Align center H' },
	{ operation: 'right', label: 'Align right' },
	{ operation: 'top', label: 'Align top' },
	{ operation: 'center-vertical', label: 'Align center V' },
	{ operation: 'bottom', label: 'Align bottom' },
	{ operation: 'center', label: 'Align center' },
] as const

const DISTRIBUTE_OPERATIONS = [
	{ operation: 'horizontal', label: 'Distribute horizontal' },
	{ operation: 'vertical', label: 'Distribute vertical' },
] as const

// Original positions of the demo shapes, captured on mount so "Reset positions" can restore them.
const originalPositions = new Map<string, { x: number; y: number }>()

function ControlPanel() {
	const editor = useEditor()

	return (
		<div className="tlui-menu control-panel">
			{ALIGN_OPERATIONS.map(({ operation, label }) => (
				<TldrawUiButton
					type="normal"
					key={operation}
					onClick={() => {
						// [2]
						const selectedIds = editor.getSelectedShapeIds()
						if (selectedIds.length > 1) {
							editor.alignShapes(selectedIds, operation)
						}
					}}
				>
					{label}
				</TldrawUiButton>
			))}
			{DISTRIBUTE_OPERATIONS.map(({ operation, label }) => (
				<TldrawUiButton
					type="normal"
					key={operation}
					onClick={() => {
						// [3]
						const selectedIds = editor.getSelectedShapeIds()
						if (selectedIds.length > 2) {
							editor.distributeShapes(selectedIds, operation)
						}
					}}
				>
					{label}
				</TldrawUiButton>
			))}
			<TldrawUiButton
				type="normal"
				onClick={() => {
					// [4]
					editor.updateShapes(
						editor.getCurrentPageShapes().flatMap((shape) => {
							const originalPos = originalPositions.get(shape.id)
							return originalPos ? [{ ...shape, ...originalPos }] : []
						})
					)
				}}
			>
				Reset positions
			</TldrawUiButton>
		</div>
	)
}

// [5]
const components: TLComponents = {
	TopPanel: ControlPanel,
}

export default function AlignAndDistributeShapesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					const shapes = [
						{
							id: createShapeId(),
							type: 'geo' as const,
							x: 100,
							y: 100,
							props: { w: 100, h: 100, color: 'blue' as const },
						},
						{
							id: createShapeId(),
							type: 'geo' as const,
							x: 300,
							y: 200,
							props: { w: 120, h: 80, color: 'red' as const },
						},
						{
							id: createShapeId(),
							type: 'geo' as const,
							x: 500,
							y: 150,
							props: { w: 80, h: 120, color: 'green' as const },
						},
						{
							id: createShapeId(),
							type: 'geo' as const,
							x: 150,
							y: 400,
							props: { w: 100, h: 100, color: 'violet' as const },
						},
						{
							id: createShapeId(),
							type: 'geo' as const,
							x: 400,
							y: 450,
							props: { w: 90, h: 90, color: 'orange' as const },
						},
					]

					originalPositions.clear()
					for (const shape of shapes) {
						originalPositions.set(shape.id, { x: shape.x, y: shape.y })
					}

					editor.createShapes(shapes)
					editor.selectAll()
				}}
				components={components}
			/>
		</div>
	)
}

/*
[1]
The operation names accepted by `editor.alignShapes` and `editor.distributeShapes`. Listing them
in a typed array lets us render one button per operation.

[2]
`alignShapes` moves the selected shapes so their edges (or centers) line up. It needs at least
two shapes; with fewer there is nothing to align to.

[3]
`distributeShapes` keeps the outermost two shapes where they are and spaces the ones in between
evenly, so it needs at least three shapes to do anything.

[4]
`updateShapes` applies all the position changes in one call, so a single undo restores every
shape.

[5]
Define `components` at module level so the `TopPanel` component identity is stable across renders.
Defining it inline would remount the panel every time the parent re-renders.
*/
```

## align-and-distribute-shapes.css

```css
.control-panel {
	display: flex;
	flex-direction: row;
	flex-wrap: wrap;
	margin: 8px;
}
```

--------

# Conditional culling

Category: Editor API

Keywords: culling, canCull, viewport, performance, glow, shadow, overflow, custom shape

Keep shapes with overflow effects rendered off-screen by overriding `canCull()`.

Culling is an optimization that hides shapes with `display: none` once their bounds leave the viewport. Shapes with visuals that extend beyond their bounds, like glows or drop shadows, pop in and out at the viewport edge when they're culled.

Override `canCull()` on your `ShapeUtil` to opt individual shapes out. In this example both shapes have the same glow, and each has a checkbox that toggles a `preventCulling` prop read by `canCull()`.

Try panning the canvas horizontally: the shape with "Prevent culling" checked stays visible as it slides off-screen, while the other disappears abruptly once its bounds leave the viewport.

## App.tsx

```tsx
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import './conditional-culling.css'

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

const GLOW_SHAPE_TYPE = 'glow-shape'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[GLOW_SHAPE_TYPE]: { w: number; h: number; preventCulling: boolean }
	}
}

type GlowShape = TLShape<typeof GLOW_SHAPE_TYPE>

class GlowShapeUtil extends BaseBoxShapeUtil<GlowShape> {
	static override type = GLOW_SHAPE_TYPE
	static override props: RecordProps<GlowShape> = {
		w: T.number,
		h: T.number,
		preventCulling: T.boolean,
	}

	getDefaultProps(): GlowShape['props'] {
		return {
			w: 150,
			h: 100,
			preventCulling: false,
		}
	}

	// [1]
	override canCull(shape: GlowShape) {
		return !shape.props.preventCulling
	}

	// [2]
	component(shape: GlowShape) {
		return (
			<HTMLContainer className="glow-shape">
				<label>
					<input
						type="checkbox"
						checked={shape.props.preventCulling}
						onChange={() =>
							this.editor.updateShape({
								id: shape.id,
								type: GLOW_SHAPE_TYPE,
								props: { preventCulling: !shape.props.preventCulling },
							})
						}
						onPointerDown={(e) => e.stopPropagation()}
					/>
					Prevent culling
				</label>
			</HTMLContainer>
		)
	}

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

const shapeUtils = [GlowShapeUtil]

export default function ConditionalCullingExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				onMount={(editor) => {
					// [3]
					editor.createShape({
						type: GLOW_SHAPE_TYPE,
						x: 200,
						y: 100,
						props: { preventCulling: true },
					})
					editor.createShape({
						type: GLOW_SHAPE_TYPE,
						x: 200,
						y: 350,
						props: { preventCulling: false },
					})
				}}
			/>
		</div>
	)
}

/*
Culling hides a shape (`display: none`) once its bounds leave the viewport. Shapes whose visuals
extend past their bounds (glows, drop shadows, other overflow) pop in and out at the viewport
edge when that happens. Returning false from `canCull()` keeps the shape visible off-screen.

[1]
`canCull()` is called per shape, so the decision can depend on the shape's own props (or any
other state). Here a checkbox on the shape flips it.

[2]
Both shapes render the same glow; only the checkbox differs. Stopping pointer-down propagation
lets the checkbox receive the click instead of the select tool starting a drag.

[3]
Two shapes stacked vertically so you can pan sideways and watch both leave the viewport at once.
The one with "Prevent culling" checked keeps its glow visible past the edge; the other vanishes
as soon as its bounds are off-screen.

Culled shapes skip layout and paint, so only opt out of culling for shapes that genuinely
need it.
*/
```

## conditional-culling.css

```css
.glow-shape {
	width: 100%;
	height: 100%;
	background-color: #2f80ed;
	border-radius: 8px;
	display: flex;
	align-items: center;
	justify-content: center;
	box-shadow: 0 0 80px 50px rgba(47, 128, 237, 0.8);
	pointer-events: all;
}

.glow-shape label {
	display: flex;
	align-items: center;
	gap: 8px;
	color: white;
	font-weight: bold;
	font-size: 13px;
	cursor: pointer;
}

.glow-shape input {
	width: 16px;
	height: 16px;
	cursor: pointer;
}
```

--------

# Dimensions HUD

Category: Editor API

Keywords: overlay, overlayutil, hud, dimensions, resize, bounds, gesture

Show a live width × height pill next to the selection with a custom `OverlayUtil`.

A non-interactive HUD that reads the editor's selection state and draws a dimensions label on the canvas overlay layer. Because overlays render in page space, the label follows pan and zoom without any `pageToScreen` plumbing; screen-sized values like padding and font size are divided by the zoom level instead.

Select a shape and resize or rotate it: the label sticks to the edge closest to the bottom of the page and flips so it's never upside down. Select several shapes to see it fall back to the selection bounds.

## App.tsx

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

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

// [1]
const overlayUtils = [...defaultOverlayUtils, DimensionsHudOverlayUtil]

export default function DimensionsHudExample() {
	return (
		<div className="tldraw__editor">
			{/* [2] */}
			<Tldraw overlayUtils={overlayUtils} />
		</div>
	)
}

/*
This example adds a non-interactive dimensions label that follows the current
selection. The label is implemented as a custom `OverlayUtil`, so it renders in
the editor's canvas overlay layer rather than in the React tree.

`DimensionsHudOverlayUtil.ts` does three things:

- `isActive()` subscribes to the current selection and skips work when nothing
  is selected.
- `getOverlays()` derives the label's page-space position, dimensions, and
  rotation from the selected shape or selection bounds.
- `render()` draws the pill with Canvas 2D APIs.

[1]
Register the custom overlay util after `defaultOverlayUtils` so the built-in
overlays remain enabled. The util's `options.zIndex` controls where it appears
relative to the selection handles and other canvas overlays.

[2]
Pass the overlay util array to the `overlayUtils` prop on `<Tldraw>`. Utils are
constructed once on mount, so define the array at module level.
*/
```

## DimensionsHudOverlayUtil.ts

```ts
import { Box, OverlayUtil, type TLOverlay, Vec } from 'tldraw'

interface TLDimensionsHudOverlay extends TLOverlay {
	props: {
		x: number
		y: number
		w: number
		h: number
		rotation: number
	}
}

const LABEL_PADDING = 20
const PI2 = Math.PI * 2

type LabelEdge = 'top' | 'right' | 'bottom' | 'left'

// [1]
function getLabelEdge(rotation: number): LabelEdge {
	const quarterTurn = Math.round(rotation / (Math.PI / 2))
	const normalizedQuarterTurn = ((quarterTurn % 4) + 4) % 4

	switch (normalizedQuarterTurn) {
		case 0:
			return 'bottom'
		case 1:
			return 'right'
		case 2:
			return 'top'
		default:
			return 'left'
	}
}

// [2]
function getReadableRotation(rotation: number): number {
	const normalizedRotation = ((rotation + Math.PI) % PI2) - Math.PI
	return Math.abs(normalizedRotation) > Math.PI / 2 ? rotation + Math.PI : rotation
}

// [3]
function getLabelPointForEdge(edge: LabelEdge, bounds: Box, padding: number): Vec {
	switch (edge) {
		case 'bottom':
			return new Vec(bounds.midX, bounds.maxY + padding)
		case 'right':
			return new Vec(bounds.maxX + padding, bounds.midY)
		case 'top':
			return new Vec(bounds.midX, bounds.minY - padding)
		case 'left':
			return new Vec(bounds.minX - padding, bounds.midY)
	}
}

export class DimensionsHudOverlayUtil extends OverlayUtil<TLDimensionsHudOverlay> {
	static override type = 'dimensions-hud'
	override options = { zIndex: 950 }

	override isActive(): boolean {
		return this.editor.getSelectedShapeIds().length > 0
	}

	override getOverlays(): TLDimensionsHudOverlay[] {
		const selectedShapeIds = this.editor.getSelectedShapeIds()

		if (selectedShapeIds.length === 0) return []

		// [4]
		if (selectedShapeIds.length > 1) {
			const bounds = this.editor.getSelectionPageBounds()
			if (!bounds) return []
			const zoom = this.editor.getZoomLevel()

			return [
				{
					id: 'dimensions-hud',
					type: 'dimensions-hud',
					props: {
						x: bounds.midX,
						y: bounds.maxY + LABEL_PADDING / zoom,
						w: Math.round(bounds.width),
						h: Math.round(bounds.height),
						rotation: 0,
					},
				},
			]
		}

		const shape = this.editor.getShape(selectedShapeIds[0])
		if (!shape) return []

		// [5]
		const bounds = this.editor.getShapeGeometry(shape).bounds
		const transform = this.editor.getShapePageTransform(shape)
		const zoom = this.editor.getZoomLevel()
		const rotation = transform.rotation()

		// [6]
		const padding = LABEL_PADDING / zoom

		const labelEdge = getLabelEdge(rotation)
		const localLabelPoint = getLabelPointForEdge(labelEdge, bounds, padding)

		const labelPoint = transform.applyToPoint(localLabelPoint)
		const labelRotation =
			labelEdge === 'left' || labelEdge === 'right' ? rotation + Math.PI / 2 : rotation
		const readableLabelRotation = getReadableRotation(labelRotation)

		return [
			{
				id: 'dimensions-hud',
				type: 'dimensions-hud',
				props: {
					x: labelPoint.x,
					y: labelPoint.y,
					w: Math.round(bounds.width),
					h: Math.round(bounds.height),
					rotation: readableLabelRotation,
				},
			},
		]
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLDimensionsHudOverlay[]): void {
		const overlay = overlays[0]
		if (!overlay) return

		const colors = this.editor.getCurrentTheme().colors[this.editor.getColorMode()]

		const { x, y, w, h, rotation } = overlay.props
		const zoom = this.editor.getZoomLevel()

		ctx.save()

		// [7]
		ctx.textAlign = 'center'
		ctx.textBaseline = 'middle'
		ctx.font = `${10 / zoom}px sans-serif`

		const dimensionsLabel = `${w} × ${h}`
		const metrics = ctx.measureText(dimensionsLabel)
		const textHeight = metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent
		const textWidth = metrics.width
		const pillPaddingX = 5 / zoom
		const pillWidth = textWidth + pillPaddingX * 2
		const pillHeight = textHeight * 2

		ctx.translate(x, y)
		ctx.rotate(rotation)

		ctx.fillStyle = colors.selectionStroke
		ctx.beginPath()
		ctx.roundRect(-pillWidth / 2, -pillHeight / 2, pillWidth, pillHeight, pillHeight / 3.5)
		ctx.fill()

		ctx.fillStyle = colors.selectedContrast
		ctx.fillText(dimensionsLabel, 0, 0)
		ctx.restore()
	}
}

/*
[1]
Pick the side of the selected shape that is closest to the bottom of the page.
This keeps the label near the user's expected resize readout position even when
the shape is rotated.

[2]
Flip the label by half a turn when it would otherwise be upside down.

[3]
Calculate the label point in the shape's local coordinate space. The shape's
page transform converts it to page space later.

[4]
Multiple selections do not have a single rotation, so the label uses the
selection's page bounds and stays horizontal.

[5]
Use shape geometry bounds for the width and height. These are local bounds, so
they represent the unrotated dimensions the user is editing.

[6]
Overlay drawing happens in page space. Divide fixed screen-space values by the
zoom level so padding, text, and the pill size look consistent while zooming.

[7]
Save and restore the canvas context around all drawing state because overlay
utils share the same Canvas 2D context.
*/
```

--------

# Lasso select tool

Category: Editor API

Keywords: lasso, selection, freehand, overlays, custom tool, state machine, atom, statenode, getstrokepoints, getsvgpathfromstrokepoints, overlayutil

Select shapes by drawing a freehand lasso around them with a custom tool and a canvas overlay.

The tool is a `StateNode` with an `idle` child and a `lassoing` child. While lassoing, the tool stores the pointer's page-space points in an `atom`, so anything that reads them re-renders as they change. A custom `OverlayUtil` reads that atom, smooths the points with `getStrokePoints`, converts them to an SVG path with `getSvgPathFromStrokePoints`, and draws the result onto the canvas overlay with `Path2D`.

On pointer up, the tool selects every shape whose page-space vertices are all inside the lasso polygon (`pointInPolygon`) and whose outline does not cross the lasso (`polygonsIntersect`), then switches back to the select tool.

Press `W` or pick the lasso from the toolbar, then drag a loop around some shapes. Only shapes fully enclosed by the loop are selected.

## App.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	Tldraw,
	TldrawUiMenuItem,
	TLUiOverrides,
	useIsToolSelected,
	useTools,
} from 'tldraw'
import { LassoOverlayUtil } from './LassoOverlayUtil'
import { LassoSelectTool } from './LassoSelectTool'
// There's a guide at the bottom of this file!

//[1]
const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		tools['lasso-select'] = {
			id: 'lasso-select',
			icon: 'color',
			label: 'Lasso select',
			kbd: 'w', //w for wrangle 🤠
			onSelect: () => {
				editor.setCurrentTool('lasso-select')
			},
		}
		return tools
	},
}

//[2]
const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isLassoSelected = useIsToolSelected(tools['lasso-select'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['lasso-select']} isSelected={isLassoSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	KeyboardShortcutsDialog: (props) => {
		const tools = useTools()
		return (
			<DefaultKeyboardShortcutsDialog {...props}>
				<DefaultKeyboardShortcutsDialogContent />
				<TldrawUiMenuItem {...tools['lasso-select']} />
			</DefaultKeyboardShortcutsDialog>
		)
	},
}

//[3]
const overlayUtils = [LassoOverlayUtil]

export default function LassoSelectToolExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				tools={[LassoSelectTool]}
				overrides={uiOverrides}
				components={components}
				overlayUtils={overlayUtils}
				persistenceKey="lasso-select-example"
			/>
		</div>
	)
}

/*
The tool itself lives in LassoSelectTool.ts and the overlay in LassoOverlayUtil.ts. For a simpler
selection tool, see the `MiniSelectTool` and `MicroSelectTool` in the only-editor example.

[1]
The UI override registers the tool with the UI so it has an icon, label, and keyboard shortcut. See
the add-tool-to-toolbar example for more on this.

[2]
The `components` override adds the tool to the toolbar and the keyboard shortcuts dialog. These are
defined at module level so `<Tldraw>` doesn't see a new object on every render.

[3]
`LassoOverlayUtil` draws the lasso onto the canvas overlay. It reads the tool's `points` atom, smooths
the points with `getStrokePoints`, converts them to an SVG path, and paints it with a `Path2D`.
*/
```

## LassoOverlayUtil.ts

```ts
import { getStrokePoints, getSvgPathFromStrokePoints, OverlayUtil, TLOverlay } from 'tldraw'
import { LassoingState } from './LassoSelectTool'

interface TLLassoOverlay extends TLOverlay {
	props: {
		svgPath: string
	}
}

export class LassoOverlayUtil extends OverlayUtil<TLLassoOverlay> {
	static override type = 'lasso'

	override isActive(): boolean {
		return this.editor.isIn('lasso-select.lassoing')
	}

	override getOverlays(): TLLassoOverlay[] {
		const lassoing = this.editor.getStateDescendant<LassoingState>('lasso-select.lassoing')
		const points = lassoing?.points.get() ?? []
		if (points.length === 0) return []

		const smoothedPoints = getStrokePoints(points)
		const svgPath = getSvgPathFromStrokePoints(smoothedPoints, true)
		if (!svgPath) return []

		return [
			{
				id: 'lasso',
				type: 'lasso',
				props: { svgPath },
			},
		]
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLLassoOverlay[]): void {
		const overlay = overlays[0]
		if (!overlay) return

		const zoom = this.editor.getZoomLevel()
		const colors = this.editor.getCurrentTheme().colors[this.editor.getColorMode()]
		const path = new Path2D(overlay.props.svgPath)

		ctx.globalAlpha = 0.5
		ctx.fillStyle = colors.selectionFill
		ctx.fill(path)
		ctx.globalAlpha = 1

		ctx.lineWidth = 2 / zoom
		ctx.strokeStyle = colors.selectionStroke
		ctx.stroke(path)
	}
}
```

## LassoSelectTool.ts

```ts
import {
	atom,
	pointInPolygon,
	polygonsIntersect,
	StateNode,
	TLPointerEventInfo,
	TLShape,
	VecModel,
} from 'tldraw'

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

export class LassoSelectTool extends StateNode {
	static override id = 'lasso-select'
	static override children() {
		return [IdleState, LassoingState]
	}
	static override initial = 'idle'
}

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

	override onPointerDown(info: TLPointerEventInfo) {
		const { editor } = this

		editor.selectNone()
		this.parent.transition('lassoing', info)
	}
}

//[1]
export class LassoingState extends StateNode {
	static override id = 'lassoing'

	info = {} as TLPointerEventInfo

	markId = null as null | string

	//[a]
	points = atom<VecModel[]>('lasso points', [])

	override onEnter(info: TLPointerEventInfo) {
		this.points.set([])
		this.markId = null
		this.info = info

		this.startLasso()
	}

	private startLasso() {
		this.markId = this.editor.markHistoryStoppingPoint('lasso start')
	}

	//[b]
	override onPointerMove(): void {
		this.addPointToLasso()
	}

	private addPointToLasso() {
		const { inputs } = this.editor

		const { x, y, z } = inputs.getCurrentPagePoint().toFixed()
		const newPoint = { x, y, z }

		this.points.set([...this.points.get(), newPoint])
	}

	//[c]
	private getShapesInLasso() {
		const { editor } = this

		const shapes = editor.getCurrentPageRenderingShapesSorted()
		const lassoPoints = this.points.get()
		const shapesInLasso = shapes.filter((shape) => {
			return this.doesLassoFullyContainShape(lassoPoints, shape)
		})

		return shapesInLasso
	}

	private doesLassoFullyContainShape(lassoPoints: VecModel[], shape: TLShape): boolean {
		const { editor } = this

		const geometry = editor.getShapeGeometry(shape)
		const pageTransform = editor.getShapePageTransform(shape)
		const shapeVertices = pageTransform.applyToPoints(geometry.vertices)

		const allVerticesInside = shapeVertices.every((vertex) => {
			return pointInPolygon(vertex, lassoPoints)
		})

		if (!allVerticesInside) {
			return false
		}

		// All vertices can be inside the lasso while an edge still crosses it, e.g. a
		// wide shape inside a concave lasso. Reject those too.
		if (geometry.isClosed) {
			if (polygonsIntersect(shapeVertices, lassoPoints)) {
				return false
			}
		}

		return true
	}

	override onPointerUp(): void {
		this.complete()
	}

	override onComplete() {
		this.complete()
	}

	//[d]
	complete() {
		const { editor } = this

		const shapesInLasso = this.getShapesInLasso()
		editor.setSelectedShapes(shapesInLasso)

		editor.setCurrentTool('select')
	}
}

/*
For a general guide on building tools with child states, see the `MiniSelectTool` in the only-editor example.

[1]
`LassoingState` is active from pointer down until pointer up.

    [a]
    `points` is an `atom` rather than a plain array so that `LassoOverlayUtil`, which reads it while
    rendering the canvas overlay, re-renders whenever a point is added.

    [b]
    Each pointer move appends the current page-space pointer position to `points`.

    [c]
    A shape counts as inside the lasso when every one of its page-space vertices is inside the lasso
    polygon and none of its edges cross the lasso outline.

    [d]
    On pointer up (or when the editor completes the interaction some other way, e.g. a menu opens or
    the page changes), select the enclosed shapes and hand back to the select tool.

If you wanted to take the lasso further, you could:
- live update the selection as the user moves the mouse, similar to how the default select and brush select tools work
- use modifier keys to add or subtract from the selection instead of just setting the selection
- properly handle what happens when we select a shape that's grouped with other shapes (do we select the shape within the group or move up a level and select the entire group? what about layers?)
- extend the default selection tool to allow for lasso selection when a hotkey is pressed, similar to the brush select tool
- add a little bit of leeway to the lasso selection logic to allow for shapes that are mostly, but not fully, enclosed in the lasso to be selected

*/
```

--------

# Locked shapes

Category: Editor API

Keywords: lock, unlock, locked, islocked, ignoreshapelock, selectlockedshapes, template, background, togglelock, editor.run, programmatic, read-only

Lock shapes against user editing, move them from code with `ignoreShapeLock`, and let users select them with the `selectLockedShapes` option.

The blue shapes are locked on mount with `editor.toggleLock`. Users can't drag, resize, edit, or delete them, and left-clicking one does nothing (right-click still selects it).

- **Scatter / Reset** wrap `editor.updateShapes` in `editor.run(fn, { ignoreShapeLock: true })`, which lifts the lock guard for the callback so code can move shapes the user can't.
- **Allow selecting locked shapes** toggles the `selectLockedShapes` editor option, which lets locked shapes be picked by left-click, brush, and scribble selection. It only affects selection; the lock guards on moving, resizing, editing, and deleting still apply. Editor options are fixed for the editor's lifetime, so flipping the toggle passes a new `options` object to `<Tldraw>` and the editor is recreated (the store, and so the shapes, are kept).

## App.tsx

```tsx
import { useMemo } from 'react'
import {
	atom,
	createShapeId,
	Editor,
	Tldraw,
	TldrawUiButton,
	TLComponents,
	TLShapeId,
	toRichText,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './locked-shapes.css'

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

const TEMPLATE_IDS: TLShapeId[] = [
	createShapeId('t1'),
	createShapeId('t2'),
	createShapeId('t3'),
	createShapeId('t4'),
]

const HOME_POSITIONS = [
	{ x: 100, y: 100 },
	{ x: 250, y: 100 },
	{ x: 100, y: 250 },
	{ x: 250, y: 250 },
]

// [1]
const selectLockedShapes$ = atom('selectLockedShapes', false)

function ControlPanel() {
	const editor = useEditor()
	const selectLockedShapes = useValue(selectLockedShapes$)

	// [2]
	const moveTemplates = (positions: { x: number; y: number }[]) => {
		editor.run(
			() => {
				editor.updateShapes(TEMPLATE_IDS.map((id, i) => ({ id, type: 'geo', ...positions[i] })))
			},
			{ ignoreShapeLock: true }
		)
	}

	const handleScatter = () => {
		moveTemplates(
			TEMPLATE_IDS.map(() => ({ x: 50 + Math.random() * 300, y: 50 + Math.random() * 300 }))
		)
	}

	return (
		<div className="tlui-menu locked-shapes-panel">
			<label title="When on, left-click and brush selection include locked shapes.">
				<input
					type="checkbox"
					checked={selectLockedShapes}
					onChange={() => selectLockedShapes$.set(!selectLockedShapes)}
				/>
				Allow selecting locked shapes
			</label>
			<TldrawUiButton type="normal" onClick={handleScatter}>
				Scatter
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={() => moveTemplates(HOME_POSITIONS)}>
				Reset
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: ControlPanel,
}

// [3]
function handleMount(editor: Editor) {
	if (!editor.getShape(TEMPLATE_IDS[0])) {
		const props = {
			geo: 'rectangle' as const,
			w: 130,
			h: 130,
			dash: 'dashed' as const,
			color: 'light-blue' as const,
			fill: 'semi' as const,
			richText: toRichText('Locked'),
		}
		editor.createShapes(
			TEMPLATE_IDS.map((id, i) => ({ id, type: 'geo', ...HOME_POSITIONS[i], props }))
		)
		editor.toggleLock(TEMPLATE_IDS)
	}
	editor.zoomToFit({ animation: { duration: 0 } })
}

export default function LockedShapesExample() {
	const selectLockedShapes = useValue(selectLockedShapes$)
	const options = useMemo(() => ({ selectLockedShapes }), [selectLockedShapes])

	return (
		<div className="tldraw__editor">
			<Tldraw components={components} options={options} onMount={handleMount} />
		</div>
	)
}

/*
Locked shapes can't be moved, resized, edited, or deleted by the user. This example shows two ways the
editor lets you work around that:

- `editor.run(fn, { ignoreShapeLock: true })` lifts the lock guard for the duration of the callback, so
  code can move shapes the user can't drag.
- The `selectLockedShapes` editor option lets locked shapes be selected by left-click, brush, and
  scribble selection. Only selection changes; the lock guards still apply to everything else.

Try it: left-click a blue shape and nothing happens (right-click still selects it). Turn on "Allow
selecting locked shapes" and left-click or brush across one; it selects, but the handles won't move it.
Scatter and Reset move the shapes regardless of the toggle.

[1]
The toggle lives in a module-level `atom` so both the control panel (inside the editor) and the example
component (outside it) can read it with `useValue`. Editor options are read-only once the editor is
created, so the example passes a new `options` object to `<Tldraw>`, which recreates the editor with
the new setting. The store is preserved, so the shapes and camera survive the swap.

[2]
Both buttons wrap `updateShapes` in `editor.run` with `ignoreShapeLock: true`. Without it, updates to
locked shapes are silently dropped.

[3]
On mount, create a 2x2 grid of shapes and lock them with `toggleLock`. `onMount` runs again whenever the
editor is recreated, so it checks whether the shapes already exist first.
*/
```

## locked-shapes.css

```css
.locked-shapes-panel {
	display: flex;
	gap: 8px;
	align-items: center;
	padding: 4px 8px;
}

.locked-shapes-panel label {
	display: flex;
	align-items: center;
	gap: 6px;
	font-size: 13px;
	cursor: pointer;
	user-select: none;
}
```

--------

# Reactive inputs

Category: Editor API

Keywords: inputs manager, pointer tracking, mouse position, velocity, usevalue, reactive state, screen point, page point, origin point, pointer events, modifier keys

Track pointer positions, velocity, and modifier keys reactively with `editor.inputs` and `useValue`.

`editor.inputs` exposes the current, previous, and origin pointer positions in both screen and page space, the pointer velocity, and the state of the modifier keys. Each getter (`getCurrentPagePoint()`, `getPointerVelocity()`, `getShiftKey()`, and so on) reads a reactive atom, so wrapping a call in `useValue` subscribes the component and re-renders it whenever the value changes.

Move the pointer around the canvas and hold modifier keys to watch the panel update. Origin points only change on pointer down.

## App.tsx

```tsx
import { TLComponents, Tldraw, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './reactive-inputs.css'

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

const components: TLComponents = {
	TopPanel: ReactiveInputsPanel,
}

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

function formatNum(n: number, decimals: number): string {
	const s = n.toFixed(decimals)
	return n >= 0 ? ` ${s}` : s
}

function ReactiveInputsPanel() {
	const editor = useEditor()

	// [1]
	const currentScreenPoint = useValue(
		'current screen point',
		() => editor.inputs.getCurrentScreenPoint(),
		[editor]
	)
	const currentPagePoint = useValue(
		'current page point',
		() => editor.inputs.getCurrentPagePoint(),
		[editor]
	)
	const previousScreenPoint = useValue(
		'previous screen point',
		() => editor.inputs.getPreviousScreenPoint(),
		[editor]
	)
	const previousPagePoint = useValue(
		'previous page point',
		() => editor.inputs.getPreviousPagePoint(),
		[editor]
	)
	const originScreenPoint = useValue(
		'origin screen point',
		() => editor.inputs.getOriginScreenPoint(),
		[editor]
	)
	const originPagePoint = useValue('origin page point', () => editor.inputs.getOriginPagePoint(), [
		editor,
	])
	const pointerVelocity = useValue('pointer velocity', () => editor.inputs.getPointerVelocity(), [
		editor,
	])

	// [2]
	const shiftKey = useValue('shift key', () => editor.inputs.getShiftKey(), [editor])
	const ctrlKey = useValue('ctrl key', () => editor.inputs.getCtrlKey(), [editor])
	const altKey = useValue('alt key', () => editor.inputs.getAltKey(), [editor])
	const metaKey = useValue('meta key', () => editor.inputs.getMetaKey(), [editor])
	const accelKey = useValue('accel key', () => editor.inputs.getAccelKey(), [editor])

	return (
		<div className="tlui-menu reactive-inputs-panel">
			<div className="reactive-inputs-content">
				{/* [3] */}
				<div className="input-group">
					<div className="input-label">Screen point</div>
					<div className="input-value">
						{formatNum(currentScreenPoint.x, 0)}, {formatNum(currentScreenPoint.y, 0)}
					</div>
				</div>

				<div className="input-group">
					<div className="input-label">Page point</div>
					<div className="input-value">
						{formatNum(currentPagePoint.x, 0)}, {formatNum(currentPagePoint.y, 0)}
					</div>
				</div>

				<div className="input-group">
					<div className="input-label">Prev screen</div>
					<div className="input-value">
						{formatNum(previousScreenPoint.x, 0)}, {formatNum(previousScreenPoint.y, 0)}
					</div>
				</div>

				<div className="input-group">
					<div className="input-label">Prev page</div>
					<div className="input-value">
						{formatNum(previousPagePoint.x, 0)}, {formatNum(previousPagePoint.y, 0)}
					</div>
				</div>

				<div className="input-group">
					<div className="input-label">Origin screen</div>
					<div className="input-value">
						{formatNum(originScreenPoint.x, 0)}, {formatNum(originScreenPoint.y, 0)}
					</div>
				</div>

				<div className="input-group">
					<div className="input-label">Origin page</div>
					<div className="input-value">
						{formatNum(originPagePoint.x, 0)}, {formatNum(originPagePoint.y, 0)}
					</div>
				</div>

				{/* [4] */}
				<div className="input-group">
					<div className="input-label">Velocity</div>
					<div className="input-value">
						{formatNum(pointerVelocity.x, 2)}, {formatNum(pointerVelocity.y, 2)}
						<span className="input-hint"> px/ms</span>
					</div>
				</div>

				<div className="input-group">
					<div className="input-label">Modifiers</div>
					<div className="modifier-keys">
						<span className="modifier-key" data-active={shiftKey}>
							Shift
						</span>
						<span className="modifier-key" data-active={ctrlKey}>
							Ctrl
						</span>
						<span className="modifier-key" data-active={altKey}>
							Alt
						</span>
						<span className="modifier-key" data-active={metaKey}>
							Meta
						</span>
						<span className="modifier-key" data-active={accelKey}>
							Accel
						</span>
					</div>
				</div>
			</div>
		</div>
	)
}
/*
[1]
`editor.inputs` exposes pointer state through getters (`getCurrentPagePoint()`, `getOriginScreenPoint()`,
and so on) that read reactive atoms. Reading them inside `useValue` subscribes the component, so it
re-renders whenever the pointer moves. Reading them outside a reactive context still works but won't
update the UI.

[2]
Modifier keys are reactive too. `getAccelKey()` is the platform accelerator (Cmd on Mac, Ctrl elsewhere),
which is what you want for cross-platform shortcuts.

[3]
Screen points are relative to the editor's container. Page points are in canvas coordinates, so they
account for the camera's pan and zoom. Origin points are where the last pointer down happened.

[4]
Pointer velocity is updated by the tick manager, in pixels per millisecond. It's useful for detecting
flicks or driving physics-style interactions.
*/
```

## reactive-inputs.css

```css
/* tlui-menu provides the native panel background, radius, and shadow. */
.reactive-inputs-panel {
	margin: 8px;
	padding: var(--tl-space-2);
	pointer-events: all;
}

.reactive-inputs-content {
	display: flex;
	flex-wrap: wrap;
	gap: var(--tl-space-2);
	align-items: center;
}

.input-group {
	display: flex;
	align-items: baseline;
	gap: var(--tl-space-1);
	padding: var(--tl-space-1) var(--tl-space-3);
	background: var(--tl-color-muted-2);
	border-radius: var(--tl-radius-2);
}

.input-label {
	font-size: 12px;
	color: var(--tl-color-text);
	white-space: nowrap;
}

.input-value {
	font-size: 10px;
	color: var(--tl-color-text);
	white-space: nowrap;
	font-variant-numeric: tabular-nums;
	min-width: 80px;
}

.input-hint {
	font-size: 11px;
	color: var(--tl-color-text-3);
}

.modifier-keys {
	display: flex;
	flex-wrap: wrap;
	gap: var(--tl-space-1);
}

.modifier-key {
	display: inline-block;
	padding: var(--tl-space-1) var(--tl-space-2);
	font-size: 11px;
	background: var(--tl-color-muted-1);
	color: var(--tl-color-text-3);
	border-radius: var(--tl-radius-1);
}

.modifier-key[data-active='true'] {
	background: var(--tl-color-selected);
	color: var(--tl-color-selected-contrast);
}
```

--------

# Replace a built-in overlay

Category: Editor API

Keywords: overlay, overlayutil, brush, selection, custom, render

Replace the built-in selection brush by subclassing `BrushOverlayUtil` and overriding its `render` method.

Every canvas overlay (the selection brush, scribble, snap indicators, shape handles) is an `OverlayUtil` subclass you can replace. This example extends the built-in `BrushOverlayUtil` and overrides `render` to draw a dashed purple rectangle instead of the default. Because the subclass inherits the `brush` type, passing it in `overlayUtils` replaces the default brush; `<Tldraw>` merges custom utils over the defaults by type.

Drag-select on the canvas to see it.

## App.tsx

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

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

// [1]
const overlayUtils = [DashedBrushOverlayUtil]

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

/*
The canvas overlays (brush, scribble, snap indicators, selection handles, and so on) are all
`OverlayUtil` subclasses. To replace one, subclass the built-in util and override the methods you
want to change.

`DashedBrushOverlayUtil.ts` extends `BrushOverlayUtil` and overrides `render` to draw a dashed purple
rectangle. `getOverlays`, `isActive`, and the static `type` are inherited, so it activates exactly when
the built-in brush would. Try drag-selecting a region on the canvas.

[1]
`<Tldraw>` merges the overlay utils you pass with the defaults, and a custom util whose static `type`
matches a default replaces it. Since our subclass inherits `type = 'brush'`, passing it alone is enough
to swap out the built-in brush. `shapeUtils` and `bindingUtils` merge by static `type` the same
way; `tools` merge by static `id`.
*/
```

## DashedBrushOverlayUtil.ts

```ts
import { BrushOverlayUtil, TLBrushOverlay } from 'tldraw'

export class DashedBrushOverlayUtil extends BrushOverlayUtil {
	override render(ctx: CanvasRenderingContext2D, overlays: TLBrushOverlay[]): void {
		const overlay = overlays[0]
		if (!overlay) return
		const { x, y, w, h } = overlay.props
		const zoom = this.editor.getZoomLevel()

		ctx.fillStyle = 'rgba(147, 51, 234, 0.08)'
		ctx.fillRect(x, y, w, h)

		ctx.save()
		ctx.lineWidth = 2 / zoom
		ctx.setLineDash([8 / zoom, 4 / zoom])
		ctx.strokeStyle = 'rgb(147, 51, 234)'
		ctx.strokeRect(x, y, w, h)
		ctx.restore()
	}
}
```

--------

# Toggle focus mode

Category: Editor API

Keywords: focus mode, isfocusmode, updateinstancestate, distraction free, hide ui, onmount

Enable focus mode on mount with `updateInstanceState`.

Focus mode hides the default UI so only the canvas is visible. It's a flag on the editor's instance state, so `editor.updateInstanceState({ isFocusMode: true })` turns it on and the UI responds. Users can toggle it themselves with `Cmd/Ctrl+.` or the exit button that focus mode leaves in the corner.

## App.tsx

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

export default function FocusModeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [1]
					editor.updateInstanceState({ isFocusMode: true })
				}}
			/>
		</div>
	)
}

/*
[1]
Focus mode is a flag on the editor's instance state. `updateInstanceState` sets it; the default UI
reads it and hides everything except a small exit button. When a `persistenceKey` is used, this
flag is preserved as a user preference, so setting it in `onMount` forces it on regardless.
*/
```

--------

# Hovered overlay

Category: Editor API

Keywords: overlay, overlaymanager, hover, hit test, selection, handle, reactive

Read the canvas overlay under the pointer with `editor.overlays.getHoveredOverlay()`.

The `OverlayManager` on `editor.overlays` tracks every active canvas overlay (selection handles, resize corners, rotation handles, shape handles) and which one is under the pointer. `getHoveredOverlay()` is reactive, so this example reads it with `useValue` and prints its type and id in the top panel. Select a shape, then hover its handles to see the readout update. `getOverlayAtPoint(point)` does the same hit test for an arbitrary page point.

## App.tsx

```tsx
import { TLComponents, Tldraw, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './hovered-overlay.css'

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

// [1]
function HoveredOverlayReadout() {
	const editor = useEditor()
	const hovered = useValue('hoveredOverlay', () => editor.overlays.getHoveredOverlay(), [editor])

	return (
		<div className="hovered-overlay-readout">
			{hovered ? (
				<>
					<div>
						<span>type</span>
						<code>{hovered.type}</code>
					</div>
					<div>
						<span>id</span>
						<code>{hovered.id}</code>
					</div>
				</>
			) : (
				<div className="hovered-overlay-readout__empty">Select a shape, then hover its handles</div>
			)}
		</div>
	)
}

// [2]
const components: TLComponents = {
	TopPanel: HoveredOverlayReadout,
}

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

/*
The editor exposes an `OverlayManager` on `editor.overlays` that tracks every
active canvas overlay — selection handles, resize corners, rotation handles,
shape handles, and so on. It gives you reactive access to the overlay the user
is hovering and hit-testing at an arbitrary page point.

Key methods on `editor.overlays`:

- `getHoveredOverlay()` — the `TLOverlay` currently under the pointer, or null.
  Reactive: updates as the pointer moves.
- `getOverlayAtPoint(point, margin?)` — hit test any page-space point against
  all interactive overlays. Returns the topmost match, or null.
- `getCurrentOverlays()` — every active overlay in paint order.
- `getOverlayGeometry(overlay)` — cached hit-test geometry for an overlay.

[1]
Read `editor.overlays.getHoveredOverlay()` inside `useValue` so the component
re-renders whenever the hovered overlay changes. Select a shape to produce
handles, then hover one to see its type (for example `selection_foreground` or
`shape_handle`) and its id.

[2]
Mount the readout into the `TopPanel` component slot.
*/
```

## hovered-overlay.css

```css
.hovered-overlay-readout {
	background: var(--color-panel);
	border: 1px solid var(--color-divider);
	border-radius: 8px;
	padding: 8px 12px;
	margin: 8px;
	font-size: 12px;
	color: var(--color-text);
	pointer-events: none;
	display: flex;
	flex-direction: column;
	gap: 4px;
	min-width: 220px;
}

.hovered-overlay-readout > div {
	display: flex;
	gap: 8px;
	align-items: baseline;
}

.hovered-overlay-readout span {
	color: var(--color-text-3);
	font-size: 11px;
	text-transform: uppercase;
	letter-spacing: 0.5px;
	width: 36px;
}

.hovered-overlay-readout code {
	font-family: var(--tl-font-mono, monospace);
	font-size: 12px;
}

.hovered-overlay-readout__empty {
	color: var(--color-text-3);
	font-style: italic;
}
```

--------

# Interaction end callback

Category: Editor API

Keywords: callback, interaction, drag, resize, rotate, tool, oninteractionend, translating, setcurrenttool, programmatic

Run custom logic when a programmatically started drag ends with `onInteractionEnd`.

When a tool starts one of the select tool's interactions itself, for example `editor.setCurrentTool('select.translating', info)`, the `onInteractionEnd` field in `info` controls what happens when the interaction finishes. Pass a tool id string to report that tool as the current one while the drag runs (and return to it if tool lock is on), or a function to run arbitrary code.

This example's tool creates a square on click and immediately starts translating it. Click and drag anywhere: when you release, the callback changes the fill to a pattern and returns to the tool so the next click creates another square.

## App.tsx

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

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

// [1]
class QuickShapeTool extends StateNode {
	static override id = 'quick-shape'

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

	override onPointerDown(info: TLPointerEventInfo) {
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		const shapeId = createShapeId()

		this.editor.createShape({
			id: shapeId,
			type: 'geo',
			x: currentPagePoint.x - 50,
			y: currentPagePoint.y - 50,
			props: { w: 100, h: 100, fill: 'solid' },
		})

		this.editor.setSelectedShapes([shapeId])

		// [2]
		this.editor.setCurrentTool('select.translating', {
			...info,
			target: 'shape',
			shape: this.editor.getShape(shapeId),
			isCreating: true,
			// [3]
			onInteractionEnd: () => {
				this.editor.updateShape({
					id: shapeId,
					type: 'geo',
					props: { fill: 'pattern' },
				})
				this.editor.setCurrentTool('quick-shape')
			},
		})
	}
}

const tools = [QuickShapeTool]

export default function InteractionEndExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw tools={tools} initialState="quick-shape" hideUi />
		</div>
	)
}

/*
[1]
A tool that creates a shape on pointer down and immediately hands off to the select tool's
translating state, so the shape follows the pointer until it's released.

[2]
`select.translating` is normally entered from `select.pointing_shape`. Entering it directly needs
the same info: the pointer event, the target shape, and `isCreating`, which tells the state that
the shape was just created so it won't Alt-clone it and will treat the drag as part of creation.

[3]
`onInteractionEnd` runs when the drag finishes. Passing a string such as 'quick-shape' mainly
masks the current tool id, so the UI keeps showing that tool during the drag; it only switches
back to it on completion when tool lock is on. Passing a function lets you do more first. Here we swap the fill
to a pattern and then return to this tool so the next click creates another shape.
*/
```

--------

# Performance hooks

Category: Editor API

Keywords: performance, fps, frame, interaction, camera, resize, translate, perf, monitoring, devtools

Subscribe to `editor.performance` events to show frame time stats for interactions and camera moves.

`editor.performance.on(event, fn)` subscribes to performance events and returns an unsubscribe function. This example listens for `interaction-end`, which fires when a translate, resize, rotate, or draw finishes, and `camera-end`, which fires once panning or zooming settles. Both include frame time stats (average, p95, p99, fps) plus context like shape counts and zoom level, which the panel renders.

It also creates a `PerformanceApiAdapter`, which mirrors the same events into the browser's Performance API as `tldraw:*` marks and measures so they show up in a DevTools performance recording.

Drag a shape, or pan and zoom the canvas, and watch the panel update.

## App.tsx

```tsx
import { useEffect, useState } from 'react'
import {
	Editor,
	PerformanceApiAdapter,
	TLCameraEndPerfEvent,
	TLComponents,
	TLInteractionEndPerfEvent,
	TLPerfFrameTimeStats,
	Tldraw,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './performance-hooks.css'

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

function FrameTimeStats({ event }: { event: TLPerfFrameTimeStats }) {
	return (
		<div className="perf-section">
			<div className="perf-section-title">Frame times</div>
			<div className="perf-row">
				<span className="perf-label">Duration</span>
				<span className="perf-value">{event.duration.toFixed(0)}ms</span>
			</div>
			<div className="perf-row">
				<span className="perf-label">FPS</span>
				<span className="perf-value">{event.fps.toFixed(1)}</span>
			</div>
			<div className="perf-row">
				<span className="perf-label">Frames</span>
				<span className="perf-value">{event.frameCount}</span>
			</div>
			<div className="perf-row">
				<span className="perf-label">Avg</span>
				<span className="perf-value">{event.avgFrameTime.toFixed(1)}ms</span>
			</div>
			<div className="perf-row">
				<span className="perf-label">p95</span>
				<span className="perf-value">{event.p95FrameTime.toFixed(1)}ms</span>
			</div>
		</div>
	)
}

type LastEvent =
	| { kind: 'interaction'; event: TLInteractionEndPerfEvent }
	| { kind: 'camera'; event: TLCameraEndPerfEvent }

// [1]
function PerfPanel() {
	const editor = useEditor()
	const [last, setLast] = useState<LastEvent | null>(null)

	useEffect(() => {
		// [2]
		const unsubs = [
			editor.performance.on('interaction-end', (event) => {
				setLast({ kind: 'interaction', event })
			}),
			editor.performance.on('camera-end', (event) => {
				setLast({ kind: 'camera', event })
			}),
		]

		// [3]
		const adapter = new PerformanceApiAdapter(editor.performance)

		return () => {
			unsubs.forEach((unsub) => unsub())
			adapter.dispose()
		}
	}, [editor])

	return (
		<div className="perf-panel">
			{last ? (
				<>
					<div className="perf-section">
						<div className="perf-section-title">
							{last.kind === 'interaction'
								? `Interaction: ${last.event.name}`
								: `Camera: ${last.event.type}`}
						</div>
					</div>
					<FrameTimeStats event={last.event} />
					{last.kind === 'interaction' ? (
						<div className="perf-section">
							<div className="perf-section-title">Context</div>
							{Object.entries(last.event.selectedShapeTypes).map(([type, count]) => (
								<div className="perf-row" key={type}>
									<span className="perf-label">{type}</span>
									<span className="perf-value">{count}</span>
								</div>
							))}
							<div className="perf-row">
								<span className="perf-label">All shapes</span>
								<span className="perf-value">{last.event.shapeCount}</span>
							</div>
							<div className="perf-row">
								<span className="perf-label">Zoom</span>
								<span className="perf-value">{(last.event.zoomLevel * 100).toFixed(0)}%</span>
							</div>
						</div>
					) : (
						<div className="perf-section">
							<div className="perf-row">
								<span className="perf-label">Visible shapes</span>
								<span className="perf-value">{last.event.visibleShapeCount}</span>
							</div>
							<div className="perf-row">
								<span className="perf-label">Culled shapes</span>
								<span className="perf-value">{last.event.culledShapeCount}</span>
							</div>
							<div className="perf-row">
								<span className="perf-label">Zoom</span>
								<span className="perf-value">{(last.event.zoomLevel * 100).toFixed(0)}%</span>
							</div>
						</div>
					)}
				</>
			) : (
				<div className="perf-hint">Drag a shape or pan the canvas to see performance stats</div>
			)}
		</div>
	)
}

const components: TLComponents = {
	InFrontOfTheCanvas: PerfPanel,
}

function handleMount(editor: Editor) {
	editor.createShapes([
		{ type: 'geo', x: 100, y: 100, props: { w: 200, h: 200, fill: 'solid' } },
		{ type: 'geo', x: 400, y: 100, props: { w: 150, h: 150, geo: 'ellipse', fill: 'solid' } },
		{ type: 'geo', x: 200, y: 350, props: { w: 250, h: 100, geo: 'diamond', fill: 'solid' } },
	])
}

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

/*
[1]
The panel lives in the `InFrontOfTheCanvas` slot so it can use `useEditor`. It shows only the most
recent event; each new one replaces the last.

[2]
`editor.performance.on('interaction-end', fn)` fires when any interaction completes (translate,
resize, rotate, draw, and so on). `camera-end` fires once panning or zooming has settled. Both carry
frame time stats (avg, p95, p99, fps) plus context such as shape counts and zoom level. `on` returns
an unsubscribe function, which the effect cleanup calls.

[3]
`PerformanceApiAdapter` mirrors the same events into the browser's Performance API with
`performance.mark()` and `performance.measure()`. Record in the DevTools performance tab while
interacting and you'll see measures like `tldraw:interaction:translating` in the timings lane. It's
optional; dispose it when you're done.
*/
```

## performance-hooks.css

```css
.perf-panel {
	position: absolute;
	bottom: 64px;
	right: 8px;
	display: flex;
	flex-direction: column;
	gap: 12px;
	padding: 8px 12px;
	font-size: 12px;
	min-width: 200px;
	background-color: var(--tl-color-panel);
	border-radius: var(--tl-radius-3);
	box-shadow: var(--tl-shadow-2);
	pointer-events: none;
	z-index: var(--tl-layer-panels);
}

.perf-section {
	display: flex;
	flex-direction: column;
	gap: 3px;
}

.perf-section-title {
	font-size: 12px;
	margin-bottom: 2px;
}

.perf-row {
	display: flex;
	justify-content: space-between;
	gap: 12px;
}

.perf-label {
	opacity: 0.6;
}

.perf-value {
	font-family: var(--tl-font-mono);
	font-size: 11px;
}

.perf-hint {
	opacity: 0.5;
}
```

--------

# Selection bounds

Category: Editor API

Keywords: selection, bounds, rotation, geometry, getselectionpagebounds, getselectionrotatedpagebounds, getselectionrotation

Visualize the difference between `getSelectionPageBounds()` and `getSelectionRotatedPageBounds()` for the current selection.

`getSelectionPageBounds()` returns the smallest upright rectangle around the selection; `getSelectionRotatedPageBounds()` returns a box aligned to the selection's shared rotation, which is what the visible selection handles use. This example draws both over the canvas with an `InFrontOfTheCanvas` component that converts page bounds to viewport pixels using `pageToViewport()` and the zoom level.

Select the single rotated shape, the group with a shared rotation, and the two ungrouped shapes with different rotations to see when the two boxes differ and when the rotated box falls back to axis-aligned.

## App.tsx

```tsx
import { Editor, TLComponents, Tldraw, createShapeId, toRichText, track, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './selection-bounds.css'

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

const DEMO_IDS = {
	blue: createShapeId('selection-bounds-blue'),
	greenA: createShapeId('selection-bounds-green-a'),
	greenB: createShapeId('selection-bounds-green-b'),
	greenGroup: createShapeId('selection-bounds-green-group'),
	purple: createShapeId('selection-bounds-purple'),
	red: createShapeId('selection-bounds-red'),
	hint: createShapeId('selection-bounds-hint'),
} as const

const ALL_DEMO_IDS = Object.values(DEMO_IDS)
const SAME_ROTATION = Math.PI / 6

const DEMO_SHAPES: Parameters<Editor['createShapes']>[0] = [
	{
		id: DEMO_IDS.blue,
		type: 'geo' as const,
		x: 120,
		y: 250,
		rotation: SAME_ROTATION,
		props: {
			geo: 'rectangle' as const,
			w: 180,
			h: 110,
			color: 'blue' as const,
			fill: 'semi' as const,
			dash: 'draw' as const,
		},
	},
	{
		id: DEMO_IDS.greenA,
		type: 'geo' as const,
		x: 430,
		y: 205,
		props: {
			geo: 'rectangle' as const,
			w: 140,
			h: 80,
			color: 'green' as const,
			fill: 'semi' as const,
			dash: 'solid' as const,
		},
	},
	{
		id: DEMO_IDS.greenB,
		type: 'geo' as const,
		x: 610,
		y: 245,
		props: {
			geo: 'rectangle' as const,
			w: 120,
			h: 70,
			color: 'green' as const,
			fill: 'semi' as const,
			dash: 'solid' as const,
		},
	},
	{
		id: DEMO_IDS.purple,
		type: 'geo' as const,
		x: 880,
		y: 205,
		rotation: Math.PI / 8,
		props: {
			geo: 'rectangle' as const,
			w: 130,
			h: 80,
			color: 'violet' as const,
			fill: 'semi' as const,
			dash: 'solid' as const,
		},
	},
	{
		id: DEMO_IDS.red,
		type: 'geo' as const,
		x: 1040,
		y: 260,
		rotation: -Math.PI / 10,
		props: {
			geo: 'rectangle' as const,
			w: 130,
			h: 80,
			color: 'red' as const,
			fill: 'semi' as const,
			dash: 'solid' as const,
		},
	},
]

function seedDemoContent(editor: Editor) {
	const existingDemoShapeIds = ALL_DEMO_IDS.filter((id) => editor.getShape(id))

	if (existingDemoShapeIds.length) {
		editor.deleteShapes(existingDemoShapeIds)
	}

	editor.createShapes([
		...DEMO_SHAPES,
		{
			id: DEMO_IDS.hint,
			type: 'text' as const,
			x: 880,
			y: 340,
			props: {
				richText: toRichText('⬆ Select both boxes,\nthen rotate them!'),
				color: 'grey' as const,
				size: 's' as const,
				autoSize: true,
			},
		},
	])
	editor.groupShapes([DEMO_IDS.greenA, DEMO_IDS.greenB], {
		groupId: DEMO_IDS.greenGroup,
		select: false,
	})
	editor.updateShapes([{ id: DEMO_IDS.greenGroup, type: 'group', rotation: SAME_ROTATION }])
	editor.select(DEMO_IDS.blue)
	editor.zoomToFit({ animation: { duration: 0 } })
}

const SelectionBoundsOverlay = track(() => {
	const editor = useEditor()
	const axisAlignedBounds = editor.getSelectionPageBounds() // [1]
	const rotatedBounds = editor.getSelectionRotatedPageBounds() // [2]

	if (!axisAlignedBounds || !rotatedBounds) return null

	// [3]
	const zoom = editor.getZoomLevel()
	const rotation = editor.getSelectionRotation()
	const axisAlignedViewportPoint = editor.pageToViewport(axisAlignedBounds.point)
	const rotatedViewportPoint = editor.pageToViewport(rotatedBounds.point)

	return (
		<>
			<div
				className="selection-bounds-box selection-bounds-box--axis"
				style={{
					width: axisAlignedBounds.width * zoom,
					height: axisAlignedBounds.height * zoom,
					transform: `translate(${axisAlignedViewportPoint.x}px, ${axisAlignedViewportPoint.y}px)`,
				}}
			/>
			<div
				className="selection-bounds-box selection-bounds-box--rotated"
				style={{
					width: rotatedBounds.width * zoom,
					height: rotatedBounds.height * zoom,
					transform: `translate(${rotatedViewportPoint.x}px, ${rotatedViewportPoint.y}px) rotate(${rotation}rad)`,
				}}
			/>
		</>
	)
})

function BoundsKey() {
	return (
		<div className="selection-bounds-key">
			<div className="selection-bounds-key-item">
				<div className="selection-bounds-key-swatch selection-bounds-key-swatch--axis" />
				<span>getSelectionPageBounds — smallest upright rectangle</span>
			</div>
			<div className="selection-bounds-key-item">
				<div className="selection-bounds-key-swatch selection-bounds-key-swatch--rotated" />
				<span>getSelectionRotatedPageBounds — aligned to selection rotation</span>
			</div>
		</div>
	)
}

const components: TLComponents = {
	InFrontOfTheCanvas: SelectionBoundsOverlay,
	TopPanel: BoundsKey,
}

export default function SelectionBoundsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="selection-bounds-example"
				components={components}
				onMount={(editor) => {
					if (ALL_DEMO_IDS.every((id) => editor.getShape(id))) {
						return
					}

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

/*
The editor keeps two kinds of bounds for the current selection.

[1]
`getSelectionPageBounds()` is the axis-aligned bounding box (blue dashed). It has zero rotation and is
the smallest upright rectangle containing every selected shape. It's used for hit testing and culling,
not for the visible selection UI.

[2]
`getSelectionRotatedPageBounds()` is the rotated selection box (amber solid). When the selected shapes
share one rotation, this box follows it, which is why the resize handles on two equally rotated shapes
line up with the shapes' own axes. When rotations differ there's no sensible shared angle, so it falls
back to the axis-aligned box.

[3]
Both boxes are in page space. `pageToViewport()` converts their origins to viewport pixels, and the sizes
are scaled by the zoom level, so plain HTML elements can be laid over the canvas. The component is
wrapped in `track` so it re-renders whenever the selection or camera changes.

Try selecting each demo:
1. The blue shape: a single rotated shape, where the two boxes differ.
2. The green group: two shapes with a shared rotation, so the rotated box still follows their angle.
3. The purple and red pair: two ungrouped shapes with different rotations, so the rotated box collapses
   to the axis-aligned one. Rotate one of them on its own to see how the axis-aligned box changes while
   the rotated box stays aligned to the page.
*/
```

## selection-bounds.css

```css
.selection-bounds-box {
	position: absolute;
	top: 0;
	left: 0;
	pointer-events: none;
	transform-origin: top left;
}

.selection-bounds-box--axis {
	border: 2px dashed rgba(45, 116, 255, 0.95);
	background: rgba(45, 116, 255, 0.08);
	z-index: 9998;
}

.selection-bounds-box--rotated {
	border: 2px solid rgba(237, 137, 54, 0.95);
	background: rgba(237, 137, 54, 0.12);
	z-index: 9999;
}

.selection-bounds-key {
	display: flex;
	flex-direction: column;
	gap: 4px;
	padding: 8px 12px;
	font-size: 12px;
	font-family: monospace;
	pointer-events: none;
}
.selection-bounds-key-item {
	display: flex;
	align-items: center;
	gap: 6px;
}

.selection-bounds-key-swatch {
	width: 16px;
	height: 10px;
	border-radius: 2px;
}

.selection-bounds-key-swatch--axis {
	border: 2px dashed rgba(45, 116, 255, 0.95);
	background: rgba(45, 116, 255, 0.08);
}

.selection-bounds-key-swatch--rotated {
	border: 2px solid rgba(237, 137, 54, 0.95);
	background: rgba(237, 137, 54, 0.12);
}
```

--------

# Easter egg styles

Category: Editor API

Keywords: easter egg, white, color, fill, lined-fill, label, scale, hidden styles, keyboard shortcuts

Set style values that are hidden or hard to find in the default style panel.

Several style values are valid on shapes but are not prominent in the default UI. Some have keyboard shortcuts; all can be set through the shape's props:

- **White** color (`Alt+T`), which the color picker leaves out
- **Fill** (`Alt+F`), a solid fill in the shape's full color, and **lined fill** (`Alt+Shift+F`), a slightly lighter solid variant, both in the fill picker's overflow dropdown
- **Label color**, a separate color for a shape's label text, with no picker at all
- **Scale**, a multiplier for stroke width and text size that the "Dynamic size" preference sets automatically

The example creates one shape for each. Try selecting a shape and pressing the shortcuts to see the styles change.

## App.tsx

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

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

export default function EasterEggStylesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					editor.createShapes([
						// [1]
						{
							type: 'geo',
							x: 0,
							y: 0,
							props: {
								geo: 'rectangle',
								w: 250,
								h: 250,
								color: 'blue',
								fill: 'fill',
								richText: toRichText('Fill\n(Alt+F)'),
							},
						},
						{
							type: 'geo',
							x: 300,
							y: 0,
							props: {
								geo: 'rectangle',
								w: 250,
								h: 250,
								color: 'blue',
								fill: 'lined-fill',
								richText: toRichText('Lined fill\n(Alt+Shift+F)'),
							},
						},
						// [2]
						{
							type: 'geo',
							x: 600,
							y: 0,
							props: {
								geo: 'rectangle',
								w: 250,
								h: 250,
								color: 'white',
								fill: 'fill',
								richText: toRichText('White\n(Alt+T)'),
							},
						},
						// [3]
						{
							type: 'geo',
							x: 900,
							y: 0,
							props: {
								geo: 'rectangle',
								w: 250,
								h: 250,
								color: 'blue',
								richText: toRichText('Label color'),
								labelColor: 'red',
							},
						},
						// [4]
						{
							type: 'geo',
							x: 1200,
							y: 0,
							props: {
								geo: 'rectangle',
								w: 250,
								h: 250,
								color: 'blue',
								scale: 2.5,
								richText: toRichText('Scale'),
							},
						},
					])

					editor.zoomToFit()
				}}
			/>
		</div>
	)
}

/*
Some style values are valid on shapes but are hidden or hard to find in the default style panel.
They can still be set programmatically or, for some, with a keyboard shortcut.

[1]
`fill: 'fill'` (Alt+F) is a solid fill in the shape's full color rather than the tinted 'solid'
fill; `fill: 'lined-fill'` (Alt+Shift+F) is a slightly lighter solid variant. Both are tucked
away in the fill picker's overflow dropdown.

[2]
`color: 'white'` (Alt+T) is a white color option not shown in the color picker.

[3]
`labelColor` sets the label text color independently of the shape's `color`. The default style
panel has no picker for it, so it can only be set programmatically.

[4]
`scale` multiplies the shape's stroke width and text size without changing `w`/`h`. The "Dynamic
size" preference sets it automatically based on zoom when creating shapes; here it's set directly.
*/
```

--------

# Toolbar groups

Category: UI & theming

Keywords: toolbar, toolbar groups, TldrawUiMenuGroup, DefaultToolbar, customize toolbar, toolbar items, toolbar layout, orientation

Split the toolbar into labelled groups with dividers between them.

Pass children to `DefaultToolbar` to replace its default items. Wrap related items in `TldrawUiMenuGroup` to draw a divider between groups; the built-in `*ToolbarItem` components (`SelectToolbarItem`, `DrawToolbarItem`, `RectangleToolbarItem`, and so on) give you the standard tools. Any menu item works in the toolbar too. Here the first group is a plain `TldrawUiMenuItem` that toggles the toolbar between horizontal and vertical, so you can see how groups lay out in both orientations.

## App.tsx

```tsx
import { useMemo, useState } from 'react'
import {
	ArrowDownToolbarItem,
	ArrowLeftToolbarItem,
	ArrowRightToolbarItem,
	ArrowUpToolbarItem,
	CloudToolbarItem,
	DefaultToolbar,
	DiamondToolbarItem,
	DrawToolbarItem,
	EllipseToolbarItem,
	EraserToolbarItem,
	HandToolbarItem,
	HexagonToolbarItem,
	HighlightToolbarItem,
	LaserToolbarItem,
	OvalToolbarItem,
	RectangleToolbarItem,
	RhombusToolbarItem,
	SelectToolbarItem,
	StarToolbarItem,
	TLComponents,
	Tldraw,
	TldrawUiMenuGroup,
	TldrawUiMenuItem,
	TriangleToolbarItem,
} from 'tldraw'
import 'tldraw/tldraw.css'

export default function ToolbarGroupsExample() {
	const [orientation, setOrientation] = useState<'horizontal' | 'vertical'>('horizontal')

	// [1]
	const components = useMemo((): TLComponents => {
		return {
			Toolbar: () => (
				<DefaultToolbar orientation={orientation}>
					{/* [2] */}
					<TldrawUiMenuGroup id="orientation">
						<TldrawUiMenuItem
							id="orientation"
							onSelect={() =>
								setOrientation(orientation === 'horizontal' ? 'vertical' : 'horizontal')
							}
							label="Toggle orientation"
							icon={<span style={{ fontSize: '2em' }}>🔄</span>}
						/>
					</TldrawUiMenuGroup>
					<TldrawUiMenuGroup id="controls">
						<SelectToolbarItem />
						<HandToolbarItem />
						<EraserToolbarItem />
					</TldrawUiMenuGroup>
					<TldrawUiMenuGroup id="pens">
						<DrawToolbarItem />
						<HighlightToolbarItem />
						<LaserToolbarItem />
					</TldrawUiMenuGroup>
					<TldrawUiMenuGroup id="shapes">
						<RectangleToolbarItem />
						<EllipseToolbarItem />
						<TriangleToolbarItem />
						<DiamondToolbarItem />
						<HexagonToolbarItem />
						<OvalToolbarItem />
						<RhombusToolbarItem />
						<StarToolbarItem />
						<CloudToolbarItem />
					</TldrawUiMenuGroup>
					<TldrawUiMenuGroup id="arrows">
						<ArrowLeftToolbarItem />
						<ArrowUpToolbarItem />
						<ArrowDownToolbarItem />
						<ArrowRightToolbarItem />
					</TldrawUiMenuGroup>
				</DefaultToolbar>
			),
		}
	}, [orientation])

	return (
		<div className="tldraw__editor">
			<Tldraw components={components} />
		</div>
	)
}

/*
[1]
The toolbar component closes over `orientation`, so we rebuild the components
object with `useMemo` when it changes. Everything else in the toolbar comes from
the built-in `*ToolbarItem` components, which read the tools from context.

[2]
`TldrawUiMenuGroup` draws a divider between groups of items. Any menu item works
inside the toolbar, not just tool items; here the first group is a plain
`TldrawUiMenuItem` that flips the toolbar's orientation. Try it: the groups
stack vertically and the overflow menu moves with them.
*/
```

--------

# Vertical toolbar

Category: UI & theming

Keywords: vertical toolbar, toolbar orientation, DefaultToolbar, components override, layout

Move the toolbar from the bottom of the screen to a vertical strip on the left.

`DefaultToolbar` takes an `orientation` prop. Override the `Toolbar` slot with a component that renders `<DefaultToolbar orientation="vertical" />` and the toolbar, its groups, and its overflow menu all switch to a vertical layout. To also change which tools appear, pass children to `DefaultToolbar` (see the [toolbar groups](https://tldraw.dev/examples/toolbar-groups) example).

## App.tsx

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

const components: TLComponents = {
	Toolbar: () => <DefaultToolbar orientation="vertical" />,
}

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

--------

# Add a tool to the toolbar

Category: UI & theming

Keywords: custom tool, toolbar, icon, asset urls, keyboard shortcuts dialog, defaulttoolbar, tldrawuimenuitem, useistoolselected, usetools, components

Add a custom tool to the toolbar with its own icon and keyboard shortcut.

To make a custom tool appear on tldraw's toolbar you need four things: register the tool item in the UI's tools context with the `tools` override, override the `Toolbar` component to render a `TldrawUiMenuItem` for it, override the `KeyboardShortcutsDialog` so its shortcut appears in the dialog, and pass an `assetUrls` entry for the tool's icon.

The sticker tool is selected on load. Click on the canvas to drop a heart, or press `S` to switch back to it after using another tool. For more information on how to implement custom tools, check out the custom tool example.

## App.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TLUiAssetUrlOverrides,
	TLUiOverrides,
	Tldraw,
	TldrawUiMenuItem,
	useIsToolSelected,
	useTools,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { StickerTool } from './sticker-tool-util'

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

// [1]
const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		tools.sticker = {
			id: 'sticker',
			icon: 'heart-icon',
			label: 'Sticker',
			kbd: 's',
			onSelect: () => {
				editor.setCurrentTool('sticker')
			},
		}
		return tools
	},
}

// [2]
const components: TLComponents = {
	Toolbar: (props) => {
		const tools = useTools()
		const isStickerSelected = useIsToolSelected(tools['sticker'])
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...tools['sticker']} isSelected={isStickerSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
	// [3]
	KeyboardShortcutsDialog: (props) => {
		const tools = useTools()
		return (
			<DefaultKeyboardShortcutsDialog {...props}>
				<DefaultKeyboardShortcutsDialogContent />
				{/* Ideally, we'd interleave this into the tools group */}
				<TldrawUiMenuItem {...tools['sticker']} />
			</DefaultKeyboardShortcutsDialog>
		)
	},
}

// [4]
export const customAssetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'heart-icon': '/heart-icon.svg',
	},
}

// [5]
const customTools = [StickerTool]

export default function ToolInToolbarExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				tools={customTools}
				initialState="sticker"
				overrides={uiOverrides}
				components={components}
				assetUrls={customAssetUrls}
			/>
		</div>
	)
}

/*
Introduction:
You can make an icon for your custom tool appear on tldraw's toolbar. To do this
you need to add the tool to the UI's tools context, override the toolbar
component, optionally add the tool to the keyboard shortcuts dialog, and pass in
an asset URL for its icon. For more information on how to implement custom
tools, check out the custom tool example.

[1]
The `tools` override adds a tool item to the UI's tools context. The item
describes how the tool appears in menus (icon, label, keyboard shortcut) and
what happens when it's selected. This is separate from the `StateNode` class
that implements the tool's behavior; the UI needs both.

[2]
Override the `Toolbar` component so we can place our tool in it. `DefaultToolbar`
provides the toolbar chrome and `DefaultToolbarContent` renders the built-in
tools, so we render our own `TldrawUiMenuItem` before it. `useIsToolSelected`
lets the button show as active when the sticker tool is the current tool.

[3]
The keyboard shortcuts dialog doesn't know about custom tools, so we override
it and append our tool after `DefaultKeyboardShortcutsDialogContent`. This makes
the tool's shortcut show up in the dialog.

[4]
The tool item references an icon named `heart-icon`, so we tell the UI where to
find that icon via the `assetUrls` prop. Any icon name that isn't a built-in
tldraw icon needs an entry here.

[5]
Define the tools array outside the component so it's a stable reference. We
pass the tools, overrides, components, and asset URLs to the `Tldraw` component,
and set `initialState="sticker"` so the tool is selected on load.
*/
```

## sticker-tool-util.tsx

```tsx
import { StateNode, toRichText } from 'tldraw'

// Check out the custom tool example for a more detailed explanation of the tool class.

const OFFSET = 12
export class StickerTool extends StateNode {
	static override id = 'sticker'

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

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

--------

# Remove a tool from the toolbar

Category: UI & theming

Keywords: hide tool, remove tool, overrides, customization, toolbar customization, disable tool, tool visibility

Remove the text tool from the toolbar and keyboard shortcuts with a `tools` override.

The `tools` override in `TLUiOverrides` receives the map of UI tool items and returns the one the UI should use. Deleting an entry removes that tool from the toolbar, its keyboard shortcut, and the keyboard shortcuts dialog. The tool is still registered with the editor, so it can be activated programmatically with `editor.setCurrentTool`. Here we remove the text tool; try pressing `T` and note that nothing happens.

## App.tsx

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

// [1]
const overrides: TLUiOverrides = {
	tools(_editor, tools) {
		delete tools.text
		return tools
	},
}

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

/*
[1]
The `tools` override receives the map of UI tool items and returns the map the
UI should use. Deleting an entry removes the tool from the toolbar, its
keyboard shortcut, and the keyboard shortcuts dialog. The tool itself is still
registered with the editor, so `editor.setCurrentTool('text')` still works.
Define the overrides object outside the component (or memoize it) so the UI
doesn't rebuild on every render.
*/
```

--------

# Change default colors

Category: UI & theming

Keywords: colors, colours, theme, palette, style panel, defaultcolorstyle, color values, theming, customization

Change the values in tldraw's default color palette with `editor.updateTheme()`.

Get the current theme with `editor.getTheme()`, change the color values you want, and pass the result to `editor.updateTheme()`. Here the "black" color renders as aqua in light mode. Try drawing something with the default color to see the change.

To add or remove colors, or to register additional named themes, see the custom theme and multiple themes examples.

## App.tsx

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

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

export default function ChangingDefaultColorsExample() {
	return (
		<div className="tldraw__editor">
			{/* [1] */}
			<Tldraw
				persistenceKey="changing-default-colors-example"
				onMount={(editor) => {
					const theme = editor.getTheme('default')!
					editor.updateTheme({
						...theme,
						colors: {
							...theme.colors,
							light: {
								...theme.colors.light,
								black: { ...theme.colors.light.black, solid: 'aqua' },
							},
						},
					})
				}}
			/>
		</div>
	)
}

/*
[1]
Use `editor.updateTheme()` to change a theme's color palette. Get the current
theme with `editor.getTheme()`, copy it with the values you want changed, and
pass it back. Here we make the "black" color's solid value aqua in light mode.

Changing values this way keeps the set of color names the same, so existing
shapes (and other users in a multiplayer session) keep working. To add or
remove colors, or register additional named themes, see the custom theme and
multiple themes examples.
*/
```

--------

# Change default styles

Category: UI & theming

Keywords: styles, default style, style props, size, color, dash, fill, setdefaultvalue

Change the default value of a style prop with `setDefaultValue`.

Every style prop has a built-in default value: new shapes use `m` for size, `black` for color, and so on. Call `setDefaultValue` on the style prop to change it. In this example the size style defaults to `s`, so newly created shapes are small.

Call `setDefaultValue` at module level, before any editor is created, so the change applies everywhere the style is used.

## App.tsx

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

// Call this at module level, before any editor is created, so every editor
// (and every new shape) picks up the new default.
DefaultSizeStyle.setDefaultValue('s')

export default function ChangingDefaultStyleExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="changing-default-style-example" />
		</div>
	)
}
```

--------

# Changing menus

Category: UI & theming

Keywords: menu, toolbar, context menu, main menu, page menu, ActionsMenu, DebugMenu, HelpMenu, StylePanel, QuickActions, ZoomMenu, components, TldrawUiMenuItem

Add items to every one of tldraw's menus, including the toolbar, main menu, context menu, and page menu.

Use the `components` prop to override tldraw's default menus. You can provide a React component of your own, import the default component and add to it, or return `null` to hide it completely. Each default menu comes as a pair, for example `DefaultMainMenu` and `DefaultMainMenuContent`, so you can wrap the default content with your own items. This example customizes every menu in tldraw:

- Toolbar
- Main menu
- Context menu
- Page menu
- Actions menu
- Debug menu
- Help menu
- Keyboard shortcuts dialog
- Navigation panel
- Quick actions panel
- Style panel
- Zoom menu

The custom additions are highlighted in thistle so they're easy to spot.

## App.tsx

```tsx
import {
	DefaultActionsMenu,
	DefaultActionsMenuContent,
	DefaultColorStyle,
	DefaultContextMenu,
	DefaultContextMenuContent,
	DefaultDebugMenu,
	DefaultDebugMenuContent,
	DefaultHelpMenu,
	DefaultHelpMenuContent,
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultMainMenu,
	DefaultMainMenuContent,
	DefaultPageMenu,
	DefaultQuickActions,
	DefaultQuickActionsContent,
	DefaultStylePanel,
	DefaultStylePanelContent,
	DefaultToolbar,
	DefaultToolbarContent,
	DefaultZoomMenu,
	DefaultZoomMenuContent,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	TldrawUiMenuGroup,
	TldrawUiMenuItem,
	TldrawUiToolbar,
	TLUiContextMenuProps,
	TLUiKeyboardShortcutsDialogProps,
	TLUiStylePanelProps,
	useEditor,
	useIsToolSelected,
	useTldrawUiComponents,
	useTools,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
function CustomActionsMenu() {
	return (
		<div style={{ backgroundColor: 'thistle' }}>
			<DefaultActionsMenu>
				<div style={{ backgroundColor: 'thistle' }}>
					<TldrawUiMenuItem
						id="like"
						label="Like my posts"
						icon="external-link"
						readonlyOk
						onSelect={() => {
							window.open('https://x.com/tldraw', '_blank')
						}}
					/>
				</div>
				<DefaultActionsMenuContent />
			</DefaultActionsMenu>
		</div>
	)
}
// [2]
function CustomContextMenu(props: TLUiContextMenuProps) {
	return (
		<DefaultContextMenu {...props}>
			<TldrawUiMenuGroup id="example">
				<div style={{ backgroundColor: 'thistle' }}>
					<TldrawUiMenuItem
						id="like"
						label="Like my posts"
						icon="external-link"
						readonlyOk
						onSelect={() => {
							window.open('https://x.com/tldraw', '_blank')
						}}
					/>
				</div>
			</TldrawUiMenuGroup>
			<DefaultContextMenuContent />
		</DefaultContextMenu>
	)
}
// [3]
function CustomDebugMenu() {
	return (
		<div style={{ backgroundColor: 'thistle' }}>
			<DefaultDebugMenu>
				<DefaultDebugMenuContent />
				<div style={{ backgroundColor: 'thistle' }}>
					<TldrawUiMenuGroup id="example">
						<TldrawUiMenuItem
							id="like"
							label="Like my posts"
							icon="external-link"
							readonlyOk
							onSelect={() => {
								window.open('https://x.com/tldraw', '_blank')
							}}
						/>
					</TldrawUiMenuGroup>
				</div>
			</DefaultDebugMenu>
		</div>
	)
}
// [4]
function CustomHelpMenu() {
	return (
		<DefaultHelpMenu>
			<div style={{ backgroundColor: 'thistle' }}>
				<TldrawUiMenuGroup id="example">
					<TldrawUiMenuItem
						id="like"
						label="Like my posts"
						icon="external-link"
						readonlyOk
						onSelect={() => {
							window.open('https://x.com/tldraw', '_blank')
						}}
					/>
				</TldrawUiMenuGroup>
			</div>
			<DefaultHelpMenuContent />
		</DefaultHelpMenu>
	)
}
// [5]
function CustomKeyboardShortcutsDialog(props: TLUiKeyboardShortcutsDialogProps) {
	return (
		<DefaultKeyboardShortcutsDialog {...props}>
			<div style={{ backgroundColor: 'thistle' }}>
				<TldrawUiMenuItem
					id="like-my-posts"
					label="Like my posts"
					icon="external-link"
					readonlyOk
					kbd=":)"
					onSelect={() => {
						window.open('https://x.com/tldraw', '_blank')
					}}
				/>
			</div>
			<DefaultKeyboardShortcutsDialogContent />
		</DefaultKeyboardShortcutsDialog>
	)
}
// [6]
function CustomMainMenu() {
	return (
		<DefaultMainMenu>
			<div style={{ backgroundColor: 'thistle' }}>
				<TldrawUiMenuGroup id="example">
					<TldrawUiMenuItem
						id="like"
						label="Like my posts"
						icon="external-link"
						readonlyOk
						onSelect={() => {
							window.open('https://x.com/tldraw', '_blank')
						}}
					/>
				</TldrawUiMenuGroup>
			</div>
			<DefaultMainMenuContent />
		</DefaultMainMenu>
	)
}
// [7]
function CustomNavigationPanel() {
	const { ZoomMenu } = useTldrawUiComponents()
	return (
		<div style={{ backgroundColor: 'thistle', padding: '14px' }}>
			here you are
			<TldrawUiToolbar orientation="horizontal" label="Navigation">
				{ZoomMenu && <ZoomMenu />}
			</TldrawUiToolbar>
		</div>
	)
}
// [8]
function CustomPageMenu() {
	return (
		<div style={{ transform: 'rotate(3.14rad)', backgroundColor: 'thistle' }}>
			<DefaultPageMenu />
		</div>
	)
}
// [9]
function CustomQuickActions() {
	return (
		<DefaultQuickActions>
			<DefaultQuickActionsContent />
			<div style={{ backgroundColor: 'thistle' }}>
				<TldrawUiMenuItem id="code" icon="code" onSelect={() => window.alert('code')} />
			</div>
		</DefaultQuickActions>
	)
}
// [10]
function CustomStylePanel(props: TLUiStylePanelProps) {
	const editor = useEditor()

	return (
		<DefaultStylePanel {...props}>
			<div style={{ backgroundColor: 'thistle' }}>
				<TldrawUiButton
					type="menu"
					onClick={() => {
						editor.setStyleForSelectedShapes(DefaultColorStyle, 'red')
					}}
				>
					<TldrawUiButtonLabel>Red</TldrawUiButtonLabel>
				</TldrawUiButton>
			</div>
			<div style={{ backgroundColor: 'thistle' }}>
				<TldrawUiButton
					type="menu"
					onClick={() => {
						editor.setStyleForSelectedShapes(DefaultColorStyle, 'green')
					}}
				>
					<TldrawUiButtonLabel>Green</TldrawUiButtonLabel>
				</TldrawUiButton>
			</div>
			<DefaultStylePanelContent />
		</DefaultStylePanel>
	)
}
// [11]
function CustomToolbar() {
	const editor = useEditor()
	const tools = useTools()
	const isRhombusSelected = useIsToolSelected(tools['rhombus-2'])
	return (
		<DefaultToolbar>
			<TldrawUiMenuItem
				{...tools['rhombus-2']}
				label="geo-style.rhombus-2"
				isSelected={isRhombusSelected}
			/>
			<DefaultToolbarContent />
			<TldrawUiButton
				type="icon"
				onClick={() => {
					editor.selectAll().deleteShapes(editor.getSelectedShapeIds())
				}}
				title="Delete all"
			>
				🧨
			</TldrawUiButton>
		</DefaultToolbar>
	)
}
// [12]
function CustomZoomMenu() {
	return (
		<DefaultZoomMenu>
			<div style={{ backgroundColor: 'thistle' }}>
				<TldrawUiMenuGroup id="example">
					<TldrawUiMenuItem
						id="like"
						label="Like my posts"
						icon="external-link"
						readonlyOk
						onSelect={() => {
							window.open('https://x.com/tldraw', '_blank')
						}}
					/>
				</TldrawUiMenuGroup>
			</div>
			<DefaultZoomMenuContent />
		</DefaultZoomMenu>
	)
}
const components: TLComponents = {
	ActionsMenu: CustomActionsMenu,
	ContextMenu: CustomContextMenu,
	DebugMenu: CustomDebugMenu,
	HelpMenu: CustomHelpMenu,
	KeyboardShortcutsDialog: CustomKeyboardShortcutsDialog,
	MainMenu: CustomMainMenu,
	NavigationPanel: CustomNavigationPanel,
	PageMenu: CustomPageMenu,
	QuickActions: CustomQuickActions,
	StylePanel: CustomStylePanel,
	Toolbar: CustomToolbar,
	ZoomMenu: CustomZoomMenu,
}

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

/*
You can use the `components` prop to override tldraw's default menus. You can provide a React
component of your own, import our default component and add to it, or return null to hide it
completely. This example does this with every menu in tldraw. The thistle-colored areas mark the
custom additions.

[1]
The actions menu is a dropdown found in the top-left of the tldraw component, or just above the
toolbar on smaller screens. It contains actions related to editing shapes such as grouping,
rotating, or changing shape order.

[2]
Create some shapes, select them, and right click the selection to see the custom context menu.

[3]
The debug menu contains helpful menu items for debugging the tldraw component. To show it, turn
on debug mode in the preferences.

[4]
The help menu contains menu items to change the language of the application and to open the
keyboard shortcuts dialog.

[5]
The keyboard shortcuts dialog is a modal that lists all the keyboard shortcuts available in
tldraw. You can open it via the help menu.

[6]
The main menu contains the Edit, Shape, and Preferences submenus, among others. To open it, click
the hamburger icon in the top left corner of the tldraw component.

[7]
The navigation panel is in the bottom left of the tldraw component at larger breakpoints. It
normally contains the zoom menu and a minimap. Replacing it drops the zoom menu too, so this one
renders `ZoomMenu` from `useTldrawUiComponents` to keep [12] reachable. The zoom menu's trigger is a
toolbar button, so it has to sit inside a `TldrawUiToolbar`.

[8]
The page menu contains options for creating and editing pages. To open it, click the page name in
the top left of the tldraw component.

[9]
The quick actions menu appears next to the main menu, or above the toolbar on smaller screens.

[10]
The style panel appears on the right side of the tldraw component. It contains options to change
the style of shapes, such as color, stroke width, and opacity.

[11]
The toolbar contains the tools used to create and select shapes. Here we add the left-leaning
rhombus geo shape at the front and a "delete all" button at the end. There is no `tool.rhombus-2`
translation key, so the item reuses the style panel's `geo-style.rhombus-2` label.

[12]
The zoom menu is in the bottom left of the tldraw component. The button that opens it is labeled
with a percentage indicating the editor's current zoom level.
*/
```

--------

# Format rich text on multiple shapes

Category: UI & theming

Keywords: rich text, formatting, batch edit, multiple shapes, style panel, bold, marks, programmatic formatting, tlrichtext, document traversal

Add a style panel button that bolds (or unbolds) all the text in every selected shape at once.

Rich text in tldraw is a TipTap (ProseMirror) JSON document stored in `shape.props.richText`. Each text node can carry a `marks` array, and bold is represented as `{ type: 'bold' }`. This example walks that document with three small helpers, `makeAllTextBold`, `removeBoldFromAllText`, and `isAllTextBold`, and writes the result back with `editor.updateShapes`.

The button lives in a custom `StylePanel` that wraps `DefaultStylePanel`. It reads the selection with `useValue`, so it enables itself whenever any selected shape has rich text and shows as active when every text node is already bold. Try selecting a mix of text, geo, and note shapes and toggling the button.

For the same idea built on ProseMirror's `Node` API (bold, italic, and highlight, including shapes nested inside frames and groups), see the [text mass style updates](https://tldraw.dev/examples/text-mass-style-updates) example.

## App.tsx

```tsx
import {
	DefaultStylePanel,
	DefaultStylePanelContent,
	ExtractShapeByProps,
	TLComponents,
	TLRichText,
	TLShape,
	TLUiStylePanelProps,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonIcon,
	TldrawUiButtonLabel,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'

type ShapeWithRichText = ExtractShapeByProps<{ richText: TLRichText }>

function isShapeWithRichText(shape: TLShape | null | undefined): shape is ShapeWithRichText {
	return !!(shape && 'richText' in shape.props)
}

// [1]
function makeAllTextBold(richText: TLRichText): TLRichText {
	if (!richText || !richText.content) {
		return richText
	}

	const processNode = (node: any): any => {
		if (node.type === 'text') {
			const hasBold = node.marks?.some((mark: any) => mark.type === 'bold')
			if (hasBold) {
				return node
			}
			return {
				...node,
				marks: [...(node.marks || []), { type: 'bold' }],
			}
		}

		if (node.content && Array.isArray(node.content)) {
			return {
				...node,
				content: node.content.map(processNode),
			}
		}

		return node
	}

	return {
		...richText,
		content: richText.content.map(processNode),
	}
}

function isAllTextBold(richText: TLRichText): boolean {
	if (!richText || !richText.content) {
		return false
	}

	const checkNode = (node: any): boolean => {
		if (node.type === 'text') {
			return node.marks?.some((mark: any) => mark.type === 'bold') ?? false
		}

		if (node.content && Array.isArray(node.content)) {
			return node.content.every(checkNode)
		}

		// Leaf nodes without text (hard breaks, etc.) have nothing to bold
		return true
	}

	return richText.content.every(checkNode)
}

function removeBoldFromAllText(richText: TLRichText): TLRichText {
	if (!richText || !richText.content) {
		return richText
	}

	const processNode = (node: any): any => {
		if (node.type === 'text') {
			const marks = node.marks?.filter((mark: any) => mark.type !== 'bold') || []
			return {
				...node,
				marks: marks.length > 0 ? marks : undefined,
			}
		}

		if (node.content && Array.isArray(node.content)) {
			return {
				...node,
				content: node.content.map(processNode),
			}
		}

		return node
	}

	return {
		...richText,
		content: richText.content.map(processNode),
	}
}

// [2]
function CustomStylePanel(props: TLUiStylePanelProps) {
	const editor = useEditor()

	const shapesWithRichText = useValue(
		'shapes with rich text',
		() => editor.getSelectedShapes().filter(isShapeWithRichText),
		[editor]
	)
	const hasRichTextSelection = shapesWithRichText.length > 0

	const allBold =
		hasRichTextSelection && shapesWithRichText.every((shape) => isAllTextBold(shape.props.richText))

	const handleToggleBold = () => {
		if (!hasRichTextSelection) return

		// [3]
		editor.run(() => {
			editor.markHistoryStoppingPoint('toggle bold')
			editor.updateShapes(
				shapesWithRichText.map((shape) => ({
					id: shape.id,
					type: shape.type,
					props: {
						richText: allBold
							? removeBoldFromAllText(shape.props.richText)
							: makeAllTextBold(shape.props.richText),
					},
				}))
			)
		})
	}

	return (
		<DefaultStylePanel {...props}>
			<div className="tlui-style-panel__section">
				<TldrawUiButton
					type="menu"
					isActive={allBold}
					onClick={handleToggleBold}
					title="Bold all text in selected shapes"
					disabled={!hasRichTextSelection}
				>
					<TldrawUiButtonIcon icon="bold" />
					<TldrawUiButtonLabel>Bold all text</TldrawUiButtonLabel>
				</TldrawUiButton>
			</div>
			<DefaultStylePanelContent />
		</DefaultStylePanel>
	)
}

const components: TLComponents = {
	StylePanel: CustomStylePanel,
}

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

/*
This example adds a "Bold all text" toggle to the style panel that applies to
every selected shape with rich text at once. Rich text in tldraw is a TipTap
(ProseMirror) JSON document; each text node can carry a `marks` array such as
`[{ type: 'bold' }]`. Here we walk that JSON directly. For a version that uses
ProseMirror's Node API instead, see the "Text mass style updates" example.

[1]
The helpers recursively map over the document, adding or removing the bold mark
on text nodes and leaving the structure untouched. `isAllTextBold` is the
inverse check that decides whether the button should add or remove bold.

[2]
`ExtractShapeByProps<{ richText: TLRichText }>` narrows to any shape whose props
include rich text (text, geo, note, arrow), so the panel works across shape
types. Reading the selection inside `useValue` keeps the button state in sync
as the selection or the shapes' text changes.

[3]
`editor.updateShapes` applies all the changes in one go, and the history stopping
point makes the whole toggle a single undo step. Shapes are never mutated
directly; we always pass a new `richText` object through the editor.
*/
```

--------

# Custom theme

Category: UI & theming

Keywords: theme, brand, custom, colors, fonts, dark mode, light mode, palette, updatetheme

Add custom colors and fonts to the theme, remove built-in ones, and adjust theme values at runtime.

Pass a `themes` prop to `<Tldraw>` to replace the default theme. This example adds a "pink" color and two custom fonts (a bundled pixel font and a remote Google Font), removes the "light-\*" colors and the serif font, and adds translations so the style panel shows readable names. Custom color and font names are declared to TypeScript via module augmentation of `TLThemeDefaultColors`, `TLThemeFonts`, and `TLRemovedDefaultThemeColors`.

The sliders in the bottom right change the theme's `fontSize`, `lineHeight`, and `strokeWidth` at runtime with `editor.updateTheme()`. Draw some shapes and drag the stroke width slider to see them update. To register additional named themes and switch between them, see the multiple themes example.

## App.tsx

```tsx
import { useCallback, useEffect, useRef, useState } from 'react'
import {
	DEFAULT_THEME,
	Editor,
	TLDefaultColor,
	TLTheme,
	TLThemeFont,
	TLThemes,
	TLUiOverrides,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	toRichText,
} from 'tldraw'
import 'tldraw/tldraw.css'
import silkscreenBoldUrl from './custom-font/Silkscreen-Bold.ttf'
import silkscreenRegularUrl from './custom-font/Silkscreen-Regular.ttf'
import './custom-theme.css'

// [1]
declare module '@tldraw/tlschema' {
	interface TLThemeDefaultColors {
		pink: TLDefaultColor
	}
	interface TLThemeFonts {
		pixel: TLThemeFont
		cursive: TLThemeFont
	}
	// [2]
	interface TLRemovedDefaultThemeColors {
		'light-violet': true
		'light-blue': true
		'light-green': true
		'light-red': true
	}
}

// Helper to create a full color entry from a base solid color
function makeColor(solid: string, semi: string, pattern: string): TLDefaultColor {
	return {
		solid,
		semi,
		pattern,
		fill: solid,
		linedFill: semi,
		frameHeadingStroke: solid,
		frameHeadingFill: semi,
		frameStroke: solid,
		frameFill: semi,
		frameText: solid,
		noteFill: semi,
		noteText: solid,
		highlightSrgb: solid,
		highlightP3: solid,
	}
}

// [3]
const pinkLight = makeColor('#e91e8c', '#fce4f2', '#f06baf')
const pinkDark = makeColor('#f06baf', '#3d1a2e', '#e91e8c')

// [4]
const pixelFont: TLThemeFont = {
	fontFamily: "'Silkscreen', sans-serif",
	icon: <div style={{ fontFamily: 'Silkscreen, sans-serif', fontSize: 16, lineHeight: 1 }}>Aa</div>,
	faces: [
		{
			family: 'Silkscreen',
			src: { url: silkscreenRegularUrl },
			weight: 'normal',
			style: 'normal',
		},
		{
			family: 'Silkscreen',
			src: { url: silkscreenBoldUrl },
			weight: 'bold',
			style: 'normal',
		},
	],
}

// Custom font — use a Google Font loaded via full URLs. These versioned
// gstatic URLs expire when Google revs the font; refresh them from
// https://fonts.googleapis.com/css2?family=Comic+Neue:wght@400;700 if they 404.
const cursiveFont: TLThemeFont = {
	fontFamily: "'Comic Neue', cursive",
	icon: <div style={{ fontFamily: "'Comic Neue', cursive", fontSize: 16, lineHeight: 1 }}>Aa</div>,
	faces: [
		{
			family: 'Comic Neue',
			src: {
				url: 'https://fonts.gstatic.com/s/comicneue/v9/4UaHrEJDsxBrF37olUeD96rp57F2IwM.woff2',
				format: 'woff2',
			},
			weight: 'normal',
			style: 'normal',
		},
		{
			family: 'Comic Neue',
			src: {
				url: 'https://fonts.gstatic.com/s/comicneue/v9/4UaErEJDsxBrF37olUeD_xHM8pxULilENlY.woff2',
				format: 'woff2',
			},
			weight: 'bold',
			style: 'normal',
		},
	],
}

// [5]
const { serif: _serif, ...keptFonts } = DEFAULT_THEME.fonts
const customFonts = { ...keptFonts, pixel: pixelFont, cursive: cursiveFont } as TLTheme['fonts']

// [6]
function colorsWithoutLightVariants(base: Record<string, unknown>, pink: TLDefaultColor) {
	const {
		'light-violet': _lv,
		'light-blue': _lb,
		'light-green': _lg,
		'light-red': _lr,
		...kept
	} = base
	return { ...kept, pink } as TLTheme['colors']['light']
}

// [7]
const uiOverrides: TLUiOverrides = {
	translations: {
		en: {
			'color-style.pink': 'Pink',
			'font-style.pixel': 'Pixel',
			'font-style.cursive': 'Cursive',
		},
	},
}

// [8]
const DEFAULTS = {
	fontSize: 16,
	lineHeight: 1.35,
	strokeWidth: 2,
}

// [9]
const themes: Partial<TLThemes> = {
	default: {
		id: 'default',
		fontSize: DEFAULTS.fontSize,
		lineHeight: DEFAULTS.lineHeight,
		strokeWidth: DEFAULTS.strokeWidth,
		fonts: customFonts,
		colors: {
			light: colorsWithoutLightVariants(DEFAULT_THEME.colors.light, pinkLight),
			dark: colorsWithoutLightVariants(DEFAULT_THEME.colors.dark, pinkDark),
		},
	},
}

export default function CustomThemeExample() {
	const [fontSize, setFontSize] = useState(DEFAULTS.fontSize)
	const [lineHeight, setLineHeight] = useState(DEFAULTS.lineHeight)
	const [strokeWidth, setStrokeWidth] = useState(DEFAULTS.strokeWidth)
	const editorRef = useRef<Editor | null>(null)

	// Apply slider values to the theme programmatically. Rather than passing
	// a new `themes` object whenever a value changes (which would recreate the
	// store and reload the canvas from persistence), we update the existing
	// "default" theme in place via `editor.updateTheme()`. Spreading the current
	// theme preserves the custom colors and fonts while overriding the adjusted
	// values. Shapes re-render reactively without the board flashing.
	useEffect(() => {
		const editor = editorRef.current
		if (!editor) return
		editor.updateTheme({ ...editor.getTheme('default')!, fontSize, lineHeight, strokeWidth })
	}, [fontSize, lineHeight, strokeWidth])

	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="custom-theme-example"
				themes={themes}
				overrides={uiOverrides}
				onMount={(editor) => {
					editorRef.current = editor
					if (editor.getCurrentPageShapeIds().size > 0) return

					editor.createShape({
						type: 'geo',
						x: 100,
						y: 100,
						props: { w: 200, h: 200, color: 'red' },
					})
					editor.createShape({
						type: 'geo',
						x: 350,
						y: 100,
						props: {
							w: 200,
							h: 200,
							color: 'blue',
							geo: 'ellipse',
							richText: toRichText('Hello'),
						},
					})
					// [10]
					editor.createShape({
						type: 'geo',
						x: 600,
						y: 100,
						props: { w: 200, h: 200, color: 'pink', geo: 'diamond' },
					})
					editor.createShape({
						type: 'text',
						x: 100,
						y: 350,
						props: { richText: toRichText('Theme text'), size: 'l' },
					})
					// [11]
					editor.createShape({
						type: 'text',
						x: 350,
						y: 350,
						props: { richText: toRichText('Pixel font!'), size: 'l', font: 'pixel' },
					})
					editor.createShape({
						type: 'text',
						x: 600,
						y: 350,
						props: { richText: toRichText('Cursive font!'), size: 'l', font: 'cursive' },
					})
					editor.createShape({
						type: 'note',
						x: 100,
						y: 500,
						props: {
							color: 'black',
							richText: toRichText('A sticky note'),
						},
					})
				}}
			>
				<ThemeControls
					fontSize={fontSize}
					onFontSizeChange={setFontSize}
					lineHeight={lineHeight}
					onLineHeightChange={setLineHeight}
					strokeWidth={strokeWidth}
					onStrokeWidthChange={setStrokeWidth}
				/>
			</Tldraw>
		</div>
	)
}

// [12]
function ThemeControls({
	fontSize,
	onFontSizeChange,
	lineHeight,
	onLineHeightChange,
	strokeWidth,
	onStrokeWidthChange,
}: {
	fontSize: number
	onFontSizeChange(v: number): void
	lineHeight: number
	onLineHeightChange(v: number): void
	strokeWidth: number
	onStrokeWidthChange(v: number): void
}) {
	return (
		<div className="tlui-menu custom-theme-toolbar" onPointerDown={(e) => e.stopPropagation()}>
			<ThemeSlider
				label="Font size"
				value={fontSize}
				onChange={onFontSizeChange}
				min={8}
				max={32}
				step={1}
				defaultValue={DEFAULTS.fontSize}
			/>
			<ThemeSlider
				label="Line height"
				value={lineHeight}
				onChange={onLineHeightChange}
				min={1}
				max={2}
				step={0.05}
				defaultValue={DEFAULTS.lineHeight}
			/>
			<ThemeSlider
				label="Stroke width"
				value={strokeWidth}
				onChange={onStrokeWidthChange}
				min={0.5}
				max={6}
				step={0.25}
				defaultValue={DEFAULTS.strokeWidth}
			/>

			<TldrawUiButton
				type="low"
				onClick={() => {
					onFontSizeChange(DEFAULTS.fontSize)
					onLineHeightChange(DEFAULTS.lineHeight)
					onStrokeWidthChange(DEFAULTS.strokeWidth)
				}}
			>
				<TldrawUiButtonLabel>Reset to defaults</TldrawUiButtonLabel>
			</TldrawUiButton>
		</div>
	)
}

function ThemeSlider({
	label,
	value,
	onChange,
	min,
	max,
	step,
	defaultValue,
}: {
	label: string
	value: number
	onChange(v: number): void
	min: number
	max: number
	step: number
	defaultValue: number
}) {
	const [localValue, setLocalValue] = useState(value)
	const isDragging = useRef(false)

	// sync from parent when not actively dragging
	if (!isDragging.current && localValue !== value) {
		setLocalValue(value)
	}

	const isDefault = localValue === defaultValue

	const handleInput = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
		isDragging.current = true
		setLocalValue(Number(e.target.value))
	}, [])

	const handleCommit = useCallback(() => {
		if (!isDragging.current) return
		isDragging.current = false
		onChange(localValue)
	}, [onChange, localValue])

	return (
		<div className="custom-theme-slider">
			<div className="custom-theme-slider__header">
				<span className="custom-theme-slider__label">{label}</span>
				<span className="custom-theme-slider__value" data-default={isDefault}>
					{localValue % 1 === 0 ? localValue : localValue.toFixed(2)}
				</span>
			</div>
			<input
				type="range"
				min={min}
				max={max}
				step={step}
				value={localValue}
				onChange={handleInput}
				onPointerUp={handleCommit}
			/>
		</div>
	)
}

/*

[1]
Extend the `TLThemeDefaultColors` and `TLThemeFonts` interfaces via module
augmentation so TypeScript knows about the custom "pink" color and the "pixel"
and "cursive" fonts. Because `themes` is passed to `<Tldraw>`, the names are
registered with the style enums automatically at store creation.

[2]
Extend `TLRemovedDefaultThemeColors` to remove built-in colors from the type.
This is the type-level half of removing the "light-*" variants; [6] removes
them from the theme values.

[3]
Define color entries for light and dark variants. Each theme needs a full
`TLDefaultColor` entry for the custom color in both palettes.

[4]
A custom font has a `fontFamily` CSS string and, for fonts that need loading, a
`faces` array of `TLFontFace` entries pointing at the font files (here bundled
locally via import; the cursive font below uses remote URLs). System fonts like
Arial or Georgia can omit `faces`. The `icon` field is the React element the
style panel uses as the button for this font; here "Aa" rendered in the font
itself.

[5]
Remove a built-in font: destructure "serif" out of the default font palette and
spread the rest. The serif option disappears from the style panel and the two
custom fonts take its place.

[6]
Remove built-in colors: destructure the "light-*" variants out of the default
palette. They won't appear in the style panel, and "pink" is added in their place.

[7]
Translation overrides provide human-readable names for custom style values.
Without these, the tooltip for "pink" would show the raw key "color-style.pink".

[8]
Default values for the adjustable theme properties. These match `DEFAULT_THEME`.

[9]
The `themes` prop is a stable object passed once to `<Tldraw>`. It registers the
custom color and fonts at store creation and seeds the starting values. Slider
adjustments are applied at runtime with `editor.updateTheme()` rather than by
passing a new `themes` prop, because a new object would recreate the store and
reload the canvas from persistence. `updateTheme` updates the active theme
reactively, so shapes re-render immediately. Which palette (light or dark) is
used follows the user's color scheme preference.

[10]
Create a shape using the custom "pink" color. Because the theme declares the
color, it passes validation.

[11]
Create shapes using the custom "pixel" and "cursive" fonts. They show up in the
style panel alongside the remaining built-in fonts (draw, sans, mono).

[12]
A panel with sliders for `fontSize`, `lineHeight`, and `strokeWidth`. Try
drawing some shapes with different sizes and then moving the stroke width
slider to see how theme values affect shape rendering.

*/
```

## custom-theme.css

```css
.custom-theme-toolbar {
	pointer-events: all;
	display: flex;
	flex-direction: column;
	gap: 16px;
	padding: 8px;
	bottom: 56px;
	right: 8px;
	width: 200px;
	position: absolute;
	height: fit-content;
}

.custom-theme-slider {
	display: flex;
	flex-direction: column;
	gap: 4px;
}

.custom-theme-slider__header {
	display: flex;
	justify-content: space-between;
	align-items: baseline;
}

.custom-theme-slider__label {
	white-space: nowrap;
}

.custom-theme-slider__value {
	font-variant-numeric: tabular-nums;
	min-width: 36px;
	text-align: right;
}

.custom-theme-slider__value[data-default='true'] {
	opacity: 0.5;
}

.custom-theme-slider input[type='range'] {
	width: 100%;
	margin: 0;
	accent-color: var(--color-selected);
}
```

--------

# Multiple themes

Category: UI & theming

Keywords: theme, themes, brand, custom, module augmentation, TLThemes, switch, setcurrenttheme

Register several named themes and switch between them at runtime.

Themes are keyed by id in the `TLThemes` interface. Augment that interface with your theme ids so `editor.setCurrentTheme()` is type-checked, build each theme by cloning `DEFAULT_THEME` and overriding the colors you care about, and pass them to `<Tldraw>` through the `themes` prop. Switch at runtime with `editor.setCurrentTheme(id)`; `editor.getCurrentThemeId()` is reactive.

Try clicking the theme buttons at the top left. The blue rectangle and violet note recolor because those palette entries differ between the themes.

## App.tsx

```tsx
import {
	DEFAULT_THEME,
	Editor,
	TLTheme,
	TLThemeId,
	TLThemes,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	structuredClone,
	toRichText,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './multiple-themes.css'

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

// [1]
declare module '@tldraw/tlschema' {
	interface TLThemes {
		ocean: TLTheme
		sunset: TLTheme
	}
}

// [2]
const OCEAN_THEME: TLTheme = structuredClone(DEFAULT_THEME)
OCEAN_THEME.id = 'ocean'
OCEAN_THEME.colors.light.blue.solid = '#2b7ab5'
OCEAN_THEME.colors.light.violet.solid = '#6a5acd'
OCEAN_THEME.colors.light.violet.noteFill = '#b8a9e8'
OCEAN_THEME.colors.light.violet.noteText = '#000000'
OCEAN_THEME.colors.dark.blue.solid = '#3a9bd5'
OCEAN_THEME.colors.dark.violet.solid = '#7b6bd4'
OCEAN_THEME.colors.dark.violet.noteFill = '#3a2d6e'
OCEAN_THEME.colors.dark.violet.noteText = '#f2f2f2'

const SUNSET_THEME: TLTheme = structuredClone(DEFAULT_THEME)
SUNSET_THEME.id = 'sunset'
SUNSET_THEME.colors.light.blue.solid = '#e07038'
SUNSET_THEME.colors.light.violet.solid = '#9b4dca'
SUNSET_THEME.colors.light.violet.noteFill = '#dab0f0'
SUNSET_THEME.colors.light.violet.noteText = '#000000'
SUNSET_THEME.colors.dark.blue.solid = '#f0884a'
SUNSET_THEME.colors.dark.violet.solid = '#b060d8'
SUNSET_THEME.colors.dark.violet.noteFill = '#5c2870'
SUNSET_THEME.colors.dark.violet.noteText = '#f2f2f2'

// [3]
const themes: Partial<TLThemes> = {
	ocean: OCEAN_THEME,
	sunset: SUNSET_THEME,
}

function createInitialShapes(editor: Editor) {
	if (editor.getCurrentPageShapeIds().size > 0) return
	editor.createShapes([
		{
			type: 'geo',
			x: 100,
			y: 100,
			props: { w: 200, h: 200, color: 'blue', richText: toRichText('Try switching themes') },
		},
		{
			type: 'note',
			x: 350,
			y: 100,
			props: { color: 'violet', richText: toRichText('Colors change per theme') },
		},
	])
}

export default function MultipleThemesExample() {
	return (
		<div className="tldraw__editor">
			{/* [4] */}
			<Tldraw
				persistenceKey="multiple-themes-example"
				themes={themes}
				onMount={createInitialShapes}
			>
				<ThemeSwitcher />
			</Tldraw>
		</div>
	)
}

// [5]
const THEME_LABELS: Record<TLThemeId, string> = {
	default: 'Default',
	ocean: 'Ocean',
	sunset: 'Sunset',
}

function ThemeSwitcher() {
	const editor = useEditor()
	const currentThemeId = useValue('themeId', () => editor.getCurrentThemeId(), [editor])

	return (
		<div className="tlui-menu theme-switcher">
			{(Object.keys(THEME_LABELS) as TLThemeId[]).map((id) => (
				<TldrawUiButton
					key={id}
					type={currentThemeId === id ? 'primary' : 'normal'}
					onClick={() => editor.setCurrentTheme(id)}
				>
					<TldrawUiButtonLabel>{THEME_LABELS[id]}</TldrawUiButtonLabel>
				</TldrawUiButton>
			))}
		</div>
	)
}

/*

[1]
Extend the `TLThemes` interface to register custom theme IDs.
This gives you type-safe theme names throughout the API — `editor.setCurrentTheme('ocean')`
will autocomplete, and passing an unregistered name will be a type error.

[2]
Define theme objects by cloning `DEFAULT_THEME` and overriding just the colors
you want to change. Each theme contains both `light` and `dark` color palettes.

[3]
Collect the themes in a `Partial<TLThemes>`. The `default` theme is always registered,
so only the additional themes need to be listed. Keep this object at module level: it's
a prop of `<Tldraw>`, and a new object each render would re-register the themes.

[4]
`<Tldraw>` registers the `themes` at mount time and keeps them updated if the prop
changes. You can also register or update themes later with `editor.updateTheme()`.

[5]
`editor.setCurrentTheme(id)` switches theme at runtime and `editor.getCurrentThemeId()`
is reactive, so reading it in `useValue` keeps the active button highlighted.

*/
```

## multiple-themes.css

```css
.theme-switcher {
	position: absolute;
	top: 60px;
	left: 12px;
	display: flex;
	gap: 4px;
	padding: 4px;
	pointer-events: all;
}
```

--------

# Hide UI components

Category: UI & theming

Keywords: hide ui, components override, minimal ui, headless, remove ui, TLUiComponents, null components

Hide any built-in UI component by setting its slot to `null`.

Every part of the default UI is a slot in `TLUiComponents`. Passing `null` for a slot removes it. This example sets every slot to `null` so you can see the full list; in practice you'd only null out the pieces you want gone. Hiding `Toasts`, `Dialogs`, or `A11y` also disables the features that render through them. To remove the whole UI at once, use the `hideUi` prop instead.

## App.tsx

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

// [1]
const components: Required<TLUiComponents> = {
	ContextMenu: null,
	ActionsMenu: null,
	HelpMenu: null,
	ZoomMenu: null,
	MainMenu: null,
	Minimap: null,
	StylePanel: null,
	PageMenu: null,
	NavigationPanel: null,
	Toolbar: null,
	KeyboardShortcutsDialog: null,
	QuickActions: null,
	HelperButtons: null,
	DebugPanel: null,
	DebugMenu: null,
	SharePanel: null,
	MenuPanel: null,
	TopPanel: null,
	CursorChatBubble: null,
	RichTextToolbar: null,
	ImageToolbar: null,
	VideoToolbar: null,
	Dialogs: null,
	Toasts: null,
	A11y: null,
	FollowingIndicator: null,
	PeopleMenu: null,
	PeopleMenuAvatar: null,
	PeopleMenuItem: null,
	PeopleMenuFacePile: null,
	UserPresenceEditor: null,
}

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

/*
[1]
Setting a slot to `null` removes that part of the UI. Set only the slots you
want to hide; the `Required<>` type is here so this example lists every slot,
which is handy as a reference. Hiding `Toasts`, `Dialogs`, or `A11y`
also disables the features that render through them (toast notifications,
dialogs like the keyboard shortcuts panel, and screen reader announcements). To
hide everything at once, use the `hideUi` prop instead.
*/
```

--------

# Menu system hover

Category: UI & theming

Keywords: menu, hover, dropdown, programmatic, control, editor.menus, addopenmenu, deleteopenmenu, usemenuisopen

Open and close a dropdown menu from hover events using `editor.menus`.

tldraw keeps track of open menus in `editor.menus`, keyed by id. The UI's dropdown primitives read that state, so you can open or close a menu from anywhere by writing to it:

- `editor.menus.addOpenMenu(id)` opens a menu
- `editor.menus.deleteOpenMenu(id)` closes it
- `useMenuIsOpen(id)` subscribes to a menu's open state

Try hovering the green-labeled zone to open the dropdown and the red-labeled zone to close it. Clicking the trigger button still works as usual. This is handy for hover-driven toolbars or for closing menus in response to events elsewhere in your app.

## App.tsx

```tsx
import {
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	TldrawUiDropdownMenuContent,
	TldrawUiDropdownMenuItem,
	TldrawUiDropdownMenuRoot,
	TldrawUiDropdownMenuTrigger,
	useEditor,
	useMenuIsOpen,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './menu-system-hover.css'

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

// [1]
function HoverControlledMenu() {
	const editor = useEditor()
	const [isOpen] = useMenuIsOpen('hover-menu')

	return (
		<div className="hover-menu-container">
			{/* [2] */}
			<div
				className="hover-zone hover-zone-open"
				onMouseEnter={() => editor.menus.addOpenMenu('hover-menu')}
			>
				Hover to open menu
			</div>

			{/* [3] */}
			<div
				className="hover-zone hover-zone-close"
				onMouseEnter={() => editor.menus.deleteOpenMenu('hover-menu')}
			>
				Hover to close menu
			</div>

			{/* [4] */}
			<TldrawUiDropdownMenuRoot id="hover-menu">
				<TldrawUiDropdownMenuTrigger>
					<TldrawUiButton type="normal">
						<TldrawUiButtonLabel>Menu {isOpen ? '(open)' : '(closed)'}</TldrawUiButtonLabel>
					</TldrawUiButton>
				</TldrawUiDropdownMenuTrigger>
				<TldrawUiDropdownMenuContent>
					<TldrawUiDropdownMenuItem>
						<TldrawUiButton type="menu">
							<TldrawUiButtonLabel>Menu item 1</TldrawUiButtonLabel>
						</TldrawUiButton>
					</TldrawUiDropdownMenuItem>
					<TldrawUiDropdownMenuItem>
						<TldrawUiButton type="menu">
							<TldrawUiButtonLabel>Menu item 2</TldrawUiButtonLabel>
						</TldrawUiButton>
					</TldrawUiDropdownMenuItem>
					<TldrawUiDropdownMenuItem>
						<TldrawUiButton type="menu">
							<TldrawUiButtonLabel>Menu item 3</TldrawUiButtonLabel>
						</TldrawUiButton>
					</TldrawUiDropdownMenuItem>
				</TldrawUiDropdownMenuContent>
			</TldrawUiDropdownMenuRoot>
		</div>
	)
}

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

/*
tldraw tracks which menus are open in `editor.menus`, keyed by menu id. The dropdown
primitives read and write that state, so anything else that writes it can open or close
a menu too. Here two hover zones do exactly that.

[1]
`useMenuIsOpen(id)` returns `[isOpen, setIsOpen]` for a menu id and re-renders when the
state changes.

[2]
`editor.menus.addOpenMenu('hover-menu')` marks the menu as open. The dropdown with the
matching `id` responds by opening.

[3]
`editor.menus.deleteOpenMenu('hover-menu')` marks it closed again.

[4]
`TldrawUiDropdownMenuRoot` takes the same `id`, which is what links it to [2] and [3].
Clicking the trigger still toggles the menu the normal way.
*/
```

## menu-system-hover.css

```css
.hover-menu-container {
	position: absolute;
	top: 100px;
	left: 0;
	display: flex;
	flex-direction: column;
	gap: var(--tl-space-3);
	padding: var(--tl-space-3);
	z-index: var(--tl-layer-panels);
}

.hover-zone {
	padding: var(--tl-space-3) var(--tl-space-5);
	border-radius: var(--tl-radius-2);
	font-size: 13px;
	font-weight: 500;
	cursor: default;
	user-select: none;
	transition: opacity 0.15s ease;
	background-color: var(--tl-color-low);
	pointer-events: auto;
}

.hover-zone:hover {
	opacity: 0.8;
}

.hover-zone-open {
	color: var(--tl-color-success);
}

.hover-zone-close {
	color: var(--tl-color-danger);
}
```

--------

# Screen reader accessibility

Category: UI & theming

Keywords: accessibility, a11y, screen reader, aria, getariadescriptor, gettext, usea11y, announcements, aria live region, polite, assertive, wcag

Make custom shapes describe themselves to screen readers, and announce messages from your own UI.

When a shape is selected, tldraw announces it through an ARIA live region. The text comes from the shape util: `getAriaDescriptor()` first, falling back to `getText()`, followed by the shape type and its position in reading order. The card shape here overrides both methods, and a `translations` override gives the custom type a readable name (`tool.note-card`) for that announcement.

The top panel shows the other half: `useA11y()` returns an `announce()` function you can call from any component inside `<Tldraw />`. Use `priority: 'polite'` for confirmations and status updates that can wait, and `priority: 'assertive'` for errors that should interrupt. Try selecting a card with a screen reader running, then press the buttons.

## App.tsx

```tsx
import { useState } from 'react'
import {
	BaseBoxShapeUtil,
	HTMLContainer,
	RecordProps,
	T,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TLShape,
	TLUiOverrides,
	useA11y,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './screen-reader-accessibility.css'

const CARD_SHAPE_TYPE = 'note-card'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[CARD_SHAPE_TYPE]: { w: number; h: number; title: string; description: string }
	}
}

type CardShape = TLShape<typeof CARD_SHAPE_TYPE>

export class CardShapeUtil extends BaseBoxShapeUtil<CardShape> {
	static override type = CARD_SHAPE_TYPE
	static override props: RecordProps<CardShape> = {
		w: T.number,
		h: T.number,
		title: T.string,
		description: T.string,
	}

	getDefaultProps(): CardShape['props'] {
		return {
			w: 300,
			h: 180,
			title: 'Untitled',
			description: '',
		}
	}

	// [1]
	override getAriaDescriptor(shape: CardShape): string | undefined {
		const { title, description } = shape.props
		if (description) {
			return `${title} - ${description}`
		}
		return title
	}

	// [2]
	override getText(shape: CardShape): string | undefined {
		return `${shape.props.title}\n${shape.props.description}`
	}

	component(shape: CardShape) {
		const { title, description } = shape.props

		return (
			<HTMLContainer className="card-shape">
				<div className="card-shape-title">{title}</div>
				{description && <div className="card-shape-description">{description}</div>}
			</HTMLContainer>
		)
	}

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

const customShapes = [CardShapeUtil]

// [3]
const overrides: TLUiOverrides = {
	translations: {
		en: { [`tool.${CARD_SHAPE_TYPE}`]: 'Note card' },
	},
}

function CustomAnnouncementPanel() {
	const editor = useEditor()
	// [4]
	const a11y = useA11y()
	const [isEnabled, setIsEnabled] = useState(false)

	// [5]
	const handleActionConfirmation = () => {
		const selectedShapes = editor.getSelectedShapes()
		if (selectedShapes.length > 0) {
			a11y.announce({
				msg: `Action completed for ${selectedShapes.length} shape${selectedShapes.length === 1 ? '' : 's'}`,
				priority: 'polite',
			})
		} else {
			a11y.announce({
				msg: 'No shapes selected',
				priority: 'polite',
			})
		}
	}

	// [6]
	const handleValidation = () => {
		const selectedShapes = editor.getSelectedShapes()
		if (selectedShapes.length === 0) {
			a11y.announce({
				msg: 'Validation failed: No shapes selected',
				priority: 'assertive',
			})
		} else {
			const hasText = selectedShapes.some((shape) => {
				const util = editor.getShapeUtil(shape)
				return util.getText(shape)
			})
			if (!hasText) {
				a11y.announce({
					msg: 'Validation failed: Selected shapes must contain text',
					priority: 'assertive',
				})
			} else {
				a11y.announce({
					msg: 'Validation passed',
					priority: 'polite',
				})
			}
		}
	}

	// [7]
	const handleToggle = () => {
		const newState = !isEnabled
		setIsEnabled(newState)
		a11y.announce({
			msg: `Feature ${newState ? 'enabled' : 'disabled'}`,
			priority: 'polite',
		})
	}

	return (
		<div className="tlui-menu announcement-panel">
			<TldrawUiButton type="normal" onClick={handleActionConfirmation}>
				Perform action
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={handleValidation}>
				Validate selection
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={handleToggle}>
				{isEnabled ? 'Disable' : 'Enable'} feature
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: CustomAnnouncementPanel,
}

export default function ScreenReaderAccessibilityExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapes}
				overrides={overrides}
				components={components}
				onMount={(editor) => {
					// [8]
					editor.createShape({
						type: CARD_SHAPE_TYPE,
						x: 100,
						y: 100,
						props: {
							title: 'Meeting Notes',
							description: 'Discussed Q4 planning and team goals',
						},
					})

					editor.createShape({
						type: CARD_SHAPE_TYPE,
						x: 450,
						y: 100,
						props: {
							title: 'Project Ideas',
							description: 'Brainstorming session for new features',
						},
					})

					editor.createShape({
						type: CARD_SHAPE_TYPE,
						x: 100,
						y: 320,
						props: {
							title: 'Action Items',
							description: 'Follow up with design team by Friday',
						},
					})
				}}
			/>
		</div>
	)
}

/*
This example shows two sides of screen reader support: making a custom shape
describe itself when selected, and announcing your own messages from custom UI.

[1]
`getAriaDescriptor()` returns the text announced when the shape is selected.
It's the place for an alt-text-style description that may differ from what's
visibly rendered. If it returns nothing, the announcer falls back to
`getText()`.

[2]
`getText()` returns the shape's visible text. The editor uses it for text
extraction and search, and the announcer uses it as the fallback described in
[1]. Returning it here also lets the "Validate selection" button below check
whether the selected shapes have any text at all.

[3]
The selection announcement ends with the shape's type, looked up as
`tool.<type>` in the UI translations. Without an override a custom shape is
announced by its raw key ("tool.note-card"), so we add a translation for it.

[4]
`useA11y()` returns the accessibility context. It must be called from a
component rendered inside `<Tldraw />`, such as this `TopPanel` component.

[5]
Polite announcements queue behind whatever the screen reader is currently
saying. Use them for confirmations and status updates.

[6]
Assertive announcements interrupt the current speech. Reserve them for
messages the user must hear now, like validation errors.

[7]
Announce state changes when the visible change alone (here, the button label
flipping) wouldn't be noticed by a screen reader user.

[8]
Create three sample cards. Select one to hear the `getAriaDescriptor()`
text, followed by the shape type and its index in reading order ("1 of 3").
The announcements render into an off-screen ARIA live region owned by the
default `A11y` component, so nothing visible changes.
*/
```

## screen-reader-accessibility.css

```css
.announcement-panel {
	display: flex;
	flex-direction: row;
	flex-wrap: wrap;
	margin: 8px;
}

.card-shape {
	padding: var(--tl-space-5);
	background-color: white;
	border: 1px solid var(--tl-color-low-border);
	border-radius: var(--tl-radius-3);
	display: flex;
	flex-direction: column;
	gap: var(--tl-space-3);
}
```

--------

# Things on the canvas

Category: UI & theming

Keywords: canvas overlay, OnTheCanvas, InFrontOfTheCanvas, components, custom component, camera, page coordinates, pageToViewport, usevalue

Render React components on the canvas that either scale with the camera or float in front of it.

Two component slots live inside the canvas. `OnTheCanvas` components are positioned in page space and behave like shapes: they scale with the zoom and move when you pan. `InFrontOfTheCanvas` components render in screen space, so they follow the page but stay the same size. This example puts two counters on the canvas and a label in front of it that follows the current selection using `editor.getSelectionRotatedPageBounds()` and `editor.pageToViewport()`.

Try zooming: the counters grow and shrink, the label doesn't. Both slots are set through the `components` prop.

## App.tsx

```tsx
import { useState } from 'react'
import { Tldraw, TLEditorComponents, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './things-on-the-canvas.css'

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

// [1]
function MyComponent() {
	const [state, setState] = useState(0)
	const editor = useEditor()

	return (
		<>
			<div
				className="on-the-canvas-card"
				style={{ top: 50, left: 50, backgroundColor: 'goldenrod' }}
				onPointerDown={editor.markEventAsHandled}
			>
				<p>The count is {state}! </p>
				<button onClick={() => setState((s) => s - 1)}>-1</button>
				<p>These components are on the canvas. They will scale with camera zoom like shapes.</p>
			</div>
			<div
				className="on-the-canvas-card"
				style={{ top: 210, left: 150, backgroundColor: 'pink' }}
				onPointerDown={editor.markEventAsHandled}
			>
				<p>The count is {state}! </p>
				<button onClick={() => setState((s) => s + 1)}>+1</button>
				<p>Create and select a shape to see the in front of the canvas component</p>
			</div>
		</>
	)
}

// [2]
function MyComponentInFront() {
	const editor = useEditor()
	const position = useValue(
		'selection position',
		() => {
			const bounds = editor.getSelectionRotatedPageBounds()
			if (!bounds) return null
			return editor.pageToViewport(bounds.point)
		},
		[editor]
	)
	if (!position) return null

	return (
		<div
			className="in-front-of-the-canvas-card"
			style={{ top: Math.max(64, position.y - 64), left: Math.max(64, position.x) }}
		>
			<p>This won’t scale with zoom.</p>
		</div>
	)
}

// [3]
const components: TLEditorComponents = {
	OnTheCanvas: MyComponent,
	InFrontOfTheCanvas: MyComponentInFront,
}

export default function OnTheCanvasExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="things-on-the-canvas-example" components={components} />
		</div>
	)
}

/*
This example shows the two component slots that live inside the canvas:
`OnTheCanvas` and `InFrontOfTheCanvas`. `OnTheCanvas` components behave like
shapes: they scale with the zoom and move when the page is panned.
`InFrontOfTheCanvas` components render in screen space, so they move with the
page but don't scale.

For a component that ignores the camera entirely, put it in a UI slot such as
`TopPanel` or `SharePanel` instead (see the "UI zones" example).

[1]
Our `OnTheCanvas` component. Its `top`/`left` are page coordinates. We call
`editor.markEventAsHandled` on pointer down so clicks on the card don't also
reach the canvas and start a selection or brush.

[2]
Our `InFrontOfTheCanvas` component. We want it to sit next to the selection,
so we read the selection bounds inside `useValue`; the component re-renders
whenever the selection or the camera changes. `editor.pageToViewport` converts
the page-space point into viewport (screen) coordinates.

[3]
Define the components object once at module level, so `<Tldraw>` doesn't see a
new object on every render.
*/
```

## things-on-the-canvas.css

```css
.on-the-canvas-card {
	position: absolute;
	width: 200px;
	padding: 12px;
	border-radius: 8px;
	user-select: unset;
	box-shadow:
		0 0 0 1px rgba(0, 0, 0, 0.1),
		0 4px 8px rgba(0, 0, 0, 0.1);
}

.in-front-of-the-canvas-card {
	position: absolute;
	border-radius: 8px;
	padding: 0 10px;
	background: #efefef;
	box-shadow:
		0 0 0 1px rgba(0, 0, 0, 0.1),
		0 4px 8px rgba(0, 0, 0, 0.1);
}
```

--------

# Toasts and dialogs

Category: UI & theming

Keywords: toasts, dialogs, useToasts, useDialogs, addToast, addDialog, notifications, modals, TldrawUiDialog

Show toasts and dialogs from your own UI with the `useToasts` and `useDialogs` hooks.

`useToasts()` returns `addToast`, `removeToast`, and `clearToasts`; `useDialogs()` returns `addDialog`, `removeDialog`, and `clearDialogs`. Both hooks work in any component rendered inside `<Tldraw />`. This example puts a row of launcher buttons in the `SharePanel` slot.

`addDialog` takes a component that receives an `onClose` prop. Build the content from tldraw's dialog primitives (`TldrawUiDialogHeader`, `TldrawUiDialogBody`, `TldrawUiDialogFooter`) to match the default UI, or render anything you want. The example also shows a dialog containing a select menu, and a dialog that opens a second one on top of itself. Try opening the select and clicking outside it: the select closes but the dialog stays.

## App.tsx

```tsx
import { Select as _Select } from 'radix-ui'
import { useState } from 'react'
import {
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	TldrawUiDialogBody,
	TldrawUiDialogCloseButton,
	TldrawUiDialogFooter,
	TldrawUiDialogHeader,
	TldrawUiDialogTitle,
	TLUiDialogProps,
	useContainer,
	useDialogs,
	useToasts,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
function MyDialog({ onClose }: TLUiDialogProps) {
	return (
		<>
			<TldrawUiDialogHeader>
				<TldrawUiDialogTitle>Title</TldrawUiDialogTitle>
				<TldrawUiDialogCloseButton />
			</TldrawUiDialogHeader>
			<TldrawUiDialogBody style={{ maxWidth: 350 }}>
				<p>
					This dialog body holds a few sentences of text so you can see how longer content behaves.
					Regular prose wraps onto multiple lines within the dialog width.
				</p>
				<p>
					Long unbroken strings, like
					https://example.com/a/really/long/url/that/cannot/wrap/onto/the/next/line, also break
					instead of overflowing or being clipped.
				</p>
			</TldrawUiDialogBody>
			<TldrawUiDialogFooter className="tlui-dialog__footer__actions">
				<TldrawUiButton type="normal" onClick={onClose}>
					<TldrawUiButtonLabel>Cancel</TldrawUiButtonLabel>
				</TldrawUiButton>
				<TldrawUiButton type="primary" onClick={onClose}>
					<TldrawUiButtonLabel>Continue</TldrawUiButtonLabel>
				</TldrawUiButton>
			</TldrawUiDialogFooter>
		</>
	)
}

// [2]
function MySimpleDialog({ onClose }: TLUiDialogProps) {
	return (
		<div style={{ padding: 16 }}>
			<h2>Title</h2>
			<p>Description...</p>
			<button onClick={onClose}>Okay</button>
		</div>
	)
}

// [3]
function MyDialogWithSelect({ onClose }: TLUiDialogProps) {
	const container = useContainer()
	const [value, setValue] = useState('a')
	return (
		<>
			<TldrawUiDialogHeader>
				<TldrawUiDialogTitle>Dialog with a select</TldrawUiDialogTitle>
				<TldrawUiDialogCloseButton />
			</TldrawUiDialogHeader>
			<TldrawUiDialogBody style={{ maxWidth: 350 }}>
				<p>A select opened inside a modal is its own dismissable layer.</p>
				<_Select.Root value={value} onValueChange={setValue}>
					<_Select.Trigger
						data-testid="dialog-select.trigger"
						style={{ display: 'flex', alignItems: 'center', gap: 8 }}
					>
						<_Select.Value />
						<_Select.Icon>▾</_Select.Icon>
					</_Select.Trigger>
					<_Select.Portal container={container}>
						<_Select.Content
							data-testid="dialog-select.content"
							position="popper"
							sideOffset={4}
							style={{
								backgroundColor: 'var(--tl-color-panel)',
								boxShadow: 'var(--tl-shadow-3)',
								borderRadius: 'var(--tl-radius-2)',
								padding: 4,
								zIndex: 'var(--tl-layer-canvas-overlays)',
							}}
						>
							<_Select.Viewport>
								{['a', 'b', 'c'].map((v) => (
									<_Select.Item
										key={v}
										value={v}
										data-testid={`dialog-select.item-${v}`}
										style={{ padding: '4px 8px', cursor: 'pointer' }}
									>
										<_Select.ItemText>Option {v}</_Select.ItemText>
									</_Select.Item>
								))}
							</_Select.Viewport>
						</_Select.Content>
					</_Select.Portal>
				</_Select.Root>
			</TldrawUiDialogBody>
			<TldrawUiDialogFooter className="tlui-dialog__footer__actions">
				<TldrawUiButton type="primary" onClick={onClose}>
					<TldrawUiButtonLabel>Done</TldrawUiButtonLabel>
				</TldrawUiButton>
			</TldrawUiDialogFooter>
		</>
	)
}

// [4]
function MyNestedDialog({ onClose }: TLUiDialogProps) {
	const { addDialog } = useDialogs()
	return (
		<div data-testid="dialog-parent" style={{ padding: 16 }}>
			<h2>Parent dialog</h2>
			<p>Opens another dialog on top of itself.</p>
			<button
				data-testid="dialog-parent.open-nested"
				onClick={() => addDialog({ component: MyConfirmDialog })}
			>
				Open nested dialog
			</button>
			<button onClick={onClose}>Close</button>
		</div>
	)
}

function MyConfirmDialog({ onClose }: TLUiDialogProps) {
	return (
		<div data-testid="dialog-nested" style={{ padding: 16 }}>
			<h2>Nested dialog</h2>
			<button data-testid="dialog-nested.confirm" onClick={onClose}>
				Confirm
			</button>
		</div>
	)
}

// [5]
function CustomSharePanel() {
	const { addToast } = useToasts()
	const { addDialog } = useDialogs()

	return (
		<div style={{ padding: 16, gap: 16, display: 'flex', pointerEvents: 'all' }}>
			<button
				onClick={() => {
					addToast({ title: 'Hello world!', severity: 'success' })
				}}
			>
				Show toast
			</button>
			<button
				onClick={() => {
					addToast({
						title: 'This is a very long toast title that keeps going and going',
						description:
							'Long descriptions and unbroken strings like https://example.com/a/really/long/url/that/cannot/wrap/onto/the/next/line wrap within the toast instead of overflowing.',
						severity: 'info',
					})
				}}
			>
				Show long toast
			</button>
			<button
				data-testid="show-dialog"
				onClick={() => {
					addDialog({
						component: MyDialog,
						onClose: () => addToast({ title: 'Dialog closed', severity: 'info' }),
					})
				}}
			>
				Show dialog
			</button>
			<button
				onClick={() => {
					addDialog({ component: MySimpleDialog })
				}}
			>
				Show simple dialog
			</button>
			<button
				data-testid="show-dialog-with-select"
				onClick={() => {
					addDialog({ component: MyDialogWithSelect })
				}}
			>
				Show dialog with select
			</button>
		</div>
	)
}

// [6]
function StackedDialogLauncher() {
	const { addDialog } = useDialogs()
	return (
		<button
			data-testid="show-nested-dialog"
			style={{
				position: 'absolute',
				top: '50%',
				left: 8,
				transform: 'translateY(-50%)',
				pointerEvents: 'all',
			}}
			onClick={() => addDialog({ component: MyNestedDialog })}
		>
			Show nested dialog
		</button>
	)
}

const components: TLComponents = {
	SharePanel: CustomSharePanel,
	InFrontOfTheCanvas: StackedDialogLauncher,
}

export default function ToastsDialogsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw components={components} persistenceKey="toasts-and-dialogs-example" />
		</div>
	)
}

/*
The `useToasts` and `useDialogs` hooks return functions to add, remove, and
clear toasts and dialogs from anywhere inside `<Tldraw />`.

[1]
A dialog built from tldraw's dialog primitives (`TldrawUiDialogHeader`,
`TldrawUiDialogBody`, `TldrawUiDialogFooter`, and so on), so it matches the rest
of the UI. `onClose` is passed to your component by the dialog system; call it
from your own buttons to close the dialog. The `onClose` you pass to `addDialog`
is separate: it runs after the dialog closes, however it was dismissed (here we
show a toast from it).

[2]
...or render anything you like. The dialog system only supplies the modal
wrapper and the `onClose` callback.

[3]
Dialogs can contain their own popups, like this Radix select. Because tldraw's
dialog is a Radix dismissable layer, clicking outside an open select closes just
the select and leaves the dialog open; a second outside click closes the dialog.
Portal the select into `useContainer()` so it inherits tldraw's CSS variables.

[4]
Dialogs stack. A dialog can call `addDialog` to open another on top of itself,
and each one, including the topmost, keeps its own controls interactive.

[5]
The launcher buttons live in the `SharePanel` slot, top right of the UI.

[6]
The stacked-dialog launcher is rendered in `InFrontOfTheCanvas` instead, because
the share panel overflows off-screen on narrow mobile layouts and the e2e test
for stacked dialogs needs to reach it with a tap.
*/
```

--------

# UI primitives

Category: UI & theming

Keywords: button, dropdown, select, input, slider, popover, icon, tooltip, menu, ui

Tour the UI primitives tldraw exports for building panels, menus, and dialogs that match its look.

Everything in tldraw's default UI is built from a small set of exported primitives, and you can use the same ones in your own components. This example renders them all in an `OnTheCanvas` panel so you can zoom in and inspect them:

- `TldrawUiButton` with `TldrawUiButtonLabel` and `TldrawUiButtonIcon`, in its normal, primary, danger, icon, and menu types
- `TldrawUiDropdownMenu*` for menus with groups, checkbox items, and submenus
- `TldrawUiSelect*` for a select control, with and without item icons
- `TldrawUiInput` and `TldrawUiSlider`
- `TldrawUiPopover*` for floating content
- `TldrawUiIcon` for every icon in `iconTypes`
- `TldrawUiTooltip` and `TldrawUiKbd`

The primitives read tldraw's UI context and CSS variables, so they must be rendered inside `<Tldraw />` (in a `components` slot or as children) and they follow the editor's light or dark mode automatically.

## App.tsx

```tsx
import { useState } from 'react'
import {
	iconTypes,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonIcon,
	TldrawUiButtonLabel,
	TldrawUiDropdownMenuCheckboxItem,
	TldrawUiDropdownMenuContent,
	TldrawUiDropdownMenuGroup,
	TldrawUiDropdownMenuItem,
	TldrawUiDropdownMenuRoot,
	TldrawUiDropdownMenuSub,
	TldrawUiDropdownMenuSubContent,
	TldrawUiDropdownMenuSubTrigger,
	TldrawUiDropdownMenuTrigger,
	TldrawUiIcon,
	TldrawUiInput,
	TldrawUiKbd,
	TldrawUiPopover,
	TldrawUiPopoverContent,
	TldrawUiPopoverTrigger,
	TldrawUiSelect,
	TldrawUiSelectContent,
	TldrawUiSelectItem,
	TldrawUiSelectTrigger,
	TldrawUiSelectValue,
	TldrawUiSlider,
	TldrawUiTooltip,
	TLEditorComponents,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './ui-primitives.css'

// [1]
function UiShowcase() {
	const editor = useEditor()
	const [checkboxValue, setCheckboxValue] = useState(false)
	const [inputValue, setInputValue] = useState('')
	const [sliderValue, setSliderValue] = useState(50)
	const [selectValue, setSelectValue] = useState('medium')

	return (
		<div className="ui-showcase" onPointerDown={editor.markEventAsHandled}>
			<h2>UI primitives</h2>

			{/* Buttons */}
			<section>
				<h3>Buttons</h3>
				<div className="ui-row">
					<TldrawUiButton type="normal" onClick={() => {}}>
						<TldrawUiButtonLabel>Normal</TldrawUiButtonLabel>
					</TldrawUiButton>
					<TldrawUiButton type="primary" onClick={() => {}}>
						<TldrawUiButtonLabel>Primary</TldrawUiButtonLabel>
					</TldrawUiButton>
					<TldrawUiButton type="danger" onClick={() => {}}>
						<TldrawUiButtonLabel>Danger</TldrawUiButtonLabel>
					</TldrawUiButton>
					<TldrawUiButton type="normal" disabled>
						<TldrawUiButtonLabel>Disabled</TldrawUiButtonLabel>
					</TldrawUiButton>
				</div>
				<div className="ui-row">
					<TldrawUiButton type="icon" title="Draw tool">
						<TldrawUiButtonIcon icon="tool-pencil" />
					</TldrawUiButton>
					<TldrawUiButton type="icon" title="Eraser tool">
						<TldrawUiButtonIcon icon="tool-eraser" />
					</TldrawUiButton>
					<TldrawUiButton type="icon" title="Select tool">
						<TldrawUiButtonIcon icon="tool-pointer" />
					</TldrawUiButton>
					<TldrawUiButton type="normal">
						<TldrawUiButtonIcon icon="external-link" />
						<TldrawUiButtonLabel>With icon</TldrawUiButtonLabel>
					</TldrawUiButton>
				</div>
			</section>

			{/* Dropdown Menu */}
			<section>
				<h3>Dropdown menu</h3>
				<div className="ui-row">
					<TldrawUiDropdownMenuRoot id="example-dropdown">
						<TldrawUiDropdownMenuTrigger>
							<TldrawUiButton type="normal">
								<TldrawUiButtonLabel>Open menu</TldrawUiButtonLabel>
							</TldrawUiButton>
						</TldrawUiDropdownMenuTrigger>
						<TldrawUiDropdownMenuContent side="bottom" align="start">
							<TldrawUiDropdownMenuGroup>
								<TldrawUiDropdownMenuItem>
									<TldrawUiButton type="menu">
										<TldrawUiButtonLabel>Cut</TldrawUiButtonLabel>
										<TldrawUiKbd>⌘X</TldrawUiKbd>
									</TldrawUiButton>
								</TldrawUiDropdownMenuItem>
								<TldrawUiDropdownMenuItem>
									<TldrawUiButton type="menu">
										<TldrawUiButtonLabel>Copy</TldrawUiButtonLabel>
										<TldrawUiKbd>⌘C</TldrawUiKbd>
									</TldrawUiButton>
								</TldrawUiDropdownMenuItem>
								<TldrawUiDropdownMenuItem>
									<TldrawUiButton type="menu">
										<TldrawUiButtonLabel>Paste</TldrawUiButtonLabel>
										<TldrawUiKbd>⌘V</TldrawUiKbd>
									</TldrawUiButton>
								</TldrawUiDropdownMenuItem>
							</TldrawUiDropdownMenuGroup>
							<TldrawUiDropdownMenuGroup>
								<TldrawUiDropdownMenuCheckboxItem
									checked={checkboxValue}
									title="Toggle option"
									onSelect={() => setCheckboxValue(!checkboxValue)}
								>
									<TldrawUiButtonLabel>Checkbox item</TldrawUiButtonLabel>
								</TldrawUiDropdownMenuCheckboxItem>
							</TldrawUiDropdownMenuGroup>
							<TldrawUiDropdownMenuGroup>
								<TldrawUiDropdownMenuSub id="example-submenu">
									<TldrawUiDropdownMenuSubTrigger label="More options..." />
									<TldrawUiDropdownMenuSubContent>
										<TldrawUiDropdownMenuItem>
											<TldrawUiButton type="menu">
												<TldrawUiButtonLabel>Option A</TldrawUiButtonLabel>
											</TldrawUiButton>
										</TldrawUiDropdownMenuItem>
										<TldrawUiDropdownMenuItem>
											<TldrawUiButton type="menu">
												<TldrawUiButtonLabel>Option B</TldrawUiButtonLabel>
											</TldrawUiButton>
										</TldrawUiDropdownMenuItem>
									</TldrawUiDropdownMenuSubContent>
								</TldrawUiDropdownMenuSub>
							</TldrawUiDropdownMenuGroup>
						</TldrawUiDropdownMenuContent>
					</TldrawUiDropdownMenuRoot>
				</div>
			</section>

			{/* Select */}
			<section>
				<h3>Select</h3>
				<div className="ui-row">
					<TldrawUiSelect id="size-select-icons" value={selectValue} onValueChange={setSelectValue}>
						<TldrawUiSelectTrigger>
							<TldrawUiSelectValue placeholder="Select size...">{selectValue}</TldrawUiSelectValue>
						</TldrawUiSelectTrigger>
						<TldrawUiSelectContent>
							<TldrawUiSelectItem value="small" label="Small" icon="size-small" />
							<TldrawUiSelectItem value="medium" label="Medium" icon="size-medium" />
							<TldrawUiSelectItem value="large" label="Large" icon="size-large" />
						</TldrawUiSelectContent>
					</TldrawUiSelect>
					<TldrawUiSelect id="size-select" value={selectValue} onValueChange={setSelectValue}>
						<TldrawUiSelectTrigger>
							<TldrawUiSelectValue placeholder="Select...">{selectValue}</TldrawUiSelectValue>
						</TldrawUiSelectTrigger>
						<TldrawUiSelectContent>
							<TldrawUiSelectItem value="small" label="Small" />
							<TldrawUiSelectItem value="medium" label="Medium" />
							<TldrawUiSelectItem value="large" label="Large" />
						</TldrawUiSelectContent>
					</TldrawUiSelect>
					<TldrawUiSelect
						id="size-select-disabled"
						value={selectValue}
						onValueChange={setSelectValue}
						disabled
					>
						<TldrawUiSelectTrigger>
							<TldrawUiSelectValue placeholder="Select...">{selectValue}</TldrawUiSelectValue>
						</TldrawUiSelectTrigger>
						<TldrawUiSelectContent>
							<TldrawUiSelectItem value="small" label="Small" />
							<TldrawUiSelectItem value="medium" label="Medium" />
							<TldrawUiSelectItem value="large" label="Large" />
						</TldrawUiSelectContent>
					</TldrawUiSelect>
				</div>
			</section>

			{/* Input */}
			<section>
				<h3>Input</h3>
				<div className="ui-row">
					<TldrawUiInput
						placeholder="Enter text..."
						value={inputValue}
						onValueChange={setInputValue}
					/>
				</div>
			</section>

			{/* Slider */}
			<section>
				<h3>Slider</h3>
				<div className="ui-row ui-row-wide">
					<TldrawUiSlider
						label="opacity"
						title="Opacity"
						value={sliderValue}
						steps={100}
						onValueChange={setSliderValue}
					/>
					<span className="ui-value">{sliderValue}%</span>
				</div>
			</section>

			{/* Popover */}
			<section>
				<h3>Popover</h3>
				<div className="ui-row">
					<TldrawUiPopover id="example-popover">
						<TldrawUiPopoverTrigger>
							<TldrawUiButton type="normal">
								<TldrawUiButtonLabel>Open popover</TldrawUiButtonLabel>
							</TldrawUiButton>
						</TldrawUiPopoverTrigger>
						<TldrawUiPopoverContent side="bottom" align="start">
							<div className="ui-popover-content">
								<p>This is popover content!</p>
								<p>It can contain any elements.</p>
							</div>
						</TldrawUiPopoverContent>
					</TldrawUiPopover>
				</div>
			</section>

			{/* Icons */}
			<section>
				<h3>Icons ({iconTypes.length})</h3>
				<div className="ui-icon-grid">
					{iconTypes.map((icon) => (
						<TldrawUiTooltip key={icon} content={icon}>
							<div className="ui-icon-cell">
								<TldrawUiIcon icon={icon} label={icon} />
							</div>
						</TldrawUiTooltip>
					))}
				</div>
			</section>

			{/* Tooltip */}
			<section>
				<h3>Tooltip</h3>
				<div className="ui-row">
					<TldrawUiTooltip content="This is a tooltip!">
						<TldrawUiButton type="normal">
							<TldrawUiButtonLabel>Hover me</TldrawUiButtonLabel>
						</TldrawUiButton>
					</TldrawUiTooltip>
					<TldrawUiTooltip content="Info tooltip">
						<TldrawUiButton type="icon" title="Info">
							<TldrawUiButtonIcon icon="question-mark" />
						</TldrawUiButton>
					</TldrawUiTooltip>
				</div>
			</section>

			{/* Keyboard shortcuts */}
			<section>
				<h3>Keyboard shortcuts</h3>
				<div className="ui-row">
					<TldrawUiKbd>⌘</TldrawUiKbd>
					<TldrawUiKbd>⇧</TldrawUiKbd>
					<TldrawUiKbd>⌥</TldrawUiKbd>
					<TldrawUiKbd>⌃</TldrawUiKbd>
					<TldrawUiKbd>⌘S</TldrawUiKbd>
					<TldrawUiKbd>⌘⇧Z</TldrawUiKbd>
				</div>
			</section>
		</div>
	)
}

// [2]
const components: TLEditorComponents = {
	OnTheCanvas: UiShowcase,
}

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

/*
[1]
A tour of the UI primitives exported from tldraw: buttons, dropdown menus,
selects, inputs, sliders, popovers, icons, tooltips, and keyboard shortcut
badges. They all read tldraw's CSS variables, so anything you build with them
matches the rest of the UI (including dark mode). The showcase calls
`editor.markEventAsHandled` on pointer down so clicks on the controls don't also
reach the canvas.

[2]
The showcase is rendered in the `OnTheCanvas` slot, so it scales with the
camera. That's deliberate: zoom in to inspect the components at different
sizes. The primitives need the UI context that `<Tldraw />` provides, so they
must be rendered inside it (a `components` slot, or as children).
*/
```

## ui-primitives.css

```css
.ui-showcase {
	position: absolute;
	top: 32px;
	left: 32px;
	pointer-events: all;
	background: var(--tl-color-panel);
	border-radius: var(--tl-radius-3);
	padding: 16px;
	width: 380px;
	box-shadow: var(--tl-shadow-2);
	user-select: none;
}

.ui-showcase h2 {
	margin: 0 0 16px 0;
	font-size: 16px;
	font-weight: 600;
}

.ui-showcase h3 {
	margin: 0 0 8px 0;
	font-size: 12px;
	font-weight: 500;
	color: var(--tl-color-text-1);
	text-transform: uppercase;
	letter-spacing: 0.5px;
}

.ui-showcase section {
	margin-bottom: 20px;
}

.ui-showcase section:last-child {
	margin-bottom: 0;
}

.ui-row {
	display: flex;
	flex-wrap: wrap;
	gap: 8px;
	align-items: center;
}

.ui-row-wide {
	width: 100%;
}

.ui-value {
	font-size: 12px;
	color: var(--tl-color-text-1);
	min-width: 40px;
}

.ui-popover-content {
	padding: 12px 16px;
	font-size: 13px;
}

.ui-popover-content p {
	margin: 0 0 8px 0;
}

.ui-popover-content p:last-child {
	margin-bottom: 0;
}

.ui-icon-grid {
	display: grid;
	grid-template-columns: repeat(auto-fill, 24px);
	gap: 4px;
}

.ui-icon-cell {
	display: flex;
	align-items: center;
	justify-content: center;
	width: 24px;
	height: 24px;
	border-radius: 4px;
}

.ui-icon-cell:hover {
	background: var(--tl-color-muted-2);
}
```

--------

# UI zones

Category: UI & theming

Keywords: zones, TopPanel, SharePanel, ui zones, custom panels, components override, top zone, share zone

Fill the empty `TopPanel` and `SharePanel` slots with your own components.

The default UI leaves two slots empty for you: `TopPanel` in the top center of the screen and `SharePanel` in the top right, above the style panel. Set either one through the `components` prop to render your own React component there. tldraw.com uses them for the document title and the share button.

## App.tsx

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

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

// [1]
function CustomTopPanel() {
	return (
		<div
			style={{
				backgroundColor: 'thistle',
				width: '100%',
				textAlign: 'center',
				padding: '2px',
				minWidth: '80px',
			}}
		>
			<p>Top panel</p>
		</div>
	)
}

// [2]
function CustomSharePanel() {
	return (
		<div
			style={{
				backgroundColor: 'thistle',
				width: '100%',
				textAlign: 'center',
				minWidth: '80px',
			}}
		>
			<p>Share panel</p>
		</div>
	)
}

const components: TLComponents = {
	SharePanel: CustomSharePanel,
	TopPanel: CustomTopPanel,
}

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

/*
The default UI leaves two slots empty for you to fill: `TopPanel` in the top
center of the screen, and `SharePanel` in the top right, above the style panel.
Both are set through the `components` prop like any other slot.

[1]
Rendered in the top center. tldraw.com uses this slot for the document title.

[2]
Rendered in the top right. tldraw.com uses this slot for the share button and
collaborator avatars.
*/
```

--------

# Hide the entire UI

Category: UI & theming

Keywords: hideui, bare editor, minimal, custom ui, headless

Hide all of tldraw's default UI with the `hideUi` prop.

Passing `hideUi` to `<Tldraw>` removes the toolbar, menus, and panels while keeping the canvas, default shapes, tools, and keyboard shortcuts. The editor is fully functional; you just need to provide your own controls, typically by rendering components inside `<Tldraw>` that call `useEditor()`.

Keyboard shortcuts still work here, so try pressing `d` for the draw tool or `r` for a rectangle. See the custom UI example for building your own controls.

## App.tsx

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

export default function HideUiExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="hide-ui-example" hideUi />
		</div>
	)
}

/*
`hideUi` removes all of tldraw's default UI but keeps the editor, its tools, and its
keyboard shortcuts. Build your own controls on top with `useEditor()`; see the
custom UI example for a starting point.
*/
```

--------

# Replace the entire UI

Category: UI & theming

Keywords: hideui, custom ui, keyboard shortcuts, setcurrenttool, track, useeditor, toolbar, buttons

Hide tldraw's UI with `hideUi` and build your own toolbar and shortcuts on top of the editor.

Pass `hideUi` to the `Tldraw` component to hide the default UI, then render your own components as children so they can reach the editor through `useEditor`. This example adds a minimal toolbar with select, pencil, and eraser buttons, plus keyboard shortcuts for switching tools and deleting shapes.

The toolbar is wrapped in `track()` so the active button follows `editor.getCurrentToolId()`. `hideUi` doesn't remove the context menu; see the exploded example for how to omit it.

## App.tsx

```tsx
import { useEffect } from 'react'
import { Tldraw, track, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './custom-ui.css'

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

// [1]
export default function CustomUiExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw hideUi>
				<CustomUi />
			</Tldraw>
		</div>
	)
}

// [2]
const CustomUi = track(() => {
	const editor = useEditor()

	useEffect(() => {
		const handleKeyUp = (e: KeyboardEvent) => {
			if (editor.getEditingShapeId() !== null) return
			const target = e.target as HTMLElement | null
			if (target?.isContentEditable) return
			if (target?.tagName === 'INPUT' || target?.tagName === 'TEXTAREA') return

			switch (e.key) {
				case 'Delete':
				case 'Backspace': {
					editor.deleteShapes(editor.getSelectedShapeIds())
					break
				}
				case 'v': {
					editor.setCurrentTool('select')
					break
				}
				case 'e': {
					editor.setCurrentTool('eraser')
					break
				}
				case 'x':
				case 'p':
				case 'b':
				case 'd': {
					editor.setCurrentTool('draw')
					break
				}
			}
		}

		window.addEventListener('keyup', handleKeyUp)
		return () => {
			window.removeEventListener('keyup', handleKeyUp)
		}
	}, [editor])

	return (
		<div className="custom-layout">
			<div className="custom-toolbar">
				<button
					className="custom-button"
					data-isactive={editor.getCurrentToolId() === 'select'}
					onClick={() => editor.setCurrentTool('select')}
				>
					Select
				</button>
				<button
					className="custom-button"
					data-isactive={editor.getCurrentToolId() === 'draw'}
					onClick={() => editor.setCurrentTool('draw')}
				>
					Pencil
				</button>
				<button
					className="custom-button"
					data-isactive={editor.getCurrentToolId() === 'eraser'}
					onClick={() => editor.setCurrentTool('eraser')}
				>
					Eraser
				</button>
			</div>
		</div>
	)
})

/*
[1]
We render the `Tldraw` component with the `hideUi` prop, which hides the default toolbar, style
panel, menus, and so on. Our custom UI is rendered as a child of `Tldraw`, which gives it access to
the editor instance via React context.

The context menu isn't hidden by `hideUi`. If you want to hide it too, render the parts that make
up the `Tldraw` component separately and omit the context menu; see the exploded example.

[2]
The component is wrapped in `track()` so it re-renders when the signals it reads change; here
`editor.getCurrentToolId()` drives which button is active. See the signals example for more:
https://tldraw.dev/examples/signals

We get the editor via `useEditor` and add a window `keyup` listener for our own shortcuts. The
listener skips key presses while a shape is being edited or when an input has focus, so typing text
doesn't switch tools.
*/
```

## custom-ui.css

```css
.custom-layout {
	position: absolute;
	inset: 0px;
	z-index: 300;
	pointer-events: none;
}

.custom-toolbar {
	position: absolute;
	top: 0px;
	left: 0px;
	width: 100%;
	display: flex;
	align-items: center;
	justify-content: center;
	padding: 8px;
	gap: 8px;
}

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

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

--------

# Contextual toolbar

Category: UI & theming

Keywords: contextual toolbar, infrontofthecanvas, selection, ui overlay, custom ui, toolbar, selected shapes

Show a toolbar above the selected shapes using the `TldrawUiContextualToolbar` primitive.

The toolbar is rendered in the `InFrontOfTheCanvas` slot, so it appears above the canvas but below the rest of the UI. It positions itself using the bounds returned from `getSelectionBounds`, and reads the shared size style of the selection with `editor.getSharedStyles()`.

Select shapes of different types and change their size from the toolbar; this works just like changing the size from the style panel on the right.

## App.tsx

```tsx
import {
	Box,
	DefaultSizeStyle,
	Tldraw,
	TldrawUiButtonIcon,
	TldrawUiContextualToolbar,
	TldrawUiToolbarButton,
	TLEditorComponents,
	TLEditorSnapshot,
	track,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import _jsonSnapshot from './snapshot.json'

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

const jsonSnapshot = _jsonSnapshot as any as TLEditorSnapshot

const SIZES = [
	{ value: 's', icon: 'size-small' },
	{ value: 'm', icon: 'size-medium' },
	{ value: 'l', icon: 'size-large' },
	{ value: 'xl', icon: 'size-extra-large' },
] as const

// [1]
const ContextualToolbarComponent = track(() => {
	const editor = useEditor()
	const showToolbar = editor.isIn('select.idle')

	// [2]
	const size = editor.getSharedStyles().get(DefaultSizeStyle)
	if (!size || !showToolbar) return null
	const currentSize = size.type === 'shared' ? size.value : undefined

	// [3]
	const getSelectionBounds = () => {
		const fullBounds = editor.getSelectionRotatedScreenBounds()
		if (!fullBounds) return undefined
		return new Box(fullBounds.x, fullBounds.y, fullBounds.width, 0)
	}

	return (
		<TldrawUiContextualToolbar getSelectionBounds={getSelectionBounds} label="Sizes">
			{SIZES.map(({ value, icon }) => {
				return (
					<TldrawUiToolbarButton
						key={value}
						title={value.toUpperCase()}
						type="icon"
						isActive={value === currentSize}
						onClick={() => editor.setStyleForSelectedShapes(DefaultSizeStyle, value)}
					>
						<TldrawUiButtonIcon small icon={icon} />
					</TldrawUiToolbarButton>
				)
			})}
		</TldrawUiContextualToolbar>
	)
})

const components: TLEditorComponents = {
	InFrontOfTheCanvas: ContextualToolbarComponent,
}

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

/*
`TldrawUiContextualToolbar` is rendered in the `InFrontOfTheCanvas` slot, so it sits on top of
the shapes but behind the rest of the UI.

[1]
The component is wrapped in `track()` so it re-renders when the selection, camera, or tool state
changes. We only show the toolbar while the select tool is idle, so it disappears while shapes are
being dragged, resized, or rotated.

[2]
Different shapes support different style properties. `getSharedStyles()` returns the styles
supported by every selected shape; if none of them support `DefaultSizeStyle` we don't show the
toolbar at all. If all the shapes have the same size, the entry's type is `shared` and we highlight
that size. If they differ, the type is `mixed` and nothing is highlighted.

[3]
`getSelectionBounds` tells the toolbar where to position itself. Here we use the selection's
rotated screen bounds with a height of zero so the toolbar sits along the top edge; you can use
any other logic you like.
*/
```

--------

# Custom canvas components

Category: UI & theming

Keywords: components, Background, Canvas, Grid, Cursor, ShapeIndicator, OnTheCanvas, InFrontOfTheCanvas, custom ui, override

Replace tldraw's on-canvas components, such as the background, with your own.

tldraw's on-canvas UI is built from replaceable React components: the background, grid, cursors, shape indicators, and more. Pass your own via the `components` prop, or pass `null` to hide one. This example replaces the `Background` component with a light blue div. See `TLEditorComponents` for the full list of slots.

## App.tsx

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

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

// [1]
const components: TLEditorComponents = {
	Background: () => {
		return <div style={{ position: 'absolute', inset: 0, backgroundColor: '#f0f8ff' }} />
	},
}

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

/*
The `components` prop replaces the background, grid, cursors, shape indicators, and more. See
`TLEditorComponents` for the full list.

[1]
Define the components object outside the React component so it's a stable reference. Here we
replace the `Background` component with a plain div in a light blue color. Passing `null` for a
component hides it entirely.
*/
```

--------

# Custom grid

Category: UI & theming

Keywords: grid, canvas, 2d context, Grid component, getViewportPageBounds, devicePixelRatio, camera, custom rendering

Draw a custom grid on the canvas with a 2d canvas context.

Override the `Grid` component via the `components` prop to draw your own grid. The component receives the camera position, zoom, and grid size, and this example uses them to draw minor and major grid lines into a 2d canvas at the device's pixel ratio. Grid mode is turned on in `onMount` so the grid is visible immediately.

Try zooming and panning; the grid redraws to match the camera and switches color in dark mode.

## App.tsx

```tsx
import { useLayoutEffect, useRef } from 'react'
import { TLComponents, Tldraw, approximately, useColorMode, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'

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

const components: TLComponents = {
	// [1]
	Grid: ({ size, ...camera }) => {
		const editor = useEditor()

		// [2]
		const screenBounds = useValue('screenBounds', () => editor.getViewportScreenBounds(), [editor])
		const devicePixelRatio = useValue('dpr', () => editor.getInstanceState().devicePixelRatio, [
			editor,
		])
		const isDarkMode = useColorMode() === 'dark'

		const canvas = useRef<HTMLCanvasElement>(null)

		useLayoutEffect(() => {
			if (!canvas.current) return
			// [3]
			const canvasW = screenBounds.w * devicePixelRatio
			const canvasH = screenBounds.h * devicePixelRatio
			canvas.current.width = canvasW
			canvas.current.height = canvasH

			const ctx = canvas.current?.getContext('2d')
			if (!ctx) return

			ctx.clearRect(0, 0, canvasW, canvasH)

			// [4]
			const pageViewportBounds = editor.getViewportPageBounds()

			const startPageX = Math.ceil(pageViewportBounds.minX / size) * size
			const startPageY = Math.ceil(pageViewportBounds.minY / size) * size
			const endPageX = Math.floor(pageViewportBounds.maxX / size) * size
			const endPageY = Math.floor(pageViewportBounds.maxY / size) * size
			const numRows = Math.round((endPageY - startPageY) / size)
			const numCols = Math.round((endPageX - startPageX) / size)

			ctx.strokeStyle = isDarkMode ? '#555' : '#BBB'

			// [5]
			for (let row = 0; row <= numRows; row++) {
				const pageY = startPageY + row * size
				// convert the page-space Y offset into our canvas' coordinate space
				const canvasY = (pageY + camera.y) * camera.z * devicePixelRatio
				const isMajorLine = approximately(pageY % (size * 10), 0)
				drawLine(ctx, 0, canvasY, canvasW, canvasY, isMajorLine ? 3 : 1)
			}
			for (let col = 0; col <= numCols; col++) {
				const pageX = startPageX + col * size
				// convert the page-space X offset into our canvas' coordinate space
				const canvasX = (pageX + camera.x) * camera.z * devicePixelRatio
				const isMajorLine = approximately(pageX % (size * 10), 0)
				drawLine(ctx, canvasX, 0, canvasX, canvasH, isMajorLine ? 3 : 1)
			}
		}, [screenBounds, camera, size, devicePixelRatio, editor, isDarkMode])

		// [6]
		return <canvas className="tl-grid" ref={canvas} />
	},
}

export default function CustomGridExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="custom-grid-example"
				components={components}
				onMount={(e) => {
					e.updateInstanceState({ isGridMode: true })
				}}
			/>
		</div>
	)
}

function drawLine(
	ctx: CanvasRenderingContext2D,
	x1: number,
	y1: number,
	x2: number,
	y2: number,
	width: number
) {
	ctx.beginPath()
	ctx.moveTo(x1, y1)
	ctx.lineTo(x2, y2)
	ctx.lineWidth = width
	ctx.stroke()
}

/*
[1]
To add a custom grid, override the `Grid` component. It receives the camera position and zoom
along with the grid size in page space, and re-renders whenever the camera moves.

[2]
Besides the camera, the grid also needs to redraw when the screen bounds change, when the device
pixel ratio changes, or when the color mode changes. `useValue` and `useColorMode` subscribe to
those values so the component re-renders when they change.

[3]
To avoid pixelation we render at the device's actual resolution, so the canvas size is scaled by
the device pixel ratio.

[4]
Calculate the first and last grid lines visible in the viewport, in page space, so we only draw
the lines that are actually on screen.

[5]
Convert each page-space line position into canvas pixels using the camera and device pixel ratio.
Major lines are drawn every 10 grid units.

[6]
The `tl-grid` class is important for correct positioning and pointer-event handling.
*/
```

--------

# Drag and drop tray

Category: UI & theming

Keywords: drag, drop, tray, shapes, InFrontOfTheCanvas, useAtom, useQuickReactor, screenToPage

Drag items from a custom tray onto the canvas to create shapes.

The tray is a custom `InFrontOfTheCanvas` component that renders over the canvas. Each item tracks its own pointer events through a small state machine (`idle`, `pointing_item`, `dragging`) held in a `useAtom`. A drag only starts after the pointer moves more than 10px, so clicking an item does nothing.

On drop, `editor.screenToPage()` converts the pointer position to page space and `editor.createShape()` places the shape there. `useQuickReactor` positions the drag preview by writing to the DOM directly, avoiding a React render per pointer move.

Try dragging an emoji from the tray on the left onto the canvas. Press Escape mid-drag to cancel.

## App.tsx

```tsx
import { useMemo, useRef } from 'react'
import {
	Box,
	TLEditorComponents,
	Tldraw,
	Vec,
	useAtom,
	useEditor,
	useQuickReactor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './drag-and-drop-tray.css'
import { TRAY_ITEMS, TrayItem } from './trayitems'

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

// [1]
type DragState =
	| {
			name: 'idle'
	  }
	| {
			name: 'pointing_item'
			item: TrayItem
			startPosition: Vec
	  }
	| {
			name: 'dragging'
			item: TrayItem
			currentPosition: Vec
	  }

// [2]
const DragAndDropTray = () => {
	const rTrayContainer = useRef<HTMLDivElement>(null)
	const rDraggingImage = useRef<HTMLDivElement>(null)

	const editor = useEditor()

	// [3]
	const dragState = useAtom<DragState>('dragState', () => ({
		name: 'idle',
	}))

	// [4]
	const { handlePointerUp, handlePointerDown } = useMemo(() => {
		let target: HTMLDivElement | null = null

		function handlePointerMove(e: PointerEvent) {
			const current = dragState.get()
			const screenPoint = new Vec(e.clientX, e.clientY)

			switch (current.name) {
				case 'idle': {
					break
				}
				case 'pointing_item': {
					const dist = Vec.Dist(screenPoint, current.startPosition)
					if (dist > 10) {
						// [a]
						dragState.set({
							name: 'dragging',
							item: current.item,
							currentPosition: screenPoint,
						})
					}
					break
				}
				case 'dragging': {
					// [b]
					dragState.set({
						...current,
						currentPosition: screenPoint,
					})
					break
				}
			}
		}

		function handlePointerUp(e: React.PointerEvent) {
			const current = dragState.get()

			target = e.currentTarget as HTMLDivElement
			target.releasePointerCapture(e.pointerId)

			switch (current.name) {
				case 'idle': {
					break
				}
				case 'pointing_item': {
					dragState.set({
						name: 'idle',
					})
					break
				}
				case 'dragging': {
					// [c]
					const screenPoint = new Vec(e.clientX, e.clientY)
					const pagePoint = editor.screenToPage(screenPoint)

					editor.markHistoryStoppingPoint('create shape from tray')

					editor.createShape({
						...current.item.shapeBase,
						x: pagePoint.x - 50, // center on cursor at 100x100
						y: pagePoint.y - 50,
					})

					dragState.set({
						name: 'idle',
					})

					break
				}
			}

			removeEventListeners()
		}

		function handlePointerDown(e: React.PointerEvent) {
			e.preventDefault()
			target = e.currentTarget as HTMLDivElement
			target.setPointerCapture(e.pointerId)

			const itemIndex = target.dataset.drag_item_index!
			const item = TRAY_ITEMS[+itemIndex]

			if (!item) return

			const startPosition = new Vec(e.clientX, e.clientY)

			// [d]
			dragState.set({
				name: 'pointing_item',
				item,
				startPosition,
			})

			target.addEventListener('pointermove', handlePointerMove)
			document.addEventListener('keydown', handleKeyDown)
		}

		function handleKeyDown(e: KeyboardEvent) {
			const current = dragState.get()
			if (e.key === 'Escape' && current.name === 'dragging') {
				removeEventListeners()
			}
		}

		function removeEventListeners() {
			if (target) {
				target.removeEventListener('pointermove', handlePointerMove)
				document.removeEventListener('keydown', handleKeyDown)
			}

			dragState.set({
				name: 'idle',
			})
		}

		return {
			handlePointerDown,
			handlePointerUp,
		}
	}, [dragState, editor])

	const state = useValue('dragState', () => dragState.get(), [dragState])

	// [5]
	useQuickReactor(
		'drag-image-style',
		() => {
			const current = dragState.get()
			const imageRef = rDraggingImage.current
			const trayContainerRef = rTrayContainer.current
			if (!imageRef || !trayContainerRef) return

			switch (current.name) {
				case 'idle':
				case 'pointing_item': {
					imageRef.style.display = 'none'
					break
				}
				case 'dragging': {
					const trayContainerRect = trayContainerRef.getBoundingClientRect()
					const box = new Box(
						trayContainerRect.x,
						trayContainerRect.y,
						trayContainerRect.width,
						trayContainerRect.height
					)
					const viewportScreenBounds = editor.getViewportScreenBounds()
					const isInside = Box.ContainsPoint(box, current.currentPosition)
					if (isInside) {
						imageRef.style.display = 'none'
					} else {
						imageRef.style.position = 'absolute'
						imageRef.style.pointerEvents = 'none'
						imageRef.style.left = '0px'
						imageRef.style.top = '0px'
						imageRef.style.transform = `translate(${current.currentPosition.x - viewportScreenBounds.x - 25}px, ${current.currentPosition.y - viewportScreenBounds.y - 25}px)`
						imageRef.style.width = '50px'
						imageRef.style.height = '50px'
						imageRef.style.fontSize = '40px'
						imageRef.style.display = 'flex'
						imageRef.style.alignItems = 'center'
					}
				}
			}
		},
		[dragState]
	)

	return (
		<>
			{/* [6] */}
			<div className="drag-tray" ref={rTrayContainer}>
				<div className="drag-tray-items">
					{TRAY_ITEMS.map((item, index) => (
						<div
							key={item.id}
							className="drag-tray-item"
							data-drag_item_index={index}
							onPointerDown={handlePointerDown}
							onPointerUp={handlePointerUp}
						>
							{item.emoji}
						</div>
					))}
				</div>
			</div>
			{/* [7] */}
			<div ref={rDraggingImage}>{state.name === 'dragging' && state.item.emoji}</div>
		</>
	)
}

// [8]
const components: TLEditorComponents = {
	InFrontOfTheCanvas: DragAndDropTray,
}

export default function DragAndDropTrayExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="drag-and-drop-tray-example" components={components} />
		</div>
	)
}

/*
This example builds a tray of items that can be dragged onto the canvas to create shapes.
The tray is a custom `InFrontOfTheCanvas` component, so it renders over the canvas but
inside tldraw's UI layer, and it drives the interaction with its own small state machine.

[1]
`DragState` is a discriminated union: `idle`, `pointing_item` (pointer is down but hasn't
moved far enough to count as a drag), and `dragging`. Modelling it this way means each
handler only has to deal with the transitions that are valid from its current state.

[2]
`rTrayContainer` is used for bounds checking (we hide the preview while the pointer is
still over the tray) and `rDraggingImage` is the preview element that follows the cursor.

[3]
`useAtom` gives us a reactive atom that both the memoized event handlers and the
`useQuickReactor` below can read without being recreated when the state changes.

[4]
The handlers are created once in `useMemo` and read the atom directly, so they don't go
stale.
	[a] We only enter `dragging` after the pointer moves more than 10px, so a plain click
	on a tray item doesn't accidentally create a shape.
	[b] While dragging we just track the pointer position; the preview is positioned in [5].
	[c] On pointer up while dragging, convert the screen point to page space with
	`editor.screenToPage()` and create the shape there. `markHistoryStoppingPoint` makes
	each drop its own undo step.
	[d] On pointer down we capture the pointer on the item element, so we keep receiving
	move/up events even when the pointer leaves it. The item index comes from a `data-`
	attribute so one handler serves every item.

[5]
`useQuickReactor` runs synchronously whenever `dragState` changes and writes styles to the
preview element directly. Positioning via the DOM rather than React state avoids a React
render on every pointer move. The offset by `getViewportScreenBounds()` converts the
client coordinates to coordinates relative to the editor container, which is what an
`InFrontOfTheCanvas` component is positioned against.

[6]
Each tray item gets the shared pointer handlers and a `data-drag_item_index` attribute
that [4d] reads back.

[7]
The preview element only has content while dragging; [5] handles showing and hiding it.

[8]
`components` is defined at module level so `<Tldraw>` doesn't see a new object on every
render, which would remount the UI.
*/
```

## drag-and-drop-tray.css

```css
.drag-tray {
	position: absolute;
	left: 10px;
	top: 50px;
	background: var(--tl-color-panel);
	border-radius: 9px;
	box-shadow: var(--tl-shadow-1);
	z-index: 1000;
	pointer-events: all;
	overflow: hidden;
}

.drag-tray-items {
	display: flex;
	flex-direction: column;
	gap: 4px;
}

.drag-tray-item {
	display: flex;
	align-items: center;
	justify-content: center;
	gap: 12px;
	width: 40px;
	height: 40px;
	border-radius: 8px;
	cursor: grab;
	transition: all 0.2s ease;
	user-select: none;
	font-size: 18px;
}
```

## trayitems.ts

```ts
import { TLShape, toRichText } from 'tldraw'

// Distributes over the shape union so `props` is typed against the matching shape's props.
export type TrayItem<T extends TLShape = TLShape> = T extends T
	? {
			id: string
			emoji: string
			label: string
			shapeBase: {
				type: T['type']
				props: Partial<T['props']>
			}
		}
	: never

export const TRAY_ITEMS: TrayItem<TLShape>[] = [
	{
		id: 'snowman',
		emoji: '⛄',
		label: 'Snowman',
		shapeBase: {
			type: 'geo',
			props: {
				richText: toRichText('⛄'),
				size: 'm',
			},
		},
	},
	{
		id: 'ice-cream',
		emoji: '🍦',
		label: 'Ice Cream',
		shapeBase: {
			type: 'geo',
			props: {
				richText: toRichText('🍦'),
				size: 'm',
			},
		},
	},
	{
		id: 'smiley',
		emoji: '😊',
		label: 'Smiley',
		shapeBase: {
			type: 'geo',
			props: {
				richText: toRichText('😊'),
				size: 'm',
			},
		},
	},
	{
		id: 'star',
		emoji: '⭐',
		label: 'Star',
		shapeBase: {
			type: 'geo',
			props: {
				richText: toRichText('⭐'),
				size: 'm',
			},
		},
	},
	{
		id: 'heart',
		emoji: '❤️',
		label: 'Heart',
		shapeBase: {
			type: 'geo',
			props: {
				richText: toRichText('❤️'),
				size: 'm',
			},
		},
	},
]
```

--------

# Error boundary

Category: UI & theming

Keywords: error handling, shapeerrorfallback, error boundary, components, crash recovery, fallback ui

Customize the fallback shown when a shape throws while rendering.

Every shape renders inside its own error boundary, so a shape that throws doesn't crash the editor. Instead tldraw renders the `ShapeErrorFallback` component in its place. Override it through the `components` prop to show your own message; it receives the thrown `error` as a prop.

This example registers a shape whose `component()` always throws and creates one on mount so you can see the custom fallback immediately.

## App.tsx

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

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

// [1]
const shapeUtils = [ErrorShapeUtil]

// [2]
const components: TLComponents = {
	ShapeErrorFallback: ({ error }) => <div>Shape error! {String(error)}</div>,
}

export default function ErrorBoundaryExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				onMount={(editor) => {
					// [3]
					editor.createShape({ type: 'error' })
				}}
			/>
		</div>
	)
}

/*
Each shape renders inside its own error boundary, so a shape that throws shows a fallback
instead of taking down the editor. This example customizes that fallback.

[1]
A custom shape whose `component()` always throws. See ErrorShape.ts.

[2]
`ShapeErrorFallback` receives the thrown `error`. Like `shapeUtils`, `components` is
defined at module level so `<Tldraw>` doesn't see a new object every render.

[3]
Create the error shape on mount so the fallback is visible straight away.
*/
```

## ErrorShape.ts

```ts
import { BaseBoxShapeUtil, TLShape } from 'tldraw'

const ERROR_TYPE = 'error'

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

export type ErrorShape = TLShape<typeof ERROR_TYPE>

export class ErrorShapeUtil extends BaseBoxShapeUtil<ErrorShape> {
	static override type = ERROR_TYPE
	getDefaultProps() {
		return { w: 100, h: 100 }
	}
	component() {
		throw new Error('Error!')
	}
	// Indicators are drawn on a shared canvas overlay with no error boundary, so
	// throwing here would break every overlay. Return nothing instead.
	getIndicatorPath() {
		return undefined
	}
}
```

--------

# Selection UI

Category: UI & theming

Keywords: selection, ui overlay, infrontofthecanvas, custom controls, duplicate, handles, usevalue, getselectionrotatedscreenbounds

Add duplicate-in-direction buttons around the selection using the `InFrontOfTheCanvas` slot.

The `InFrontOfTheCanvas` component renders in screen space above the canvas, so anything you put there stays a fixed size while the camera moves. This example reads `editor.getSelectionRotatedScreenBounds()` and `editor.getSelectionRotation()` inside `useValue` to position four buttons around the selection, rotated to match it. Each button calls `editor.duplicateShapes` with an offset computed from the selection's rotated bounds.

Try selecting a shape, rotating it, and clicking the arrows.

## App.tsx

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

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

// [1]
function SelectionUi() {
	const editor = useEditor()

	// [2]
	const info = useValue(
		'selection bounds',
		() => {
			const screenBounds = editor.getViewportScreenBounds()
			const rotation = editor.getSelectionRotation()
			const rotatedScreenBounds = editor.getSelectionRotatedScreenBounds()
			if (!rotatedScreenBounds) return
			return {
				x: rotatedScreenBounds.x - screenBounds.x,
				y: rotatedScreenBounds.y - screenBounds.y,
				width: rotatedScreenBounds.width,
				height: rotatedScreenBounds.height,
				rotation,
			}
		},
		[editor]
	)

	if (!info) return null

	return (
		<div
			style={{
				position: 'absolute',
				top: 0,
				left: 0,
				transformOrigin: 'top left',
				transform: `translate(${info.x}px, ${info.y}px) rotate(${info.rotation}rad)`,
				pointerEvents: 'all',
			}}
		>
			<DuplicateInDirectionButton y={-40} x={info.width / 2 - 16} rotation={-Math.PI / 2} />
			<DuplicateInDirectionButton y={info.height / 2 - 16} x={info.width + 8} rotation={0} />
			<DuplicateInDirectionButton
				y={info.height + 8}
				x={info.width / 2 - 16}
				rotation={Math.PI / 2}
			/>
			<DuplicateInDirectionButton y={info.height / 2 - 16} x={-40} rotation={Math.PI} />
		</div>
	)
}

// [3]
function DuplicateInDirectionButton({
	x,
	y,
	rotation,
}: {
	x: number
	y: number
	rotation: number
}) {
	const editor = useEditor()

	return (
		<button
			style={{
				position: 'absolute',
				width: 32,
				height: 32,
				transform: `translate(${x}px, ${y}px) rotate(${rotation}rad)`,
			}}
			onClick={() => {
				const selectionRotation = editor.getSelectionRotation() ?? 0
				const rotatedPageBounds = editor.getSelectionRotatedPageBounds()
				if (!rotatedPageBounds) return

				editor.markHistoryStoppingPoint('duplicate in direction')

				const PADDING = 32

				// [4]
				const center = Vec.Rot(rotatedPageBounds.center, selectionRotation)
				const int = intersectLineSegmentPolygon(
					center,
					Vec.Add(center, new Vec(100000, 0).rot(selectionRotation + rotation)),
					rotatedPageBounds
						.clone()
						.expandBy(PADDING)
						.corners.map((c) => c.rot(selectionRotation))
				)
				if (!int?.[0]) return

				const delta = Vec.Sub(int[0], center)
				const offset = delta.uni().mul(delta.len() * 2)

				editor.duplicateShapes(editor.getSelectedShapes(), offset)
			}}
		>
			→
		</button>
	)
}

const components: TLComponents = {
	InFrontOfTheCanvas: SelectionUi,
}

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

/*
This example adds four "duplicate in this direction" buttons around the current
selection, rendered in the InFrontOfTheCanvas slot.

[1]
InFrontOfTheCanvas renders in screen space above the canvas, so it doesn't
scale with the camera. That makes it the right place for controls that should
stay a fixed size while following the selection. The slot's wrapper has
`pointer-events: none` and already marks pointer events as handled, so we only
need to opt our container back in with `pointerEvents: 'all'`.

[2]
`getSelectionRotatedScreenBounds` gives the selection's bounds in screen space,
already rotated to match the selection. Those coordinates are relative to the
whole window, so we subtract the viewport's screen position to get coordinates
relative to the tldraw component. Reading everything inside `useValue` keeps
the buttons glued to the selection as it moves, rotates, or the camera pans.

[3]
Each button's `rotation` sets both its CSS rotation and the direction the copies
are offset in, zeroed to the right.

[4]
To offset the copies by exactly one selection-width plus padding in the chosen
direction, we cast a ray from the selection's center and find where it exits the
padded, rotated selection bounds. Doubling that distance lands the duplicates
just past the original in that direction.
*/
```

--------

# Text mass style updates

Category: UI & theming

Keywords: text, contextual, mass, style, bold, italic, highlight, styles

Toggle bold, italic, or highlight on all the text in the selected shapes, including text nested in frames.

Rich text in tldraw is a TipTap (ProseMirror) JSON document. This example parses it with ProseMirror's `Node.fromJSON` (using a schema built from `tipTapDefaultExtensions`), adds or removes a mark on every text node, and writes the result back with `editor.updateShape`. Container shapes such as frames and groups are handled by recursing into `editor.getSortedChildIdsForParent`.

The buttons live in a custom `StylePanel` that wraps `DefaultStylePanel`. They only appear when the selection (expanded with `editor.getShapeAndDescendantIds`) contains at least one shape with rich text, and each shows as active when every text node already carries its mark. Try selecting a frame full of text and pressing "Bold all".

For a lighter version that walks the JSON directly, see the [format rich text on multiple shapes](https://tldraw.dev/examples/rich-text-on-multiple-shapes) example.

## App.tsx

```tsx
import { getSchema, JSONContent } from '@tiptap/core'
import { Fragment, Node, Schema } from '@tiptap/pm/model'
import {
	DefaultStylePanel,
	DefaultStylePanelContent,
	Editor,
	ExtractShapeByProps,
	tipTapDefaultExtensions,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonIcon,
	TldrawUiButtonLabel,
	TLRichText,
	TLShape,
	TLShapeId,
	TLUiStylePanelProps,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

const schema = getSchema(tipTapDefaultExtensions)

type Style = 'bold' | 'italic' | 'highlight'

const STYLES: { style: Style; icon: string; label: string }[] = [
	{ style: 'bold', icon: 'bold', label: 'Bold' },
	{ style: 'italic', icon: 'italic', label: 'Italic' },
	{ style: 'highlight', icon: 'highlight', label: 'Highlight' },
]

type RichTextShape = ExtractShapeByProps<{ richText: TLRichText }>

function isRichTextShape(shape: TLShape): shape is RichTextShape {
	return 'richText' in shape.props
}

function isUniformlyMarked(doc: Node, markName: string): boolean {
	let hasText = false
	let allMarked = true
	doc.descendants((node) => {
		if (node.isText) {
			hasText = true
			if (!node.marks.some((m) => m.type.name === markName)) {
				allMarked = false
			}
		}
	})
	return hasText && allMarked
}

// [1]
function setMark(doc: Node, schema: Schema, markName: string, active: boolean): Node {
	const markType = schema.marks[markName]

	return mapTextNodes(doc, schema, (node) => {
		if (active) {
			return node.mark(markType.create().addToSet(node.marks))
		} else {
			return node.mark(node.marks.filter((m) => m.type !== markType))
		}
	})
}

function mapTextNodes(node: Node, schema: Schema, fn: (textNode: Node) => Node): Node {
	if (node.isText) return fn(node)
	if (node.content.size === 0) return node
	const children: Node[] = []
	node.content.forEach((child) => {
		children.push(mapTextNodes(child, schema, fn))
	})
	return node.copy(Fragment.from(children))
}

// [2]
function setMarkOnShape(editor: Editor, id: TLShapeId, style: Style, active: boolean) {
	const shape = editor.getShape(id)
	if (!shape) return
	if (isRichTextShape(shape)) {
		const richText = shape.props.richText
		const doc = Node.fromJSON(schema, richText as JSONContent)
		const updated = setMark(doc, schema, style, active)
		editor.updateShape({
			id,
			type: shape.type,
			props: { richText: updated.toJSON() },
		})
	} else {
		editor
			.getSortedChildIdsForParent(id)
			.forEach((childId) => setMarkOnShape(editor, childId, style, active))
	}
}

function isUniformlyStyled(editor: Editor, shapeId: TLShapeId, style: Style) {
	const shape = editor.getShape(shapeId)
	if (!shape || !isRichTextShape(shape)) return false
	const doc = Node.fromJSON(schema, shape.props.richText as JSONContent)
	return isUniformlyMarked(doc, style)
}

// [3]
function CustomStylePanel(props: TLUiStylePanelProps) {
	const editor = useEditor()

	const selectedShapeIds = useValue('selected shape ids', () => editor.getSelectedShapeIds(), [
		editor,
	])

	const allTextShapeIds = useValue(
		'text shape ids',
		() => {
			const allIds = editor.getShapeAndDescendantIds(selectedShapeIds)
			return [...allIds].filter((id) => {
				const shape = editor.getShape(id)
				return !!shape && isRichTextShape(shape)
			})
		},
		[editor, selectedShapeIds]
	)

	const hasTextShapes = allTextShapeIds.length > 0

	return (
		<DefaultStylePanel {...props}>
			{hasTextShapes && (
				<div className="tlui-style-panel__section">
					{STYLES.map(({ style, icon, label }) => (
						<StyleButton
							key={style}
							style={style}
							icon={icon}
							label={label}
							textShapeIds={allTextShapeIds}
						/>
					))}
				</div>
			)}
			<DefaultStylePanelContent />
		</DefaultStylePanel>
	)
}

// [4]
function StyleButton({
	style,
	icon,
	label,
	textShapeIds,
}: {
	style: Style
	icon: string
	label: string
	textShapeIds: TLShapeId[]
}) {
	const editor = useEditor()

	const isActive = useValue(
		`all ${style}`,
		() => textShapeIds.every((id) => isUniformlyStyled(editor, id, style)),
		[editor, textShapeIds, style]
	)

	return (
		<TldrawUiButton
			type="menu"
			isActive={isActive}
			onClick={() => {
				editor.run(() => {
					editor.markHistoryStoppingPoint(`toggle ${style}`)
					editor.getSelectedShapeIds().forEach((id) => {
						setMarkOnShape(editor, id, style, !isActive)
					})
				})
			}}
			title={`${label} all text in selected shapes`}
		>
			<TldrawUiButtonIcon icon={icon} />
			<TldrawUiButtonLabel>{label} all</TldrawUiButtonLabel>
		</TldrawUiButton>
	)
}

const components: TLComponents = {
	StylePanel: CustomStylePanel,
}

export default function TextMassStyleUpdatesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="mass-style-updates-example" components={components} />
		</div>
	)
}

/*
This example adds bold, italic, and highlight buttons to the style panel that
toggle the mark on all text in the selected shapes at once, including text
shapes nested inside selected frames and groups. Rich text is a TipTap
(ProseMirror) JSON document; rather than walk the JSON by hand we parse it into
a ProseMirror `Node` and use its mark API. For a hand-rolled JSON version, see
the "Format rich text on multiple shapes" example.

[1]
`setMark` and `mapTextNodes` rebuild a ProseMirror document with each text
node's marks changed. ProseMirror nodes are immutable, so we return a new tree
rather than mutating in place.

[2]
`setMarkOnShape` parses `shape.props.richText` with `Node.fromJSON`, using the
schema built from tldraw's default TipTap extensions, and writes the result back
with `toJSON()`. It handles both shapes with rich text (by rewriting the document)
and container shapes like frames and groups (by recursing into their children
via `getSortedChildIdsForParent`). The add/remove decision is made once per
click: if every text node in every selected shape already has the mark, remove
it everywhere; otherwise add it everywhere.

[3]
The custom `StylePanel` wraps `DefaultStylePanel` and adds a section above the
default content. `getShapeAndDescendantIds` expands the selection to include
nested shapes so the buttons appear when a frame containing text is selected.

[4]
Each button reads its active state inside `useValue`, so it stays in sync as
the selection or the shapes' text changes. Reactivity here comes from
`editor.getShape` being read inside the computation.
*/
```

--------

# Add connected shape

Category: UI & theming

Keywords: plus button, quick connect, infrontofthecanvas, selection, arrow, bindings, duplicate, node, diagram, flowchart

Show plus buttons around a selected shape that create a new connected shape, like in Figma.

When a single shape is selected, four plus buttons appear on the edges of its selection bounds. Clicking one duplicates the shape in that direction and connects the two shapes with a bound arrow, then selects the new shape so you can keep extending the diagram.

The buttons are rendered in the `InFrontOfTheCanvas` component slot and positioned by converting the shape's page bounds to viewport coordinates with `pageToViewport`. The connection is made by creating an arrow shape and binding both of its terminals with `createBindings`.

## App.tsx

```tsx
import {
	DefaultColorStyle,
	Editor,
	TLComponents,
	Tldraw,
	TLShape,
	createShapeId,
	track,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './add-connected-shape.css'

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

// [1]
const DIRECTIONS = [
	{ name: 'up', dx: 0, dy: -1 },
	{ name: 'right', dx: 1, dy: 0 },
	{ name: 'down', dx: 0, dy: 1 },
	{ name: 'left', dx: -1, dy: 0 },
] as const

type Direction = (typeof DIRECTIONS)[number]

const GAP = 80
const BUTTON_OFFSET = 24

// [2]
function addConnectedShape(editor: Editor, shape: TLShape, direction: Direction) {
	const bounds = editor.getShapePageBounds(shape.id)
	if (!bounds) return

	editor.run(() => {
		editor.markHistoryStoppingPoint('add connected shape')

		// [3]
		editor.duplicateShapes([shape.id], {
			x: direction.dx * (bounds.width + GAP),
			y: direction.dy * (bounds.height + GAP),
		})

		// If duplication did nothing (e.g. a locked shape), the original is
		// still the only selected shape — don't connect it to itself.
		const newShape = editor.getOnlySelectedShape()
		if (!newShape || newShape.id === shape.id) return

		// [4]
		const color = editor.getShapeStyleIfExists(shape, DefaultColorStyle)

		const arrowId = createShapeId()
		editor.createShape({
			id: arrowId,
			type: 'arrow',
			x: bounds.center.x,
			y: bounds.center.y,
			props: color ? { color } : {},
		})

		editor.createBindings([
			{
				fromId: arrowId,
				toId: shape.id,
				type: 'arrow',
				props: {
					terminal: 'start',
					normalizedAnchor: { x: 0.5, y: 0.5 },
					isExact: false,
					isPrecise: false,
				},
			},
			{
				fromId: arrowId,
				toId: newShape.id,
				type: 'arrow',
				props: {
					terminal: 'end',
					normalizedAnchor: { x: 0.5, y: 0.5 },
					isExact: false,
					isPrecise: false,
				},
			},
		])
	})
}

// [5]
const AddConnectedShapeButtons = track(() => {
	const editor = useEditor()

	if (!editor.isIn('select.idle')) return null

	const shape = editor.getOnlySelectedShape()
	if (!shape || editor.isShapeOfType(shape, 'arrow')) return null

	const bounds = editor.getShapePageBounds(shape.id)
	if (!bounds) return null

	return (
		<>
			{DIRECTIONS.map((direction) => {
				// [6]
				const edgeMidpoint = editor.pageToViewport({
					x: bounds.center.x + direction.dx * (bounds.width / 2),
					y: bounds.center.y + direction.dy * (bounds.height / 2),
				})

				return (
					<button
						key={direction.name}
						className="add-connected-button"
						style={{
							transform: `translate(${edgeMidpoint.x + direction.dx * BUTTON_OFFSET}px, ${edgeMidpoint.y + direction.dy * BUTTON_OFFSET}px)`,
						}}
						onPointerDown={(e) => e.stopPropagation()}
						onClick={() => addConnectedShape(editor, shape, direction)}
					>
						+
					</button>
				)
			})}
		</>
	)
})

const components: TLComponents = {
	InFrontOfTheCanvas: AddConnectedShapeButtons,
}

export default function AddConnectedShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				components={components}
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size > 0) return

					const id = createShapeId()
					const { x, y } = editor.getViewportPageBounds().center
					editor.createShape({
						id,
						type: 'geo',
						x: x - 80,
						y: y - 50,
						props: { w: 160, h: 100, fill: 'semi', color: 'light-blue' },
					})
					editor.select(id)
				}}
			/>
		</div>
	)
}

/*
This example shows how to add "plus" buttons around a selected shape that create
a new connected shape in that direction, similar to quick-connect affordances in
tools like Figma and FigJam.

[1]
Each button corresponds to a direction. The dx/dy unit vector is used both to
position the button on the selection edge and to place the new shape.

[2]
When a button is clicked, we create the new shape and connect it with an arrow
inside a single `editor.run()` transaction. `markHistoryStoppingPoint` makes the
whole operation undoable in one step.

[3]
`duplicateShapes` clones the selected shape (keeping its type, size, and styles)
at a page-space offset in the chosen direction, and selects the copy — so the
user can keep tapping a plus button to grow the diagram.

[4]
`getShapeStyleIfExists` reads a style from a shape, returning `undefined` when
that shape type doesn't support the style — so the arrow's color is copied from
the source shape when it has one. Without this, `createShape` would fill the
color from the editor's "next shape" styles — whatever color was last active in
the style panel — which usually won't match the shapes it connects.

To connect the two shapes we create an arrow shape and bind each terminal to a
shape with `createBindings`. With `isPrecise: false` the arrow targets the
center of each shape and gracefully stops at the shape's outline, so it always
leaves from the correct edge no matter where the shapes move.

[5]
The buttons are rendered in the `InFrontOfTheCanvas` component slot: above the
canvas, below the rest of the UI. The component is wrapped in `track()` so it
re-renders when the selection, camera, or state chart changes. We only show the
buttons when exactly one non-arrow shape is selected and the select tool is
idle, so they disappear while translating, resizing, or pointing.

[6]
The shape's page bounds are converted to viewport (screen) coordinates with
`pageToViewport`, and each button is pushed a fixed number of screen pixels
away from the edge so the buttons stay the same size at any zoom level. This
example uses the shape's axis-aligned page bounds, so the buttons stay upright
even when the shape is rotated.
*/
```

## add-connected-shape.css

```css
.add-connected-button {
	position: absolute;
	top: -14px;
	left: -14px;
	width: 28px;
	height: 28px;
	border: none;
	border-radius: 50%;
	background: var(--tl-color-selection-stroke);
	color: var(--tl-color-selected-contrast);
	font-size: 18px;
	line-height: 1;
	cursor: pointer;
	pointer-events: all;
	display: flex;
	align-items: center;
	justify-content: center;
	box-shadow: var(--tl-shadow-1);
	opacity: 0.8;
}

.add-connected-button:hover {
	opacity: 1;
}
```

--------

# Color picker

Category: UI & theming

Keywords: color, picker, theme, palette, custom, fonts, updatetheme, meta

Add custom colors and fonts to the theme palette at runtime.

A toolbar in the top-left adds new entries to the editor's color palette via a native color picker, and to the font palette via a curated Google Fonts dropdown. Each new entry shows up immediately in the style panel and applies to any selected shape.

All possible custom slots (`custom-1..20`, `gf-1..10`) are declared up front via module augmentation and registered through a stable `themes` prop, so persisted shapes always pass validation. The actual colors and fonts are pushed into the live theme with `editor.updateTheme()`. The palette itself is stored on the document's `meta`, so it persists, syncs across tabs, and takes part in undo/redo together with the shapes that use it.

Try adding a color, applying it to a shape, then pressing undo.

## App.tsx

```tsx
import { useEffect, useMemo, useRef, useState } from 'react'
import 'tldraw/tldraw.css'
import './color-picker.css'
import {
	DEFAULT_THEME,
	DefaultColorStyle,
	DefaultFontStyle,
	Editor,
	JsonObject,
	TLDOCUMENT_ID,
	TLDefaultColor,
	TLShape,
	TLShapePartial,
	TLTheme,
	TLThemeFont,
	TLThemes,
	TLUiOverrides,
	Tldraw,
	useValue,
} from 'tldraw'

// Pre-declare slot names for custom colors and fonts. The runtime only
// fills the slots the user has actually added, but TypeScript needs concrete
// keys to compute `TLDefaultColorStyle` / `TLDefaultFontStyle`.
const MAX_CUSTOM_COLORS = 20
const MAX_CUSTOM_FONTS = 10

const PERSISTENCE_KEY = 'color-picker-example'

type CustomColorKey =
	| 'custom-1'
	| 'custom-2'
	| 'custom-3'
	| 'custom-4'
	| 'custom-5'
	| 'custom-6'
	| 'custom-7'
	| 'custom-8'
	| 'custom-9'
	| 'custom-10'
	| 'custom-11'
	| 'custom-12'
	| 'custom-13'
	| 'custom-14'
	| 'custom-15'
	| 'custom-16'
	| 'custom-17'
	| 'custom-18'
	| 'custom-19'
	| 'custom-20'

type CustomFontKey =
	| 'gf-1'
	| 'gf-2'
	| 'gf-3'
	| 'gf-4'
	| 'gf-5'
	| 'gf-6'
	| 'gf-7'
	| 'gf-8'
	| 'gf-9'
	| 'gf-10'

declare module '@tldraw/tlschema' {
	interface TLThemeDefaultColors {
		'custom-1': TLDefaultColor
		'custom-2': TLDefaultColor
		'custom-3': TLDefaultColor
		'custom-4': TLDefaultColor
		'custom-5': TLDefaultColor
		'custom-6': TLDefaultColor
		'custom-7': TLDefaultColor
		'custom-8': TLDefaultColor
		'custom-9': TLDefaultColor
		'custom-10': TLDefaultColor
		'custom-11': TLDefaultColor
		'custom-12': TLDefaultColor
		'custom-13': TLDefaultColor
		'custom-14': TLDefaultColor
		'custom-15': TLDefaultColor
		'custom-16': TLDefaultColor
		'custom-17': TLDefaultColor
		'custom-18': TLDefaultColor
		'custom-19': TLDefaultColor
		'custom-20': TLDefaultColor
	}
	interface TLThemeFonts {
		'gf-1': TLThemeFont
		'gf-2': TLThemeFont
		'gf-3': TLThemeFont
		'gf-4': TLThemeFont
		'gf-5': TLThemeFont
		'gf-6': TLThemeFont
		'gf-7': TLThemeFont
		'gf-8': TLThemeFont
		'gf-9': TLThemeFont
		'gf-10': TLThemeFont
	}
}

interface GoogleFont {
	name: string
	family: string
}
const GOOGLE_FONTS: GoogleFont[] = [
	{ name: 'Roboto', family: "'Roboto', sans-serif" },
	{ name: 'Lato', family: "'Lato', sans-serif" },
	{ name: 'Open Sans', family: "'Open Sans', sans-serif" },
	{ name: 'Montserrat', family: "'Montserrat', sans-serif" },
	{ name: 'Raleway', family: "'Raleway', sans-serif" },
	{ name: 'Oswald', family: "'Oswald', sans-serif" },
	{ name: 'Playfair Display', family: "'Playfair Display', serif" },
	{ name: 'Merriweather', family: "'Merriweather', serif" },
	{ name: 'Pacifico', family: "'Pacifico', cursive" },
	{ name: 'Caveat', family: "'Caveat', cursive" },
	{ name: 'Permanent Marker', family: "'Permanent Marker', cursive" },
	{ name: 'Bebas Neue', family: "'Bebas Neue', sans-serif" },
]

// Fan a single hex onto every role in TLDefaultColor. The theme renderer
// reads different roles for different contexts (outline vs fill vs note
// background); we use the picked hex for all of them plus a translucent
// variant for the semi fills.
function makeColor(solid: string): TLDefaultColor {
	const translucent = solid + '33'
	return {
		solid,
		semi: translucent,
		pattern: solid,
		fill: solid,
		linedFill: translucent,
		frameHeadingStroke: solid,
		frameHeadingFill: translucent,
		frameStroke: solid,
		frameFill: translucent,
		frameText: solid,
		noteFill: translucent,
		noteText: solid,
		highlightSrgb: solid,
		highlightP3: solid,
	}
}

function makeFontEntry(family: string): TLThemeFont {
	return {
		fontFamily: family,
		icon: <div style={{ fontFamily: family, fontSize: 16, lineHeight: 1 }}>Aa</div>,
	}
}

const customColorTranslations: Record<string, string> = {}
for (let i = 1; i <= MAX_CUSTOM_COLORS; i++) {
	customColorTranslations[`color-style.custom-${i}`] = `Custom ${i}`
}
const customFontTranslations: Record<string, string> = {}
for (let i = 1; i <= MAX_CUSTOM_FONTS; i++) {
	customFontTranslations[`font-style.gf-${i}`] = `Google font ${i}`
}
const uiOverrides: TLUiOverrides = {
	translations: {
		en: { ...customColorTranslations, ...customFontTranslations },
	},
}

// Inject one <link> loading every curated Google Font family, so dropdown
// previews render in the right typeface and canvas text picks up the family
// once it's registered in the theme.
let googleFontsLoaded = false
function ensureGoogleFontsLoaded() {
	if (googleFontsLoaded) return
	googleFontsLoaded = true
	const families = GOOGLE_FONTS.map((f) => `family=${f.name.replace(/ /g, '+')}`).join('&')
	const link = document.createElement('link')
	link.rel = 'stylesheet'
	link.href = `https://fonts.googleapis.com/css2?${families}&display=swap`
	document.head.appendChild(link)
}

// The palette (which hex/family each `custom-*` / `gf-*` slot maps to) lives
// on the tldraw document's `meta`. Shapes only persist the slot *key* (`custom-2`,
// `gf-1`); this is where the slot's actual value is kept. Storing it in the
// document — instead of a separate React/localStorage copy — means the editor
// persists it (via `persistenceKey`), syncs it across tabs, and includes it in
// undo/redo for free, always atomically with the shapes that reference it. There
// is therefore nothing to hand-reconcile: no cross-tab listener, no load-time
// recovery, no save-failure handling.
const PALETTE_META_KEY = 'colorPickerPalette'

interface Palette {
	hexes: string[]
	fonts: GoogleFont[]
}

function isGoogleFont(v: unknown): v is GoogleFont {
	return (
		typeof v === 'object' &&
		v !== null &&
		typeof (v as GoogleFont).family === 'string' &&
		typeof (v as GoogleFont).name === 'string'
	)
}

// `meta` is free-form JSON, so normalise whatever we read into a known shape.
// This also guards against a corrupt or hand-edited document.
function parsePalette(raw: unknown): Palette {
	const obj = (raw ?? {}) as { hexes?: unknown; fonts?: unknown }
	return {
		hexes: Array.isArray(obj.hexes)
			? obj.hexes.filter((h): h is string => typeof h === 'string').slice(0, MAX_CUSTOM_COLORS)
			: [],
		fonts: Array.isArray(obj.fonts)
			? obj.fonts.filter(isGoogleFont).slice(0, MAX_CUSTOM_FONTS)
			: [],
	}
}

function readRawPalette(editor: Editor): unknown {
	return editor.getDocumentSettings().meta[PALETTE_META_KEY]
}

// Write the palette into the document `meta`. Call this inside `editor.run` so it
// batches into one undo step with any shape repair that goes with it.
function writePalette(editor: Editor, palette: Palette) {
	editor.store.update(TLDOCUMENT_ID, (doc) => ({
		...doc,
		meta: { ...doc.meta, [PALETTE_META_KEY]: palette as unknown as JsonObject },
	}))
}

const isCustomColor = (v: unknown): v is string => typeof v === 'string' && /^custom-\d+$/.test(v)
const isCustomFont = (v: unknown): v is string => typeof v === 'string' && /^gf-\d+$/.test(v)

const DEFAULT_COLOR = DefaultColorStyle.defaultValue
const DEFAULT_FONT = DefaultFontStyle.defaultValue

// When the palette is cleared, the slots leave the *live* theme, so every
// shape and the per-tab "next shape" style that still names a `custom-*` / `gf-*`
// slot is remapped back to a built-in value (`black` / `draw`). The enum keeps
// every slot registered (see `buildCompleteTheme`), so this isn't needed to keep
// records valid — it just stops those shapes from rendering with an empty slot.
// Run inside the same `editor.run` as the palette write so the two move together
// through undo/redo.
function repairShapesUsingCustomStyles(editor: Editor) {
	const updates: TLShapePartial[] = []
	for (const record of editor.store.allRecords()) {
		if (record.typeName !== 'shape') continue
		const shape = record as TLShape
		const props = shape.props as Record<string, unknown>
		const next: Record<string, unknown> = {}
		if (isCustomColor(props.color)) next.color = DEFAULT_COLOR
		if (isCustomColor(props.labelColor)) next.labelColor = DEFAULT_COLOR
		if (isCustomFont(props.font)) next.font = DEFAULT_FONT
		if (Object.keys(next).length > 0) {
			updates.push({ id: shape.id, type: shape.type, props: next } as TLShapePartial)
		}
	}
	if (updates.length > 0) editor.updateShapes(updates)

	// `stylesForNextShape` lives on the per-tab `instance` record; reset any entry
	// that points at a slot we're removing so the next created shape doesn't
	// re-apply it.
	const stylesForNextShape = editor.getInstanceState().stylesForNextShape
	const fixed: Record<string, unknown> = {}
	for (const [id, value] of Object.entries(stylesForNextShape)) {
		if (isCustomColor(value)) fixed[id] = DEFAULT_COLOR
		else if (isCustomFont(value)) fixed[id] = DEFAULT_FONT
	}
	if (Object.keys(fixed).length > 0) {
		editor.updateInstanceState({ stylesForNextShape: { ...stylesForNextShape, ...fixed } })
	}
}

export default function ColorPickerExample() {
	const [editor, setEditor] = useState<Editor | null>(null)
	// Register *every* possible slot up front (with placeholder values). Passed
	// as the stable `themes` prop, this makes `createTLStore` register the full
	// style enum before the persisted document is validated on load, so shapes
	// referencing any slot pass validation even before the palette is read. The
	// visible colors/fonts are pushed separately via `editor.updateTheme` below.
	const [initialThemes] = useState<Partial<TLThemes>>(() => ({ default: buildCompleteTheme() }))

	// Read the palette straight from the document `meta`, reactively. Because
	// the store drives local edits, undo/redo, and cross-tab sync alike, this one
	// read covers all three with no extra plumbing. `useValue` returns the stored
	// reference (stable until the document record changes, so unrelated edits like
	// moving a shape don't churn it); `useMemo` normalises it.
	const rawPalette = useValue('palette', () => (editor ? readRawPalette(editor) : undefined), [
		editor,
	])
	const palette = useMemo(() => parsePalette(rawPalette), [rawPalette])

	// Push the palette's actual colors/fonts into the live theme. The style
	// panel and canvas read this, so only slots the palette contains are shown; the
	// complete prop's placeholder slots stay hidden. Runs on load, on every palette
	// change, and on undo/redo (all surface through `palette` above).
	useEffect(() => {
		if (!editor) return
		editor.updateTheme(buildTheme(palette.hexes, palette.fonts))
		if (palette.fonts.length > 0) ensureGoogleFontsLoaded()
	}, [editor, palette])

	const addColor = (hex: string) => {
		if (!editor || palette.hexes.length >= MAX_CUSTOM_COLORS) return
		const hexes = [...palette.hexes, hex]
		editor.run(() => {
			writePalette(editor, { hexes, fonts: palette.fonts })
			// Put the new color into the live theme before applying it, so a
			// selected shape repaints with it immediately. The enum already knows the
			// slot (complete `themes` prop), so the style set never trips validation.
			editor.updateTheme(buildTheme(hexes, palette.fonts))
			if (editor.getSelectedShapeIds().length > 0) {
				const key = `custom-${hexes.length}` as CustomColorKey
				editor.setStyleForSelectedShapes(DefaultColorStyle, key)
			}
		})
	}

	const addFont = (font: GoogleFont) => {
		if (!editor || palette.fonts.length >= MAX_CUSTOM_FONTS) return
		if (palette.fonts.some((f) => f.family === font.family)) return
		const fonts = [...palette.fonts, font]
		ensureGoogleFontsLoaded()
		editor.run(() => {
			writePalette(editor, { hexes: palette.hexes, fonts })
			editor.updateTheme(buildTheme(palette.hexes, fonts))
			if (editor.getSelectedShapeIds().length > 0) {
				// DefaultFontStyle's static type is the four built-ins; the runtime
				// enum (complete `themes` prop) knows this slot.
				const key = `gf-${fonts.length}` as CustomFontKey
				editor.setStyleForSelectedShapes(DefaultFontStyle, key as 'draw')
			}
		})
	}

	// Remove every custom color and font. We clear the palette and remap every
	// shape / next-shape style off the custom slots in a single `editor.run`, so
	// it's one undo step and the palette can never drift from the shapes that
	// reference it — undo restores both together, redo clears both together.
	const clearCustomStyles = () => {
		if (!editor) return
		editor.run(() => {
			repairShapesUsingCustomStyles(editor)
			writePalette(editor, { hexes: [], fonts: [] })
		})
	}

	const hasCustomStyles = palette.hexes.length > 0 || palette.fonts.length > 0

	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey={PERSISTENCE_KEY}
				themes={initialThemes}
				overrides={uiOverrides}
				onMount={(editor) => setEditor(editor)}
			>
				<div className="color-picker-toolbar" onPointerDown={(e) => e.stopPropagation()}>
					<AddColorButton addColor={addColor} isFull={palette.hexes.length >= MAX_CUSTOM_COLORS} />
					<AddFontButton
						addedFamilies={palette.fonts.map((f) => f.family)}
						addFont={addFont}
						isFull={palette.fonts.length >= MAX_CUSTOM_FONTS}
					/>
					{hasCustomStyles && (
						<button
							className="color-picker-button"
							onClick={clearCustomStyles}
							title="Remove all custom colors and fonts, resetting any shapes that use them"
						>
							Clear custom styles
						</button>
					)}
				</div>
			</Tldraw>
		</div>
	)
}

function buildTheme(hexes: string[], fonts: GoogleFont[]): TLTheme {
	const lightColors = { ...DEFAULT_THEME.colors.light } as TLTheme['colors']['light']
	const darkColors = { ...DEFAULT_THEME.colors.dark } as TLTheme['colors']['dark']
	for (let i = 0; i < hexes.length; i++) {
		const key = `custom-${i + 1}` as CustomColorKey
		const entry = makeColor(hexes[i])
		lightColors[key] = entry
		darkColors[key] = entry
	}

	const themeFonts = { ...DEFAULT_THEME.fonts } as TLTheme['fonts']
	for (let i = 0; i < fonts.length; i++) {
		const key = `gf-${i + 1}` as CustomFontKey
		themeFonts[key] = makeFontEntry(fonts[i].family)
	}

	return {
		...DEFAULT_THEME,
		id: 'default',
		colors: { light: lightColors, dark: darkColors },
		fonts: themeFonts,
	}
}

// A stable theme that registers *every* possible custom slot (`custom-1..N`,
// `gf-1..N`). It's passed as the `themes` prop, which `createTLStore` registers
// into the style enum *before* the persisted document is validated on load, and
// which the editor re-registers on every render. Registering the full set means:
//   - persisted or cross-tab shapes can never reference a slot the enum doesn't
//     know, so they always pass validation (no load crash, no per-render drop);
//   - the enum is never narrowed, so adding/removing palette entries can't
//     invalidate existing shapes.
// The placeholder values here are never shown: the style panel and canvas read
// the *live* theme, which we set with `editor.updateTheme(buildTheme(...))` to
// contain only the slots actually in the palette.
function buildCompleteTheme(): TLTheme {
	const hexes = Array.from({ length: MAX_CUSTOM_COLORS }, () => '#000000')
	const fonts: GoogleFont[] = Array.from({ length: MAX_CUSTOM_FONTS }, (_, i) => ({
		name: `placeholder-${i + 1}`,
		family: 'sans-serif',
	}))
	return buildTheme(hexes, fonts)
}

// Color add flow — the native picker opens immediately on "+ Add color".
// The picker fires onChange continuously while dragging, so we stage a preview
// and only commit on the explicit Add button.
function AddColorButton({ addColor, isFull }: { addColor(hex: string): void; isFull: boolean }) {
	const [isStaging, setIsStaging] = useState(false)
	const [staged, setStaged] = useState(() => randomHex())
	const inputRef = useRef<HTMLInputElement>(null)

	const open = () => {
		setStaged(randomHex())
		setIsStaging(true)
		inputRef.current?.click()
	}
	const reopen = () => inputRef.current?.click()
	const commit = () => {
		addColor(staged)
		setIsStaging(false)
	}
	const cancel = () => setIsStaging(false)

	return (
		<div className="color-picker-add-color">
			<input
				ref={inputRef}
				type="color"
				value={staged}
				onChange={(e) => setStaged(e.target.value)}
				className="color-picker-add-color__input"
				aria-hidden
				tabIndex={-1}
			/>
			{isStaging ? (
				<div className="color-picker-add-color__staging">
					<button
						type="button"
						className="color-picker-add-color__swatch"
						style={{ background: staged }}
						onClick={reopen}
						aria-label="Change color"
					/>
					<span className="color-picker-add-color__hex">{staged.toUpperCase()}</span>
					<button className="color-picker-button color-picker-button--primary" onClick={commit}>
						Add
					</button>
					<button
						className="color-picker-button color-picker-button--icon"
						onClick={cancel}
						aria-label="Cancel"
					>
						×
					</button>
				</div>
			) : (
				<button
					className="color-picker-button"
					disabled={isFull}
					onClick={open}
					title={isFull ? `Custom color slots full (${MAX_CUSTOM_COLORS})` : 'Add a custom color'}
				>
					+ Add color
				</button>
			)}
		</div>
	)
}

// Font add flow — dropdown of curated Google Fonts. Selection is atomic
// (one click = one commit), so no staging needed. Already-added fonts are
// shown but disabled.
function AddFontButton({
	addedFamilies,
	addFont,
	isFull,
}: {
	addedFamilies: string[]
	addFont(font: GoogleFont): void
	isFull: boolean
}) {
	const [isOpen, setIsOpen] = useState(false)
	const containerRef = useRef<HTMLDivElement>(null)

	const open = () => {
		ensureGoogleFontsLoaded()
		setIsOpen(true)
	}
	const close = () => setIsOpen(false)

	useEffect(() => {
		if (!isOpen) return
		const handler = (e: MouseEvent) => {
			if (!containerRef.current?.contains(e.target as Node)) close()
		}
		document.addEventListener('mousedown', handler)
		return () => document.removeEventListener('mousedown', handler)
	}, [isOpen])

	return (
		<div className="color-picker-add-font" ref={containerRef}>
			<button
				className="color-picker-button"
				disabled={isFull}
				onClick={() => (isOpen ? close() : open())}
				title={isFull ? `Custom font slots full (${MAX_CUSTOM_FONTS})` : 'Add a Google font'}
			>
				+ Add font
			</button>
			{isOpen && (
				<div className="color-picker-font-dropdown">
					{GOOGLE_FONTS.map((font) => {
						const alreadyAdded = addedFamilies.includes(font.family)
						return (
							<button
								key={font.name}
								className="color-picker-font-dropdown__item"
								disabled={alreadyAdded}
								onClick={() => {
									addFont(font)
									close()
								}}
							>
								<span style={{ fontFamily: font.family }}>{font.name}</span>
								{alreadyAdded && <span className="color-picker-font-dropdown__added">Added</span>}
							</button>
						)
					})}
				</div>
			)}
		</div>
	)
}

function randomHex(): string {
	const hue = Math.floor(Math.random() * 360)
	return hslToHex(hue, 70, 55)
}

function hslToHex(h: number, s: number, l: number): string {
	const sNorm = s / 100
	const lNorm = l / 100
	const k = (n: number) => (n + h / 30) % 12
	const a = sNorm * Math.min(lNorm, 1 - lNorm)
	const f = (n: number) =>
		Math.round(255 * (lNorm - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)))))
	const toHex = (v: number) => v.toString(16).padStart(2, '0')
	return `#${toHex(f(0))}${toHex(f(8))}${toHex(f(4))}`
}
```

## color-picker.css

```css
.color-picker-toolbar {
	position: absolute;
	top: 56px;
	left: 8px;
	display: flex;
	gap: 8px;
	pointer-events: all;
	z-index: 300;
}

.color-picker-button {
	padding: 6px 10px;
	font-size: 12px;
	font-weight: 500;
	border: 1px solid var(--tl-color-divider);
	border-radius: 8px;
	background: var(--tl-color-panel);
	color: var(--tl-color-text);
	cursor: pointer;
	box-shadow: var(--tl-shadow-1);
	line-height: 1;
}

.color-picker-button:hover:not(:disabled) {
	background: var(--tl-color-muted-2);
}

.color-picker-button:disabled {
	opacity: 0.5;
	cursor: not-allowed;
}

.color-picker-button--primary {
	background: var(--tl-color-selected);
	color: var(--tl-color-selected-contrast);
	border-color: var(--tl-color-selected);
}

.color-picker-button--primary:hover:not(:disabled) {
	filter: brightness(1.08);
	background: var(--tl-color-selected);
}

.color-picker-button--icon {
	padding: 4px 8px;
	font-size: 14px;
}

.color-picker-add-color {
	position: relative;
}

.color-picker-add-color__input {
	position: absolute;
	inset: 0;
	opacity: 0;
	pointer-events: none;
}

.color-picker-add-color__staging {
	display: flex;
	align-items: center;
	gap: 6px;
	padding: 4px;
	background: var(--tl-color-panel);
	border: 1px solid var(--tl-color-divider);
	border-radius: 10px;
	box-shadow: var(--tl-shadow-1);
}

.color-picker-add-color__swatch {
	width: 28px;
	height: 28px;
	padding: 0;
	border: 1px solid var(--tl-color-divider);
	border-radius: 6px;
	cursor: pointer;
}

.color-picker-add-color__hex {
	font-family: var(--tl-font-mono, monospace);
	font-size: 11px;
	color: var(--tl-color-text);
	min-width: 64px;
}

.color-picker-add-font {
	position: relative;
}

.color-picker-font-dropdown {
	position: absolute;
	top: calc(100% + 4px);
	left: 0;
	min-width: 200px;
	max-height: 320px;
	overflow-y: auto;
	background: var(--tl-color-panel);
	border: 1px solid var(--tl-color-divider);
	border-radius: 10px;
	box-shadow: var(--tl-shadow-2);
	padding: 4px;
	display: flex;
	flex-direction: column;
}

.color-picker-font-dropdown__item {
	display: flex;
	align-items: center;
	justify-content: space-between;
	gap: 8px;
	padding: 8px 10px;
	font-size: 14px;
	background: transparent;
	border: none;
	border-radius: 6px;
	color: var(--tl-color-text);
	cursor: pointer;
	text-align: left;
}

.color-picker-font-dropdown__item:hover:not(:disabled) {
	background: var(--tl-color-muted-2);
}

.color-picker-font-dropdown__item:disabled {
	opacity: 0.5;
	cursor: not-allowed;
}

.color-picker-font-dropdown__added {
	font-size: 10px;
	text-transform: uppercase;
	letter-spacing: 0.05em;
	color: var(--tl-color-text-3);
}
```

--------

# Custom actions

Category: UI & theming

Keywords: actions, overrides, keyboard shortcuts, kbd, custom actions, useactions, helpers, addtoast, tluiactionitem

Add a custom action and change an existing action's keyboard shortcut using the `overrides` prop.

The `actions` override receives tldraw's default actions and returns the set to use. Here we add a `my-action` action that shows a toast when you press `S`, and change the delete action's shortcut to `Shift + X`.

Try pressing `S` on the canvas to see the toast, then select a shape and press `Shift + X` to delete it. For more information on keyboard shortcuts see the [keyboard shortcuts example](https://tldraw.dev/examples/keyboard-shortcuts).

## App.tsx

```tsx
import { Tldraw, TLUiActionItem, TLUiActionsContextType, TLUiOverrides } from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
const overrides: TLUiOverrides = {
	actions(_editor, actions, helpers) {
		const myCustomAction: TLUiActionItem = {
			id: 'my-action',
			label: 'My action',
			icon: 'circle',
			// [2]
			kbd: 's',
			onSelect(source) {
				// [3]
				helpers.addToast({ title: `My action was selected from ${source}!` })
			},
		}

		// [4]
		const newActions: TLUiActionsContextType = {
			...actions,
			'my-action': myCustomAction,
			delete: {
				...actions['delete'],
				kbd: 'shift+x',
			},
		}

		return newActions
	},
}

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

/*
Tldraw's actions can be fired via keyboard shortcuts, or from anywhere in the user interface via
the `useActions` hook. This example shows how to override tldraw's actions object via the Tldraw
component's `overrides` prop. To learn more about surfacing actions in a customized menu, see the
custom menus example.

[1]
Define the overrides outside of the component (or memoize them) so the object is stable across
renders. The `actions` override receives the editor, the default actions, and a set of UI helpers,
and returns the actions object to use.

[2]
Keyboard shortcuts use the same syntax as tldraw's built-in actions, e.g. `'s'` or `'shift+x'`.
For more information on keyboard shortcuts see the keyboard shortcuts example.

[3]
UI helpers like `addToast`, `removeToast`, and `addDialog` are available on the helpers object.

[4]
Return a new object with the new action added. You can also modify existing actions, as shown here
by changing the delete action's shortcut.
*/
```

--------

# Custom error capture

Category: UI & theming

Keywords: error, ErrorFallback, error boundary, crash handling, getErrorAnnotations, sentry, debugging, error tracking

Customize the error screen that appears when the editor crashes and read the annotations tldraw attaches to errors.

When a critical error occurs in the editor, tldraw displays an error screen with options to refresh or reset. Override the `ErrorFallback` component in the `components` prop to replace it with your own.

tldraw annotates errors with extra information about the editor's state at the time of the error, such as the active tool and the selected shapes. Read it with `getErrorAnnotations(error)` and forward it to your error tracking service (like Sentry). This example shows the annotations on screen instead.

Click "Throw an error" to trigger a crash and see the custom fallback.

A separate component, `ShapeErrorFallback`, handles errors in individual shapes; see the error boundary example for that. `ErrorFallback` handles editor-level errors that affect the entire application.

## App.tsx

```tsx
import { getErrorAnnotations, Tldraw, TLEditorComponents, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './custom-error-capture.css'

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

// [1]
const components: TLEditorComponents = {
	// [2]
	ErrorFallback: ({ error }) => {
		// [3]
		const annotations = error instanceof Error ? getErrorAnnotations(error) : null

		return (
			<div className="custom-error">
				<h1>Something went wrong</h1>
				<div>{error instanceof Error ? error.message : String(error)}</div>

				{/* [4] */}
				{annotations && (
					<pre className="custom-error__annotations">{JSON.stringify(annotations, null, 2)}</pre>
				)}

				<button onClick={() => window.location.reload()}>Refresh</button>
			</div>
		)
	},
	// [5]
	InFrontOfTheCanvas: () => {
		const editor = useEditor()
		return (
			<button
				className="custom-error__button"
				onClick={() => {
					// [6]
					editor.createShape({
						// @ts-expect-error
						type: 'does-not-exist',
					})
				}}
			>
				Throw an error
			</button>
		)
	},
}

export default function CustomErrorCaptureExample() {
	return (
		<div className="tldraw__editor">
			{/* [7] */}
			<Tldraw components={components} />
		</div>
	)
}

/*
[1]
Define your component overrides outside of the React component so that they're static. If you must
define them inside the component, wrap them in `useMemo` so they aren't recreated on every render.

[2]
`ErrorFallback` is displayed when a critical error occurs in the editor that would otherwise crash
the entire application. This is different from `ShapeErrorFallback`, which handles errors in
individual shapes. The component receives the error, so you can match it to your app's design and
offer recovery options.

[3]
`getErrorAnnotations` retrieves the debugging information tldraw attaches to errors: tags
(key-value pairs for categorization) and extras (additional context data such as the current tool
or the selected shapes). This is what you'd forward to an error reporting service like Sentry.

[4]
Here we show the annotations on screen so you can see what's captured. In production you'd send
them to your error tracking service instead of displaying them to users.

[5]
For this example, we've added a button in the `InFrontOfTheCanvas` slot that intentionally
triggers an error so you can see the custom `ErrorFallback` in action. In a real application the
fallback only appears when genuine errors occur.

[6]
Creating a shape with an unknown type throws inside the editor, which is enough to trip the error
boundary. The `@ts-expect-error` is there because TypeScript rightly rejects the bad type.

[7]
Pass the components to the `Tldraw` component via the `components` prop.
*/
```

## custom-error-capture.css

```css
.custom-error__button {
	position: absolute;
	top: 100px;
	left: 100px;
	pointer-events: all;
}

.custom-error {
	position: absolute;
	inset: 0;
	display: flex;
	flex-direction: column;
	gap: 8px;
	align-items: center;
	justify-content: center;
	background: #f5f5f5;
}

.custom-error__annotations {
	margin: 8px 0;
	padding: 8px;
	background: white;
	border: 1px solid #ccc;
	border-radius: 4px;
	font-size: 12px;
	max-width: 600px;
	max-height: 300px;
	overflow-y: auto;
	text-align: left;
}
```

--------

# Custom indicators

Category: UI & theming

Keywords: indicators, shape indicator, overlay, overlayutils, shapeindicatoroverlayutil, getrenderingshapes

Change when shape indicators are shown by replacing the shape indicator overlay util.

Shape indicators are the outlines drawn around a shape when you hover or select it. They're rendered by `ShapeIndicatorOverlayUtil`. Subclass it, override `getOverlays()` to return the ids you want outlined, and pass it in the `overlayUtils` prop. Because it shares the built-in util's `type`, it replaces the default rather than adding a second layer.

This example outlines every rendered shape all of the time. Try adding shapes or zooming out; each visible shape, including the group's children, keeps its outline.

## App.tsx

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

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

// [1]
class AllShapesIndicatorOverlayUtil extends ShapeIndicatorOverlayUtil {
	override getOverlays(): TLShapeIndicatorOverlay[] {
		const ids = this.editor.getRenderingShapes().map((s) => s.id)
		if (ids.length === 0) return []
		return [
			{
				id: 'shape_indicator',
				type: 'shape_indicator',
				props: { idsToDisplay: ids, hintingShapeIds: [] },
			},
		]
	}
}

// [2]
const overlayUtils = [AllShapesIndicatorOverlayUtil]

export default function IndicatorsLogicExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				overlayUtils={overlayUtils}
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size === 0) {
						const bottomLeftA = createShapeId()
						const bottomLeftB = createShapeId()
						editor.createShapes([
							{ type: 'geo', x: 100, y: 100 },
							{ type: 'geo', x: 500, y: 150, props: { geo: 'ellipse' } },
							{ id: bottomLeftA, type: 'geo', x: 100, y: 500 },
							{ id: bottomLeftB, type: 'geo', x: 250, y: 400 },
							{ type: 'text', x: 500, y: 500, props: { richText: toRichText('Hello, world!') } },
						])
						editor.groupShapes([bottomLeftA, bottomLeftB])
						editor.setSelectedShapes([])
					}
				}}
			/>
		</div>
	)
}

/*
Shape indicators are the outlines drawn around hovered and selected shapes. They're
painted by `ShapeIndicatorOverlayUtil`, an overlay util, so changing when they appear
means replacing that util.

[1]
Subclass `ShapeIndicatorOverlayUtil` and override `getOverlays()`. The default only lists
selected, hovered, and hinted shapes; here we list every shape currently being rendered,
so all of them get an outline all of the time. Filter the ids to indicate only some shapes.
`render()` is inherited, so the outlines still look like the built-in ones.

[2]
Pass the util via `overlayUtils`. It has the same `static type` (`'shape_indicator'`)
as the built-in util, so it replaces it instead of running alongside it. Defining the
array at module level keeps `<Tldraw>` from seeing a new array on every render.
*/
```

--------

# Custom keyboard shortcuts

Category: UI & theming

Keywords: shortcuts, hotkeys, keybindings, kbd, overrides, actions, tools, customize

Change tldraw's default keyboard shortcuts for tools and actions.

Shortcuts are the `kbd` field on tool and action definitions. Use the `actions` and `tools` functions of `TLUiOverrides` to return copies with different `kbd` strings, then pass the overrides to `<Tldraw>`. The keyboard shortcuts dialog reads the same field, so it updates automatically.

Try it:

- Press `x` to toggle the grid
- Press `p` to select the draw tool
- Press `cmd+1` (or `ctrl+1`) to copy the selection as a PNG

For adding shortcuts to custom tools, see the custom config example.

## App.tsx

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

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

// [1]
const overrides: TLUiOverrides = {
	// [a]
	actions(_editor, actions) {
		return {
			...actions,
			'toggle-grid': { ...actions['toggle-grid'], kbd: 'x' },
			'copy-as-png': { ...actions['copy-as-png'], kbd: 'cmd+1,ctrl+1' },
		}
	},
	// [b]
	tools(_editor, tools) {
		return { ...tools, draw: { ...tools.draw, kbd: 'p' } }
	},
}

export default function KeyboardShortcutsExample() {
	return (
		<div className="tldraw__editor">
			{/* [2] */}
			<Tldraw overrides={overrides} />
		</div>
	)
}

/*
Keyboard shortcuts belong to either tools (draw, eraser, ...) or actions (undo, group,
toggle grid, ...). Both are described by objects with a `kbd` string, so changing a
shortcut is a matter of returning a copy of the object with a different `kbd`.

The `kbd` syntax is a comma-separated list of key combos, e.g. `'x'`, `'shift+x'`,
`'cmd+1,ctrl+1'` (the second combo covers Windows and Linux). The keyboard shortcuts
dialog reads the same `kbd` strings, so it stays in sync with your overrides.

[1]
`overrides` is a `TLUiOverrides` object. Each function receives the defaults and returns
the replacements. It's defined at module level so `<Tldraw>` doesn't see a new object on
every render.
	[a] `toggle-grid` moves from cmd+' to `x`, and `copy-as-png` moves from cmd+shift+c
	to cmd+1. The override replaces the default shortcut rather than adding to it.
	[b] The draw tool moves from `d` to `p`.

[2]
Pass the overrides to `<Tldraw>`. Open the keyboard shortcuts dialog from the help menu
to see the new bindings. For shortcuts on custom tools, see the custom config example.
*/
```

--------

# Escape shape focus trap

Category: UI & theming

Keywords: tab, keyboard navigation, accessibility, a11y, shape toolbar, focus, contextual toolbar, keyboard

Tab from a selected shape into a custom contextual toolbar instead of cycling to the next shape.

By default tldraw traps the Tab key while shapes are selected and uses it to move between shapes. This example intercepts that with a capture-phase `keydown` listener registered in `onMount`, so it runs before tldraw's own handler and can call `stopImmediatePropagation()`.

- Tab with a shape selected and focus on the canvas moves focus to the first toolbar button.
- Tab and Shift+Tab inside the toolbar cycle between its buttons.
- Tab on the last button (or Shift+Tab on the first) returns focus to the canvas and restores shape navigation.
- Escape inside the toolbar also returns focus to the canvas.

Try it: click a shape, then press Tab to focus the toolbar. Use Tab and Shift+Tab to move between buttons, and Escape to return to the canvas.

## App.tsx

```tsx
import { useCallback } from 'react'
import {
	Box,
	Tldraw,
	TldrawUiButtonIcon,
	TldrawUiContextualToolbar,
	TldrawUiToolbarButton,
	TLEditorComponents,
	track,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
const ShapeToolbar = track(() => {
	const editor = useEditor()
	const showToolbar = editor.isIn('select.idle') && editor.getOnlySelectedShapeId()

	// [2]
	const handleReturn = useCallback(() => {
		editor.getContainer().focus()
	}, [editor])

	if (!showToolbar) return null

	// [3]
	const getSelectionBounds = () => {
		const fullBounds = editor.getSelectionRotatedScreenBounds()
		if (!fullBounds) return undefined
		return new Box(fullBounds.x, fullBounds.y, fullBounds.width, 0)
	}

	return (
		<TldrawUiContextualToolbar getSelectionBounds={getSelectionBounds} label="Shape actions">
			<TldrawUiToolbarButton
				type="icon"
				title="Duplicate"
				onClick={() => {
					editor.duplicateShapes(editor.getSelectedShapes())
					handleReturn()
				}}
			>
				<TldrawUiButtonIcon small icon="duplicate" />
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title="Delete"
				onClick={() => {
					editor.deleteShapes(editor.getSelectedShapeIds())
					handleReturn()
				}}
			>
				<TldrawUiButtonIcon small icon="trash" />
			</TldrawUiToolbarButton>
		</TldrawUiContextualToolbar>
	)
})

const components: TLEditorComponents = {
	InFrontOfTheCanvas: ShapeToolbar,
}

export default function EscapeShapeFocusTrapExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				components={components}
				onMount={(editor) => {
					editor.createShape({ type: 'geo', x: 400, y: 200 })

					// [4]
					const container = editor.getContainer()
					const getToolbar = () => container.querySelector<HTMLElement>('.tlui-contextual-toolbar')

					// [5]
					function enableFocusRing() {
						container.classList.remove('tl-container__no-focus-ring')
					}

					function handleKeyDown(e: KeyboardEvent) {
						const toolbarEl = getToolbar()
						const isInToolbar = toolbarEl?.contains(document.activeElement)

						// [6]
						if (e.key === 'Tab' && !isInToolbar) {
							const hasSelected = editor.getOnlySelectedShapeId() !== null
							const isOnCanvas =
								document.activeElement === container ||
								document.activeElement?.classList.contains('tl-container')

							if (hasSelected && isOnCanvas && !e.shiftKey) {
								e.preventDefault()
								e.stopImmediatePropagation()
								const btn = toolbarEl?.querySelector<HTMLElement>('button')
								if (btn) {
									btn.focus()
									enableFocusRing()
								}
							}
							return
						}

						// [7]
						if (e.key === 'Tab' && isInToolbar && toolbarEl) {
							const buttons = Array.from(toolbarEl.querySelectorAll<HTMLElement>('button'))
							const currentIndex = buttons.indexOf(document.activeElement as HTMLElement)
							if (currentIndex === -1) return

							e.preventDefault()
							e.stopImmediatePropagation()

							if (e.shiftKey) {
								if (currentIndex === 0) {
									container.focus()
								} else {
									buttons[currentIndex - 1].focus()
								}
							} else {
								if (currentIndex === buttons.length - 1) {
									container.focus()
								} else {
									buttons[currentIndex + 1].focus()
								}
							}
							enableFocusRing()
							return
						}

						// [8]
						if (e.key === 'Escape' && isInToolbar) {
							e.preventDefault()
							e.stopImmediatePropagation()
							container.focus()
						}
					}

					// [9]
					container.addEventListener('keydown', handleKeyDown, { capture: true })
					return () => container.removeEventListener('keydown', handleKeyDown, { capture: true })
				}}
			/>
		</div>
	)
}

/*
[1]
A contextual toolbar that appears above the selected shape. `track()` re-renders it
whenever the editor state it reads (the tool state and the selection) changes.

[2]
Moving focus back to the container hands Tab back to tldraw's built-in shape navigation.

[3]
Position the toolbar on the top edge of the selection, the same pattern used in the
contextual toolbar example.

[4]
The keyboard interception is registered in `onMount` so its cleanup runs when the editor
unmounts.

[5]
Because we call `stopImmediatePropagation()` in [6] and [7], the editor's `FocusManager`
(which listens on `document.body`) never sees the Tab key and so never removes
`tl-container__no-focus-ring`. Removing it ourselves keeps the focus outline visible on
the toolbar buttons.

[6]
Tab with focus on the canvas and one shape selected: focus the first toolbar button
instead of letting tldraw cycle to the next shape.

[7]
Tab inside the toolbar cycles between its buttons. Tab on the last button or Shift+Tab on
the first returns focus to the canvas, so focus can't leak into unrelated UI.

[8]
Escape inside the toolbar returns focus to the canvas.

[9]
The listener is registered with `capture: true` so it runs before tldraw's own bubble-phase
handler in `useDocumentEvents`, which is what makes `stopImmediatePropagation()` effective.
*/
```

--------

# Overlay theme colors

Category: UI & theming

Keywords: theme, overlay, brush, selection, snap, laser, color

Restyle the brush, selection, snap lines, and laser with theme colors.

Canvas overlays read their colors from the active theme. Overriding `brushFill`, `brushStroke`, `selectionFill`, `selectionStroke`, `selectedContrast`, `snap`, and `laser` on the theme restyles every built-in overlay in one place — no subclassing needed. This example swaps all of them for a magenta palette.

## App.tsx

```tsx
import { DEFAULT_THEME, TLTheme, TLThemes, Tldraw, structuredClone } from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
const OVERLAY_COLORS_LIGHT = {
	brushFill: 'rgba(236, 72, 153, 0.15)',
	brushStroke: 'rgba(236, 72, 153, 0.6)',
	selectionFill: 'rgba(236, 72, 153, 0.05)',
	selectionStroke: 'rgb(236, 72, 153)',
	selectedContrast: '#ffffff',
	snap: 'rgb(236, 72, 153)',
	laser: 'rgb(236, 72, 153)',
}

const OVERLAY_COLORS_DARK = {
	brushFill: 'rgba(236, 72, 153, 0.2)',
	brushStroke: 'rgba(236, 72, 153, 0.6)',
	selectionFill: 'rgba(236, 72, 153, 0.1)',
	selectionStroke: 'rgb(236, 72, 153)',
	selectedContrast: '#ffffff',
	snap: 'rgb(236, 72, 153)',
	laser: 'rgb(236, 72, 153)',
}

// [2]
const magentaTheme: TLTheme = structuredClone(DEFAULT_THEME)
Object.assign(magentaTheme.colors.light, OVERLAY_COLORS_LIGHT)
Object.assign(magentaTheme.colors.dark, OVERLAY_COLORS_DARK)

const themes: Partial<TLThemes> = { default: magentaTheme }

export default function OverlayThemeColorsExample() {
	return (
		<div className="tldraw__editor">
			{/* [3] */}
			<Tldraw persistenceKey="overlay-theme-colors-example" themes={themes} />
		</div>
	)
}

/*
Canvas overlays read their colors from the active theme. This lets you restyle
the brush, selection outline, snap indicators, laser pointer, and handle
contrast color in one place — no need to subclass every built-in overlay util.

The overlay-related keys on `TLThemeColors` are:

- `brushFill`, `brushStroke` — the drag-select rectangle.
- `selectionFill`, `selectionStroke` — the selection bounding box.
- `selectedContrast` — handle fill color against the selection stroke.
- `snap` — snap indicator lines.
- `laser` — laser pointer trail color.

Try drag-selecting (brush), selecting a shape (selection + handles), drawing
with the laser tool, or moving a shape next to another (snap lines).

[1]
Define the overlay-related color overrides. `TLThemeColors` contains many more
keys — shape palette colors (`red`, `blue`, …), text, background, cursor —
that we want to leave alone.

[2]
Clone `DEFAULT_THEME` and merge only the overlay overrides into the `light` and
`dark` palettes. The shape palette and UI chrome stay as-is.

[3]
Pass the modified theme under the `default` key. `<Tldraw>` registers it at
mount time — no module augmentation needed because we're updating the
already-registered `default` theme rather than adding a new named theme.
*/
```

--------

# Selection color condition

Category: UI & theming

Keywords: selection, color, conditional styling, css variables, react, getselectedshapes, isshapeoftype, css class

Turn the selection red whenever every selected shape is a rectangle.

Selection colors are part of the editor's theme (`selectionStroke` and `selectionFill` in `TLTheme`), so changing them means swapping the theme rather than overriding CSS variables. This example clones `DEFAULT_THEME` into a red variant, then uses `react` inside `onMount` to watch `editor.getSelectedShapes()` and call `editor.updateTheme` with either variant depending on the selection.

Try selecting the two rectangles (red), then add the ellipse to the selection (back to blue).

## App.tsx

```tsx
import { DEFAULT_THEME, TLTheme, Tldraw, react, structuredClone } from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
const RECTANGLE_SELECTION_THEME: TLTheme = structuredClone(DEFAULT_THEME)
RECTANGLE_SELECTION_THEME.colors.light.selectionStroke = '#cc0000'
RECTANGLE_SELECTION_THEME.colors.light.selectionFill = 'rgba(255, 68, 68, 0.24)'
RECTANGLE_SELECTION_THEME.colors.dark.selectionStroke = '#ff4444'
RECTANGLE_SELECTION_THEME.colors.dark.selectionFill = 'rgba(255, 68, 68, 0.32)'

export default function SelectionColorConditionExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [2]
					const stopListening = react('update selection theme', () => {
						const selectedShapes = editor.getSelectedShapes()

						// [3]
						const allAreRectangles =
							selectedShapes.length > 0 &&
							selectedShapes.every(
								(shape) => editor.isShapeOfType(shape, 'geo') && shape.props.geo === 'rectangle'
							)

						// [4]
						editor.updateTheme({
							...(allAreRectangles ? RECTANGLE_SELECTION_THEME : DEFAULT_THEME),
							id: 'default',
						})
					})

					// [5]
					editor
						.createShapes([
							{ type: 'geo', x: 0, y: 0 },
							{ type: 'geo', x: 120, y: 0 },
						])
						.selectAll()
						.zoomToSelection()
						.createShape({ type: 'geo', x: 60, y: 120, props: { geo: 'ellipse' } })

					return stopListening
				}}
			/>
		</div>
	)
}

/*
This example changes the selection color based on which shapes are selected:
red when every selected shape is a rectangle, the default blue otherwise.

[1]
Selection colors live on the theme (`selectionStroke` and `selectionFill`), not
in CSS variables, because the selection overlays are drawn to canvas. We clone
DEFAULT_THEME and override those two colors for both light and dark modes.

[2]
`react` runs the callback once, then again whenever any signal it read changes.
Here it reads the selection, so it re-runs on every selection change. It
returns a disposer, which we return from onMount so it's cleaned up when the
editor unmounts.

[3]
Change this condition to check for any shape type or combination.

[4]
`editor.updateTheme` replaces the theme registered under the given id. Both
variants keep the id 'default', so this swaps the current theme in place and
leaves the module-level DEFAULT_THEME object untouched.

[5]
Some shapes to test with. The two rectangles are selected on load.
*/
```

--------

# Stroke size picker

Category: UI & theming

Keywords: stroke, size, picker, pen, draw, style panel, styleprop, custom styles

Give the draw tool twelve stroke sizes instead of four.

The draw tool's built-in size style has only four values (s, m, l, xl). This example gives draw shapes a numeric stroke size style defined with `StyleProp.define`, wires it into the draw shape's stroke width with `DrawShapeUtil.configure`, and composes a custom style panel that swaps the built-in size picker for a twelve-option preset picker. The picker only appears when the draw tool is active or draw shapes are selected; every other shape keeps the default size picker.

To use a custom style with a custom shape instead, check the [custom shape with custom styles example](https://tldraw.dev/examples/shape-with-custom-styles).

## App.tsx

```tsx
import {
	DefaultStylePanel,
	DrawShapeUtil,
	StyleProp,
	StylePanelArrowKindPicker,
	StylePanelArrowheadPicker,
	StylePanelColorPicker,
	StylePanelDashPicker,
	StylePanelFillPicker,
	StylePanelFontPicker,
	StylePanelGeoShapePicker,
	StylePanelLabelAlignPicker,
	StylePanelOpacityPicker,
	StylePanelSection,
	StylePanelSizePicker,
	StylePanelSplinePicker,
	StylePanelTextAlignPicker,
	T,
	TLComponents,
	TLUiStylePanelProps,
	Tldraw,
	drawShapeProps,
	useStylePanelContext,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './stroke-size-picker.css'

// [1]
const strokeSizeStyle = StyleProp.define('example:strokeSize', {
	defaultValue: 4,
	type: T.number,
})

// [2]
declare module '@tldraw/tlschema' {
	interface TLDrawShapeProps {
		strokeSize: number
	}
}

// [3]
class CustomDrawShapeUtil extends DrawShapeUtil.configure({
	getCustomDisplayValues(_editor, shape) {
		return { strokeWidth: shape.props.strokeSize }
	},
}) {
	static override props = { ...drawShapeProps, strokeSize: strokeSizeStyle }

	override getDefaultProps() {
		return { ...super.getDefaultProps(), strokeSize: strokeSizeStyle.defaultValue }
	}
}

const shapeUtils = [CustomDrawShapeUtil]

const STROKE_SIZE_PRESETS = [1, 2, 3, 4, 6, 8, 10, 12, 16, 20, 26, 32]

// [4]
function StrokeSizePicker() {
	const { styles, onValueChange, onHistoryMark } = useStylePanelContext()
	const strokeSize = styles.get(strokeSizeStyle)

	// [5]
	if (strokeSize === undefined) return <StylePanelSizePicker />

	const value = strokeSize.type === 'mixed' ? null : strokeSize.value

	return (
		<div className="stroke-size-picker">
			{STROKE_SIZE_PRESETS.map((size) => (
				<button
					key={size}
					className="stroke-size-picker__preset"
					data-active={value === size}
					title={`Stroke size ${size}`}
					onClick={() => {
						onHistoryMark('set stroke size')
						onValueChange(strokeSizeStyle, size)
					}}
				>
					<div
						className="stroke-size-picker__dot"
						style={{ width: 4 + size / 2, height: 4 + size / 2 }}
					/>
				</button>
			))}
		</div>
	)
}

// [6]
function CustomStylePanel(props: TLUiStylePanelProps) {
	return (
		<DefaultStylePanel {...props}>
			<StylePanelSection>
				<StylePanelColorPicker />
				<StylePanelOpacityPicker />
			</StylePanelSection>
			<StylePanelSection>
				<StylePanelFillPicker />
				<StylePanelDashPicker />
				<StrokeSizePicker />
			</StylePanelSection>
			<StylePanelSection>
				<StylePanelFontPicker />
				<StylePanelTextAlignPicker />
				<StylePanelLabelAlignPicker />
			</StylePanelSection>
			<StylePanelSection>
				<StylePanelGeoShapePicker />
				<StylePanelArrowKindPicker />
				<StylePanelArrowheadPicker />
				<StylePanelSplinePicker />
			</StylePanelSection>
		</DefaultStylePanel>
	)
}

const components: TLComponents = {
	StylePanel: CustomStylePanel,
}

export default function StrokeSizePickerExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				onMount={(editor) => {
					editor.setCurrentTool('draw')
				}}
			/>
		</div>
	)
}

/*
This example replaces the draw tool's four stroke sizes (s, m, l, xl) with a
custom numeric stroke size style, controlled from the style panel by a
twelve-option preset picker.

[1]
We define a numeric style prop for the stroke size. Because it's a style
(rather than a plain shape prop), the editor remembers the most recent value
for the next shape you draw, shows it in the style panel whenever it's
relevant, and reports a "mixed" value when a multi-shape selection disagrees.

[2]
We extend the draw shape's props interface via declaration merging, so
`shape.props.strokeSize` is fully typed everywhere in this file.

[3]
We customize the default draw shape in two steps. `DrawShapeUtil.configure`
overrides `getCustomDisplayValues`, which the draw shape resolves its stroke
width through, so rendering, hit testing, and image exports all use our
custom size. The subclass then adds the style to the shape's props and
default props, which registers it with the editor's styles system and the
store's validator. Passing the util to `Tldraw` via the `shapeUtils` prop
replaces the built-in draw shape util, so the default draw tool picks it up
automatically.

[4]
The picker reads the current value from `useStylePanelContext`. Its
`onValueChange` helper applies the style to any selected shapes and remembers
it for the next shapes, exactly like the built-in pickers.

[5]
The style map only contains the stroke size style when it's relevant: when
the draw tool is active, or when the selection includes draw shapes.
Everywhere else (geo shapes, arrows, text, and so on) we fall back to the
default four-value size picker, since those shapes still use the built-in
size style.

[6]
We compose the style panel from the same building blocks as the default
panel, swapping the size picker slot for our stroke size picker. See
`DefaultStylePanelContent` for the full list of available sections. Make sure
to forward the panel's props to `DefaultStylePanel`: the editor passes
`isMobile` when it renders the panel inside the mobile toolbar popover.
*/
```

## stroke-size-picker.css

```css
.stroke-size-picker {
	display: grid;
	grid-template-columns: repeat(6, 1fr);
}

.stroke-size-picker__preset {
	all: unset;
	display: flex;
	align-items: center;
	justify-content: center;
	height: 32px;
	border-radius: var(--tl-radius-2);
	cursor: pointer;
}

.stroke-size-picker__preset:hover {
	background: var(--tl-color-muted-2);
}

.stroke-size-picker__preset[data-active='true'] {
	background: var(--tl-color-hint);
}

.stroke-size-picker__dot {
	border-radius: 50%;
	background: var(--tl-color-text-1);
}
```

--------

# Dark mode

Category: UI & theming

Keywords: dark mode, theme, system preferences, color scheme, colorscheme

Start the editor in dark mode with the `colorScheme` prop.

Pass `colorScheme="dark"` to `<Tldraw>` to render in dark mode. The prop accepts `'light'` (the default), `'dark'`, or `'system'`, which follows the operating system's preference.

The prop only sets the default. If the user has a `colorScheme` set in their preferences (for example via `editor.user.updateUserPreferences`), that preference wins. To let users switch at runtime, see the toggle dark mode example.

## App.tsx

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

export default function DarkModeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw colorScheme="dark" />
		</div>
	)
}

/*
The `colorScheme` prop sets the editor's default color scheme: 'light' (the default),
'dark', or 'system' to follow the OS preference. A user preference set via
`editor.user.updateUserPreferences({ colorScheme })` takes priority over this prop,
so a persisted user preference from another example may override it. See the
dark-mode-toggle example for switching at runtime.
*/
```

--------

# Force mobile layout

Category: UI & theming

Keywords: mobile, responsive, breakpoint, forcemobile, layout, ui layout

Force the UI to use the mobile layout regardless of screen size.

The `forceMobile` prop pins tldraw's UI to the mobile breakpoint, so the toolbar and menus render in their compact mobile arrangement even in a wide window. Without it, the layout is chosen from the width of the editor's container.

Try resizing the window: the layout stays in mobile mode.

## App.tsx

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

export default function ForceMobileExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="force-mobile-example" forceMobile />
		</div>
	)
}

/*
The `forceMobile` prop pins the UI to the mobile breakpoint regardless of the
container's width. Useful for previewing the mobile layout on desktop, or when
the editor is embedded in a narrow panel where the desktop layout wouldn't fit.
*/
```

--------

# Toggle dark mode

Category: UI & theming

Keywords: theme, dark mode, light mode, colorscheme, user preferences, updateuserpreferences, getisdarkmode, setcolormode

Toggle between light and dark mode by updating the user's `colorScheme` preference.

The user's `colorScheme` preference is the source of truth for the editor's color mode. This example adds a button to the `TopPanel` slot that reads the current mode with `editor.user.getIsDarkMode()` and flips it with `editor.user.updateUserPreferences({ colorScheme })`. `editor.setColorMode()` is a shorthand for the same update.

Try clicking the button at the top of the page. Because user preferences are persisted to local storage, the setting is remembered across reloads. To set a default without a toggle, see the dark mode example.

## App.tsx

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

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

function DarkModeButton() {
	const editor = useEditor()
	// [1]
	const isDark = useValue('isDark', () => editor.user.getIsDarkMode(), [editor])

	return (
		<div className="tlui-menu">
			<TldrawUiButton
				type="normal"
				// [2]
				onClick={() =>
					editor.user.updateUserPreferences({ colorScheme: isDark ? 'light' : 'dark' })
				}
			>
				{isDark ? 'Switch to light mode' : 'Switch to dark mode'}
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel: DarkModeButton,
}

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

/*
[1]
`editor.user.getIsDarkMode()` resolves the user's `colorScheme` preference (including
'system') to a boolean. Reading it inside `useValue` keeps the button label in sync
when the preference changes from anywhere, e.g. the toggle in the main menu.

[2]
`editor.setColorMode('dark')` is a shorthand for the same preference update.
*/
```

--------

# Inspector panel

Category: UI & theming

Keywords: inspector, properties, props, selection, panel, debug, usevalue, bindings, shared styles, getselectedshapes, getbindingsinvolvingshape, editorprovider

Show the properties, shared styles, and bindings of the current selection in a side panel.

The panel is a plain React component rendered next to `<Tldraw>` rather than inside it. The editor instance is captured from `onMount` and passed to `EditorProvider`, which makes `useEditor()` and `useValue()` work outside the canvas.

With one shape selected it lists the shape's record fields and `props`, plus any bindings from `editor.getBindingsInvolvingShape()`. With several selected it shows `editor.getSharedStyles()`, marking styles that differ across the selection as mixed.

Try selecting a shape, then drawing an arrow to it and selecting the arrow to see its binding. Select several shapes with different colors to see mixed styles.

## App.tsx

```tsx
import { useState } from 'react'
import {
	Editor,
	EditorProvider,
	SharedStyle,
	StyleProp,
	TLBinding,
	TLShapeId,
	Tldraw,
	useColorMode,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './inspector-panel.css'

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

function InspectorPanel() {
	const editor = useEditor()

	// [1]
	const selectedShapes = useValue('selected shapes', () => editor.getSelectedShapes(), [editor])
	const sharedStyles = useValue('shared styles', () => editor.getSharedStyles(), [editor])
	const bindings = useValue(
		'bindings',
		() => {
			const only = editor.getOnlySelectedShape()
			return only ? editor.getBindingsInvolvingShape(only.id) : []
		},
		[editor]
	)

	if (selectedShapes.length === 0) {
		return (
			<div className="inspector-panel">
				<h3>Inspector</h3>
				<p>No shape selected</p>
			</div>
		)
	}

	if (selectedShapes.length > 1) {
		return (
			<div className="inspector-panel">
				<h3>Inspector</h3>
				{sharedStyles.size > 0 && (
					<div className="inspector-section">
						<h4>Shared styles</h4>
						{Array.from(sharedStyles.entries()).map(([styleProp, sharedStyle]) => (
							<SharedStyleRow key={styleProp.id} styleProp={styleProp} sharedStyle={sharedStyle} />
						))}
					</div>
				)}
				<p>{selectedShapes.length} shapes selected</p>
			</div>
		)
	}

	const [selectedShape] = selectedShapes
	const { props, ...rest } = selectedShape

	return (
		<div className="inspector-panel">
			<h3>Inspector</h3>
			<div className="inspector-section">
				{Object.entries(rest).map(([key, value]) => (
					<PropertyRow key={key} name={key} value={value} />
				))}
			</div>

			{Object.keys(props).length > 0 && (
				<div className="inspector-section">
					<h4>Shape props</h4>
					{Object.entries(props).map(([key, value]) => (
						<PropertyRow key={key} name={key} value={value} />
					))}
				</div>
			)}

			{bindings.length > 0 && (
				<div className="inspector-section">
					<h4>Bindings ({bindings.length})</h4>
					{bindings.map((binding) => (
						<BindingRow key={binding.id} binding={binding} selectedShapeId={selectedShape.id} />
					))}
				</div>
			)}
		</div>
	)
}

// [2]
function SharedStyleRow({
	styleProp,
	sharedStyle,
}: {
	styleProp: StyleProp<unknown>
	sharedStyle: SharedStyle<unknown>
}) {
	const isMixed = sharedStyle.type === 'mixed'
	return (
		<div className="property-row">
			<span className="property-name">{styleProp.id.replace('tldraw:', '')}:</span>
			<span className={`property-value ${isMixed ? 'mixed-style' : 'shared-style'}`}>
				{isMixed ? '(mixed)' : formatValue(sharedStyle.value)}
			</span>
		</div>
	)
}

function formatValue(val: unknown): string {
	if (val === null || val === undefined) return String(val)
	if (typeof val === 'string') return `"${val}"`
	if (Array.isArray(val)) return `Array(${val.length})`
	if (typeof val === 'object') return `Object(${Object.keys(val).length} keys)`
	return String(val)
}

function PropertyRow({ name, value }: { name: string; value: unknown }) {
	const [isExpanded, setIsExpanded] = useState(false)
	const isObject = value !== null && typeof value === 'object'

	if (!isObject) {
		return (
			<div className="property-row">
				<span className="property-name">{name}:</span>
				<span className="property-value">{formatValue(value)}</span>
			</div>
		)
	}

	return (
		<div className="property-row">
			<div className="property-row-header">
				<span className="property-name">{name}:</span>
				<button
					className="toggle-button"
					onClick={() => setIsExpanded(!isExpanded)}
					title={isExpanded ? 'Collapse' : 'Expand'}
				>
					{isExpanded ? '−' : '+'}
				</button>
				<span className="property-value">{formatValue(value)}</span>
			</div>
			{isExpanded && (
				<div className="property-json">
					<pre>{JSON.stringify(value, null, 2)}</pre>
				</div>
			)}
		</div>
	)
}

// [3]
function BindingRow({
	binding,
	selectedShapeId,
}: {
	binding: TLBinding
	selectedShapeId: TLShapeId
}) {
	const editor = useEditor()
	const isFrom = binding.fromId === selectedShapeId
	const otherShapeId = isFrom ? binding.toId : binding.fromId
	const otherShape = useValue('other shape', () => editor.getShape(otherShapeId), [
		editor,
		otherShapeId,
	])

	return (
		<div className="binding-row">
			<div className="binding-header">
				<span className="binding-type">{binding.type}</span>
				<span className="binding-direction">({isFrom ? 'from' : 'to'})</span>
			</div>
			<PropertyRow name="id" value={binding.id} />
			<PropertyRow name={isFrom ? 'toId' : 'fromId'} value={otherShapeId} />
			{otherShape && <PropertyRow name="shape" value={otherShape.type} />}
			{Object.keys(binding.props).length > 0 && <PropertyRow name="props" value={binding.props} />}
		</div>
	)
}

// [4]
function InspectorPanelWrapper() {
	const colorMode = useColorMode()
	return (
		<div className={colorMode === 'dark' ? 'tl-theme__dark' : 'tl-theme__light'}>
			<InspectorPanel />
		</div>
	)
}

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

	return (
		<div className="example-container">
			<div className="canvas-container">
				<Tldraw persistenceKey="inspector-panel-example" onMount={setEditor} />
			</div>
			{editor && (
				<EditorProvider editor={editor}>
					<InspectorPanelWrapper />
				</EditorProvider>
			)}
		</div>
	)
}

/*
[1]
Everything the panel shows is read inside `useValue`, so the panel re-renders whenever
the selection or the selected shapes' records change. `getSharedStyles()` and
`getBindingsInvolvingShape()` are the same APIs the style panel and arrow bindings use.

[2]
`getSharedStyles()` returns a map from `StyleProp` to a `SharedStyle`: either
`{ type: 'shared', value }` when every selected shape agrees, or `{ type: 'mixed' }`.

[3]
Bindings are directional records with `fromId` and `toId`. For an arrow bound to a
shape, the arrow is `from` and the shape is `to`.

[4]
Components rendered outside `<Tldraw>` don't inherit its theme class, so we apply
`tl-theme__dark` / `tl-theme__light` ourselves based on `useColorMode()`.

[5]
The panel lives outside `<Tldraw>`, so it can't call `useEditor()` on its own. We grab
the editor from `onMount` and wrap the panel in `EditorProvider` to make the editor
hooks work there.
*/
```

## inspector-panel.css

```css
.example-container {
	display: flex;
	height: 100vh;
	width: 100%;
}

.canvas-container {
	flex: 1;
	height: 100vh;
}

/* Theme variables */
.tl-theme__light .inspector-panel {
	--inspector-bg: white;
	--inspector-border: #ccc;
	--inspector-text: inherit;
	--inspector-heading: #666;
	--inspector-muted: #666;
	--inspector-value: #333;
	--inspector-btn-bg: #e0e0e0;
	--inspector-btn-border: #ccc;
	--inspector-btn-text: inherit;
	--inspector-btn-hover: #d0d0d0;
	--inspector-btn-active: #c0c0c0;
	--inspector-json-bg: #f8f8f8;
	--inspector-json-border: #e0e0e0;
	--inspector-json-text: #444;
	--inspector-binding-bg: #f9f9f9;
	--inspector-binding-border: #007acc;
	--inspector-binding-type: #007acc;
	--inspector-binding-dir-bg: #e0e0e0;
	--inspector-binding-dir-text: #666;
}

.tl-theme__dark .inspector-panel {
	--inspector-bg: #2a2a2a;
	--inspector-border: #555;
	--inspector-text: #e0e0e0;
	--inspector-heading: #aaa;
	--inspector-muted: #aaa;
	--inspector-value: #ddd;
	--inspector-btn-bg: #555;
	--inspector-btn-border: #666;
	--inspector-btn-text: #e0e0e0;
	--inspector-btn-hover: #666;
	--inspector-btn-active: #777;
	--inspector-json-bg: #1e1e1e;
	--inspector-json-border: #555;
	--inspector-json-text: #ddd;
	--inspector-binding-bg: #333;
	--inspector-binding-border: #4da6ff;
	--inspector-binding-type: #4da6ff;
	--inspector-binding-dir-bg: #555;
	--inspector-binding-dir-text: #ccc;
}

.inspector-panel {
	width: 300px;
	background: var(--inspector-bg);
	border-left: 1px solid var(--inspector-border);
	color: var(--inspector-text);
	padding: 16px;
	font-family: monospace;
	font-size: 12px;
	overflow-y: auto;
}

.inspector-panel h3 {
	margin: 0 0 16px 0;
	font-size: 14px;
	font-weight: bold;
}

.inspector-panel h4 {
	margin: 16px 0 8px 0;
	font-size: 12px;
	font-weight: bold;
	color: var(--inspector-heading);
	text-transform: uppercase;
}

.inspector-panel h4:first-child {
	margin-top: 0;
}

.inspector-panel p {
	margin: 0;
	color: var(--inspector-muted);
	font-style: italic;
}

.inspector-section {
	margin-bottom: 16px;
}

.inspector-section:last-child {
	margin-bottom: 0;
}

.property-row {
	margin-bottom: 4px;
	line-height: 1.4;
}

.property-row-header {
	display: flex;
	align-items: center;
}

.property-name {
	flex: 0 0 1;
	font-weight: bold;
	margin-right: 8px;
}

.property-value {
	flex: 1;
	word-break: break-all;
	color: var(--inspector-value);
}

/* Shared style indicators */
.shared-style {
	color: #0066cc;
}

.mixed-style {
	color: #ff6600;
	font-style: italic;
}

.toggle-button {
	background: var(--inspector-btn-bg);
	border: 1px solid var(--inspector-btn-border);
	color: var(--inspector-btn-text);
	border-radius: 2px;
	width: 18px;
	height: 18px;
	font-size: 12px;
	font-weight: bold;
	cursor: pointer;
	display: flex;
	align-items: center;
	justify-content: center;
	padding: 0;
	line-height: 1;
	margin-right: 8px;
}

.toggle-button:hover {
	background: var(--inspector-btn-hover);
}

.toggle-button:active {
	background: var(--inspector-btn-active);
}

.property-json {
	margin-top: 4px;
	margin-left: 8px;
	background: var(--inspector-json-bg);
	border: 1px solid var(--inspector-json-border);
	border-radius: 4px;
	padding: 8px;
	overflow-x: auto;
}

.property-json pre {
	margin: 0;
	font-size: 11px;
	line-height: 1.3;
	color: var(--inspector-json-text);
	white-space: pre-wrap;
	word-break: break-word;
}

/* Binding-specific styles */
.binding-row {
	margin-bottom: 12px;
	padding: 8px;
	background: var(--inspector-binding-bg);
	border-radius: 4px;
	border-left: 3px solid var(--inspector-binding-border);
}

.binding-header {
	display: flex;
	align-items: center;
	margin-bottom: 4px;
	gap: 8px;
}

.binding-type {
	font-weight: bold;
	color: var(--inspector-binding-type);
	text-transform: uppercase;
	font-size: 11px;
}

.binding-direction {
	font-size: 10px;
	color: var(--inspector-binding-dir-text);
	background: var(--inspector-binding-dir-bg);
	padding: 2px 6px;
	border-radius: 2px;
}

.binding-props {
	margin-top: 4px;
}

.binding-prop {
	margin-left: 8px;
}

.binding-row:last-child {
	margin-bottom: 0;
}
```

--------

# Layer panel

Category: UI & theming

Keywords: layers, panel, tree view, hierarchy, visibility, show, hide, getsortedchildidsforparent, getshapevisibility, meta, infrontofthecanvas

Build a minimal layers panel that lists, selects, renames, and hides shapes.

The panel is an `InFrontOfTheCanvas` component that walks the page with `editor.getSortedChildIdsForParent()`, recursing into groups and frames to build a tree. Each row reads its shape reactively with `useValue`, so the list stays in sync as you draw.

Visibility is stored on `shape.meta` and enforced through the `getShapeVisibility` prop: `meta.hidden` hides a shape and its children, and `meta.force_show` lets a child stay visible inside a hidden parent.

Try clicking a row to select the shape (shift-click to add to the selection), double-clicking a name to rename it, and clicking the eye icon to hide it. Double-click the eye on a child of a hidden group to force it visible.

## App.tsx

```tsx
import { TLComponents, TLEditorSnapshot, Tldraw, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import { ShapeList } from './ShapeList'
import './layer-panel.css'
import snapshot from './snapshot.json'

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

const components: TLComponents = {
	// [1]
	InFrontOfTheCanvas: () => {
		const editor = useEditor()
		const shapeIds = useValue(
			'shapeIds',
			() => editor.getSortedChildIdsForParent(editor.getCurrentPageId()),
			[editor]
		)
		return (
			<div className="layer-panel">
				<div className="layer-panel-title">Shapes</div>

				<ShapeList
					// [2]
					shapeIds={shapeIds}
					depth={0}
				/>
			</div>
		)
	},
}

export default function LayerPanelExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="layer-panel-example"
				components={components}
				// [3]
				getShapeVisibility={(s) =>
					s.meta.force_show ? 'visible' : s.meta.hidden ? 'hidden' : 'inherit'
				}
				// Initial content so the panel has something to show.
				snapshot={snapshot as unknown as TLEditorSnapshot}
			/>
		</div>
	)
}

/*
[1]
The panel is an `InFrontOfTheCanvas` component. It reads the current page's top-level
shape ids with `getSortedChildIdsForParent(pageId)` inside `useValue`, so it re-renders
when shapes are added, removed, or reordered.

[2]
`ShapeList` (see ShapeList.tsx) recurses into groups and frames using the same
`getSortedChildIdsForParent` call with a shape id as the parent.

[3]
`getShapeVisibility` decides whether a shape is hidden. The panel stores its choice in
`shape.meta`: `hidden` hides a shape (and, via 'inherit', its children); `force_show`
lets a child stay visible even when its parent is hidden.
*/
```

## ShapeList.tsx

```tsx
import capitalize from 'lodash/capitalize'
import { useRef, useState } from 'react'
import { Editor, TLShapeId, useEditor, useValue } from 'tldraw'
import { VisibilityOff, VisibilityOn } from '../../../icons/icons'

const selectedBg = '#E8F4FE'
const childSelectedBg = '#F3F9FE'
const childBg = '#00000006'

function ShapeItem({
	shapeId,
	depth,
	parentIsSelected,
	parentIsHidden,
}: {
	shapeId: TLShapeId
	depth: number
	parentIsSelected?: boolean
	parentIsHidden?: boolean
}) {
	const editor = useEditor()

	const shape = useValue('shape', () => editor.getShape(shapeId), [editor])
	const children = useValue('children', () => editor.getSortedChildIdsForParent(shapeId), [editor])
	const isHidden = useValue('isHidden', () => editor.isShapeHidden(shapeId), [editor])
	const isSelected = useValue('isSelected', () => editor.getSelectedShapeIds().includes(shapeId), [
		editor,
	])
	const shapeName = useValue('shapeName', () => getShapeName(editor, shapeId), [editor])

	const [isEditingName, setIsEditingName] = useState(false)

	const timeSinceLastVisibilityToggle = useRef(Date.now())

	if (!shape) return null

	return (
		<>
			<div
				className="shape-item"
				onDoubleClick={() => {
					setIsEditingName(true)
				}}
				onPointerDown={() => {
					if (editor.inputs.getCtrlKey() || editor.inputs.getShiftKey()) {
						if (isSelected) {
							editor.deselect(shape)
						} else {
							editor.select(...editor.getSelectedShapes(), shape)
						}
					} else {
						editor.select(shape)
					}
				}}
				style={{
					paddingLeft: 10 + depth * 20,
					opacity: isHidden ? 0.5 : 1,
					background: isSelected
						? selectedBg
						: parentIsSelected
							? childSelectedBg
							: depth > 0
								? childBg
								: undefined,
				}}
			>
				{isEditingName ? (
					<input
						autoFocus
						className="shape-name-input"
						defaultValue={shapeName}
						onBlur={() => setIsEditingName(false)}
						onChange={(ev) => {
							if (shape.type === 'frame') {
								editor.updateShape({ ...shape, props: { name: ev.target.value } })
							} else {
								editor.updateShape({ ...shape, meta: { name: ev.target.value } })
							}
						}}
						onKeyDown={(ev) => {
							if (ev.key === 'Enter' || ev.key === 'Escape') {
								ev.currentTarget.blur()
							}
						}}
					/>
				) : (
					<div className="shape-name">{shapeName}</div>
				)}
				<button
					className="shape-visibility-toggle"
					onPointerDown={(ev) => {
						// Don't let the click also select the row.
						ev.stopPropagation()
						const now = Date.now()
						if (now - timeSinceLastVisibilityToggle.current < 200) {
							editor.updateShape({
								...shape,
								meta: { hidden: false, force_show: true },
							})
							timeSinceLastVisibilityToggle.current = 0
						} else {
							editor.updateShape({
								...shape,
								meta: { hidden: !shape.meta.hidden, force_show: false },
							})
							timeSinceLastVisibilityToggle.current = now
						}
					}}
				>
					{shape.meta.hidden ? <VisibilityOff /> : <VisibilityOn />}
				</button>
			</div>
			{!!children?.length && (
				<ShapeList
					shapeIds={children}
					depth={depth + 1}
					parentIsHidden={parentIsHidden || isHidden}
					parentIsSelected={parentIsSelected || isSelected}
				/>
			)}
		</>
	)
}

export function ShapeList({
	shapeIds,
	depth,
	parentIsSelected,
	parentIsHidden,
}: {
	shapeIds: TLShapeId[]
	depth: number
	parentIsSelected?: boolean
	parentIsHidden?: boolean
}) {
	if (!shapeIds.length) return null
	return (
		<div className="shape-tree">
			{shapeIds.map((shapeId) => (
				<ShapeItem
					key={shapeId}
					shapeId={shapeId}
					depth={depth}
					parentIsHidden={parentIsHidden}
					parentIsSelected={parentIsSelected}
				/>
			))}
		</div>
	)
}

function getShapeName(editor: Editor, shapeId: TLShapeId) {
	const shape = editor.getShape(shapeId)
	if (!shape) return 'Unknown shape'
	return (
		(shape.meta.name as string) ||
		editor.getShapeUtil(shape).getText(shape) ||
		capitalize(shape.type + ' shape')
	)
}
```

## layer-panel.css

```css
.layer-panel {
	position: absolute;
	left: 0;
	top: 42px;
	width: 200px;
	height: calc(100% - 42px);
	background: white;
	display: flex;
	flex-direction: column;
	pointer-events: all;
}
.shape-tree {
	display: flex;
	flex-direction: column;
}
.shape-item {
	display: flex;
	align-items: center;
	justify-content: space-between;
	padding: 6px 10px;
}

.shape-visibility-toggle {
	padding: 3px 6px;
	border-radius: 3px;
	outline: none;
	border: none;
	background: none;
	flex-shrink: 0;
}
.shape-visibility-toggle:hover {
	cursor: pointer;
	background-color: #0000000b;
}

.layer-panel-title {
	padding: 10px;
	font-size: smaller;
	font-weight: bolder;
}

.shape-name-input {
	border: none;
	background: none;
	width: 0;
	flex-grow: 1;
	padding: 0;
}

.shape-name {
	overflow: hidden;
	text-overflow: ellipsis;
	text-wrap: nowrap;
}
```

--------

# Page panel

Category: UI & theming

Keywords: pages, page menu, sidebar, thumbnails, previews, external ui, page list

Replace the page menu with a custom sidebar with live thumbnails of every page.

This example shows how to build a custom page panel in your own DOM, outside the canvas. The panel uses `editor.getPages()` inside `useValue` to re-render whenever pages change. It manages pages with `editor.setCurrentPage`, `editor.createPage`, `editor.renamePage`, and `editor.deletePage`. Double-click a page to rename it.

The canvas only renders the current page, so the thumbnails are exported images: `editor.getPageShapeIds(pageId)` and `editor.getSvgString` both work for any page, not just the current one. Thumbnails regenerate on a debounced store listener as you draw.

## App.tsx

```tsx
import { useEffect, useState } from 'react'
import {
	Editor,
	EditorProvider,
	PageRecordType,
	TLComponents,
	TLPage,
	TLPageId,
	Tldraw,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './page-panel.css'

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

// [1]
const components: TLComponents = {
	PageMenu: null,
}

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

	return (
		<div className="page-panel-layout">
			{/* [2] */}
			{editor && (
				<EditorProvider editor={editor}>
					<PagePanel />
				</EditorProvider>
			)}
			<div className="page-panel-canvas">
				<Tldraw persistenceKey="page-panel-example" components={components} onMount={setEditor} />
			</div>
		</div>
	)
}

function PagePanel() {
	const editor = useEditor()

	// [3]
	const pages = useValue('pages', () => editor.getPages(), [editor])
	const currentPageId = useValue('current page id', () => editor.getCurrentPageId(), [editor])

	// [4]
	function handleCreatePage() {
		const newPageId = PageRecordType.createId()
		editor.run(() => {
			editor.markHistoryStoppingPoint('creating page')
			editor.createPage({ id: newPageId, name: `Page ${pages.length + 1}` })
			editor.setCurrentPage(newPageId)
		})
	}

	function handleRenamePage(page: TLPage) {
		const name = window.prompt('Rename page', page.name)
		if (name && name !== page.name) {
			editor.markHistoryStoppingPoint('renaming page')
			editor.renamePage(page.id, name)
		}
	}

	function handleDeletePage(page: TLPage) {
		editor.markHistoryStoppingPoint('deleting page')
		editor.deletePage(page.id)
	}

	return (
		<div className="page-panel">
			<div className="page-panel-list">
				{pages.map((page, index) => (
					<div
						key={page.id}
						className="page-panel-item"
						data-iscurrent={page.id === currentPageId}
						onClick={() => editor.setCurrentPage(page.id)}
						onDoubleClick={() => handleRenamePage(page)}
					>
						<PageThumbnail pageId={page.id} />
						<div className="page-panel-item-footer">
							<span className="page-panel-item-index">{index + 1}</span>
							<span className="page-panel-item-name">{page.name}</span>
							{pages.length > 1 && (
								<button
									className="page-panel-item-delete"
									title="Delete page"
									onClick={(e) => {
										e.stopPropagation()
										handleDeletePage(page)
									}}
								>
									×
								</button>
							)}
						</div>
					</div>
				))}
			</div>
			<button className="page-panel-add" onClick={handleCreatePage}>
				+ New page
			</button>
		</div>
	)
}

function PageThumbnail({ pageId }: { pageId: TLPageId }) {
	const editor = useEditor()
	const [src, setSrc] = useState<string | null>(null)

	useEffect(() => {
		let isCancelled = false
		let timeout: ReturnType<typeof setTimeout> | undefined

		// [5]
		async function generateThumbnail() {
			const shapeIds = editor.getPageShapeIds(pageId)
			if (shapeIds.size === 0) {
				if (!isCancelled) setSrc(null)
				return
			}
			const result = await editor.getSvgString([...shapeIds], {
				background: false,
				padding: 16,
			})
			if (isCancelled || !result) return
			setSrc(`data:image/svg+xml;charset=utf-8,${encodeURIComponent(result.svg)}`)
		}

		generateThumbnail()

		// [6]
		const removeListener = editor.store.listen(
			() => {
				if (editor.getCurrentPageId() !== pageId) return
				clearTimeout(timeout)
				timeout = setTimeout(generateThumbnail, 300)
			},
			{ scope: 'document', source: 'user' }
		)

		return () => {
			isCancelled = true
			clearTimeout(timeout)
			removeListener()
		}
	}, [editor, pageId])

	return (
		<div className="page-panel-thumbnail">
			{src ? <img src={src} alt="" /> : <span className="page-panel-thumbnail-empty">Empty</span>}
		</div>
	)
}

/*
This example shows how to replace the built-in page menu with a custom page
panel in your own DOM, outside the canvas, with live thumbnail previews of
every page.

The canvas only renders the shapes of the current page, so we export the
other pages as images to show their previews.

[1]
Hide the built-in page menu by overriding the `PageMenu` component with null.

[2]
Use the `onMount` prop to grab the editor instance and store it in React
state. Wrapping external components in `EditorProvider` lets them use
`useEditor` and `useValue` even though they're rendered outside `<Tldraw />`.

[3]
`editor.getPages()` is a computed (reactive) value backed by a store query for
all page records, sorted by index. Reading it inside `useValue` means this
component re-renders automatically whenever pages are created, deleted,
renamed, or reordered.

[4]
Create the page with an explicit id so we can navigate to it right away.
`editor.run` batches the two changes, and `markHistoryStoppingPoint` makes the
whole thing a single undo step. Note that `editor.deletePage` automatically
switches to another page if you delete the current one.

[5]
The canvas never renders pages other than the current one, so we export them
as images instead. `editor.getPageShapeIds(pageId)` returns the
shape ids on any page (not just the current one), and `editor.getSvgString`
can export shapes from any page. We turn the SVG string into a data URL for a
plain <img> tag.

[6]
Regenerate the thumbnail when the document changes, debounced so we don't
re-export on every pointer move. Local edits can only affect the current
page, so each thumbnail skips changes made while another page is active. In a
multiplayer app you'd also listen to remote changes (source: 'all') and check
which page the changed shapes belong to.
*/
```

## page-panel.css

```css
.page-panel-layout {
	display: flex;
	width: 100%;
	height: 100vh;
}

.page-panel-canvas {
	position: relative;
	flex: 1;
	height: 100%;
}

.page-panel {
	width: 168px;
	flex-shrink: 0;
	display: flex;
	flex-direction: column;
	background: #f9fafb;
	border-right: 1px solid #e3e3e3;
}

.page-panel-list {
	flex: 1;
	overflow-y: auto;
	display: flex;
	flex-direction: column;
	gap: 8px;
	padding: 8px;
}

.page-panel-item {
	border: 1px solid #e3e3e3;
	border-radius: 6px;
	background: white;
	padding: 4px;
	cursor: pointer;
}

.page-panel-item[data-iscurrent='true'] {
	border-color: #2f80ed;
	outline: 1px solid #2f80ed;
}

.page-panel-thumbnail {
	aspect-ratio: 4 / 3;
	display: flex;
	align-items: center;
	justify-content: center;
	background: white;
	border-radius: 4px;
	overflow: hidden;
}

.page-panel-thumbnail img {
	max-width: 100%;
	max-height: 100%;
}

.page-panel-thumbnail-empty {
	color: #b0b0b0;
	font-size: 11px;
}

.page-panel-item-footer {
	display: flex;
	align-items: center;
	gap: 4px;
	padding: 4px 2px 2px 2px;
	font-size: 12px;
}

.page-panel-item-index {
	color: #999;
}

.page-panel-item-name {
	flex: 1;
	overflow: hidden;
	text-overflow: ellipsis;
	white-space: nowrap;
}

.page-panel-item-delete {
	border: none;
	background: none;
	color: #999;
	font-size: 14px;
	line-height: 1;
	padding: 0 2px;
	cursor: pointer;
	visibility: hidden;
}

.page-panel-item:hover .page-panel-item-delete {
	visibility: visible;
}

.page-panel-item-delete:hover {
	color: #d32f2f;
}

.page-panel-add {
	margin: 8px;
	padding: 6px;
	border: 1px solid #e3e3e3;
	border-radius: 6px;
	background: white;
	font-size: 12px;
	cursor: pointer;
}

.page-panel-add:hover {
	background: #f0f0f0;
}
```

--------

# Floaty window

Category: UI & theming

Keywords: camera, setcamera, window position, screenx, screeny, tick event

Pin the canvas to the desktop so the browser window appears to float over it.

On every editor `tick`, the example reads `window.screenX` and `window.screenY` and, if the window has moved, calls `editor.setCamera()` with the negative offset. The canvas stays put on screen while the window slides over it, an illusion that was [popular on social media](https://x.com/steveruizok/status/1727436505440981099) for a while.

Try dragging the browser window around the screen (it won't work while the window is maximized).

## App.tsx

```tsx
import { useEffect } from 'react'
import { Tldraw, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'

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

export default function FloatyExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="tldraw_floaty_example">
				<FloatyWindow />
			</Tldraw>
		</div>
	)
}

// [1]
function FloatyWindow() {
	const editor = useEditor()

	useEffect(() => {
		let x = window.screenX
		let y = window.screenY

		// [2]
		function updateCamera() {
			if (window.screenX === x && window.screenY === y) return
			x = window.screenX
			y = window.screenY
			editor.setCamera({ x: -x, y: -y })
		}

		// [3]
		editor.on('tick', updateCamera)
		return () => {
			editor.off('tick', updateCamera)
		}
	}, [editor])

	return null
}

/*
Moving the browser window across the screen pans the camera by the same amount, so the
canvas looks like it's pinned to the desktop while the window slides over it. This was
[popular on social media](https://x.com/steveruizok/status/1727436505440981099) for a while.

[1]
Any component rendered as a child of `<Tldraw>` can call `useEditor()`, so this hook
component runs its effect once the editor exists and renders nothing.

[2]
`window.screenX` / `screenY` are the window's position on the screen. When they change,
the camera is set to the negative of that offset so page space stays fixed relative to
the screen. Camera coordinates are page-space, so this is exact at zoom 1.

[3]
There's no DOM event for the window moving, so we poll on the editor's `tick` event and
unsubscribe in the effect cleanup.
*/
```

--------

# Custom translations and overrides

Category: UI & theming

Keywords: translation, i18n, localization, language, useTranslation, overrides, multilingual, custom text, brand voice

Override tldraw's translation strings and read them in your own components with `useTranslation`.

Apps often need to customize UI text to match their brand voice or terminology. The `translations` override on the `overrides` prop maps a language code to translation keys and strings; you can replace existing keys (here "Duplicate" becomes "Make a copy" and "Delete" becomes "Remove") or add new ones, in as many languages as you like.

The `useTranslation` hook returns a `msg` function that looks up a key in the current language, so custom components render the same strings as tldraw's built-in menus. Right click a shape to see the overrides in the context menu, or switch the language to Spanish from the language submenu in the main menu.

## App.tsx

```tsx
import {
	TLComponents,
	TLUiOverrides,
	Tldraw,
	TldrawUiButton,
	useEditor,
	useTranslation,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './custom-language-translations.css'

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

// [1]
function CustomToolbar() {
	const editor = useEditor()
	const msg = useTranslation()

	return (
		<div className="tlui-menu custom-language-toolbar">
			<TldrawUiButton
				type="normal"
				onClick={() => editor.duplicateShapes(editor.getSelectedShapeIds())}
			>
				{/* [2] */}
				{msg('action.duplicate')}
			</TldrawUiButton>
			<TldrawUiButton
				type="normal"
				onClick={() => editor.deleteShapes(editor.getSelectedShapeIds())}
			>
				{msg('action.delete')}
			</TldrawUiButton>
		</div>
	)
}

// [3]
const overrides: TLUiOverrides = {
	translations: {
		en: {
			'action.duplicate': 'Make a copy',
			'action.delete': 'Remove',
		},
		es: {
			'action.duplicate': 'Hacer una copia',
			'action.delete': 'Eliminar',
		},
	},
}

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

export default function CustomLanguageTranslationExample() {
	return (
		<div className="tldraw__editor">
			{/* [5] */}
			<Tldraw overrides={overrides} components={components} />
		</div>
	)
}

/*
This example shows how to customize tldraw's translation strings and use them in your own
components. This is useful when you need to match your app's brand voice or terminology.

[1]
The `useTranslation` hook returns a function (conventionally named `msg`) that looks up a
translated string by key in the user's current language.

[2]
`action.duplicate` and `action.delete` are keys tldraw already uses in its own menus. Because we
override them below, both our toolbar and tldraw's built-in menus show the custom text.

[3]
The `translations` override maps a language code (like `en` or `es`) to an object of translation
keys and strings. You can override existing keys or add new ones for your own UI. Languages you
don't override fall back to tldraw's defaults.

[4]
Define the components object outside the React component so it's a stable reference. The custom
toolbar is placed in the `TopPanel` slot.

[5]
Pass both the overrides and the components to the `Tldraw` component.

The custom translations also show up in tldraw's own menus. Try creating a shape and right
clicking it to see "Make a copy" and "Remove" in the context menu, or switch the language to
Spanish from the main menu's language submenu to see the `es` overrides.
*/
```

## custom-language-translations.css

```css
.custom-language-toolbar {
	pointer-events: all;
	display: flex;
	margin: 8px;
}
```

--------

# Custom renderer

Category: UI & theming

Keywords: renderer, canvas, Background component, Canvas component, custom rendering, 2d context, alternative rendering

Draw shapes with your own 2d canvas renderer instead of tldraw's DOM rendering.

The `Background` component is replaced with a component that reads `editor.getRenderingShapes()` on every animation frame and draws draw and geo shapes to a 2d canvas, using `getColorValue` to look up theme colors. tldraw's regular shapes layer is hidden with CSS, while selection, handles, and the rest of the UI keep working.

This is a sketch of the approach rather than a complete renderer: it handles draw and geo shapes and draws a bounding box for everything else. Try drawing a few shapes and moving them around.

## App.tsx

```tsx
import { TLComponents, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { CustomRenderer } from './CustomRenderer'
import './custom-renderer.css'

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

// [1]
const components: TLComponents = {
	Background: CustomRenderer,
}

export default function CustomRendererExample() {
	return (
		// [2]
		<div className="tldraw__editor custom-renderer">
			<Tldraw persistenceKey="custom-renderer-example" components={components} />
		</div>
	)
}

/*
The shapes are drawn to a 2d canvas from the editor's shape data instead of being rendered by
React.

[1]
We replace the `Background` component with our custom renderer (see `CustomRenderer.tsx`). It
reads the rendering shapes from the editor on every animation frame and draws them itself. Even
though the DOM shapes are hidden, tldraw still does the work of figuring out which shapes to
render. In a real app you might set the `Canvas` component to null and render everything yourself.

[2]
The `.custom-renderer` class hides tldraw's regular shapes layer via CSS (see
`custom-renderer.css`) so only our canvas rendering is visible. Selection, handles, and the
rest of the UI still work as normal.
*/
```

## CustomRenderer.tsx

```tsx
import { useLayoutEffect, useRef } from 'react'
import { getColorValue, getPointsFromDrawSegment, useEditor } from 'tldraw'

export function CustomRenderer() {
	const editor = useEditor()
	const rCanvas = useRef<HTMLCanvasElement>(null)

	useLayoutEffect(() => {
		const canvas = rCanvas.current
		if (!canvas) return

		canvas.style.width = '100%'
		canvas.style.height = '100%'

		const rect = canvas.getBoundingClientRect()

		canvas.width = rect.width
		canvas.height = rect.height

		const ctx = canvas.getContext('2d')!

		let raf = -1

		function render() {
			if (!canvas) return

			ctx.resetTransform()
			ctx.clearRect(0, 0, canvas.width, canvas.height)

			const camera = editor.getCamera()
			ctx.scale(camera.z, camera.z)
			ctx.translate(camera.x, camera.y)

			const renderingShapes = editor.getRenderingShapes()
			const theme = editor.getCurrentTheme()
			const colors = theme.colors[editor.getColorMode()]
			const currentPageId = editor.getCurrentPageId()

			for (const { shape, opacity } of renderingShapes) {
				const maskedPageBounds = editor.getShapeMaskedPageBounds(shape)
				if (!maskedPageBounds) continue
				ctx.save()

				if (shape.parentId !== currentPageId) {
					ctx.beginPath()
					ctx.rect(
						maskedPageBounds.minX,
						maskedPageBounds.minY,
						maskedPageBounds.width,
						maskedPageBounds.height
					)
					ctx.clip()
				}

				ctx.beginPath()

				ctx.globalAlpha = opacity

				const transform = editor.getShapePageTransform(shape.id)
				ctx.transform(transform.a, transform.b, transform.c, transform.d, transform.e, transform.f)

				if (editor.isShapeOfType(shape, 'draw')) {
					// Draw a freehand shape
					for (const segment of shape.props.segments) {
						const points = getPointsFromDrawSegment(segment, shape.props.scaleX, shape.props.scaleY)
						ctx.moveTo(points[0].x, points[0].y)
						if (segment.type === 'straight') {
							ctx.lineTo(points[1].x, points[1].y)
						} else {
							for (const point of points.slice(1)) {
								ctx.lineTo(point.x, point.y)
							}
						}
					}
					ctx.strokeStyle = getColorValue(colors, shape.props.color, 'solid')
					ctx.lineWidth = 4
					ctx.stroke()
					if (shape.props.fill !== 'none' && shape.props.isClosed) {
						ctx.fillStyle = getColorValue(colors, shape.props.color, 'semi')
						ctx.fill()
					}
				} else if (editor.isShapeOfType(shape, 'geo')) {
					// Draw a geo shape
					const bounds = editor.getShapeGeometry(shape).bounds
					ctx.strokeStyle = getColorValue(colors, shape.props.color, 'solid')
					ctx.lineWidth = 2
					ctx.strokeRect(bounds.minX, bounds.minY, bounds.width, bounds.height)
				} else {
					// Draw any other kind of shape
					const bounds = editor.getShapeGeometry(shape).bounds
					ctx.strokeStyle = 'black'
					ctx.lineWidth = 2
					ctx.strokeRect(bounds.minX, bounds.minY, bounds.width, bounds.height)
				}
				ctx.restore()
			}

			raf = requestAnimationFrame(render)
		}

		render()

		return () => {
			cancelAnimationFrame(raf)
		}
	}, [editor])

	return <canvas ref={rCanvas} />
}
```

## custom-renderer.css

```css
/* Hide tldraw's DOM shape layer; the custom renderer draws the shapes instead. */
.custom-renderer .tl-shapes {
	display: none;
}
```

--------

# Inset editor

Category: Page layout

Keywords: inline, embedded, non-fullscreen, layout, container, positioning, inset, wrapper

Place the `Tldraw` component in a container that doesn't fill the screen.

The `Tldraw` component fills its container, and that container can be anywhere in your layout. Here it's an absolutely positioned box inset 100px from every edge of the page. Pointer events, keyboard shortcuts, camera, and UI all work the same as in a full-screen editor because the editor measures its own container rather than the window.

For examples with several fixed-size editors on one page, see [Inset editor (fixed sizes)](https://tldraw.dev/examples/inline).

## App.tsx

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

export default function InsetExample() {
	return (
		<div style={{ position: 'absolute', inset: 100 }}>
			<div className="tldraw__editor">
				<Tldraw />
			</div>
		</div>
	)
}
```

--------

# Inset editor (fixed sizes)

Category: Page layout

Keywords: inline, embedded, fixed size, width, height, responsive, multiple editors

See how the default UI adapts when the `Tldraw` component is given a fixed width and height.

The `Tldraw` component fills whatever container it's placed in. This example renders the same document (via a shared `persistenceKey`) in five containers of different fixed sizes, so you can see how the default toolbar, menus, and panels rearrange themselves as the available space shrinks.

For guidance on focus handling and UI trimming when embedding several editors in a page, see the [Inset editor (common practices)](https://tldraw.dev/examples/inline-behavior) example.

## App.tsx

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

export default function InlineExample() {
	return (
		<>
			<InlineEditor width={400} height={300} />
			<InlineEditor width={500} height={300} />
			<InlineEditor width={600} height={400} />
			<InlineEditor width={700} height={500} />
			<InlineEditor width={900} height={600} />
		</>
	)
}

function InlineEditor({ width, height }: { width: number; height: number }) {
	const title = `${width} x ${height}`
	return (
		<section style={{ padding: '12px 32px' }}>
			<h2>{title}</h2>
			<div style={{ width, height }}>
				<Tldraw persistenceKey="inset-size-example" />
			</div>
		</section>
	)
}
```

--------

# Inset editor (common practices)

Category: Page layout

Keywords: inline, embedded, focus, blur, multiple editors, autofocus, hand tool, edge scrolling, edgescrollspeed, maxpages, context

Embed several `Tldraw` blocks in a page so that only one is focused at a time, with a stripped-down UI.

When tldraw is one block among many in a larger document, the defaults for a full-page editor get in the way: every editor grabs keyboard shortcuts, the select tool makes it easy to accidentally move things while scrolling past, and the full UI is too much for a small space. This example shows the adjustments we recommend:

- Track the focused editor in a React context, and call `editor.focus()` / `editor.blur()` (with `focusContainer` / `blurContainer` off) so only one editor handles keyboard input at a time.
- Default to the hand tool on mount and whenever focus is lost, and clear the selection on blur.
- Hide the UI of unfocused editors with `hideUi`.
- Set `edgeScrollSpeed: 0` so the canvas doesn't scroll when the pointer nears the edge of a small block, and `maxPages: 0` to remove the pages menu.
- Remove the help menu, navigation panel, and main menu via `components`.

Try clicking into one block, then another, then somewhere on the page outside all of them.

## App.tsx

```tsx
import { createContext, useContext, useState } from 'react'
import { Editor, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
const focusedEditorContext = createContext(
	{} as {
		focusedEditor: Editor | null
		setFocusedEditor(editor: Editor | null): void
	}
)

// [2]
function blurEditor(editor: Editor) {
	editor.blur({ blurContainer: false })
	editor.selectNone()
	editor.setCurrentTool('hand')
}

export default function InlineBehaviorExample() {
	const [focusedEditor, setFocusedEditor] = useState<Editor | null>(null)

	return (
		<focusedEditorContext.Provider value={{ focusedEditor, setFocusedEditor }}>
			<div
				style={{
					display: 'flex',
					flexDirection: 'column',
					padding: 20,
					gap: 20,
				}}
				// [3]
				onPointerDown={() => {
					if (!focusedEditor) return
					blurEditor(focusedEditor)
					setFocusedEditor(null)
				}}
			>
				<InlineBlock persistenceKey="block-a" />
				<InlineBlock persistenceKey="block-b" />
				<InlineBlock persistenceKey="block-c" />
			</div>
		</focusedEditorContext.Provider>
	)
}

function InlineBlock({ persistenceKey }: { persistenceKey: string }) {
	const { focusedEditor, setFocusedEditor } = useContext(focusedEditorContext)
	const [editor, setEditor] = useState<Editor>()

	return (
		<div
			style={{ width: 600, height: 400, maxWidth: '100%' }}
			// [4]
			onFocus={() => {
				if (!editor) return
				if (focusedEditor && focusedEditor !== editor) {
					blurEditor(focusedEditor)
				}
				editor.focus({ focusContainer: false })
				setFocusedEditor(editor)
			}}
			onPointerDown={(e) => e.stopPropagation()}
		>
			<Tldraw
				persistenceKey={persistenceKey}
				autoFocus={false}
				// [5]
				hideUi={focusedEditor !== editor}
				// [6]
				options={{
					maxPages: 0,
					edgeScrollSpeed: 0,
				}}
				// [7]
				components={{
					HelpMenu: null,
					NavigationPanel: null,
					MainMenu: null,
				}}
				// [8]
				onMount={(editor) => {
					setEditor(editor)
					editor.setCurrentTool('hand')
				}}
			/>
		</div>
	)
}

/*
[1]
A context tracking which editor is focused. Only the focused editor handles keyboard
shortcuts, so several editors on one page don't fight over them. See also the
'Multiple editors' and 'Focus the editor' examples.

[2]
Called on any editor that loses focus. `blurContainer: false` stops the editor's
DOM container from being blurred (we manage focus at the block level), and we reset
the user's tool state so nothing is left selected or half-drawn.

[3]
Clicking anywhere on the page outside an editor blurs the focused one.

[4]
Clicking into a block focuses its editor and blurs whichever was focused before.
Stopping pointer-down propagation keeps [3] from immediately blurring it again.

[5]
Unfocused editors hide their UI.

[6]
`maxPages: 0` removes the pages menu. `edgeScrollSpeed: 0` disables edge scrolling,
which is too easily triggered when the canvas is small.

[7]
Drop UI components that don't earn their space in a small block.

[8]
Default to the hand tool on mount so scrolling past a block doesn't accidentally
move shapes, and keep a reference to the editor for the focus handlers.
*/
```

--------

# Inset canvas

Category: Page layout

Keywords: canvas position, inset, css, custom layout, canvas offset

Move the `.tl-canvas` element so it no longer fills the `Tldraw` container.

Normally the canvas fills the whole `Tldraw` container and the UI floats over it. This example uses CSS to shrink and center the `.tl-canvas` element to the middle 50% of the container, leaving the UI where it was. Pointer positions, hit testing, and the camera still line up correctly because the editor measures the canvas element itself, not its container.

This is an unusual layout; the point of the example is to show that if you need to reposition the canvas within the editor's chrome, you can do it with CSS alone.

## App.tsx

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

export default function InsetCanvasExample() {
	return (
		<div className="tldraw__editor tldraw__editor-with-inset-canvas">
			<Tldraw />
		</div>
	)
}
```

## inset-canvas.css

```css
.tldraw__editor-with-inset-canvas .tl-canvas {
	position: absolute;
	inset: 25%;
	width: 50%;
	height: 50%;
}
```

--------

# Scrollable container

Category: Page layout

Keywords: scrollable, container, layout, autofocus, focus, mousewheel, viewport, nested

Use the editor inside a page that scrolls, and see how focus decides who gets the wheel events.

The `Tldraw` component works inside a scrollable page. The one thing to be aware of is the mouse wheel: while the editor is focused it consumes wheel events to pan and zoom the canvas, and the page doesn't scroll. When it's blurred, wheel events pass through and the page scrolls as normal.

Here the editor is centered in a container larger than the viewport, with `autoFocus` on. Try scrolling with the pointer over the canvas, then set `autoFocus={false}` and try again.

## App.tsx

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

export default function ScrollExample() {
	return (
		<div
			style={{
				width: '150vw',
				height: '150vh',
				display: 'flex',
				justifyContent: 'center',
				alignItems: 'center',
				backgroundColor: '#fff',
			}}
		>
			<div style={{ width: '60vw', height: '80vh' }}>
				<Tldraw persistenceKey="scroll-example" autoFocus={true} />
			</div>
		</div>
	)
}

/*
While the editor is focused it consumes wheel events to pan and zoom, so the page won't
scroll when the pointer is over the canvas. Try turning off `autoFocus` to see the
difference.
*/
```

--------

# Multiple editors

Category: Page layout

Keywords: multiple editors, focus, autofocus, blur, context, shared document, persistencekey, sync

Put several `Tldraw` components on one page and make sure only one is focused at a time.

Each `Tldraw` component is its own editor with its own keyboard handling, so with several on a page you need to decide which one currently owns focus. This example turns off `autoFocus` on every editor and tracks the focused one in a React context. Wrapping each editor in a focusable `div` (`tabIndex={-1}`) with an `onFocus` handler lets us call `editor.focus()` on the newly focused editor and `editor.blur()` on the previous one. Clicking anywhere else on the page blurs whichever editor was focused.

Editors B and C share a `persistenceKey`, so they show the same locally synchronized document. Try drawing in one and watching the other update. The long block of text below is there so you can check that scrolling the page and typing in the textarea don't get captured by an unfocused editor.

## App.tsx

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

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

// [1]
const focusedEditorContext = createContext(
	{} as {
		focusedEditor: Editor | null
		setFocusedEditor(editor: Editor | null): void
	}
)

// [2]
export default function MultipleExample() {
	const [focusedEditor, _setFocusedEditor] = useState<Editor | null>(null)

	const setFocusedEditor = useCallback(
		(editor: Editor | null) => {
			if (focusedEditor !== editor) {
				if (focusedEditor) {
					focusedEditor.blur()
				}
				if (editor) {
					editor.focus()
				}
				_setFocusedEditor(editor)
			}
		},
		[focusedEditor]
	)

	const focusName =
		focusedEditor === (window as any).EDITOR_A
			? 'A'
			: focusedEditor === (window as any).EDITOR_B
				? 'B'
				: focusedEditor === (window as any).EDITOR_C
					? 'C'
					: 'none'

	return (
		<div
			style={{
				padding: 32,
			}}
			// Clicking anywhere on the page outside an editor blurs the focused one
			onPointerDown={() => setFocusedEditor(null)}
		>
			<focusedEditorContext.Provider value={{ focusedEditor, setFocusedEditor }}>
				<h1>Focusing: {focusName}</h1>
				<EditorA />
				<textarea data-testid="textarea" placeholder="type in me" style={{ margin: 10 }} />
				<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 }}
				// Keep pointer downs inside the editor from reaching the page-level blur handler
				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>
	)
}

/*
With several editors on one page, only one should own keyboard focus at a time. Every
editor here has `autoFocus={false}`, and we manage focus ourselves with a context.

The editors are also stashed on `window` (`EDITOR_A`, `EDITOR_B`, `EDITOR_C`) so the
e2e tests can reach them; a real app would keep them in state or refs.

[1]
A context holding the focused editor and a setter.

[2]
The setter blurs the previously focused editor and focuses the new one before
updating state, so exactly one editor has `isFocused` at any time.

[3]
Each editor is wrapped in a focusable div (`tabIndex={-1}`). When it receives DOM
focus, we mark its editor as the focused one. Editor A focuses itself on mount.

[4]
Editors B and C share a persistence key, so they display the same locally
synchronized document.

[5]
A long story that doesn't go anywhere, but it's a good way to test that scrolling
the page doesn't get captured by an unfocused editor.
*/
```

--------

# External dialog

Category: Page layout

Keywords: dialog, modal, css, styling, custom styles, embed, insert

Open dialogs over the whole page instead of inside the `Tldraw` container.

The tldraw UI renders its dialogs (insert embed, edit link, keyboard shortcuts) inside the `Tldraw` component, positioned absolutely within it. When the editor is a small inset in a larger page, that can leave dialogs cramped or clipped.

This example overrides the `.tlui-dialog__overlay` and `.tlui-dialog__positioner` styles to use `position: fixed`, so dialogs are positioned relative to the browser window instead. Try it: open the "Insert embed" dialog from the menu, or press `Cmd + I` / `Ctrl + I`, and the dialog will center over the whole page rather than the 600 × 400 editor.

## App.tsx

```tsx
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
// [1]
import './external-dialog.css'

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

/*
[1]
By default the dialog overlay and positioner are `position: absolute` and fill the
`Tldraw` container. Switching them to `position: fixed` makes them fill the browser
window instead, so a dialog can be centered over the whole page even when the editor
is a small inset. See external-dialog.css.
*/
```

## external-dialog.css

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

--------

# External UI (using context)

Category: Page layout

Keywords: custom ui, toolbar, buttons, context, createcontext, usecontext, onmount, getcurrenttoolid, setcurrenttool, getstylefornextshape, setstylefornextshapes

Control the editor from a toolbar rendered outside the `Tldraw` component, sharing the editor through React context.

UI that lives outside the `Tldraw` component can't use `useEditor()`. This example captures the editor in `onMount`, stores it in state, and then provides it through a React context so any descendant component (here, an `ExternalToolbar` rendered below the canvas) can read it with `useContext`.

The provider only renders once the editor exists, so consumers never have to handle a `null` editor. Compare with the [External UI (using state)](https://tldraw.dev/examples/external-ui) example, which keeps the editor in local state and uses it in the same component.

## 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 ExternalUiContextExample() {
	const [editor, setEditor] = useState<Editor | null>(null)

	return (
		<div style={{ margin: 32, width: 600 }}>
			<div style={{ height: 400 }}>
				<Tldraw
					// [2]
					onMount={(editor) => setEditor(editor)}
					components={{ Toolbar: null }}
				/>
			</div>
			{/* [3] */}
			{editor && (
				<editorContext.Provider value={{ editor }}>
					<ExternalToolbar />
				</editorContext.Provider>
			)}
		</div>
	)
}

// [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={() => {
						// [5]
						editor.run(() => {
							editor.setStyleForNextShapes(GeoShapeGeoStyle, 'oval')
							editor.setCurrentTool('geo')
						})
					}}
				>
					Oval
				</button>
			</div>
		</div>
	)
}

/*

[1]
A React context for the editor. Components outside `Tldraw` can't use `useEditor()`,
so we provide our own.

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

[3]
Only render the provider (and its descendants) once the editor exists, so consumers
never see a null editor.

[4]
Any descendant of the provider can read the editor from context. `useValue` keeps
the active button in sync with the current tool.

[5]
The geo tool creates whichever geo shape is set in `GeoShapeGeoStyle`, so set the
style first, then switch tools. `editor.run` batches the two updates together.
*/
```

## 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: custom ui, toolbar, buttons, state, usestate, onmount, getcurrenttoolid, setcurrenttool, getstylefornextshape, setstylefornextshapes, usevalue

Control the editor from a toolbar rendered outside the `Tldraw` component, holding the editor in React state.

UI that lives outside the `Tldraw` component can't use `useEditor()`, so it needs some other way to reach the editor instance. The simplest option is to capture it in `onMount` and store it in state in the same component that renders `<Tldraw>`.

Here the default toolbar is hidden (`components={{ Toolbar: null }}`) and replaced with three buttons rendered below the canvas. `useValue` keeps the active button in sync with `editor.getCurrentToolId()`, and the buttons call `editor.setCurrentTool()`. Because the editor is `null` until it mounts, the callbacks guard against that.

Try clicking "Oval" and drawing on the canvas. The oval button sets `GeoShapeGeoStyle` before switching to the geo tool, since the geo tool creates whichever geo shape is currently selected in the style.

For a version that distributes the editor through React context, so any descendant component can use it, see the [External UI (using context)](https://tldraw.dev/examples/external-ui-context) example.

## 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]
Components outside `Tldraw` can't use `useEditor()`, so we hold the editor in React
state instead. It's null until the editor mounts.

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

[3]
Read from the editor with `useValue` (so the active button updates when the tool
changes) and call its methods to control it. The callbacks guard against the editor
not being mounted yet.

[4]
The geo tool creates whichever geo shape is set in `GeoShapeGeoStyle` (oval,
rectangle, etc), so set the style first, then switch tools. `editor.run` batches the
two updates together.
*/
```

## 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: tldrawimage, snapshot, display snapshot, read only, getsnapshot, store snapshot, tlstoresnapshot, format, svg, png

Render a store snapshot as a static SVG or PNG image with the `TldrawImage` component.

`TldrawImage` takes a `TLStoreSnapshot` and renders it as an image, with no editor, canvas, or UI. It's a lightweight way to show a read-only preview of a document. Props like `pageId`, `bounds`, `background`, `darkMode`, `padding`, `scale`, and `format` control what gets rendered and how.

This example toggles between an editable `Tldraw` and a `TldrawImage` of the same document. Try editing the drawing, panning or zooming, switching to dark mode, then pressing "Save drawing": the image is regenerated with the editor's current page, viewport bounds, and theme. Use the format dropdown to switch between SVG and PNG output.

## 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>
	)
}

/*
[1]
Pass a `TLStoreSnapshot` to the `snapshot` prop. When the user saves, we grab a fresh
one from the editor with `getSnapshot(editor.store).document`.

[2]
`pageId` picks which page to render. It defaults to the first page, which is why we
capture the editor's current page when leaving edit mode.

[3]
The remaining props control appearance: `background` and `darkMode` match what the
user was looking at, `bounds` renders just the region that was in the viewport, and
`format` chooses between SVG and PNG output.
*/
```

--------

# Signals

Category: Events & effects

Keywords: signals, reactive, track, usevalue, usereactor, state management, side effects, computed, atom

Keep React components and side effects in sync with editor state using `track`, `useValue`, and `useReactor`.

tldraw's editor state is made of signals: every `editor.get...()` call reads one. This example shows
the three main ways to react to them from a component. `track` wraps a component so it re-renders
when any signal it read during render changes. `useValue` subscribes to just the return value of a
function. `useReactor` runs a side effect (here, updating the document title with the shape count)
whenever the signals it reads change.

Try switching tools, zooming, and adding shapes: the panel above the style panel and the browser
tab title both update. The file includes two versions of the panel, one using `track` and one using
`useValue`, that behave the same way.

## 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(function InfoPanel() {
	const editor = useEditor()
	const tool = editor.getCurrentToolId()
	const zoom = editor.getZoomLevel().toFixed(2)

	// [2]
	useReactor(
		'change title',
		() => {
			const shapes = editor.getCurrentPageShapes()
			document.title = `shapes: ${shapes.length}`
		},
		[editor]
	)

	return (
		<div className="tlui-menu" style={{ fontSize: 14, padding: 8 }}>
			<div>tool: {tool}</div>
			<div>zoom: {zoom}</div>
		</div>
	)
})

// [3]
// eslint-disable-next-line @typescript-eslint/no-unused-vars
function AlternativeInfoPanel() {
	const editor = useEditor()
	const tool = useValue('current tool', () => editor.getCurrentToolId(), [editor])
	const zoom = useValue('zoom', () => editor.getZoomLevel().toFixed(2), [editor])

	return (
		<div className="tlui-menu" style={{ fontSize: 14, padding: 8 }}>
			<div>tool: {tool}</div>
			<div>zoom: {zoom}</div>
		</div>
	)
}

const components: TLComponents = {
	SharePanel: InfoPanel,
}

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

/*
tldraw's editor state is built on signals. Any `editor.get...()` call reads a signal, and there
are two ways to make a React component follow those reads.

[1]
`track` wraps a component so that every signal read during render is recorded, and the component
re-renders when any of them change. Here that's the current tool and the zoom level. This panel
is placed in the `SharePanel` slot, above the style panel.

[2]
`useReactor` runs a side effect (rather than a render) whenever the signals it reads change,
throttled to once per animation frame. Here it keeps the document title in sync with the shape
count. `useQuickReactor` is the same but runs synchronously on every change. Both take a deps
array like `useEffect`; the effect is re-created when the deps change.

[3]
`useValue` is the more targeted alternative: pass a name, a function that reads signals, and a
deps array, and the component re-renders only when the function's *return value* changes. This
version of the panel behaves identically to [1]. Prefer `useValue` when you want to pick a few
values out of a component that shouldn't otherwise track everything it touches; `track` is
convenient when the whole component is about editor state.
*/
```

--------

# Canvas events

Category: Events & effects

Keywords: events, pointer events, mouse events, click, keyboard events, canvas events, event listeners, tleventinfo, editor.on

Log the pointer, keyboard, and other input events the editor dispatches to its tools.

The editor is an event emitter. Subscribing to `editor.on('event', handler)` gives you every
`TLEventInfo` the editor processes: pointer, keyboard, wheel, pinch, click, and tick events. This
example keeps the most recent event of each type and shows them on the right-hand side.

Try moving your cursor, dragging, and holding modifier keys, and watch the panel update. These are
input events, not document changes: to see shapes being created or deleted, look at the store events
example, and for high-level UI actions like tool selection, see the UI events example.

## App.tsx

```tsx
import { useCallback, useState } from 'react'
import { TLEventInfo, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import './canvas-events.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>>({})

	// [1]
	const handleEvent = useCallback((data: TLEventInfo) => {
		setEvents((prevEvents) => ({
			...prevEvents,
			[data.type]: {
				...data,
				lastUpdated: Date.now(),
			},
		}))
	}, [])

	const eventsArray = Object.values(events).sort((a, b) => a.lastUpdated - b.lastUpdated)

	return (
		<div className="canvas-events">
			<div className="canvas-events__editor">
				<Tldraw
					onMount={(editor) => {
						// [2]
						editor.on('event', handleEvent)
						return () => {
							editor.off('event', handleEvent)
						}
					}}
				/>
			</div>
			<div className="canvas-events__log" onCopy={(event) => event.stopPropagation()}>
				<pre>{JSON.stringify(eventsArray, undefined, 2)}</pre>
			</div>
		</div>
	)
}

/*
Canvas events are the low-level input events the editor dispatches to its tools: pointer,
keyboard, wheel, pinch, tick and so on. They don't cover document changes like creating or
deleting shapes; for those, see the store events example. For higher-level UI actions like
"zoom in" or "select tool", see the UI events example.

[1]
Pointer moves and ticks fire many times a second, so logging every event would be unreadable.
Instead we keep the latest event of each type, keyed by `type`, and show them ordered by when
they last fired.

[2]
`Editor` is an event emitter. Subscribing to `'event'` gives you every `TLEventInfo` the editor
handles, after its own processing. `onMount` can return a cleanup function, which is the right
place to unsubscribe.
*/
```

## canvas-events.css

```css
.canvas-events {
	display: flex;
}

.canvas-events__editor {
	width: 50%;
	height: 100vh;
}

.canvas-events__log {
	width: 50%;
	height: 100vh;
	padding: 8px;
	background: #eee;
	border-left: solid 2px #333;
	font-family: monospace;
	font-size: 12px;
	display: flex;
	flex-direction: column-reverse;
	overflow: auto;
	white-space: pre-wrap;
}
```

--------

# Store events

Category: Events & effects

Keywords: store, events, listen, changes, transactions, added, updated, removed, tleventmaphandler, subscribe

Listen to store changes and log shape creates, updates, deletes, and page switches.

`editor.store.listen` calls your handler once per transaction with a `HistoryEntry` describing the
records that were added, updated, and removed. This example subscribes from `onMount`, filters to
changes made by the local user, and turns the entries it cares about into readable lines in the
panel on the right.

Try creating and deleting shapes, changing their styles, or switching pages. Store events cover
document changes, not input: for pointer and keyboard events see the canvas events example, and for
high-level UI actions see the UI events example. To react to changes with side effects rather than
just observe them, see the side effects examples.

## App.tsx

```tsx
import { useCallback, useState } from 'react'
import { isEqual, TLEventMapHandler, TLShape, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import './store-events.css'

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

export default function StoreEventsExample() {
	const [storeEvents, setStoreEvents] = useState<string[]>([])

	// [1]
	const handleChangeEvent = useCallback<TLEventMapHandler<'change'>>((change) => {
		const messages: string[] = []

		for (const record of Object.values(change.changes.added)) {
			if (record.typeName === 'shape') {
				messages.push(`created shape (${record.type})`)
			}
		}

		for (const [from, to] of Object.values(change.changes.updated)) {
			if (from.typeName === 'instance' && to.typeName === 'instance') {
				if (from.currentPageId !== to.currentPageId) {
					messages.push(`changed page (${from.currentPageId}, ${to.currentPageId})`)
				}
			} else if (from.typeName === 'shape' && to.typeName === 'shape') {
				messages.push(`updated shape (${describeShapeDiff(from, to)})`)
			}
		}

		for (const record of Object.values(change.changes.removed)) {
			if (record.typeName === 'shape') {
				messages.push(`deleted shape (${record.type})`)
			}
		}

		if (messages.length) {
			setStoreEvents((events) => [...events, ...messages])
		}
	}, [])

	return (
		<div className="store-events">
			<div className="store-events__editor">
				<Tldraw
					onMount={(editor) => {
						// [2]
						return editor.store.listen(handleChangeEvent, { source: 'user', scope: 'all' })
					}}
				/>
			</div>
			<div className="store-events__log" onCopy={(event) => event.stopPropagation()}>
				<pre>{storeEvents.join('\n')}</pre>
			</div>
		</div>
	)
}

// [3]
function describeShapeDiff(from: TLShape, to: TLShape) {
	const changed: string[] = []
	for (const key of Object.keys(to) as (keyof TLShape)[]) {
		if (key === 'props') {
			for (const propKey of Object.keys(to.props)) {
				const a = (from.props as Record<string, unknown>)[propKey]
				const b = (to.props as Record<string, unknown>)[propKey]
				if (!isEqual(a, b)) changed.push(`props.${propKey}: ${JSON.stringify(b)}`)
			}
		} else if (!isEqual(from[key], to[key])) {
			changed.push(`${key}: ${JSON.stringify(to[key])}`)
		}
	}
	return changed.join(', ')
}

/*
Store events tell you what changed in the document: shapes created, updated, or deleted, pages
switched, and so on. They don't include input like pointer and keyboard events; for those, see
the canvas events example.

[1]
The listener receives a `HistoryEntry` for every transaction. Its `changes` is a `RecordsDiff`
with `added`, `updated`, and `removed` maps keyed by record id, and `updated` entries are
`[from, to]` pairs. Records of all types come through here (shapes, pages, the instance record,
camera, and so on), so we check `typeName` and turn the ones we care about into readable lines.

[2]
`editor.store.listen` returns an unsubscribe function, and `onMount` can return a cleanup
function, so returning one from the other is all the wiring needed. The filters restrict this
listener to changes made by the local user (`source: 'user'`, as opposed to `'remote'` changes
arriving from other clients) across all record scopes. Use `scope: 'document'` if you only care
about persisted document content and not things like the camera or selection.

[3]
Compare the two versions of an updated shape and list the top-level and `props` fields that
changed. Nested values like `richText` need a deep comparison, so this uses `isEqual`, which
tldraw re-exports from lodash.
*/
```

## store-events.css

```css
.store-events {
	display: flex;
}

.store-events__editor {
	width: 60%;
	height: 100vh;
}

.store-events__log {
	width: 40%;
	height: 100vh;
	padding: 8px;
	background: #eee;
	border-left: solid 2px #333;
	font-family: monospace;
	font-size: 12px;
	display: flex;
	flex-direction: column-reverse;
	overflow: auto;
}
```

--------

# UI events

Category: Events & effects

Keywords: ui events, onUiEvent, TLUiEventHandler, event logging, keyboard shortcuts, actions, tools, debugging, analytics

Listen to the actions the default UI performs and see which editor API each one calls.

The `onUiEvent` prop of `<Tldraw>` is called for every action the default UI performs, whether it
came from a menu, the toolbar, or a keyboard shortcut. Each event has a name (see `TLUiEventMap`) and
data that includes a `source`. This example logs them on the right-hand side, alongside the editor
API call the UI made for that event, which makes it a useful way to learn the SDK.

Try selecting tools, changing styles, aligning shapes, or using undo/redo. UI events fire only for
UI interactions; calling `editor.alignShapes()` yourself won't trigger one. For pointer and keyboard
input see the canvas events example, and for document changes see the store events example.

## App.tsx

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

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

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

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

	return (
		<div className="ui-events">
			<div className="ui-events__editor">
				{/* [2] */}
				<Tldraw onUiEvent={handleUiEvent} />
			</div>
			<div className="ui-events__log" onCopy={(event) => event.stopPropagation()}>
				{uiEvents.map((t, i) => (
					<pre key={i}>{t}</pre>
				))}
			</div>
		</div>
	)
}

/*
UI events are the high-level actions the default UI performs: selecting a tool, grouping
shapes, zooming, toggling grid mode, and so on. They fire whichever way the action was
triggered (menu, toolbar, or keyboard shortcut) and each comes with a `source` telling you
which. They don't fire when you call the same editor methods yourself. For the full list, see
the `TLUiEventMap` type; for `source` values, see `TLUiEventSource`.

[1]
The handler receives the event name and its data. This example also shows the editor API call
that the default UI made for the event (see `codeSnippets.ts`), which is a handy way to learn
which method does what.

[2]
Pass the handler to the `onUiEvent` prop of `<Tldraw>`. Since it's called for every UI action,
this is a good hook for analytics.

To listen to input events or document changes instead, see the canvas events and store events
examples.
*/
```

## codeSnippets.ts

```ts
// Maps UI event names to the editor API call that the default UI makes for them. This is only
// for display: the events are already handled by the time `onUiEvent` fires. Not every event
// has a one-line equivalent; those return an empty string. See `TLUiEventMap` for the full list.

const STYLE_PROPS: Record<string, string> = {
	'tldraw:color': 'DefaultColorStyle',
	'tldraw:labelColor': 'DefaultLabelColorStyle',
	'tldraw:dash': 'DefaultDashStyle',
	'tldraw:fill': 'DefaultFillStyle',
	'tldraw:font': 'DefaultFontStyle',
	'tldraw:horizontalAlign': 'DefaultHorizontalAlignStyle',
	'tldraw:verticalAlign': 'DefaultVerticalAlignStyle',
	'tldraw:textAlign': 'DefaultTextAlignStyle',
	'tldraw:size': 'DefaultSizeStyle',
	'tldraw:geo': 'GeoShapeGeoStyle',
	'tldraw:arrowKind': 'ArrowShapeKindStyle',
	'tldraw:arrowheadStart': 'ArrowShapeArrowheadStartStyle',
	'tldraw:arrowheadEnd': 'ArrowShapeArrowheadEndStyle',
	'tldraw:spline': 'LineShapeSplineStyle',
}

const REORDER_METHODS: Record<string, string> = {
	toFront: 'bringToFront',
	forward: 'bringForward',
	backward: 'sendBackward',
	toBack: 'sendToBack',
}

const SELECTION_METHODS: Record<string, string> = {
	'group-shapes': 'groupShapes',
	'ungroup-shapes': 'ungroupShapes',
	'delete-shapes': 'deleteShapes',
	'toggle-lock': 'toggleLock',
	'distribute-shapes': 'distributeShapes',
	'align-shapes': 'alignShapes',
	'stretch-shapes': 'stretchShapes',
	'flip-shapes': 'flipShapes',
	'stack-shapes': 'stackShapes',
}

const USER_PREF_TOGGLES: Record<string, string> = {
	'toggle-snap-mode': 'isSnapMode',
	'toggle-wrap-mode': 'isWrapMode',
	'toggle-dynamic-size-mode': 'isDynamicSizeMode',
	'toggle-paste-at-cursor': 'isPasteAtCursorMode',
	'toggle-keyboard-shortcuts': 'areKeyboardShortcutsEnabled',
	'toggle-invert-zoom': 'isZoomDirectionInverted',
	'toggle-reduce-motion': 'animationSpeed',
	'toggle-edge-scrolling': 'edgeScrollSpeed',
}

const INSTANCE_STATE_TOGGLES: Record<string, string> = {
	'toggle-transparent': 'exportBackground',
	'toggle-tool-lock': 'isToolLocked',
	'toggle-focus-mode': 'isFocusMode',
	'toggle-grid-mode': 'isGridMode',
	'toggle-debug-mode': 'isDebugMode',
}

const ZOOM_METHODS: Record<string, string> = {
	'zoom-in': 'zoomIn',
	'zoom-out': 'zoomOut',
	'reset-zoom': 'resetZoom',
	'zoom-to-fit': 'zoomToFit',
	'zoom-to-selection': 'zoomToSelection',
}

export function getCodeSnippet(name: string, data: any): string {
	switch (name) {
		case 'set-style':
			if (data.id === 'opacity') {
				return `editor.setOpacityForSelectedShapes(${data.value}); editor.setOpacityForNextShapes(${data.value})`
			}
			return `editor.setStyleForSelectedShapes(${STYLE_PROPS[data.id] ?? '?'}, '${data.value}'); editor.setStyleForNextShapes(${STYLE_PROPS[data.id] ?? '?'}, '${data.value}')`
		case 'select-tool':
			if (data.id === 'media') return 'insertMedia()'
			if (data.id.startsWith('geo-')) {
				const geo = data.id.replace('geo-', '')
				return `editor.setStyleForNextShapes(GeoShapeGeoStyle, '${geo}'); editor.setCurrentTool('geo')`
			}
			return `editor.setCurrentTool('${data.id}')`
		case 'rotate-ccw':
		case 'rotate-cw':
			return 'editor.rotateShapesBy(editor.getSelectedShapeIds(), <radians>)'
		case 'reorder-shapes':
			return `editor.${REORDER_METHODS[data.operation] ?? '?'}(editor.getSelectedShapeIds())`
		case 'stack-shapes':
			return `editor.stackShapes(editor.getSelectedShapeIds(), '${data.operation}', editor.options.adjacentShapeMargin)`
		case 'pack-shapes':
			return `editor.packShapes(editor.getSelectedShapeIds(), editor.options.adjacentShapeMargin)`
		case 'duplicate-shapes':
			return `editor.duplicateShapes(editor.getSelectedShapeIds(), { x: <number>, y: <number> })`
		case 'select-all-shapes':
			return `editor.selectAll()`
		case 'select-none-shapes':
			return `editor.selectNone()`
		case 'export-as':
			return `exportAs(editor, editor.getSelectedShapeIds(), { format: '${data.format}' })`
		case 'copy-as':
			return `copyAs(editor, editor.getSelectedShapeIds(), { format: '${data.format}' })`
		case 'undo':
		case 'redo':
			return `editor.${name}()`
		case 'cut':
		case 'copy':
			return `const { ${name} } = useMenuClipboardEvents(); ${name}()`
		case 'paste':
			return `const { paste } = useMenuClipboardEvents(); navigator.clipboard.read().then(paste)`
		case 'print':
			return 'printSelectionOrPages()'
		case 'stop-following':
			return `editor.stopFollowingUser()`
		case 'exit-pen-mode':
			return `editor.updateInstanceState({ isPenMode: false })`
		case 'remove-frame':
			return `removeFrame(editor, editor.getSelectedShapeIds())`
		case 'fit-frame-to-content':
			return `fitFrameToContent(editor, editor.getOnlySelectedShape().id)`
		case 'unlock-all':
			return `editor.updateShapes(editor.getCurrentPageShapes().filter((s) => s.isLocked).map((s) => ({ id: s.id, type: s.type, isLocked: false })))`
		case 'color-scheme':
			return `editor.user.updateUserPreferences({ colorScheme: '${data.value}' })`
	}

	if (name in SELECTION_METHODS) {
		const operation = data.operation !== undefined ? `, '${data.operation}'` : ''
		return `editor.${SELECTION_METHODS[name]}(editor.getSelectedShapeIds()${operation})`
	}

	if (name in ZOOM_METHODS) {
		const point =
			name === 'zoom-in' || name === 'zoom-out' || name === 'reset-zoom' ? 'undefined, ' : ''
		return `editor.${ZOOM_METHODS[name]}(${point}{ animation: { duration: editor.options.animationMediumMs } })`
	}

	if (name in USER_PREF_TOGGLES) {
		return `editor.user.updateUserPreferences({ ${USER_PREF_TOGGLES[name]}: <value> })`
	}

	if (name in INSTANCE_STATE_TOGGLES) {
		const key = INSTANCE_STATE_TOGGLES[name]
		return `editor.updateInstanceState({ ${key}: !editor.getInstanceState().${key} })`
	}

	return ''
}
```

## ui-events.css

```css
.ui-events {
	display: flex;
}

.ui-events__editor {
	width: 60%;
	height: 100vh;
}

.ui-events__log {
	width: 40%;
	height: 100vh;
	padding: 8px;
	background: #eee;
	border-left: solid 2px #333;
	font-family: monospace;
	font-size: 12px;
	overflow: auto;
}

.ui-events__log pre {
	border-bottom: 1px solid #000;
	margin-bottom: 0;
	padding-bottom: 12px;
	white-space: pre-wrap;
}
```

--------

# Block events

Category: Events & effects

Keywords: event, block, pointer-events, overlay, infrontofthecanvas, user-select

Overlay UI on the canvas that captures pointer events instead of passing them through.

The `InFrontOfTheCanvas` component slot renders a full-size layer over the canvas with
`pointer-events: none`, so anything you put there is click-through by default. To make part of it
interactive, set `pointer-events: all` on that element. The slot sits above the canvas and marks
pointer events that start inside it as handled, so tldraw won't select, draw, or pan in response.

Try clicking and dragging inside the box, then outside it. The box also sets `user-select: text` on
its paragraph, since tldraw turns text selection off inside its container by default.

## App.tsx

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

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

function WelcomeScreen() {
	return (
		// [1]
		<div className="event-blocker__backdrop">
			{/* [2] */}
			<div className="event-blocker__panel">
				{/* [3] */}
				<p>
					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="event-blocker-example" components={components} />
		</div>
	)
}

/*
[1]
The `InFrontOfTheCanvas` slot is a full-size layer over the canvas that starts with
`pointer-events: none`, so anything rendered here is click-through by default. This
backdrop just centers the panel; pointer events pass straight through it to the canvas.

[2]
Setting `pointer-events: all` on the panel opts it back in. The slot sits above the canvas
and marks pointer events that start inside it as handled (see `editor.markEventAsHandled`),
so tldraw ignores them: clicking or dragging here won't select, draw, or pan. You don't need
to call `stopPropagation` yourself.

[3]
tldraw disables text selection everywhere inside its container so that dragging on the
canvas doesn't highlight text. If you want the user to be able to select text in your
overlay, set `user-select: text` on it.
*/
```

## event-blocker.css

```css
.event-blocker__backdrop {
	position: absolute;
	inset: 0;
	display: flex;
	align-items: center;
	justify-content: center;
}

.event-blocker__panel {
	pointer-events: all;
	width: 400px;
	padding: 32px;
	border-radius: 20px;
	box-shadow: 2px 2px 12px rgba(0, 0, 0, 0.2);
	background-color: white;
}

.event-blocker__panel p {
	user-select: text;
}
```

--------

# Prevent instance changes

Category: Events & effects

Keywords: instance state, prevent change, registerbeforechangehandler, side effects, grid mode, isgridmode, validation, state protection

Reject changes to the instance record that would turn grid mode off.

Side effects aren't just for shapes: you can register handlers for any record type in the store.
This example registers a `registerBeforeChangeHandler` for the `instance` record and returns the
previous record whenever the incoming change has `isGridMode: false`, which cancels the change.

Try toggling the grid from the main menu or with the keyboard shortcut: it stays on. Rejecting a
change this way is silent, so if the change came from a user action you may want to
explain why nothing happened. To reject only some fields of a change while keeping the rest, return
a merged record instead of `prev`.

## App.tsx

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

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

					// Returning `prev` rejects the change no matter where it came from: menu, shortcut, or code.
					editor.sideEffects.registerBeforeChangeHandler('instance', (prev, next) => {
						if (!next.isGridMode) {
							return prev
						}
						return next
					})
				}}
			/>
		</div>
	)
}
```

--------

# Prevent shape changes

Category: Events & effects

Keywords: prevent transform, lock shape, registerbeforechangehandler, side effects, immutable shape, disable move, disable resize, disable rotate, shape protection

Reject changes to a shape's position, rotation, and size while still allowing style and text edits.

`editor.sideEffects.registerBeforeChangeHandler` sees every proposed shape change and returns the
record that will be written. This example compares `prev` and `next` for geo rectangles and returns
`prev` (cancelling the change) if `x`, `y`, `rotation`, `props.w`, or `props.h` would differ. Other
changes pass through untouched.

Try dragging, rotating, or resizing the rectangle: nothing happens. Now change its color or edit its
label: that works. This is a finer-grained alternative to `isLocked`, which would also stop the shape
being selected. A rejected change is silent, so consider giving the user some feedback if
this is a real permission rule.

## App.tsx

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

export default function PreventShapeChangeExample() {
	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"),
						},
					})

					// Unlike locking the shape, rejecting transforms here leaves it selectable and editable.
					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>
	)
}
```

--------

# Prevent multi-shape selection

Category: Events & effects

Keywords: selection, single selection, prevent multi-select, instance page state, registerbeforechangehandler, selectedshapeids, selection control

Limit the selection to a single shape by rewriting selection changes in a before-change handler.

The current selection is stored on the `instance_page_state` record as `selectedShapeIds`. This
example registers a `registerBeforeChangeHandler` for that record and, whenever an incoming change
would select more than one shape, returns a copy with only the last id. Since every selection
method writes to the same record, one handler covers shift-click, brush selection, select all, and
`editor.select()` calls from your own code.

Try creating a few shapes and shift-clicking or dragging a selection box over them: only one ends up
selected. Rewriting the change instead of rejecting it (by returning `prev`) means the user's action
still does something sensible.

## App.tsx

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

export default function PreventMultiShapeSelectionExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// Rewriting to the last id (rather than rejecting) keeps brushing and select-all usable.
					editor.sideEffects.registerBeforeChangeHandler('instance_page_state', (prev, next) => {
						if (
							prev.selectedShapeIds !== next.selectedShapeIds &&
							next.selectedShapeIds.length > 1
						) {
							return {
								...next,
								selectedShapeIds: [next.selectedShapeIds[next.selectedShapeIds.length - 1]],
							}
						}
						return next
					})
				}}
			/>
		</div>
	)
}
```

--------

# Before create/update shape

Category: Events & effects

Keywords: side effects, registerbeforecreatehandler, registerbeforechangehandler, intercept, validation, lifecycle, hooks, shape creation

Intercept shapes before they're created or updated and keep them inside a circle.

`editor.sideEffects.registerBeforeCreateHandler` and `registerBeforeChangeHandler` run before a
record is written to the store. Whatever the handler returns is what gets written, so you can
adjust (or reject, by returning the previous record) a change instead of reacting to it afterwards.
In this example, both handlers run the same function that pulls a shape's origin back inside a
circle around the page origin.

Try drawing shapes and dragging them out past the circle: they stop at the edge. The camera is
locked on the circle so the constraint is easy to see. For the "after" side of this API, see the
after create/update shape example.

## App.tsx

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

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

const RADIUS = 500

// [1]
function constrainShapeToRadius(editor: Editor, shape: TLShape, radius: number) {
	if (isShapeId(shape.parentId)) return shape

	const shapePoint = Vec.From(shape)
	const distanceFromCenter = shapePoint.len()

	if (distanceFromCenter > radius) {
		const newPoint = shapePoint.uni().mul(radius)
		return {
			...shape,
			x: newPoint.x,
			y: newPoint.y,
		}
	}

	return shape
}

export default function BeforeCreateUpdateShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [2]
					editor.sideEffects.registerBeforeCreateHandler('shape', (shape) => {
						return constrainShapeToRadius(editor, shape, RADIUS)
					})
					editor.sideEffects.registerBeforeChangeHandler('shape', (_prevShape, nextShape) => {
						return constrainShapeToRadius(editor, nextShape, RADIUS)
					})

					// [3]
					editor.zoomToBounds(new Box(-RADIUS, -RADIUS, RADIUS * 2, RADIUS * 2))
					editor.setCameraOptions({ isLocked: true })
				}}
				components={{
					OnTheCanvas: () => (
						<SVGContainer>
							<circle cx={0} cy={0} r={RADIUS} fill="none" stroke="black" />
						</SVGContainer>
					),
				}}
			/>
		</div>
	)
}

/*
[1]
Returns a copy of the shape whose x/y origin is within `radius` of the page origin, or the
same shape if it's already inside (or if it's parented to another shape rather than the page,
since a child's x/y are relative to its parent, not the page). Note that this constrains the
shape's origin, not its whole bounds, so shapes can still poke out past the circle.

[2]
Before-create and before-change handlers run before the record is written to the store, and
whatever they return is what gets written. That lets us adjust a shape on its way in instead
of reacting after the fact. Registering the same function for both means the constraint holds
for newly drawn shapes as well as shapes being dragged, resized, or pasted.

[3]
Lock the camera on the constrained area so it's obvious what's happening. The camera lock
isn't part of the side effect; it's just for the demo.
*/
```

--------

# Before delete shape

Category: Events & effects

Keywords: side effects, registerbeforedeletehandler, intercept, prevent deletion, lifecycle, hooks, validation

Intercept shape deletions and cancel the ones you don't want to allow.

`editor.sideEffects.registerBeforeDeleteHandler` runs before a record is removed from the store.
Return `false` to cancel the deletion; return nothing to let it proceed. In this example, red shapes
can't be deleted but everything else can.

Try selecting each text shape and pressing delete. The red one stays put, whether you delete it
directly, select all and delete, or cut it. This only guards deletions: the user can still
recolor the shape and then delete it.

## 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) => {
					editor.sideEffects.registerBeforeDeleteHandler('shape', (shape) => {
						if ('color' in shape.props && shape.props.color === 'red') {
							return false
						}
						return
					})

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

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, override, statenode, select tool, method replacement, handleDoubleClickOnCanvas, getStateDescendant, runtime, idle state, createTextOnCanvasDoubleClick

Replace what happens when the user double-clicks on empty canvas by patching the select tool's `Idle` state at runtime.

By default, double-clicking on empty canvas creates a text shape and starts editing it. That
behavior lives in the `handleDoubleClickOnCanvas` method of the select tool's `Idle` state. This
example uses `editor.getStateDescendant('select.idle')` from `onMount` to grab that state and
replace the method with one that shows an alert.

Try double-clicking on the canvas. Double-clicking an editable shape still edits it as usual, but
double-clicking a shape that can't be edited falls through to the same method, so it shows the
alert too.

**This example is hacky.** Patching a built-in state's method is a lightweight way to tweak one
behavior without writing a whole custom tool, but `handleDoubleClickOnCanvas` is not public API and
can be renamed or removed in any release. If you only want to disable the default, pass
`options={{ createTextOnCanvasDoubleClick: false }}` to `<Tldraw>` instead. If you need different
behavior, write a custom select tool.

## App.tsx

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

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

// [1]
type IdleStateNode = StateNode & {
	handleDoubleClickOnCanvas(info: TLClickEventInfo): void
}

export default function CustomDoubleClickBehaviorExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [2]
					const selectIdleState = editor.getStateDescendant<IdleStateNode>('select.idle')
					if (!selectIdleState) throw Error('SelectTool Idle state not found')

					// [3]
					selectIdleState.handleDoubleClickOnCanvas = function (_info: TLClickEventInfo) {
						window.alert('double clicked on the canvas')
					}
				}}
			/>
		</div>
	)
}

/*
The select tool's `Idle` state calls `handleDoubleClickOnCanvas` when the user double-clicks
on empty canvas (or on a shape that can't be edited). By default it creates a text shape and
starts editing it. Here we swap that method out at runtime for one that shows an alert.

[1]
The `Idle` class itself isn't exported from `tldraw`, and `handleDoubleClickOnCanvas` isn't
part of the public `StateNode` type, so we describe the shape we expect and cast to it.

[2]
`editor.getStateDescendant` walks the tool state tree by dotted path: `'select'` is the
select tool, `'select.idle'` is its idle child state. Because tools are singletons created
when the editor mounts, `onMount` is a safe place to patch them.

[3]
Assigning a `function` (rather than an arrow function) means `this` inside it is the state
node, the same as it would be for the original method. This replaces the default behavior
entirely; if you want to extend it instead, keep a reference to the original method and call
it from your replacement.

If all you want is to turn the default off, there's a simpler route: pass
`options={{ createTextOnCanvasDoubleClick: false }}` to `<Tldraw>`.
*/
```

--------

# After create/update shape

Category: Events & effects

Keywords: side effects, registeraftercreatehandler, registerafterchangehandler, lifecycle, hooks, shape creation, shape update

Run a handler after shapes are created or updated to keep only one red shape on the page.

`editor.sideEffects.registerAfterCreateHandler` and `registerAfterChangeHandler` run after a
record has been written to the store. That makes them the right place to update _other_ records in
response to a change. Here, whenever a shape is created or changed and it turns out to be red, every
other red shape on the same page is turned black.

Try selecting one of the black words and setting its color to red in the style panel: the previously
red word turns black. Because after-change handlers also fire for the updates they cause, make sure
your handler is a no-op for records that already satisfy your rule, or it will loop.

## App.tsx

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

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

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

// [1]
function ensureOnlyOneRedShape(editor: Editor, shapeId: TLShapeId) {
	const shape = editor.getShape(shapeId)!
	if (!isRedShape(shape)) return

	const pageId = editor.getAncestorPageId(shape.id)!

	const otherRedShapesOnPage = Array.from(editor.getPageShapeIds(pageId))
		.map((id) => editor.getShape(id)!)
		.filter(
			(otherShape): otherShape is ShapeWithColor =>
				otherShape.id !== shape.id && isRedShape(otherShape)
		)

	editor.updateShapes(
		otherRedShapesOnPage.map(
			(shape) =>
				({
					id: shape.id,
					type: shape.type,
					props: { color: 'black' },
				}) as TLShapePartial // [2]
		)
	)
}

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) => {
					// [3]
					editor.sideEffects.registerAfterCreateHandler('shape', (shape) => {
						ensureOnlyOneRedShape(editor, shape.id)
					})
					editor.sideEffects.registerAfterChangeHandler('shape', (_prevShape, nextShape) => {
						ensureOnlyOneRedShape(editor, nextShape.id)
					})

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

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

/*
[1]
If the given shape is red, turn every other red shape on the same page black. Not every
shape type has a `color` prop (images and videos don't, for example), so we check for it
before reading it.

[2]
`ShapeWithColor` is a union of every shape type with a `color` prop, and TypeScript can't
narrow `{ type: shape.type, props: { color } }` back to one member of that union, so we assert
the partial. Each shape's `type` still comes from the shape itself, so the update is well formed.

[3]
Because `updateShapes` here triggers the after-change handler again for the shapes it turns
black, the check has to be a no-op for non-red shapes or it would loop forever.
*/
```

--------

# After delete shape

Category: Events & effects

Keywords: side effects, registerafterdeletehandler, lifecycle, hooks, shape deletion, frames, parent shapes

Run a handler after shapes are deleted to remove frames that have become empty.

`editor.sideEffects.registerAfterDeleteHandler` runs after a record has been removed from the
store, which makes it a good place to clean up anything that depended on that record. In this
example, deleting the last child of a frame deletes the frame too.

Try deleting the shapes inside the frame one by one. Once the last one goes, the frame disappears
with it. The handler also runs for the frame it just deleted, so nested frames cascade: emptying an
inner frame can empty and delete its outer frame too.

## 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) => {
					editor.sideEffects.registerAfterDeleteHandler('shape', (shape) => {
						const parentShape = editor.getShape(shape.parentId)
						if (parentShape && parentShape.type === 'frame') {
							const siblings = editor.getSortedChildIdsForParent(parentShape.id)
							if (siblings.length === 0) {
								editor.deleteShape(parentShape.id)
							}
						}
					})

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

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, registerbeforechangehandler, movement restriction, bounded region, shape geometry, svgcontainer

Keep a shape inside a bounding box by clamping its position in a before-change side effect.

`editor.sideEffects.registerBeforeChangeHandler` sees every proposed change to a shape before it's
written and can return a modified record instead. This example uses that to keep a rectangle inside
a dashed container: whenever the shape's new position would put any of it outside, its `x` and `y`
are clamped back in.

Try dragging the rectangle or nudging it with the arrow keys: it stops at the container edge every
time, because the constraint runs at the store level rather than in any one tool. Inside a
before-change handler the new shape isn't in the store yet, so the example computes geometry with `editor.getShapeUtil(shape).getGeometry(shape)`
rather than the cached `editor.getShapeGeometry`, which would return the old version. This example
only clamps position; resizing past the edge is handled in the permissions 2 example.

## App.tsx

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

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

const CONTAINER_BOUNDS = new Box(100, 100, 400, 300)

// [1]
function constrainShapeToBounds(editor: Editor, shape: TLGeoShape): TLGeoShape {
	const localBounds = editor.getShapeUtil(shape).getGeometry(shape).bounds
	const pageBounds = new Box(
		shape.x + localBounds.x,
		shape.y + localBounds.y,
		localBounds.w,
		localBounds.h
	)

	if (CONTAINER_BOUNDS.contains(pageBounds)) return shape

	// [2]
	return {
		...shape,
		x: clamp(shape.x, CONTAINER_BOUNDS.x - localBounds.x, CONTAINER_BOUNDS.maxX - localBounds.maxX),
		y: clamp(shape.y, CONTAINER_BOUNDS.y - localBounds.y, CONTAINER_BOUNDS.maxY - localBounds.maxY),
	}
}

export default function PermissionsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [3]
					editor.sideEffects.registerBeforeChangeHandler('shape', (_prevShape, nextShape) => {
						if (editor.isShapeOfType<TLGeoShape>(nextShape, 'geo')) {
							return constrainShapeToBounds(editor, nextShape)
						}
						return nextShape
					})

					editor.createShape<TLGeoShape>({
						type: 'geo',
						x: 250,
						y: 200,
						props: { geo: 'rectangle', w: 150, h: 100 },
					})

					editor.zoomToBounds(new Box(0, 0, 600, 500), { animation: { duration: 0 } })
				}}
				components={{
					// [4]
					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]
Work out where the *proposed* shape would sit on the page. Inside a before-change handler the
new shape isn't in the store yet, so cached lookups like `editor.getShapeGeometry(shape)` or
`editor.getShapePageBounds(shape)` would describe the old version. Calling the shape util's
`getGeometry` directly computes from the record we were given.

[2]
Clamp the shape's origin so its bounds stay inside the container. Geometry bounds are in the
shape's local space (for a geo shape they start at 0,0), so we offset by them.

[3]
Before-change handlers run for every shape update, whether it came from dragging, the arrow
keys, alignment actions, or `editor.updateShapes` in your own code. Returning a modified record
is what gets written, so the constraint holds regardless of how the change was made. We only
apply it to geo shapes here.

[4]
Draw the container as a dashed rectangle in page coordinates so it's easy to see. It's purely
visual and takes no part in the constraint.
*/
```

--------

# Permissions 2

Category: Events & effects

Keywords: constraints, bounds, side effects, permissions, clamping, registerbeforechangehandler, movement restriction, bounded region, shape geometry, resize constraint

Keep a shape inside a bounding box when it's moved or resized, using a before-change side effect.

This is a follow-on to the permissions example. That one only clamps a shape's position; here the
`registerBeforeChangeHandler` side effect also clamps its size, so resizing past the container edge
shrinks the shape instead of letting it escape.

Try dragging the rectangle and pulling its resize handles past the dashed border. Because a
before-change handler sees the shape before it's written to the store, cached lookups like
`editor.getShapeGeometry` would return the shape's old size, so the example computes geometry from
the proposed record with `editor.getShapeUtil(shape).getGeometry(shape)`. The size clamp assumes an
unrotated rectangle; rotated shapes would need their page bounds clamped instead.

## App.tsx

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

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

const CONTAINER_BOUNDS = new Box(100, 100, 400, 300)

// [1]
function constrainShapeToBounds(editor: Editor, shape: TLGeoShape): TLGeoShape {
	const localBounds = editor.getShapeUtil(shape).getGeometry(shape).bounds
	const pageBounds = new Box(
		shape.x + localBounds.x,
		shape.y + localBounds.y,
		localBounds.w,
		localBounds.h
	)

	if (CONTAINER_BOUNDS.contains(pageBounds)) return shape

	// [2]
	const w = Math.min(shape.props.w, CONTAINER_BOUNDS.w)
	const h = Math.min(shape.props.h, CONTAINER_BOUNDS.h)

	return {
		...shape,
		x: clamp(shape.x, CONTAINER_BOUNDS.x, CONTAINER_BOUNDS.maxX - w),
		y: clamp(shape.y, CONTAINER_BOUNDS.y, CONTAINER_BOUNDS.maxY - h),
		props: { ...shape.props, w, h },
	}
}

export default function PermissionsExample2() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [3]
					editor.sideEffects.registerBeforeChangeHandler('shape', (_prevShape, nextShape) => {
						if (editor.isShapeOfType<TLGeoShape>(nextShape, 'geo')) {
							return constrainShapeToBounds(editor, nextShape)
						}
						return nextShape
					})

					editor.createShape<TLGeoShape>({
						type: 'geo',
						x: 250,
						y: 200,
						props: {
							geo: 'rectangle',
							w: 150,
							h: 100,
							richText: toRichText('Try to drag or resize me'),
						},
					})

					editor.zoomToBounds(new Box(0, 0, 600, 500), { animation: { duration: 0 } })
				}}
				components={{
					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>
	)
}

/*
This builds on the permissions example, which only clamps position. Here a resize that would
push the shape past the container is clamped too.

[1]
Inside a before-change handler the new shape isn't in the store yet, so cached lookups like
`editor.getShapeGeometry(shape)` or `editor.getShapePageBounds(shape)` describe the *old*
version, which is exactly wrong when the change is a resize. Calling the shape util's
`getGeometry` directly computes bounds from the record we were given.

[2]
Clamp the size to the container first, then clamp the origin so the (possibly shrunk) shape
fits. This uses `props.w`/`props.h` directly, which is fine for an unrotated rectangle whose
geometry starts at its origin. A general solution would clamp the rotated page bounds instead.

[3]
Because the constraint runs at the store level, it applies however the change was made:
dragging, resize handles, arrow keys, alignment actions, or `editor.updateShapes` from your own
code. We only apply it to geo shapes here.
*/
```

--------

# Derived view

Category: Events & effects

Keywords: computed, incremental, derivation, performance, store history, diffsince, reactive, usevalue

Derive a set of draw shape ids from the store incrementally, using the store's change history instead of rescanning every shape.

A `computed` signal can look at what changed since it last ran, rather than recomputing from
scratch. This example builds a reactive set of draw shape ids: on the first run it scans every
shape, and after that it reads `store.history.getDiffSince(lastComputedEpoch)` and only adds or
removes ids for draw shapes that were created or deleted. If nothing relevant changed, it returns
the previous set so nothing downstream re-runs.

The counter at the top of the page reads the set's size with `useValue`. Try drawing a few strokes
and deleting them; moving or restyling shapes leaves the set untouched, so nothing downstream re-runs.
The same pattern works for any expensive derived view of the document.

## App.tsx

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

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

function DrawShapeCounter() {
	const editor = useEditor()

	// [1]
	const drawShapeIds = useMemo(() => deriveDrawShapeIds(editor), [editor])
	const count = useValue('draw shape count', () => drawShapeIds.get().size, [drawShapeIds])

	return (
		<div className="tlui-menu" style={{ padding: '4px 8px' }}>
			{count} draw shapes in document
		</div>
	)
}

const components: TLComponents = {
	TopPanel: DrawShapeCounter,
}

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

// [2]
export function deriveDrawShapeIds(editor: Editor) {
	const { store } = editor
	const shapeIds = store.query.ids('shape')

	function fromScratch() {
		return new Set([...shapeIds.get()].filter((id) => editor.getShape(id)!.type === 'draw'))
	}

	return computed<Set<TLShapeId>>('drawShapeIds', (prevValue, lastComputedEpoch) => {
		// [3]
		if (isUninitialized(prevValue)) {
			return fromScratch()
		}

		// [4]
		const diff = store.history.getDiffSince(lastComputedEpoch)
		if (diff === RESET_VALUE) {
			return fromScratch()
		}

		// [5]
		let nextValue: Set<TLShapeId> | undefined

		for (const changes of diff) {
			for (const record of Object.values(changes.added)) {
				if (isShape(record) && record.type === 'draw') {
					nextValue ??= new Set(prevValue)
					nextValue.add(record.id)
				}
			}

			for (const record of Object.values(changes.removed)) {
				if (isShape(record) && record.type === 'draw') {
					nextValue ??= new Set(prevValue)
					nextValue.delete(record.id)
				}
			}
		}

		// [6]
		return nextValue ?? prevValue
	})
}

/*
Signals let you derive a value from the store and have it stay up to date. The naive way to
count draw shapes is to loop over every shape each time anything changes. That's fine for
small documents, but on large ones it's wasted work: most changes don't touch draw shapes at
all. This example builds a computed set of draw shape ids that updates itself incrementally
from the store's change history.

[1]
The derivation is created once per editor and read with `useValue`. Since `useValue` only
re-renders when the returned value changes, and we return the set's size, moving or restyling
shapes doesn't re-render this component at all.

[2]
`store.query.ids('shape')` is a reactive set of every shape id in the store. We only use it for
the from-scratch pass; the incremental path reads diffs instead.

[3]
The first time a `computed` runs, `prevValue` is a special uninitialized sentinel, so there's
nothing to diff against and we compute from scratch.

[4]
`store.history` is an atom whose value is a change counter and whose diffs are the record
changes between updates. `getDiffSince(lastComputedEpoch)` returns every change since our last
run, or `RESET_VALUE` if the history buffer no longer goes back that far (or the store was
reset), in which case we start over.

[5]
Walk the diffs and only allocate a new set if a draw shape was actually added or removed.
Updates to existing draw shapes don't change membership, so we skip `changes.updated`.

[6]
Returning `prevValue` when nothing changed means downstream signals (and `useValue`) see the
same reference and don't recompute. That's what makes the incremental approach cheap.
*/
```

--------

# Shape meta (on change)

Category: Events & effects

Keywords: meta, metadata, side effects, registerbeforechangehandler, getinitialmeta, onchange, tracking, audit, custom data

Stamp `updatedBy` and `updatedAt` metadata on shapes every time they change.

Every shape has a `meta` property for your own JSON data. This example keeps it up to date with a
`registerBeforeChangeHandler` side effect that rewrites `meta` on every user-initiated shape change,
and replaces `editor.getInitialMetaForShape` so new shapes start with the same fields. A panel at the
top shows the selected shape's meta.

Create a shape, select it, and move or restyle it: the timestamp updates with each change. The
handler ignores changes with `source: 'remote'`, so in a multiplayer document a peer's edits keep
their own author. For setting meta only at creation time, see the shape meta (on create) example.

## App.tsx

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

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

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

function MetaUiHelper() {
	const editor = useEditor()
	// [2]
	const onlySelectedShape = useValue(
		'only selected shape',
		() => editor.getOnlySelectedShape() as ShapeWithMyMeta | null,
		[editor]
	)

	return (
		<pre className="tlui-menu" style={{ margin: 0, padding: 8 }}>
			{onlySelectedShape
				? JSON.stringify(onlySelectedShape.meta, null, '\t')
				: 'Select one shape to see its meta data.'}
		</pre>
	)
}

const components: TLComponents = {
	TopPanel: MetaUiHelper,
}

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

/*
Every shape has a `meta` property for your own JSON data. tldraw stores and syncs it but never
reads it. This example stamps `updatedBy` and `updatedAt` on shapes as they change. See the
shapes docs for more on meta: https://tldraw.dev/docs/shapes#meta

[1]
A shape's `meta` is typed as `JsonObject`. To get useful types for your own fields, intersect
the shape type with the shape of your meta.

[2]
Reading `editor.getOnlySelectedShape()` inside `useValue` re-renders this panel whenever the
selection changes or the selected shape's record changes, which is what makes the meta update
live as you drag.

[3]
`getInitialMetaForShape` is called by `createShapes` for every new shape, and its result is
merged with any `meta` you passed. Replacing it here means new shapes start out with the same
fields the change handler maintains.

[4]
A before-change side effect can return a modified record to be written in place of `next`.
Filtering on `source === 'user'` skips changes that arrived from a remote peer, so in a
multiplayer document you don't overwrite the real author with the local user.
*/
```

--------

# Shape meta (on create)

Category: Events & effects

Keywords: meta, metadata, getinitialmeta, getinitialmetaforshape, oncreate, custom data, usevalue

Record who created each shape and when by replacing `editor.getInitialMetaForShape`.

Every shape has a `meta` property for your own JSON data. When `createShapes` creates a shape it
merges the result of `editor.getInitialMetaForShape(shape)` with whatever `meta` you passed. This
example replaces that method in `onMount` to stamp `createdBy` and `createdAt` on every new shape.
A panel at the top shows the selected shape's meta.

Create a shape and select it to see its meta. Since this only runs at creation, later edits leave
the values alone. To keep meta current as shapes change, see the shape meta (on change) example.

## App.tsx

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

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

// [1]
type ShapeWithMyMeta = TLShape & { meta: { createdBy: string; createdAt: number } }

function MetaUiHelper() {
	const editor = useEditor()
	// [2]
	const onlySelectedShape = useValue(
		'only selected shape',
		() => editor.getOnlySelectedShape() as ShapeWithMyMeta | null,
		[editor]
	)

	return (
		<pre className="tlui-menu" style={{ margin: 0, padding: 8 }}>
			{onlySelectedShape
				? JSON.stringify(onlySelectedShape.meta, null, '\t')
				: 'Select one shape to see its meta data.'}
		</pre>
	)
}

const components: TLComponents = {
	TopPanel: MetaUiHelper,
}

export default function OnCreateShapeMetaExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="meta-on-create-example"
				components={components}
				onMount={(editor) => {
					// [3]
					editor.getInitialMetaForShape = (_shape) => {
						return {
							createdBy: editor.user.getExternalId(),
							createdAt: Date.now(),
						}
					}
				}}
			/>
		</div>
	)
}

/*
Every shape has a `meta` property for your own JSON data. tldraw stores and syncs it but never
reads it. This example records who created each shape and when. See the shapes docs for more on
meta: https://tldraw.dev/docs/shapes#meta

[1]
A shape's `meta` is typed as `JsonObject`. To get useful types for your own fields, intersect
the shape type with the shape of your meta.

[2]
Reading `editor.getOnlySelectedShape()` inside `useValue` re-renders this panel whenever the
selection changes.

[3]
`getInitialMetaForShape` is called by `createShapes` for every new shape. Its result is merged
with any `meta` passed to `createShapes`, with the explicit meta winning. It's a plain method on
the editor, so the simplest way to customize it is to replace it in `onMount`. The shape is
passed in, so you can return different meta for different shape types.
*/
```

--------

# Unsaved changes

Category: Events & effects

Keywords: save, unsaved changes, document changes, store.listen, document scope, RecordsDiff, squashRecordDiffs, persistence, dirty state, getSnapshot

Track unsaved document changes as a squashed diff and enable a save button while there are any.

This example listens to the store with `editor.store.listen(handler, { scope: 'document' })`, so
only changes to persisted document records count, not the camera or selection. Each transaction's
diff is folded into a running `RecordsDiff` with `squashRecordDiffs`, so a shape that's created and
then deleted cancels out and repeated edits collapse into one. The save button in the top panel is
enabled while that diff is non-empty.

Try drawing something: the button lights up. Delete what you drew and it goes back to "No changes",
because the squashed diff is empty again. Clicking save hands the diff and a snapshot from
`editor.getSnapshot()` to a placeholder function and resets the diff.

## App.tsx

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

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

function emptyDiff(): RecordsDiff<TLRecord> {
	return { added: {}, removed: {}, updated: {} }
}

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

	// [1]
	const rUnsavedChanges = useRef<RecordsDiff<TLRecord>>(emptyDiff())

	useEffect(() => {
		const handleDocumentChange: TLEventMapHandler<'change'> = (entry) => {
			squashRecordDiffs([rUnsavedChanges.current, entry.changes], { mutateFirstDiff: true })
			setHasUnsavedChanges(!isDiffEmpty(rUnsavedChanges.current))
		}

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

	// [3]
	const handleSave = useCallback(() => {
		saveChanges(rUnsavedChanges.current, editor.getSnapshot())
		rUnsavedChanges.current = emptyDiff()
		setHasUnsavedChanges(false)
	}, [editor])

	return (
		<div className="tlui-menu">
			<TldrawUiButton type="normal" onClick={handleSave} disabled={!hasUnsavedChanges}>
				{hasUnsavedChanges ? 'Save changes' : 'No changes'}
			</TldrawUiButton>
		</div>
	)
}

function saveChanges(_diff: RecordsDiff<TLRecord>, _snapshot: TLEditorSnapshot) {
	// Send the diff or the snapshot to your server here.
}

function isDiffEmpty(diff: RecordsDiff<TLRecord>) {
	for (const key in diff.added) return false
	for (const key in diff.removed) return false
	for (const key in diff.updated) return false
	return true
}

const components: TLComponents = {
	TopPanel: SaveButton,
}

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

/*
[1]
Rather than a boolean "dirty" flag, we accumulate every change since the last save into a
single `RecordsDiff`. `squashRecordDiffs` folds each new transaction into it, so a shape that
was created and then deleted cancels out, and a shape edited ten times shows up as one update
from its saved state to its current state. Because the squash mutates in place, this lives in
a ref rather than React state; the boolean state is only there to re-render the button.

[2]
`scope: 'document'` limits the listener to records that are part of the persisted document
(shapes, pages, assets, bindings, the document record). Session state like the camera,
selection, and current page still writes to the store but shouldn't count as unsaved work.
`store.listen` returns its unsubscribe function, so it doubles as the effect's cleanup.

[3]
When saving, you have two things to send: the accumulated diff (small, and exactly what
changed) or a full snapshot from `editor.getSnapshot()` (simpler to store and restore). Which
you use depends on your backend. Either way, reset the diff afterwards so it starts tracking
from the newly saved state.
*/
```

--------

# Custom shape wrapper

Category: Shapes & tools

Keywords: ShapeWrapper, DefaultShapeWrapper, wrapper, dom, class names, styling, css, atom, useValue, forwardRef, components

Add a class name to individual shapes by overriding the `ShapeWrapper` component.

Every shape is rendered inside a wrapper element that tldraw positions on the canvas. Passing a component as `components.ShapeWrapper` replaces that element. The custom wrapper here renders `DefaultShapeWrapper` (so positioning still works) and adds a `custom-special-shape` class when the shape's id matches an `atom`. Reading the atom with `useValue` means only the affected wrappers re-render.

A timer moves the "special" status to a random shape every second, so you'll see a red drop shadow jump between the geo shapes. This is useful for styling or tagging shapes from outside the shape util, for example to add data attributes for CSS targeting.

## App.tsx

```tsx
import { forwardRef } from 'react'
import {
	atom,
	DefaultShapeWrapper,
	Editor,
	TLComponents,
	Tldraw,
	TLShapeId,
	TLShapeWrapperProps,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './custom-shape-wrapper.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 CustomShapeWrapperExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				components={components}
				onMount={(editor) => {
					createSomeRandomShapes(editor)

					// [4]
					const timer = editor.timers.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:

Every shape on the canvas is rendered inside a wrapper element that positions it. You can replace
that wrapper with the `ShapeWrapper` component override to add class names, data attributes, or
styling to shapes without changing the shapes themselves. In this example, a red drop shadow moves
to a different random shape every second.

[1]
An atom holds the id of the currently "special" shape. Atoms are tldraw's reactive state
primitive: anything that reads the atom inside a reactive context re-runs when it changes.

[2]
The custom wrapper. It receives the same props as the default wrapper (`shape`, `isBackground`,
`children`) plus a ref that tldraw uses to position the element, so it must forward the ref.

	[a]
	`useValue` reads the atom reactively, so only the wrapper for the shape whose status changed
	re-renders when `specialShapeId` is set.

	[b]
	Rather than reimplementing positioning, we render `DefaultShapeWrapper` and pass an extra
	`className` when this shape is the special one. The class is styled in custom-shape-wrapper.css.

[3]
Pass the wrapper through `components.ShapeWrapper`. Define the object outside the component so it
isn't recreated on every render.

[4]
The interval that picks a new special shape is created with `editor.timers`, so it's cleared
automatically when the editor is disposed; the returned cleanup also runs when the component
unmounts.
*/
```

## custom-shape-wrapper.css

```css
.custom-special-shape {
	filter: drop-shadow(0 0 3px rgba(255, 0, 0));
}
```

--------

# Custom shape

Category: Shapes & tools

Keywords: shapeutil, custom shape, getGeometry, component, indicator, HTMLContainer, Rectangle2d, getDefaultProps, props, validator

Define a minimal custom shape with a `ShapeUtil` and add it to the editor.

A custom shape needs a `ShapeUtil` subclass that declares its `type` and prop validators, returns default props, provides geometry for hit-testing, and renders a React component. Pass the util class to `<Tldraw>` through the `shapeUtils` prop and the editor can create, select, resize, and persist the shape like any built-in one.

This example's shape is a rectangle with some text inside. It extends `ShapeUtil` directly so you can see `getGeometry` and `onResize` written out; extending `BaseBoxShapeUtil` would provide both for a `w`/`h` shape. The shape is created in `onMount`. To add a toolbar tool for creating it, see the custom shape and tool example.

## 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(shape: ICustomShape) {
		return false
	}
	override canResize(shape: ICustomShape) {
		return true
	}
	override isAspectRatioLocked(shape: ICustomShape) {
		return false
	}

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

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

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

	// [g]
	getIndicatorPath(shape: ICustomShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}
}

// [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:

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.

[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 to define methods such as `getGeometry` and `onResize`.

	[a]
	This is where we define our shape's props and type for the editor. It's important to use the same
	string for the type as we did in [1]. We define the shape's props using tldraw's validator
	library, which makes 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. These are the defaults, so you don't
	have to define them; 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. `isFilled: true`
	means clicks inside the rectangle hit the shape, not just clicks on its outline. 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 returning a Path2D for a rectangle
	with the same width and height as the shape. The path is stroked onto the canvas overlay.

[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: statenode, tool, pointer events, onpointerdown, onenter, cursor, createshape, state machine

A minimal custom tool that drops a heart emoji wherever you click.

Tools are nodes in tldraw's state chart and are responsible for handling user input. A custom tool extends `StateNode`, sets a static `id`, and overrides event handlers such as `onEnter` and `onPointerDown`. Pass the class to `<Tldraw>` through the `tools` prop.

The sticker tool here sets a crosshair cursor when it becomes active and creates a text shape at `editor.inputs.getCurrentPagePoint()` on every pointer down. The example hides the UI and starts with the tool selected via `initialState`, so just click anywhere on the canvas. For a tool with child states and drag interactions, see the screenshot tool example; for adding a tool to the toolbar, see the custom shape and tool example.

## 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 example.

	[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 presses on the canvas. We create a
		text shape at the pointer's page-space position, read from `editor.inputs`, offset so
		the emoji is centered under the cursor.

[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: custom tool, statenode, screenshot, export, state machine, child states, brush selection, dragging state, overrides, toolbar, asset urls

A custom tool with child states that exports a dragged-out area of the canvas as a PNG.

Tools are `StateNode`s in tldraw's state chart, and this one has three child states: idle, pointing, and dragging. The dragging state keeps the box being drawn in an atom, which an `InFrontOfTheCanvas` component reads to draw the box over the canvas, and on pointer up it calls `exportAs` (or `copyAs` when ctrl is held) with `bounds` set to the box.

The example also shows the wiring a new tool needs: the `tools` prop, a `TLUiOverrides` entry so the UI knows the tool's label, icon, and shortcut, a custom icon via `assetUrls`, and a `Toolbar` override that adds the item.

Try selecting the screenshot tool (or press J) and dragging over some shapes. Hold shift for a 16:9 box, alt to center it on the start point, and ctrl to copy to the clipboard instead of downloading.

## App.tsx

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

// 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',
		() => {
			if (editor.getPath() !== 'screenshot.dragging') return null

			const draggingState = editor.getStateDescendant<ScreenshotDragging>('screenshot.dragging')!
			const box = draggingState.screenshotBox.get()

			// The box is in page space, but this component sits in front of the canvas in
			// viewport space, so convert it.
			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 `StateNode`. See the ScreenshotTool folder for the
tool itself. The array is defined outside of any React component and passed to the Tldraw
component's `tools` prop.

[2]
Register the tool with the UI by adding it to the `tools` object in a `TLUiOverrides`. This
gives the toolbar (and keyboard shortcuts) the tool's label, icon, shortcut, and what to do
when it's selected. The custom toolbar then places the item in front of the default content.

[3]
The toolbar item uses a custom icon, so we map its icon id to a url via `assetUrls.icons`.

[4]
While the tool's dragging state is active we draw the screenshot box in the
`InFrontOfTheCanvas` slot, which renders over the canvas but under menus and the toolbar. The
box lives in an atom on the dragging state node, so reading it inside `useValue` re-renders
this component as the user drags. `editor.getStateDescendant` finds that node by path.

[5]
All of the customizations are defined outside of the React component so they keep the same
identity across renders; new objects each render would make Tldraw re-register them.
*/
```

## 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', {})
	}
}

/*
[1]
The tool is a `StateNode` with the id "screenshot" and three child states: idle, pointing, and
dragging. `initial` names the child state to enter when the tool is selected.

[2]
Set a crosshair cursor while the tool is active and restore the default on exit.

[3]
Interrupt (e.g. a pinch gesture starts) and cancel (escape) both bail out to the select tool.
`this.parent` is the root state, whose children are the tools.
*/
```

## 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()

		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()) {
				copyAs(
					editor,
					shapes.map((s) => s.id),
					{ format: 'png', bounds: box }
				)
			} else {
				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]
The box the user is dragging out is stored in an atom so the UI can subscribe to it with
`useValue` (see the ScreenshotBox component in ScreenshotToolExample.tsx). A plain field
wouldn't trigger a re-render.

[2]
Recompute the box between the pointer-down origin and the current pointer on enter, on pointer
move, and on key down/up so the modifiers apply immediately: shift locks the box to 16:9 and
alt centers it on the origin at double size.

[3]
On pointer up, export every shape whose (masked) page bounds overlap the box as a PNG
cropped to the box, or copy it to the clipboard when ctrl is held. `exportAs` and `copyAs` are
the same helpers the export menu uses.

[4]
Cancel (escape) abandons the box and returns 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]
On pointer down, hand off to the sibling pointing state. `this.parent` is the screenshot tool.
*/
```

## 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]
`inputs.getIsDragging()` becomes true once the pointer has moved past the drag distance
threshold since pointer down. Until then we stay here, so a plain click never starts a box.

[2]
A pointer up or cancel before the drag threshold is a click, not a screenshot, so go back to idle.
*/
```

--------

# Cubic bezier curve shape

Category: Shapes & tools

Keywords: bezier, curve, handles, control points, shapeutil, editing mode, statenode, getHandles, onHandleDrag, getHandleSnapGeometry, overlay

A cubic bezier curve shape with draggable control point handles.

`BezierCurveShapeUtil` stores four points (start, end, cp1, cp2), builds a `CubicBezier2d` geometry from them, and exposes each point as a handle through `getHandles`. `onHandleDrag` updates the props: dragging an endpoint carries its control point along, and cmd/ctrl + dragging an endpoint moves the control point instead. `getHandleSnapGeometry` lets control points snap onto the endpoints, which collapses that end of the curve into a sharp corner.

The example also keeps the curve in its editing state while you work on it. A custom `ShapeHandleOverlayUtil` shows handles during editing, and `CubicBezierShapeExample.tsx` wraps a few of the select tool's state node handlers so a handle drag returns to `select.editing_shape` rather than `select.idle`. **That part is hacky:** it patches select tool state nodes at runtime, which is not public API and can break between releases. Everything else in the example (the shape util, handles, snapping, overlay util) uses supported APIs.

Try dragging the handles, cmd/ctrl + clicking a control point to collapse it, and cmd/ctrl + dragging the curve itself to bend it.

## App.tsx

```tsx
import {
	createShapeId,
	Tldraw,
	type Editor,
	type StateNode,
	type TLAnyOverlayUtilConstructor,
	type TLAnyShapeUtilConstructor,
	type TLHandle,
	type TLOverlay,
	type TLPointerEventInfo,
	type TLShapeId,
} from 'tldraw'
import { BezierShapeHandleOverlayUtil } from './BezierShapeHandleOverlayUtil'
import { BezierCurveShapeUtil } from './CubicBezierShape'
import { SneakyUndoRedoWhileEditing } from './SneakyUndoRedoWhileEditing'

const customShapes: TLAnyShapeUtilConstructor[] = [BezierCurveShapeUtil]

type ShapeHandleOverlay = TLOverlay<{ shapeId: TLShapeId; handle: TLHandle }>

type PointingHandleState = StateNode & {
	info?: TLPointerEventInfo & { target: 'handle' }
}

function getPointingHandleInfo(
	state: PointingHandleState,
	fallback?: TLPointerEventInfo
): (TLPointerEventInfo & { target: 'handle' }) | undefined {
	if (state.info?.target === 'handle') return state.info
	if (fallback?.target === 'handle') return fallback
	return undefined
}

const customOverlays: TLAnyOverlayUtilConstructor[] = [BezierShapeHandleOverlayUtil]

function startEditingBezierShape(editor: Editor, id: TLShapeId) {
	editor.setEditingShape(id)
	editor.setCurrentTool('select.editing_shape')
}

function getBezierHandleOverlayAtPoint(editor: Editor): ShapeHandleOverlay | null {
	const overlay = editor.overlays.getOverlayAtPoint(
		editor.inputs.getCurrentPagePoint(),
		editor.options.hitTestMargin / editor.getZoomLevel()
	)
	if (!overlay || overlay.type !== 'shape_handle') return null

	const shapeHandleOverlay = overlay as ShapeHandleOverlay
	const shape = editor.getShape(shapeHandleOverlay.props.shapeId)
	if (!shape || !editor.isShapeOfType(shape, 'bezier-curve')) return null

	return shapeHandleOverlay
}

function updateHoveredBezierHandle(editor: Editor) {
	const editingShape = editor.getEditingShape()
	if (!editingShape || !editor.isShapeOfType(editingShape, 'bezier-curve')) return false

	const overlay = getBezierHandleOverlayAtPoint(editor)
	const previousOverlayId = editor.overlays.getHoveredOverlayId()

	if (overlay) {
		editor.overlays.setHoveredOverlay(overlay.id)
		editor.setHoveredShape(null)

		const cursor = editor.overlays.getOverlayUtil(overlay).getCursor(overlay)
		if (cursor) {
			editor.setCursor({ type: cursor, rotation: editor.getSelectionRotation() })
		}

		return true
	}

	if (previousOverlayId) {
		editor.setCursor({ type: 'default', rotation: 0 })
	}

	editor.overlays.setHoveredOverlay(null)
	return false
}

export default function BezierCurveShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				// [1]
				overlayUtils={customOverlays}
				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)
					startEditingBezierShape(editor, id)

					// [2]
					const pointingHandleState =
						editor.getStateDescendant<PointingHandleState>('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')
					}

					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) => {
						const handleInfo = getPointingHandleInfo(pointingHandleState, info)
						if (!handleInfo) {
							originalHandlers.pointingHandle.onPointerUp?.(info)
							return
						}

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

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

									startEditingBezierShape(editor, handleInfo.shape.id)
									return
								}
							}
						}

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

						originalHandlers.pointingHandle.onPointerUp?.(info)
					}

					// return to editing state after dragging a handle
					pointingHandleState.onPointerMove = (info: TLPointerEventInfo) => {
						if (!editor.inputs.getIsDragging()) {
							originalHandlers.pointingHandle.onPointerMove?.(info)
							return
						}

						const handleInfo = getPointingHandleInfo(pointingHandleState, info)
						if (!handleInfo) {
							originalHandlers.pointingHandle.onPointerMove?.(info)
							return
						}

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

						originalHandlers.pointingHandle.onPointerMove?.(info)
					}

					editingShapeState.onPointerDown = (info: TLPointerEventInfo) => {
						const editingShape = editor.getEditingShape()
						if (editingShape && editor.isShapeOfType(editingShape, 'bezier-curve')) {
							const overlay = getBezierHandleOverlayAtPoint(editor)

							if (overlay) {
								editor.setCurrentTool('select.pointing_handle', {
									...info,
									target: 'handle',
									shape: editingShape,
									handle: overlay.props.handle,
								})
								return
							}
						}

						originalHandlers.editingShape.onPointerDown?.(info)
					}

					// allow translating in editing state
					editingShapeState.onPointerMove = (info: TLPointerEventInfo) => {
						if (updateHoveredBezierHandle(editor) && !editor.inputs.getIsDragging()) return

						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: () => {
										startEditingBezierShape(editor, editingShape.id)
									},
								})
								return
							}
						}

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

/*
Introduction:
This example creates a cubic bezier curve shape with draggable handles. The shape itself lives
in CubicBezierShape.tsx; this file wires up the editor so the curve stays in its editing state
while its handles are dragged.

[1]
The default shape handle overlay only shows handles in select.idle and select.pointing_handle.
BezierShapeHandleOverlayUtil replaces it (same `type`, 'shape_handle') and also shows handles
for bezier curves while they're being edited or while a handle is being dragged, so the handles
don't disappear mid-interaction. Other shapes fall through to the default behaviour.

[2]
The select tool's child states normally return to select.idle after a handle drag, which would
end editing. Rather than fork the whole select tool, we grab the state nodes with
`getStateDescendant` and wrap their event handlers, delegating back to the originals for any
shape that isn't a bezier curve. The wrapped handlers add three interactions:
1. Cmd/ctrl + click on a cp1/cp2 handle collapses it onto its start/end point.
2. After dragging any handle, return to select.editing_shape instead of select.idle.
3. Dragging the curve itself while editing translates it, then returns to editing.
Patching state nodes like this is a workaround, not a supported API: it depends on the select
tool's internal state ids and event flow.

[3]
Undo/redo shortcuts are ignored while a shape is being edited, because for text shapes the text
editor owns them. SneakyUndoRedoWhileEditing listens for cmd/ctrl+z at the window level and
restores the editing shape afterwards. It's a hack, but a small one.
*/
```

## BezierShapeHandleOverlayUtil.ts

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

export class BezierShapeHandleOverlayUtil extends ShapeHandleOverlayUtil {
	static override type = 'shape_handle'

	override isActive(): boolean {
		const editor = this.editor
		const onlySelectedShape = editor.getOnlySelectedShape()

		if (!onlySelectedShape || !editor.isShapeOfType(onlySelectedShape, 'bezier-curve')) {
			return super.isActive()
		}

		if (editor.getIsReadonly() || editor.getInstanceState().isChangingStyle) return false
		if (!editor.getShapeHandles(onlySelectedShape)) return false

		if (editor.isInAny('select.pointing_handle', 'select.dragging_handle')) return true

		return (
			editor.getEditingShapeId() === onlySelectedShape.id && editor.isIn('select.editing_shape')
		)
	}
}
```

## 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 isCtrlKeyOnTranslateStart = 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 newProps: Partial<MyBezierCurveShape['props']> = {}

		// cmd/ctrl + drag on start or end moves that endpoint's control point instead
		if (this.editor.inputs.getCtrlKey()) {
			switch (id) {
				case 'start': {
					return {
						...shape,
						props: {
							...shape.props,
							cp1: { x, y },
						},
					}
				}
				case 'end': {
					return {
						...shape,
						props: {
							...shape.props,
							cp2: { x, y },
						},
					}
				}
			}
		}

		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 as 'cp1' | 'cp2']: { x, y },
				}
				break
			}
		}

		return {
			...shape,
			props: {
				...shape.props,
				...newProps,
			},
		}
	}

	// [8]
	override onTranslateStart(shape: MyBezierCurveShape) {
		// sample the meta key once here so the curve doesn't start bending if the user presses
		// cmd/ctrl partway through a plain translation
		this.isCtrlKeyOnTranslateStart = this.editor.inputs.getCtrlKey()

		// bend only when the drag started on the curve itself, not on the start or end handle
		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) {
		if (this.isCtrlKeyOnTranslateStart && 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>
		)
	}

	getIndicatorPath(shape: MyBezierCurveShape) {
		const path = this.getGeometry(shape).getSvgPathData(true)
		return new Path2D(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]
Extend TLGlobalShapePropsMap to add our shape's props to the global type system: the four points
that define the curve.

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

[3]
BezierCurveShapeUtil extends ShapeUtil directly (rather than BaseBoxShapeUtil) because the shape has
no width and height props; its bounds come from the curve. `vecModelValidator` validates each point.

[4]
getGeometry returns a CubicBezier2d, which the editor uses for hit-testing, bounds, and snapping.
Because it isn't filled, clicking inside the curve's bounds but away from the line doesn't hit it.

[5]
Four handles: start, end, cp1, and cp2. A control point handle is hidden when it sits exactly on
its endpoint (a "collapsed" corner). `snapType: 'align'` lets a handle snap into alignment with the
snap points returned from [6].

[6]
getHandleSnapGeometry controls what handles snap to. `points` are what other shapes' handles snap
to; `getSelfSnapPoints` returns what this shape's own handles snap to. Control points snap to the
endpoints so you can collapse them by dragging, and endpoints snap to each other. The snap manager
handles zoom-independent thresholds and draws the snap indicators.

[7]
onHandleDrag returns the updated shape:
- Cmd/ctrl + drag on start/end moves that endpoint's control point (cp1 or cp2) instead.
- Dragging start/end also carries its control point along, so the curve keeps its shape.
- Dragging cp1/cp2 moves only that control point.

[8]
onTranslateStart and onTranslate implement "bending": cmd/ctrl + drag on the curve itself moves both
control points together instead of moving the shape. Whether to bend is decided once in
onTranslateStart, based on where the drag started and whether cmd/ctrl was down.

[9]
The component draws the curve, plus dashed lines from start→cp1 and end→cp2 while the shape is
being edited or a handle is being dragged. Stroke widths are divided by the zoom level so they stay
one screen pixel wide.
*/
```

## 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: shapeutils, tools, toolbar, custom tool, custom shape, icon, overrides, card, statenode, keyboard shortcut, migrations

Register a custom shape and a tool that creates it, with a toolbar button and keyboard shortcut.

The card shape is defined by `CardShapeUtil` (rendering, geometry, resizing, props validation, and migrations) and created by `CardShapeTool`, which extends `BaseBoxShapeTool` to get click-and-drag creation for free. Both are passed to `<Tldraw>` through the `shapeUtils` and `tools` props.

The `ui-overrides.tsx` file adds the tool to the UI: the `tools` override registers it with an icon, label, and the `c` shortcut, and the custom `Toolbar` and `KeyboardShortcutsDialog` components place it alongside the defaults.

Select the card tool in the toolbar (the ⚫️ icon) or press `c`, then click or drag on the canvas to create a card. The card's button counts clicks to show that ordinary React state works inside a shape component.

## 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}
				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.tsx for more info on how to add your icon to the toolbar.

[1]
We define arrays to hold the custom shape util and custom tool. It's important to do this outside of
any React component so that the arrays don'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

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	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.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, which
add our new tool in front of the existing default content.
*/
```

## CardShapeTool.tsx

```tsx
import { BaseBoxShapeTool } from 'tldraw'
export class CardShapeTool extends BaseBoxShapeTool {
	static override id = 'card'
	static override initial = 'idle'
	override shapeType = 'card' as const
}

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

We get click-to-create and drag-to-create for free by extending BaseBoxShapeTool, but we
could 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.
*/
```

## CardShapeUtil.tsx

```tsx
import { useState } from 'react'
import {
	HTMLContainer,
	Rectangle2d,
	ShapeUtil,
	TLDefaultColorStyle,
	TLResizeInfo,
	TLShape,
	getColorValue,
	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 { editor } = this
		const bounds = editor.getShapeGeometry(shape).bounds
		const theme = editor.getCurrentTheme()
		const colors = theme.colors[editor.getColorMode()]
		const { color } = shape.props

		//[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(colors, color, 'semi'),
					color: getColorValue(colors, 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]
	getIndicatorPath(shape: ICardShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}

	// [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 whether the shape's aspect ratio is locked and whether it
can be resized. These are the defaults, shown here so you know they exist.

[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. The colors come from the editor's current theme so the card follows dark mode.

- [a] Check it out! We can do normal React stuff here like using useState.

- [b] You need to stop the pointer down event on buttons, otherwise the editor will
	   think you're trying to select or drag the shape.

[7]
getIndicatorPath — returns a Path2D used when hovering over the shape or when it's selected.
The path is stroked onto the canvas overlay.

[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',
	{
		AddColor: 1,
	}
)

// Migrations for the custom card shape (optional but very helpful)
export const cardShapeMigrations = createShapePropsMigrationSequence({
	sequence: [
		{
			id: versions.AddColor,
			up(props) {
				// it is safe to mutate the props object here
				props.color = 'black'
			},
			down(props) {
				delete props.color
			},
		},
	],
})
```

## 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.
```

--------

# Shape with onClick

Category: Shapes & tools

Keywords: onClick, custom shape, click handler, drag

Handle clicks on a custom shape with `ShapeUtil.onClick`.

Implement `onClick` on your shape util to react when the user clicks the shape. The select tool calls it on pointer up when the pointer didn't drag; return a shape partial and the editor applies it (and skips selecting the shape), or return nothing to fall through to normal selection.

Unlike a React `onClick` on a DOM element inside the shape component, `ShapeUtil.onClick` goes through the editor's event system, so clicking and dragging both work on selected and unselected shapes. Try clicking the shape to bump the counter, then dragging it.

## App.tsx

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

// [1]
const customShapeUtils = [ClickableShapeUtil]

// [2]
export default function ShapeWithOnClickExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				onMount={(editor) => {
					editor.createShape({
						type: 'clickable',
						x: 200,
						y: 200,
					})
				}}
			/>
		</div>
	)
}

/*
[1]
We define the custom shape utils array outside of the component so it doesn't get recreated
on every render.

[2]
We pass our custom shape util to the Tldraw component and create an initial shape on mount
so there's something to interact with right away.

Try it:
- Click the shape to increment the counter
- Drag the shape to move it
- Both work whether or not the shape is selected
*/
```

## ClickableShapeUtil.tsx

```tsx
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape, TLShapePartial } from 'tldraw'

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

const CLICKABLE_SHAPE_TYPE = 'clickable'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[CLICKABLE_SHAPE_TYPE]: { w: number; h: number; count: number }
	}
}

type ClickableShape = TLShape<typeof CLICKABLE_SHAPE_TYPE>

// [2]
export class ClickableShapeUtil extends BaseBoxShapeUtil<ClickableShape> {
	static override type = CLICKABLE_SHAPE_TYPE
	static override props: RecordProps<ClickableShape> = {
		w: T.number,
		h: T.number,
		count: T.number,
	}

	getDefaultProps(): ClickableShape['props'] {
		return {
			w: 200,
			h: 100,
			count: 0,
		}
	}

	// [3]
	override onClick(shape: ClickableShape): TLShapePartial<ClickableShape> | void {
		return {
			id: shape.id,
			type: shape.type,
			props: {
				count: shape.props.count + 1,
			},
		}
	}

	// [4]
	component(shape: ClickableShape) {
		return (
			<HTMLContainer
				style={{
					backgroundColor: '#f0e6ff',
					border: '2px solid #9b59b6',
					display: 'flex',
					alignItems: 'center',
					justifyContent: 'center',
					fontSize: 18,
					fontWeight: 'bold',
					color: '#333',
				}}
			>
				Clicks: {shape.props.count}
			</HTMLContainer>
		)
	}

	// [5]
	getIndicatorPath(shape: ClickableShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}
}

/*
This example shows how to use ShapeUtil.onClick to handle clicks on a custom shape.

[1]
Extend TLGlobalShapePropsMap to register the shape's props. We include a `count` prop
that tracks how many times the shape has been clicked.

[2]
Our shape util class. We extend BaseBoxShapeUtil which provides getGeometry (a filled
rectangle from w/h), onResize, and snap geometry for free.

[3]
The onClick handler is the key part of the example. The select tool calls it on pointer
up when the user clicks the shape without dragging. If it returns a shape partial, the
editor applies it and skips selecting the shape; return nothing to fall through to the
normal selection behavior.

This is different from a React onClick on a DOM element inside the component: those
elements sit under the editor's pointer handling (HTMLContainer has pointer-events: none),
so a React handler would also need pointer-events: all and would fight with dragging.
ShapeUtil.onClick goes through the editor's event system, so click and drag coexist.

[4]
The component renders the click count. There are no React event handlers here; the click
handling is done entirely through ShapeUtil.onClick above.

[5]
getIndicatorPath returns a Path2D that tldraw strokes onto the canvas overlay as the
blue outline when the shape is selected.
*/
```

--------

# Shape with onDoubleClickEdge

Category: Shapes & tools

Keywords: onDoubleClickEdge, custom shape, resize, edge, double click

Toggle a custom shape between two sizes with `ShapeUtil.onDoubleClickEdge`.

Implement `onDoubleClickEdge` on your shape util to react when the user double-clicks one of the four edge resize handles (top, right, bottom, left) of a selected shape. Return a shape partial to update the shape, or nothing to fall through to the default double-click behavior. Corners have a matching `onDoubleClickCorner` handler.

Select the shape and double-click one of its edges: it toggles between 400×320 and 200×200.

## App.tsx

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

// [1]
const customShapeUtils = [ResizableShapeUtil]

// [2]
export default function ShapeWithOnDoubleClickEdgeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				onMount={(editor) => {
					editor.createShape({
						type: 'resizable',
						x: 200,
						y: 200,
					})
				}}
			/>
		</div>
	)
}

/*
[1]
We define the custom shape utils array outside of the component so it doesn't get
recreated on every render.

[2]
We pass our custom shape util to the Tldraw component and create an initial shape
on mount so there's something to interact with right away.

Try it:
- Select the shape, then double-click one of its edge resize handles
- The shape toggles between 400×320 and 200×200
*/
```

## ResizableShapeUtil.tsx

```tsx
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape, TLShapePartial } from 'tldraw'

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

const RESIZABLE_SHAPE_TYPE = 'resizable'

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

type ResizableShape = TLShape<typeof RESIZABLE_SHAPE_TYPE>

export class ResizableShapeUtil extends BaseBoxShapeUtil<ResizableShape> {
	static override type = RESIZABLE_SHAPE_TYPE
	static override props: RecordProps<ResizableShape> = {
		w: T.number,
		h: T.number,
	}

	getDefaultProps(): ResizableShape['props'] {
		return {
			w: 400,
			h: 320,
		}
	}

	// [2]
	override onDoubleClickEdge(shape: ResizableShape): TLShapePartial<ResizableShape> | void {
		const isAtSmallSize = shape.props.w === 200 && shape.props.h === 200
		return {
			id: shape.id,
			type: shape.type,
			props: isAtSmallSize ? { w: 400, h: 320 } : { w: 200, h: 200 },
		}
	}

	component(shape: ResizableShape) {
		return (
			<HTMLContainer
				style={{
					backgroundColor: '#e6f0ff',
					border: '2px solid #3b82f6',
					display: 'flex',
					alignItems: 'center',
					justifyContent: 'center',
					fontSize: 16,
					fontWeight: 'bold',
					color: '#1e3a8a',
					textAlign: 'center',
					padding: 8,
				}}
			>
				{shape.props.w} × {shape.props.h}
			</HTMLContainer>
		)
	}

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

/*
This example shows how to use ShapeUtil.onDoubleClickEdge to handle double-clicks
on a shape's resize edge.

[1]
Extend TLGlobalShapePropsMap to register the shape's props. We just need width
and height for this example.

[2]
The select tool calls onDoubleClickEdge when the user double-clicks one of the
selected shape's edge resize handles (top, right, bottom, left); corners go to
onDoubleClickCorner instead. We return a shape partial that toggles the shape
between two preset sizes. The editor marks a history stopping point and applies
the partial, so the toggle is a single undo step. Return nothing to fall through
to the default double-click behavior (starting to edit, if the shape allows it).
*/
```

--------

# Custom shape with custom styles

Category: Shapes & tools

Keywords: custom styles, styleprop, defineenum, style panel, defaultstylepanel, userelevantsstyles, setstyleforselectedshapes, shapeutil

Define your own style with `StyleProp.defineEnum` and expose it in the style panel.

Styles are shape props that the editor tracks across selections: the style panel shows the shared value of every selected shape, and new shapes pick up the most recently used value. This example defines a custom "rating" style, uses it as a prop on a custom shape, and adds a dropdown for it to the default style panel using `useRelevantStyles` and `editor.setStyleForSelectedShapes`.

Select the shapes and change the rating in the style panel. Try selecting both shapes at once to see the "mixed" state.

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,
	TLComponents,
	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
		}
	}
}

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

// [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>
		)
	}

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

// [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) => {
							const value = myRatingStyle.validate(+e.currentTarget.value)
							editor.run(() => {
								editor.markHistoryStoppingPoint()
								editor.setStyleForSelectedShapes(myRatingStyle, value)
								editor.setStyleForNextShapes(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>
	)
}

// [7]
const shapeUtils = [MyShapeUtil]
const components: TLComponents = {
	StylePanel: CustomStylePanel,
}

export default function ShapeWithCustomStylesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				onMount={(editor) => {
					// [8]
					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 custom style. For more on custom
shapes, see the custom shape example.

[1]
Our custom shape uses a new style called "rating". We create it with
StyleProp.defineEnum so that it has a fixed set of values and a default. The
id ('example:rating') must be unique across all styles in the editor.

[2]
Extract the type of the style's values so we can use it in the shape's props.

[3]
Pass the style as one of the shape's props. Any prop whose validator is a
StyleProp is treated as a style: the editor tracks it across selections and
shows it in the style panel.

[4]
Because this prop is a style, whatever value we put here in the default
props is overwritten when a shape is created: the editor uses its "style for
next shape" value instead, which is either the style's default value or the
value the user most recently set. This is special behavior just for styles.

[5]
Inside the component we read the style just like any other prop.

[6]
A custom style panel that renders the default style panel content plus a
dropdown for the rating style. useRelevantStyles returns the styles shared by
the selected shapes (or the current tool), and each entry is either a shared
value or 'mixed'. editor.setStyleForSelectedShapes writes the new value to
every selected shape, and editor.setStyleForNextShapes remembers it for shapes
created afterwards, which is what the default style panel does too. For more
on customizing the style panel, see the stroke size picker example.

[7]
Define shapeUtils and components outside the React component so they aren't
recreated on every render.

[8]
We create two shapes. The first does not specify a rating, so it gets the
editor's current value for the style, which is the style's default of 1 (not
the 4 in getDefaultProps, see [4]). The second specifies a rating of 5, so it
uses that value.
*/
```

--------

# Custom shape with tldraw styles

Category: Shapes & tools

Keywords: default styles, defaultsizestyle, defaultcolorstyle, style panel, getcurrenttheme, getcolorvalue, shapeutil

Use tldraw's built-in size and color styles as props on a custom shape.

The default style panel shows the styles shared by your selection or current tool. If all selected shapes have the same value for a style, that value is shown as selected; otherwise the panel shows it as "mixed". You get this for free on custom shapes by using tldraw's `StyleProp`s (here `DefaultSizeStyle` and `DefaultColorStyle`) as prop validators.

Select the shape and change the size and color in the style panel. The shape reads the color from the current theme with `editor.getCurrentTheme()` and `getColorValue`, so it also follows dark mode.

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,
} 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!

// [1]
const FONT_SIZES: Record<TLDefaultSizeStyle, number> = {
	s: 1.125,
	m: 1.5,
	l: 2.25,
	xl: 2.75,
}

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',
		}
	}

	// [3]
	component(shape: IMyShape) {
		const theme = this.editor.getCurrentTheme()
		const colors = theme.colors[this.editor.getColorMode()]

		return (
			<HTMLContainer
				id={shape.id}
				style={{ backgroundColor: 'var(--tl-color-low-border)', overflow: 'hidden' }}
			>
				<div
					style={{
						fontSize: theme.fontSize * FONT_SIZES[shape.props.size],
						color: getColorValue(colors, shape.props.color, 'solid'),
					}}
				>
					Select the shape and use the style panel to change the font size and color
				</div>
			</HTMLContainer>
		)
	}

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

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 the custom shape example.

[1]
Style values are just strings like 's' or 'black'; it's up to the shape to
decide what they mean. Here we map each size to a multiplier of the theme's
base font size (theme.fontSize is 16px in the default theme), so text scales
with custom themes. Any mapping works; these happen to match tldraw's own text
shape.

[2]
For the shape's props, we use the DefaultSizeStyle and DefaultColorStyle
StyleProps for the size and color properties. Because the validators are
StyleProps, the editor treats these props as styles: the style panel shows
them for this shape, and new shapes pick up the most recently used values.
(You can use the useRelevantStyles hook to get the styles of the user's
selected shapes in your own UI.)

[3]
Inside the component we read the styles to change how the shape looks. We get
the color from the editor's current theme via editor.getCurrentTheme() and
getColorValue, which resolves the color name for the current light or dark
mode. Reading the theme here is reactive, so the shape re-renders when the
theme or color mode changes.
*/
```

--------

# Clickable custom shape

Category: Shapes & tools

Keywords: interaction, pointer events, stop propagation, click, input, button, checkbox, todo, html, custom shape, onclick

A todo shape with a checkbox and text input that handle their own pointer events.

By default the editor handles all pointer events on the canvas, so clicking a shape selects it and dragging moves it. To let part of a shape handle its own interactions, set `pointer-events: all` on the shape's `HTMLContainer` and call `stopPropagation()` on the events you want to keep from reaching the canvas.

Try clicking the checkbox to toggle the todo and typing in the input. Once a todo is checked, the input becomes read-only and lets pointer events through, so clicking it selects the shape as usual. See `my-interactive-shape-util.tsx` for 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]

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]
The shape util array is defined outside the component so it keeps the same identity across
renders. See my-interactive-shape-util.tsx for the shape itself, which shows how to let a
shape handle its own pointer events (a checkbox and a text input) without the editor
selecting or dragging it.
*/
```

## 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>
		)
	}

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

/*
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] Shape containers have `pointer-events: none` by default so the canvas receives every
	pointer event. Set it to `all` (or `auto`) to opt in to receiving events on the shape's HTML.

	[b] Stop propagation so the editor doesn't select or start dragging the shape when the
	checkbox is clicked. The canvas container forwards the events it receives on to the editor,
	so stopping them here keeps them from reaching the canvas.

	[c] While the todo is unchecked, the text input handles its own pointer events. Once it's
	checked the input is read-only, so we let the events through to the canvas and the shape
	selects and drags as usual.

*/
```

--------

# Custom handle snap reference

Category: Shapes & tools

Keywords: handles, snapping, snapReferenceHandleId, angle snapping, shift modifier, getHandles, control points, vertex, reference point

Choose which handle a shift-drag angle snap is measured from with `snapReferenceHandleId`.

When a user holds shift while dragging a handle, the select tool snaps the handle to 15 degree increments around a reference handle. By default that reference is the next vertex handle in index order. Setting `snapReferenceHandleId` on a handle returned from `getHandles` overrides the reference.

The Y-shaped connector here has a center junction and three arms. Each arm handle names `center` as its snap reference, so shift-dragging an arm rotates it around the junction in clean angles instead of around a neighbouring arm.

The shape is selected on load so its handles are visible. Try shift-dragging one of the arm endpoints, then compare with a plain drag.

## App.tsx

```tsx
import {
	Edge2d,
	Geometry2d,
	Group2d,
	HTMLContainer,
	RecordProps,
	ShapeUtil,
	TLHandle,
	TLHandleDragInfo,
	TLShape,
	Tldraw,
	Vec,
	VecLike,
	ZERO_INDEX_KEY,
	createShapeId,
	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],
				snapReferenceHandleId: 'center',
			},
			{
				id: 'armRight',
				type: 'vertex',
				x: shape.props.armRight.x,
				y: shape.props.armRight.y,
				index: indices[3],
				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 },
			},
		}
	}

	// [7]
	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>
		)
	}

	getIndicatorPath(shape: YShape) {
		const { center, armTop, armLeft, armRight } = shape.props
		const path = new Path2D()
		path.moveTo(center.x, center.y)
		path.lineTo(armTop.x, armTop.y)
		path.moveTo(center.x, center.y)
		path.lineTo(armLeft.x, armLeft.y)
		path.moveTo(center.x, center.y)
		path.lineTo(armRight.x, armRight.y)
		return path
	}
}

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

					const id = createShapeId()
					editor.createShape({
						id,
						type: Y_SHAPE_TYPE,
						x: centerX - 100,
						y: centerY - 100,
					})
					editor.select(id)
				}}
			/>
		</div>
	)
}

/*
The shape is a Y-shaped connector: three arms radiating from a center junction point.

When you hold shift while dragging a handle, the editor snaps the handle's angle to 15 degree
increments, measured from a reference handle. By default the reference is the next vertex handle
in index order, which for a shape like this would be a neighbouring arm rather than the junction.
`snapReferenceHandleId` lets each arm name the center as its reference instead.

[1]
Extend TLGlobalShapePropsMap to add our shape's props to the global type system: four points
representing the junction and the three arm endpoints.

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

[3]
The shape util, with `vecModelValidator` for each point. Selection bounds, resize handles, and
the rotate handle are hidden because the handles are the whole interface for this shape.

[4]
The geometry is a Group2d containing three Edge2d segments from the center to each arm, so
hit-testing follows the lines rather than the bounding box.

[5]
Four handles in index order: [center, armTop, armLeft, armRight]. `getIndicesAbove` generates
fractional index keys after ZERO_INDEX_KEY so the handles have a well-defined order.

[6]
Each arm sets `snapReferenceHandleId: 'center'`. Shift + drag any arm and its angle snaps
relative to the junction. Try removing the property from one arm and shift-dragging it: the
angle then snaps relative to whichever vertex handle comes next in index order.

[7]
The component draws the three arms as SVG lines.
*/
```

--------

# Custom shape with handles

Category: Shapes & tools

Keywords: handles, custom handles, gethandles, onhandledrag, interaction, geometry, tail, shapeutil, tool

A speech bubble shape whose tail is moved with a custom handle.

Handles let the user change a shape's geometry directly. This shape returns a single handle for its tail from `getHandles`, updates the tail in `onHandleDrag`, and uses `onBeforeUpdate` to keep the tail a sensible length and outside the bubble body no matter how the shape changes. The tail is stored as a fraction of the shape's size so it scales with drag-create and resize.

Pick the speech bubble tool from the toolbar (or press S), draw a bubble, then drag the tail handle around. Double-click to add text and watch the body grow to fit.

## 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 className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				tools={tools}
				overrides={uiOverrides}
				assetUrls={customAssetUrls}
				components={components}
				persistenceKey="speech-bubble-example"
			/>
		</div>
	)
}

/*
Use handles when you want user interaction to alter the geometry of a shape. Here a speech bubble
has a handle on the tail so the user can move it. Most of the interesting code is in
SpeechBubbleUtil.tsx and helpers.tsx.

[1]
The custom shape util and tool arrays are defined outside of any React component so they don't get
redefined on every render. See SpeechBubbleUtil.tsx and SpeechBubbleTool.tsx for the definitions.

[2]
We pass the shape util and tool into the Tldraw component's `shapeUtils` and `tools` props, plus the
UI overrides, components, and asset urls that add the tool to the toolbar with its own icon. See
ui-overrides.tsx for details.
*/
```

## customhandles.css

```css
/* Resize handles are normally on top, but we want the tail handle to win when they overlap */
.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'
	override shapeType = 'speech-bubble' as const
}

/*
The speech bubble tool is a StateNode with the id "speech-bubble". Extending BaseBoxShapeTool gives
us click-to-create and drag-to-create of a `shapeType` shape for free. For a tool with more custom
behavior, see the screenshot tool example.
*/
```

## SpeechBubbleUtil.tsx

```tsx
import {
	DefaultColorStyle,
	DefaultFontStyle,
	DefaultHorizontalAlignStyle,
	DefaultSizeStyle,
	DefaultVerticalAlignStyle,
	Geometry2d,
	PlainTextLabel,
	Polygon2d,
	RecordPropsType,
	ShapeUtil,
	T,
	TLDefaultSizeStyle,
	TLHandle,
	TLHandleDragInfo,
	TLResizeInfo,
	TLShape,
	Vec,
	ZERO_INDEX_KEY,
	getColorValue,
	getFontFamily,
	resizeBox,
	structuredClone,
	vecModelValidator,
} from 'tldraw'
import { getSpeechBubbleVertices, getTailIntersectionPoint } from './helpers'

const LABEL_FONT_SIZES: Record<TLDefaultSizeStyle, number> = {
	s: 1.125,
	m: 1.375,
	l: 1.625,
	xl: 2,
}

const TEXT_PROPS = {
	fontWeight: 'normal',
	fontVariant: 'normal',
	fontStyle: 'normal',
	padding: '0px',
}

const SPEECH_BUBBLE_TYPE = 'speech-bubble'

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[SPEECH_BUBBLE_TYPE]: SpeechBubbleShapeProps
	}
}

// Stroke width multipliers per size, applied to the theme's base stroke width
const STROKE_SIZES: Record<TLDefaultSizeStyle, number> = {
	s: 1,
	m: 1.75,
	l: 2.5,
	xl: 5,
}

// 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 canEdit(shape: SpeechBubbleShape) {
		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()
		const theme = this.editor.getCurrentTheme()
		const colors = theme.colors[this.editor.getColorMode()]

		return (
			<>
				<svg className="tl-svg-container">
					<path
						d={pathData}
						strokeWidth={theme.strokeWidth * STROKE_SIZES[size]}
						stroke={getColorValue(colors, color, 'solid')}
						fill={'none'}
					/>
				</svg>
				<PlainTextLabel
					shapeId={id}
					type={type}
					fontFamily={getFontFamily(theme, font)}
					textWidth={shape.props.w}
					fontSize={theme.fontSize * LABEL_FONT_SIZES[size]}
					lineHeight={theme.lineHeight}
					textAlign={align as 'start' | 'center' | 'end'}
					verticalAlign="start"
					text={text}
					labelColor={getColorValue(colors, color, 'solid')}
					isSelected={isSelected}
					wrap
				/>
			</>
		)
	}

	getIndicatorPath(shape: SpeechBubbleShape) {
		const vertices = getSpeechBubbleVertices(shape)
		const pathData = 'M' + vertices[0] + 'L' + vertices.slice(1) + 'Z'
		return new Path2D(pathData)
	}

	override onResize(shape: SpeechBubbleShape, info: TLResizeInfo<SpeechBubbleShape>) {
		return resizeBox(shape, info)
	}

	getGrowY(shape: SpeechBubbleShape, prevGrowY = 0) {
		const PADDING = 17

		const theme = this.editor.getCurrentTheme()
		const nextTextSize = this.editor.textMeasure.measureText(shape.props.text, {
			...TEXT_PROPS,
			lineHeight: theme.lineHeight,
			fontFamily: getFontFamily(theme, shape.props.font),
			fontSize: theme.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,
			},
		}
	}
}

/*
This file contains the speech bubble shape util. Most of the logic that makes the tail behave
lives in the onBeforeUpdate handler [6]: because the tail is driven by a handle, we constrain it
there so every way of changing the shape (dragging the handle, resizing, editing text) keeps the
tail in a sensible place.

[1]
Extend TLGlobalShapePropsMap to add our shape's props to the global type system. The tail is a
VecModel.

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

[3]
The shape's props with a validator for each key. Using tldraw's StyleProps (DefaultSizeStyle,
DefaultColorStyle, DefaultFontStyle, and the align styles) here is what makes those options show
up in the style panel for this shape; add 'dash' or 'fill' the same way if you want them.

[4]
Default props. The tail is stored as a fraction of the shape's width and height rather than in
pixels, so it scales correctly when the shape is drag-created or resized. The rest of the util
converts between the normalized tail and shape space as needed.

[5]
`getHandles` returns the handles to show when the shape is selected: just the tail here. Handle
positions are in shape space, so we scale the normalized tail up. `onHandleDrag` does the reverse
when the handle moves.

[6]
onBeforeUpdate runs on every change to the shape. We use it to keep the tail at a sensible
distance from the body: pushed outside if it was dragged inside, and clamped between a minimum
and maximum length. It also recomputes `growY` so the body grows to fit the text. See helpers.tsx
for the geometry.
*/
```

## helpers.tsx

```tsx
import { Vec, intersectLineSegmentLineSegment, invLerp, lerp, pointInPolygon } from 'tldraw'
import { SpeechBubbleShape } from './SpeechBubbleUtil'

export function 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

	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

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

/**
 * 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',
	},
}

// [3]
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 adds the speech bubble tool to the toolbar and the keyboard shortcuts dialog.

[1]
The `tools` override registers the tool item with the UI: its icon, label, keyboard shortcut,
and what happens when it's selected.

[2]
The tool item uses a custom icon, so we provide its url through the Tldraw component's
`assetUrls` prop. The key must match the `icon` on the tool item.

[3]
We replace the toolbar and keyboard shortcuts dialog with versions that render our tool item
alongside the default content. Here it's added at the start; you can place it anywhere among
the default items instead.
*/
```

--------

# Custom tool with child states

Category: Shapes & tools

Keywords: custom tool, state machine, StateNode, child states, tool states, onPointerDown, onPointerMove, onEnter, transitions, pointing, dragging, idle

Split a custom tool into idle, pointing, and dragging child states to tell clicks from drags.

Tools are `StateNode`s in tldraw's state machine. Once a tool needs to distinguish a click from a drag, or a click on empty canvas from a click on a shape, giving it child states keeps each piece of behavior in the state that owns it: `Idle` decides what the user is doing, `Pointing` waits to see whether a drag starts, and `Dragging` updates the shape. `this.parent.transition()` moves between them and passes data to the next state's `onEnter`.

This builds on the [custom tool example](https://tldraw.dev/examples/custom-tool). Instructions for what to try are drawn on the canvas.

## App.tsx

```tsx
import {
	StateNode,
	TLClickEventInfo,
	TLPointerEventInfo,
	TLShape,
	TLShapeId,
	Tldraw,
	createShapeId,
	toRichText,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

const OFFSET = -12
const EMOJIS = ['❤️', '🔥', '👍', '👎', '😭', '🤣']

// [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: TLShape | null = null

	// [a]
	override onEnter(info: { shape: TLShape | null }) {
		this.shape = info.shape
	}
	// [b]
	override onPointerUp() {
		this.parent.transition('idle')
	}
	// [c]
	override onPointerMove() {
		if (this.editor.inputs.getIsDragging()) {
			this.parent.transition('dragging', { shape: this.shape })
		}
	}
}

// [4]
class Dragging extends StateNode {
	static override id = 'dragging'
	private shapeId: TLShapeId | null = null

	// [a]
	override onEnter(info: { shape: TLShape | null }) {
		if (info.shape) {
			this.shapeId = info.shape.id
			return
		}
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		this.shapeId = createShapeId()
		this.editor.createShape({
			id: this.shapeId,
			type: 'text',
			x: currentPagePoint.x + OFFSET,
			y: currentPagePoint.y + OFFSET,
			props: { richText: toRichText('❤️') },
		})
	}
	// [b]
	override onPointerUp() {
		this.parent.transition('idle')
	}
	// [c]
	override onPointerMove() {
		if (!this.shapeId) return
		const originPagePoint = this.editor.inputs.getOriginPagePoint()
		const currentPagePoint = this.editor.inputs.getCurrentPagePoint()
		const distance = originPagePoint.dist(currentPagePoint)
		this.editor.updateShape({
			id: this.shapeId,
			type: 'text',
			props: {
				richText: toRichText(EMOJIS[Math.floor(distance / 20) % EMOJIS.length]),
			},
		})
	}
}

// [5]
const customTools = [StickerTool]
export default function ToolWithChildStatesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				tools={customTools}
				initialState="sticker"
				hideUi
				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>
	)
}

/*
Tools are nodes in tldraw's state machine and handle user input. A tool with a single state
quickly turns into a tangle of flags once it has to tell clicks apart from drags. Child states
solve that: each state handles the events that matter to it and transitions to the next. This
example expands on the sticker tool from the custom tool example.

[1]
The tool declares its child states with `children()` and which one to start in with
`initial`. Events are delivered to the current child state, not to the tool itself.

[2]
Idle is the initial state. Its job is to work out what the user is trying to do and hand off
to the right state. `this.parent.transition(id, info)` switches states; `info` is passed to
the new state's `onEnter`.

	[a] Set the cursor on entering. Every child state receives `onEnter`.

	[b] Because this tool has no shape-level hit testing of its own, the pointer event's
	target is always 'canvas'. We use `editor.getShapeAtPoint` to check for a shape under
	the pointer and re-dispatch the event with `target: 'shape'` so one switch handles both
	cases. Shift-clicking a shape updates it in place; otherwise we go to Pointing.

	[c] Double clicks arrive with a `phase`; we only act on 'up' so the action runs once.
	Double-clicking empty canvas creates a sticker; double-clicking a sticker deletes it.

[3]
Pointing is a transitional state between pointer down and either pointer up (a click) or a
drag.

	[a] Remember which shape (if any) was under the pointer.

	[b] Pointer up without dragging means it was a click; go back to Idle.

	[c] `editor.inputs.getIsDragging()` becomes true once the pointer has moved past the drag
	threshold, so we don't start dragging on a tiny wobble.

[4]
Dragging updates the sticker while the pointer moves.

	[a] If we're dragging an existing sticker, keep its id. Otherwise create a new one at the
	pointer. We store the id rather than the shape record so we always read fresh data.

	[b] Pointer up ends the drag; back to Idle.

	[c] Cycle through the emojis based on how far the pointer has moved from where the drag
	started (`getOriginPagePoint`).

[5]
Pass the tool to `Tldraw` and start in it with `initialState`. For this demo we hide the UI
and put some instructions on the canvas.
*/
```

--------

# Editable custom shape

Category: Shapes & tools

Keywords: editing, canedit, double click, interactive, emoji picker, shape state, editing state

A custom shape that becomes interactive when you double-click it.

The editor has at most one editing shape at a time. While a shape is being edited it can't be dragged, resized, or rotated, and pointer events reach its content. Only shapes whose util returns true from `canEdit` can enter this state; the user gets there by double-clicking the shape or selecting it and pressing Enter, and leaves it with Escape or by clicking the canvas.

The default shapes mostly use editing for text, but it's a general mechanism. This example's shape shows an emoji, and while editing it shows a button that cycles to the next emoji with `editor.updateShape`. The component reads `editor.getEditingShapeId()` to decide what to render, turns on `pointerEvents` only while editing, and marks pointer-down events as handled so clicking the button doesn't start a drag. `onEditEnd` spins the shape when editing finishes.

Try double-clicking the shape, clicking Next a few times, then pressing Escape. The relevant code is in `EditableShapeUtil.tsx`; for a walkthrough of the shape util basics, see 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(shape: IMyEditableShape) {
		return true
	}

	// [1b]
	override canEditWhileLocked(shape: IMyEditableShape) {
		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>
		)
	}

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

	// [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] canEditWhileLocked allows the shape to be edited even when it is locked.
		This is useful for shapes that should stay put but remain interactive.

[2]
The component renders differently depending on whether the shape is being edited.

	[a] Reading `getEditingShapeId()` inside the component is reactive, so the
		shape re-renders when it enters or leaves the editing state.

	[b] While editing, we turn on pointer events and mark pointer-down events as
		handled with `editor.markEventAsHandled` so the editor doesn't start a
		drag or selection when the user clicks the button. Check out the
		interactive shape example for more on this.

	[c] The button cycles through the emojis with `editor.updateShape`.

	[d] When not editing, we show a hint instead of the button.

[3]
The onEditEnd method is called when the shape exits the editing state. In this
case we spin the shape 360 degrees with `animateShape`.
*/
```

--------

# Flex layout shape

Category: Shapes & tools

Keywords: custom shape, flexbox, layout, frame, children, BaseFrameLikeShapeUtil

A frame-like shape that lets the browser's flexbox engine arrange its children.

The layout shape extends `BaseFrameLikeShapeUtil`, so it clips its children and reparents shapes in and out as they're dragged over it, like a frame. What's different is how children get positioned: the shape renders a hidden flex container with a placeholder div per child, and a `ResizeObserver` reads each placeholder's offset and writes it back to the child's `x`/`y`. A contextual toolbar exposes the flex direction, `justify-content`, and `align-items` for the selected layout.

The layout grows to fit its children. Dragging a shape over it shows an insertion line and, on drop, `onDropShapesOver` sets the child order from the pointer position. Dragging a child out to empty page space returns it to the page and shrinks the layout.

Try dragging the loose blue shape into the layout, reordering children by dragging, and switching direction and alignment in the toolbar. For a container that computes layouts itself instead, see the [frame layout modes](https://tldraw.dev/examples/frame-layouts) example.

## App.tsx

```tsx
import { memo, useLayoutEffect, useRef } from 'react'
import {
	BaseFrameLikeShapeUtil,
	Box,
	Editor,
	Geometry2d,
	Group2d,
	HTMLContainer,
	RecordProps,
	Rectangle2d,
	T,
	TLDragShapesOutInfo,
	TLShape,
	TLShapeId,
	TLShapePartial,
	TLComponents,
	Tldraw,
	TldrawUiButtonIcon,
	TldrawUiContextualToolbar,
	TldrawUiToolbarButton,
	canonicalizeRotation,
	clamp,
	createShapeId,
	getIndicesBetween,
	last,
	resizeBox,
	toDomPrecision,
	track,
	useEditor,
	useValue,
	type TLResizeInfo,
} from 'tldraw'
import {
	FLEX_CONTAINER_DEFAULT_LABEL,
	FLEX_CONTAINER_GAP,
	FLEX_CONTAINER_PADDING,
	getChildPositions,
	getDesiredSize,
	getDropInLineStyle,
	getDropOutLineStyle,
	getFlexContainerStyles,
	getMinimumContentSize,
	type FlexContainerLayoutProps,
	type FrameLabelBoxShape,
} from './FlexContainerHelpers'
import 'tldraw/tldraw.css'
import './flex-layout.css'

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

const FLEX_LAYOUT_SHAPE_TYPE = 'flex-layout'
const FLEX_LAYOUT_ID = createShapeId('flex-layout-example')

// [1]
declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[FLEX_LAYOUT_SHAPE_TYPE]: FlexContainerLayoutProps & {
			w: number
			h: number
		}
	}
}

// [2]
type FlexLayoutShape = TLShape<typeof FLEX_LAYOUT_SHAPE_TYPE>

// [3]
const FRAME_HEADING_EXTRA_WIDTH = 12
const FRAME_HEADING_MIN_WIDTH = 32
const FRAME_HEADING_NOCOLORS_OFFSET_X = -7
const FRAME_HEADING_OFFSET_Y = 4

function getContainerHeadingSide(editor: Editor, shape: FrameLabelBoxShape): 0 | 1 | 2 | 3 {
	const pageRotation = canonicalizeRotation(editor.getShapePageTransform(shape.id)!.rotation())
	const offsetRotation = pageRotation + Math.PI / 4
	const scaledRotation = (offsetRotation * (2 / Math.PI) + 4) % 4
	return Math.floor(scaledRotation) as 0 | 1 | 2 | 3
}

function getContainerHeadingOpts(width: number) {
	return {
		fontSize: 12,
		fontFamily: 'Inter, sans-serif',
		textAlign: 'start' as const,
		width,
		height: 24,
		padding: 0,
		lineHeight: 1,
		fontStyle: 'normal',
		fontWeight: 'normal',
		overflow: 'truncate-ellipsis' as const,
		verticalTextAlign: 'middle' as const,
		offsetY: -(32 + 2),
		offsetX: 0,
	}
}

function getContainerHeadingSize(
	editor: Editor,
	shape: FrameLabelBoxShape,
	opts: ReturnType<typeof getContainerHeadingOpts>,
	label: string
) {
	const spans = editor.textMeasure.measureTextSpans(label, opts)
	const firstSpan = spans[0]
	const lastSpan = last(spans)!
	const width = lastSpan.box.w + lastSpan.box.x - firstSpan.box.x

	return new Box(0, -opts.height, width, opts.height)
}

function getContainerHeadingTranslation(shape: FrameLabelBoxShape, side: 0 | 1 | 2 | 3) {
	const u = 'px'
	const r = 'deg'
	switch (side) {
		case 0:
			return ''
		case 3:
			return `translate(${toDomPrecision(shape.props.w)}${u}, 0${u}) rotate(90${r})`
		case 2:
			return `translate(${toDomPrecision(shape.props.w)}${u}, ${toDomPrecision(shape.props.h)}${u}) rotate(180${r})`
		case 1:
			return `translate(0${u}, ${toDomPrecision(shape.props.h)}${u}) rotate(270${r})`
		default:
			throw Error('labelSide out of bounds')
	}
}

function getFlexContainerLabelGeometry(
	editor: Editor,
	shape: FrameLabelBoxShape,
	label = FLEX_CONTAINER_DEFAULT_LABEL
) {
	const z = editor.getEfficientZoomLevel()
	const labelSide = getContainerHeadingSide(editor, shape)
	const isVertical = labelSide % 2 === 1
	const rotatedTopEdgeWidth = isVertical ? shape.props.h : shape.props.w

	const opts = getContainerHeadingOpts(rotatedTopEdgeWidth)
	const headingSize = getContainerHeadingSize(editor, shape, opts, label)

	const extraWidth = FRAME_HEADING_EXTRA_WIDTH / z
	const minWidth = FRAME_HEADING_MIN_WIDTH / z
	const maxWidth = rotatedTopEdgeWidth + extraWidth

	const labelWidth = headingSize.w / z
	const labelHeight = headingSize.h / z
	const clampedLabelWidth = clamp(labelWidth + extraWidth, minWidth, maxWidth)

	const offsetX = FRAME_HEADING_NOCOLORS_OFFSET_X / z
	const offsetY = FRAME_HEADING_OFFSET_Y / z

	const width = isVertical ? labelHeight : clampedLabelWidth
	const height = isVertical ? clampedLabelWidth : labelHeight

	let x: number
	let y: number

	switch (labelSide) {
		case 0:
			x = offsetX
			y = -(labelHeight + offsetY)
			break
		case 1:
			x = -(labelHeight + offsetY)
			y = shape.props.h - (offsetX + clampedLabelWidth)
			break
		case 2:
			x = shape.props.w - (offsetX + clampedLabelWidth)
			y = shape.props.h + offsetY
			break
		case 3:
			x = shape.props.w + offsetY
			y = offsetX
			break
	}

	return new Rectangle2d({
		x,
		y,
		width,
		height,
		isFilled: true,
		isLabel: true,
		excludeFromShapeBounds: true,
	})
}

const FlexContainerHeading = memo(function FlexContainerHeading({
	shape,
	label = FLEX_CONTAINER_DEFAULT_LABEL,
}: {
	shape: FrameLabelBoxShape
	label?: string
}) {
	const editor = useEditor()
	const { side, translation } = useValue(
		'flex container heading',
		() => {
			const labelSide = getContainerHeadingSide(editor, shape)
			return {
				side: labelSide,
				translation: getContainerHeadingTranslation(shape, labelSide),
			}
		},
		[editor, shape]
	)

	return (
		<div
			className="tl-frame-heading"
			style={{
				overflow: 'hidden',
				maxWidth: `calc(var(--tl-zoom) * ${
					side === 0 || side === 2 ? Math.ceil(shape.props.w) : Math.ceil(shape.props.h)
				}px + var(--tl-frame-offset-width))`,
				bottom: '100%',
				transform: `${translation} scale(min(var(--tl-scale), 3.5)) translateX(-7px)`,
			}}
		>
			<div
				className="tl-frame-heading-hit-area flex-layout-heading__label"
				style={{
					color: 'var(--tl-color-text-1)',
					backgroundColor: '#fff',
					boxShadow: 'inset 0px 0px 0px 1px var(--tl-color-muted-1)',
				}}
			>
				{label}
			</div>
		</div>
	)
})

// [4]
class FlexLayoutShapeUtil extends BaseFrameLikeShapeUtil<FlexLayoutShape> {
	static override type = FLEX_LAYOUT_SHAPE_TYPE
	static override props: RecordProps<FlexLayoutShape> = {
		w: T.nonZeroNumber,
		h: T.nonZeroNumber,
		direction: T.literalEnum('horizontal', 'vertical'),
		align: T.literalEnum('start', 'center', 'end'),
		justify: T.literalEnum('start', 'center', 'end', 'space-between'),
	}

	override canResize() {
		return true
	}

	override canResizeChildren() {
		return false
	}

	override getDefaultProps(): FlexLayoutShape['props'] {
		return {
			w: 420,
			h: 240,
			direction: 'horizontal',
			align: 'center',
			justify: 'center',
		}
	}

	override getGeometry(shape: FlexLayoutShape): Geometry2d {
		return new Group2d({
			children: [
				new Rectangle2d({
					width: shape.props.w,
					height: shape.props.h,
					isFilled: false,
				}),
				getFlexContainerLabelGeometry(this.editor, shape, FLEX_CONTAINER_DEFAULT_LABEL),
			],
		})
	}

	override getText(_shape: FlexLayoutShape) {
		return FLEX_CONTAINER_DEFAULT_LABEL
	}

	override getAriaDescriptor(_shape: FlexLayoutShape) {
		return FLEX_CONTAINER_DEFAULT_LABEL
	}

	override component(shape: FlexLayoutShape) {
		return (
			<>
				<FlexContainerHeading shape={shape} label={FLEX_CONTAINER_DEFAULT_LABEL} />
				<FlexLayoutShapeComponent shape={shape} />
			</>
		)
	}

	// [4a]
	override onResize(shape: FlexLayoutShape, info: TLResizeInfo<FlexLayoutShape>) {
		const children = getFlexLayoutChildren(this.editor, shape.id)
		const minimum = getMinimumContentSize(this.editor, shape, children)
		return resizeBox(shape, info, {
			minWidth: minimum.w,
			minHeight: minimum.h,
		})
	}

	override onResizeEnd(_initialShape: FlexLayoutShape, currentShape: FlexLayoutShape) {
		relayoutFlexLayoutChildren(this.editor, currentShape.id)
	}

	// [4b]
	override onDragShapesOut(shape: FlexLayoutShape, shapes: TLShape[], info: TLDragShapesOutInfo) {
		if (info.nextDraggingOverShapeId) return

		const childrenToMove = shapes.filter((movingShape) => movingShape.parentId === shape.id)
		if (!childrenToMove.length) return

		this.editor.reparentShapes(childrenToMove, this.editor.getCurrentPageId())
		resizeFlexLayoutToChildren(this.editor, shape.id)
	}

	// [4c]
	override onDropShapesOver(shape: FlexLayoutShape, shapes: TLShape[]) {
		const dropIndex = getDropIndex(this.editor, shape, shapes)
		dropShapesIntoLayout(this.editor, shape, shapes, dropIndex)
	}

	// [4d]
	override onTranslateEnd(_initialShape: FlexLayoutShape, currentShape: FlexLayoutShape) {
		resizeFlexLayoutToChildren(this.editor, currentShape.id)
	}

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

const shapeUtils = [FlexLayoutShapeUtil]

// [5]
function FlexLayoutShapeComponent({ shape }: { shape: FlexLayoutShape }) {
	const editor = useEditor()
	const rMeasure = useRef<HTMLDivElement>(null)
	const children = useValue(
		'flex layout children',
		() =>
			editor
				.getSortedChildIdsForParent(shape.id)
				.map((id) => editor.getShape(id))
				.filter((child) => child !== undefined),
		[editor, shape.id]
	)
	const layoutKey = children
		.map((child) => {
			const bounds = editor.getShapeGeometry(child).bounds
			return `${child.id}:${child.x}:${child.y}:${bounds.width}:${bounds.height}`
		})
		.join('|')
	const dropIndicator = useValue(
		'flex layout drop indicator',
		() => getDropIndicator(editor, shape, children),
		[editor, shape.id, shape.props.direction, shape.props.align, shape.props.justify, layoutKey]
	)
	const isTranslatingSelectedChild = useValue(
		'flex layout is translating selected child',
		() => getIsTranslatingSelectedChild(editor, shape),
		[editor, shape.id]
	)

	useLayoutEffect(() => {
		if (isTranslatingSelectedChild) return

		const elm = rMeasure.current
		if (!elm) return
		const measureElm = elm

		resizeFlexLayoutToChildren(editor, shape.id)

		function updateChildrenFromFlexbox() {
			const updates: TLShapePartial[] = Array.from(
				measureElm.querySelectorAll<HTMLElement>('[data-shape-id]')
			).flatMap((childElm) => {
				const childId = childElm.dataset.shapeId as TLShapeId | undefined
				if (!childId) return []
				const child = editor.getShape(childId)
				if (!child || child.parentId !== shape.id) return []
				const x = childElm.offsetLeft
				const y = childElm.offsetTop
				if (Math.abs(child.x - x) < 0.5 && Math.abs(child.y - y) < 0.5) return []
				return [{ id: child.id, type: child.type, x, y } as TLShapePartial]
			})

			if (updates.length) {
				editor.updateShapes(updates)
			}
		}

		updateChildrenFromFlexbox()
		const observer = new ResizeObserver(updateChildrenFromFlexbox)
		observer.observe(measureElm)
		for (const childElm of measureElm.querySelectorAll<HTMLElement>('[data-shape-id]')) {
			observer.observe(childElm)
		}
		return () => observer.disconnect()
	}, [editor, shape, layoutKey, isTranslatingSelectedChild, shape.props.align, shape.props.justify])

	return (
		<HTMLContainer
			className="flex-layout-shape"
			data-drop-active={!!dropIndicator}
			style={{
				width: shape.props.w,
				height: shape.props.h,
			}}
		>
			<div
				ref={rMeasure}
				className="flex-layout-shape__measure"
				style={{
					width: shape.props.w,
					height: shape.props.h,
					padding: FLEX_CONTAINER_PADDING,
					gap: FLEX_CONTAINER_GAP,
					...getFlexContainerStyles(shape),
				}}
			>
				{children.map((child) => {
					const bounds = editor.getShapeGeometry(child).bounds
					return (
						<div
							key={child.id}
							data-shape-id={child.id}
							style={{
								width: bounds.width,
								height: bounds.height,
							}}
						/>
					)
				})}
			</div>
			{dropIndicator ? (
				<div
					className="flex-layout-shape__drop-line"
					data-direction={shape.props.direction}
					data-drop-type={dropIndicator.type}
					style={dropIndicator.style}
				/>
			) : null}
		</HTMLContainer>
	)
}

// [6]
const FlexLayoutToolbar = track(function FlexLayoutToolbar() {
	const editor = useEditor()
	const shape = useValue(
		'selected flex layout shape',
		() => {
			if (!editor.isIn('select.idle')) return null
			const onlySelectedShape = editor.getOnlySelectedShape()
			return onlySelectedShape?.type === FLEX_LAYOUT_SHAPE_TYPE
				? (onlySelectedShape as FlexLayoutShape)
				: null
		},
		[editor]
	)

	if (!shape) return null

	const updateLayoutProps = (props: Partial<FlexContainerLayoutProps>) => {
		editor.run(() => {
			editor.updateShapes([{ id: shape.id, type: shape.type, props } as TLShapePartial])
			relayoutFlexLayoutChildren(editor, shape.id)
		})
		editor.getContainer().focus()
	}

	const isHorizontal = shape.props.direction === 'horizontal'

	const getSelectionBounds = () => {
		const bounds = editor.getSelectionRotatedScreenBounds()
		if (!bounds) return undefined
		return new Box(bounds.x, bounds.y, bounds.width, 0)
	}

	return (
		<TldrawUiContextualToolbar getSelectionBounds={getSelectionBounds} label="Flex layout">
			<TldrawUiToolbarButton
				type="icon"
				title="Horizontal"
				isActive={shape.props.direction === 'horizontal'}
				onClick={() => updateLayoutProps({ direction: 'horizontal' })}
			>
				<TldrawUiButtonIcon small icon="stack-horizontal" />
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title="Vertical"
				isActive={shape.props.direction === 'vertical'}
				onClick={() => updateLayoutProps({ direction: 'vertical' })}
			>
				<TldrawUiButtonIcon small icon="stack-vertical" />
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title={isHorizontal ? 'Align left' : 'Align top'}
				isActive={shape.props.justify === 'start'}
				onClick={() => updateLayoutProps({ justify: 'start' })}
			>
				<TldrawUiButtonIcon
					small
					icon={isHorizontal ? 'horizontal-align-start' : 'vertical-align-start'}
				/>
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title={isHorizontal ? 'Align center' : 'Align middle'}
				isActive={shape.props.justify === 'center'}
				onClick={() => updateLayoutProps({ justify: 'center' })}
			>
				<TldrawUiButtonIcon
					small
					icon={isHorizontal ? 'horizontal-align-middle' : 'vertical-align-middle'}
				/>
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title={isHorizontal ? 'Align right' : 'Align bottom'}
				isActive={shape.props.justify === 'end'}
				onClick={() => updateLayoutProps({ justify: 'end' })}
			>
				<TldrawUiButtonIcon
					small
					icon={isHorizontal ? 'horizontal-align-end' : 'vertical-align-end'}
				/>
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title={isHorizontal ? 'Distribute horizontally' : 'Distribute vertically'}
				isActive={shape.props.justify === 'space-between'}
				onClick={() => updateLayoutProps({ justify: 'space-between' })}
			>
				<TldrawUiButtonIcon
					small
					icon={isHorizontal ? 'distribute-horizontal' : 'distribute-vertical'}
				/>
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title={isHorizontal ? 'Align top' : 'Align left'}
				isActive={shape.props.align === 'start'}
				onClick={() => updateLayoutProps({ align: 'start' })}
			>
				<TldrawUiButtonIcon
					small
					icon={isHorizontal ? 'vertical-align-start' : 'horizontal-align-start'}
				/>
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title={isHorizontal ? 'Align middle' : 'Align center'}
				isActive={shape.props.align === 'center'}
				onClick={() => updateLayoutProps({ align: 'center' })}
			>
				<TldrawUiButtonIcon
					small
					icon={isHorizontal ? 'vertical-align-middle' : 'horizontal-align-middle'}
				/>
			</TldrawUiToolbarButton>
			<TldrawUiToolbarButton
				type="icon"
				title={isHorizontal ? 'Align bottom' : 'Align right'}
				isActive={shape.props.align === 'end'}
				onClick={() => updateLayoutProps({ align: 'end' })}
			>
				<TldrawUiButtonIcon
					small
					icon={isHorizontal ? 'vertical-align-end' : 'horizontal-align-end'}
				/>
			</TldrawUiToolbarButton>
		</TldrawUiContextualToolbar>
	)
})

const components: TLComponents = { InFrontOfTheCanvas: FlexLayoutToolbar }

// [7]
function getFlexLayoutChildren(editor: Editor, shapeId: TLShapeId) {
	return editor
		.getSortedChildIdsForParent(shapeId)
		.map((id) => editor.getShape(id))
		.filter((child): child is TLShape => !!child)
}

function getIsTranslatingSelectedChild(editor: Editor, shape: FlexLayoutShape) {
	return (
		editor.getPath() === 'select.translating' &&
		editor.getSelectedShapes().some((selectedShape) => selectedShape.parentId === shape.id)
	)
}

function getDropIndex(editor: Editor, shape: FlexLayoutShape, movingShapes: TLShape[]) {
	const movingIds = new Set(movingShapes.map((movingShape) => movingShape.id))
	const children = editor
		.getSortedChildIdsForParent(shape.id)
		.map((id) => editor.getShape(id))
		.filter((child): child is TLShape => !!child && !movingIds.has(child.id))

	const point = editor.getPointInShapeSpace(shape, editor.inputs.getCurrentPagePoint())
	const axis = shape.props.direction === 'horizontal' ? 'x' : 'y'

	for (let i = 0; i < children.length; i++) {
		const child = children[i]
		const bounds = editor.getShapeGeometry(child).bounds
		const midpoint = child[axis] + (axis === 'x' ? bounds.width : bounds.height) / 2
		if (point[axis] < midpoint) return i
	}

	return children.length
}

function dropShapesIntoLayout(
	editor: Editor,
	shape: FlexLayoutShape,
	shapes: TLShape[],
	dropIndex: number
) {
	const shapesToDrop = shapes.filter((movingShape) => {
		if (movingShape.id === shape.id) return false
		return !editor.hasAncestor(shape, movingShape.id)
	})
	if (shapesToDrop.length === 0) return

	const movingIds = new Set(shapesToDrop.map((movingShape) => movingShape.id))
	const remainingChildren = editor
		.getSortedChildIdsForParent(shape.id)
		.map((id) => editor.getShape(id))
		.filter((child): child is TLShape => !!child && !movingIds.has(child.id))

	const nextChildren = [...remainingChildren]
	nextChildren.splice(dropIndex, 0, ...shapesToDrop)
	const indices = getIndicesBetween(undefined, undefined, nextChildren.length)
	const desiredSize = getDesiredSize(editor, shape, nextChildren)
	const childPositions = getChildPositions(editor, shape, nextChildren, desiredSize)

	editor.run(() => {
		editor.reparentShapes(shapesToDrop, shape.id)
		editor.updateShape<FlexLayoutShape>({
			id: shape.id,
			type: shape.type,
			props: desiredSize,
		})
		editor.updateShapes(
			nextChildren.map((child, index) => ({
				id: child.id,
				type: child.type,
				index: indices[index],
				...childPositions[index],
			})) as TLShapePartial[]
		)
	})
}

function relayoutFlexLayoutChildren(editor: Editor, shapeId: TLShapeId) {
	const shape = editor.getShape(shapeId) as FlexLayoutShape | undefined
	if (!shape) return

	const children = getFlexLayoutChildren(editor, shapeId)
	if (children.length === 0) return

	const childPositions = getChildPositions(editor, shape, children)

	editor.updateShapes(
		children.map((child, index) => ({
			id: child.id,
			type: child.type,
			...childPositions[index],
		})) as TLShapePartial[]
	)
}

function resizeFlexLayoutToChildren(editor: Editor, shapeId: TLShapeId) {
	const shape = editor.getShape(shapeId) as FlexLayoutShape | undefined
	if (!shape) return

	const children = getFlexLayoutChildren(editor, shapeId)
	const desiredSize = getDesiredSize(editor, shape, children)
	if (
		Math.abs(shape.props.w - desiredSize.w) < 0.5 &&
		Math.abs(shape.props.h - desiredSize.h) < 0.5
	) {
		return
	}

	editor.updateShape<FlexLayoutShape>({
		id: shape.id,
		type: shape.type,
		props: desiredSize,
	})
}

function getDropIndicator(editor: Editor, shape: FlexLayoutShape, children: TLShape[]) {
	if (editor.getPath() !== 'select.translating') return null

	const pagePoint = editor.inputs.getCurrentPagePoint()
	const point = editor.getPointInShapeSpace(shape, pagePoint)
	const isInside = editor.isPointInShape(shape.id, pagePoint, { hitInside: true })

	const selectedShapes = editor.getSelectedShapes()
	const isDraggingChild = selectedShapes.some(
		(selectedShape) => selectedShape.parentId === shape.id
	)
	const isDraggingOver = editor.getHintingShapeIds().includes(shape.id)

	if (isInside && (isDraggingOver || isDraggingChild)) {
		return {
			type: 'in',
			style: getDropInLineStyle(
				editor,
				shape,
				children,
				getDropIndex(editor, shape, selectedShapes)
			),
		} as const
	}

	if (isDraggingChild) {
		return {
			type: 'out',
			style: getDropOutLineStyle(shape, point),
		} as const
	}

	return null
}

// [8]
export default function FlexLayoutExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				onMount={(editor) => {
					const childA = createShapeId('flex-child-a')
					const childB = createShapeId('flex-child-b')
					const orphanC = createShapeId('flex-orphan-c')
					editor.createShapes([
						{
							id: FLEX_LAYOUT_ID,
							type: FLEX_LAYOUT_SHAPE_TYPE,
							x: 160,
							y: 160,
						},
						{
							id: childA,
							type: 'geo',
							x: FLEX_CONTAINER_PADDING,
							y: FLEX_CONTAINER_PADDING,
							parentId: FLEX_LAYOUT_ID,
							props: { w: 128, h: 72, geo: 'rectangle', color: 'red', fill: 'solid' },
						},
						{
							id: childB,
							type: 'geo',
							x: FLEX_CONTAINER_PADDING + 96 + FLEX_CONTAINER_GAP,
							y: FLEX_CONTAINER_PADDING,
							parentId: FLEX_LAYOUT_ID,
							props: { w: 96, h: 96, geo: 'rectangle', color: 'green', fill: 'solid' },
						},
						{
							id: orphanC,
							type: 'geo',
							x: 480,
							y: 480,
							props: { w: 80, h: 144, geo: 'rectangle', color: 'blue', fill: 'solid' },
						},
					])
					resizeFlexLayoutToChildren(editor, FLEX_LAYOUT_ID)
					editor.select(FLEX_LAYOUT_ID)
				}}
			/>
		</div>
	)
}

/*
Introduction:

This example shows a frame-like custom shape that uses CSS flexbox to arrange its children.

[1]
Extend TLGlobalShapePropsMap with `FlexContainerLayoutProps` (direction, align, justify) plus
width and height.

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

[3]
Frame-style label geometry and heading component, following the same rotation-aware side logic
as the built-in FrameShapeUtil. `getFlexContainerLabelGeometry` returns a `Rectangle2d` marked
`isLabel` and `excludeFromShapeBounds`, positioned just outside the shape, so clicking the label
selects the layout without the label growing the shape's bounds.

[4]
The shape util. BaseFrameLikeShapeUtil gives us frame-like behavior: clipping children,
reparenting shapes in while they're dragged over the layout, and releasing them when dragged
out. The geometry is an unfilled body plus the label hit area, so clicks on interior padding
pass through to the canvas like a frame.

	[4a]
	Allow resizing, but clamp width and height to the minimum needed to fit all children, padding,
	and gaps. Relayout children when a resize finishes.

	[4b]
	When a child is dragged out to empty page space, reparent it back to the page (as the base
	class would) and shrink the layout around the remaining children.

	[4c]
	On drop, finalize the child order (from the pointer position) and positions. The base class
	has already reparented the dropped shapes during the drag; this override just arranges them.

	[4d]
	Keep the container's size in sync after the layout itself is moved.

[5]
Render the layout shape. A hidden measurement layer runs real CSS flexbox with a placeholder
div per child at the child's size, then a ResizeObserver reads each placeholder's offset and
writes it back to the child shape's x/y. That's what lets the browser do the layout math while
the store stays the source of truth. The effect is skipped while a child is being dragged so
it doesn't fight the pointer.

[6]
A contextual toolbar shown when a single layout shape is selected, built from
`TldrawUiContextualToolbar` and `TldrawUiToolbarButton`, with direction, justify, and align
controls. Each change re-runs the layout math from `FlexContainerHelpers.tsx` so the children
snap immediately rather than waiting for the ResizeObserver.

[7]
Helpers for computing the drop index from the pointer, reparenting dropped shapes with new
fractional indices, relayout, and the drop-in / drop-out indicator lines.

[8]
Mount the editor with a layout containing two children plus a loose shape to drag in.

Visual styles for the shape live in `flex-layout.css`. Size math, axis positioning, and drop
indicator geometry are in `FlexContainerHelpers.tsx`.
*/
```

## FlexContainerHelpers.tsx

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

export const FLEX_CONTAINER_DEFAULT_LABEL = 'Flex layout'

export const FLEX_CONTAINER_PADDING = 24
export const FLEX_CONTAINER_GAP = 16
export const FLEX_CONTAINER_EMPTY_WIDTH = 160
export const FLEX_CONTAINER_EMPTY_HEIGHT = 120

export type FlexAlign = 'start' | 'center' | 'end'
export type FlexJustify = 'start' | 'center' | 'end' | 'space-between'

export interface FlexContainerLayoutProps {
	direction: 'horizontal' | 'vertical'
	align: FlexAlign
	justify: FlexJustify
}

export interface FlexContainerBoxShape {
	id: TLShapeId
	props: FlexContainerLayoutProps & { w: number; h: number }
}

export interface FrameLabelBoxShape {
	id: TLShapeId
	props: { w: number; h: number }
}

function toCssFlex(value: FlexAlign | FlexJustify) {
	if (value === 'start') return 'flex-start'
	if (value === 'end') return 'flex-end'
	return value
}

export function getFlexContainerStyles(shape: FlexContainerBoxShape): React.CSSProperties {
	const isHorizontal = shape.props.direction === 'horizontal'
	return {
		flexDirection: isHorizontal ? 'row' : 'column',
		justifyContent: toCssFlex(shape.props.justify),
		alignItems: toCssFlex(shape.props.align),
	}
}

export function getMainAxisPositions(
	sizes: number[],
	innerSize: number,
	justify: FlexJustify,
	gap: number
): number[] {
	const count = sizes.length
	if (count === 0) return []

	const contentSize = sizes.reduce((sum, size) => sum + size, 0) + gap * Math.max(0, count - 1)
	const freeSpace = innerSize - contentSize

	if (justify === 'start' || (justify === 'space-between' && count === 1)) {
		let position = 0
		return sizes.map((size) => {
			const axisPosition = position
			position += size + gap
			return axisPosition
		})
	}

	if (justify === 'end') {
		let position = freeSpace
		return sizes.map((size) => {
			const axisPosition = position
			position += size + gap
			return axisPosition
		})
	}

	if (justify === 'center') {
		let position = freeSpace / 2
		return sizes.map((size) => {
			const axisPosition = position
			position += size + gap
			return axisPosition
		})
	}

	const spacing = gap + freeSpace / (count - 1)
	let position = 0
	return sizes.map((size, index) => {
		const axisPosition = position
		position += size + (index < count - 1 ? spacing : 0)
		return axisPosition
	})
}

export function getCrossAxisOffset(childSize: number, innerSize: number, align: FlexAlign) {
	if (align === 'start') return 0
	if (align === 'end') return innerSize - childSize
	return (innerSize - childSize) / 2
}

export function getMinimumContentSize(
	editor: Editor,
	shape: FlexContainerBoxShape,
	children: TLShape[]
) {
	if (children.length === 0) {
		return { w: FLEX_CONTAINER_EMPTY_WIDTH, h: FLEX_CONTAINER_EMPTY_HEIGHT }
	}

	const bounds = children.map((child) => editor.getShapeGeometry(child).bounds)
	const totalGap = FLEX_CONTAINER_GAP * Math.max(0, children.length - 1)

	if (shape.props.direction === 'horizontal') {
		return {
			w: bounds.reduce((sum, b) => sum + b.width, 0) + totalGap + FLEX_CONTAINER_PADDING * 2,
			h: Math.max(...bounds.map((b) => b.height)) + FLEX_CONTAINER_PADDING * 2,
		}
	}

	return {
		w: Math.max(...bounds.map((b) => b.width)) + FLEX_CONTAINER_PADDING * 2,
		h: bounds.reduce((sum, b) => sum + b.height, 0) + totalGap + FLEX_CONTAINER_PADDING * 2,
	}
}

export function getDesiredSize(editor: Editor, shape: FlexContainerBoxShape, children: TLShape[]) {
	const minimum = getMinimumContentSize(editor, shape, children)
	return {
		w: Math.max(shape.props.w, minimum.w),
		h: Math.max(shape.props.h, minimum.h),
	}
}

export function getChildPositions(
	editor: Editor,
	shape: FlexContainerBoxShape,
	children: TLShape[],
	size = getDesiredSize(editor, shape, children)
) {
	const bounds = children.map((child) => editor.getShapeGeometry(child).bounds)
	const innerW = size.w - FLEX_CONTAINER_PADDING * 2
	const innerH = size.h - FLEX_CONTAINER_PADDING * 2

	if (shape.props.direction === 'horizontal') {
		const mainPositions = getMainAxisPositions(
			bounds.map((b) => b.width),
			innerW,
			shape.props.justify,
			FLEX_CONTAINER_GAP
		)

		return bounds.map((b, index) => ({
			x: FLEX_CONTAINER_PADDING + mainPositions[index],
			y: FLEX_CONTAINER_PADDING + getCrossAxisOffset(b.height, innerH, shape.props.align),
		}))
	}

	const mainPositions = getMainAxisPositions(
		bounds.map((b) => b.height),
		innerH,
		shape.props.justify,
		FLEX_CONTAINER_GAP
	)

	return bounds.map((b, index) => ({
		x: FLEX_CONTAINER_PADDING + getCrossAxisOffset(b.width, innerW, shape.props.align),
		y: FLEX_CONTAINER_PADDING + mainPositions[index],
	}))
}

export function getDropInLineStyle(
	editor: Editor,
	shape: FlexContainerBoxShape,
	children: TLShape[],
	dropIndex: number
): React.CSSProperties {
	const movingIds = new Set(editor.getSelectedShapeIds())
	const layoutChildren = children.filter((child) => !movingIds.has(child.id))

	if (shape.props.direction === 'horizontal') {
		const x = getDropLineCoordinate(editor, layoutChildren, dropIndex, 'x', shape.props.w)
		return {
			left: x - 1,
			top: FLEX_CONTAINER_PADDING,
			width: 2,
			height: shape.props.h - FLEX_CONTAINER_PADDING * 2,
		}
	}

	const y = getDropLineCoordinate(editor, layoutChildren, dropIndex, 'y', shape.props.h)
	return {
		left: FLEX_CONTAINER_PADDING,
		top: y - 1,
		width: shape.props.w - FLEX_CONTAINER_PADDING * 2,
		height: 2,
	}
}

export function getDropOutLineStyle(
	shape: FlexContainerBoxShape,
	point: { x: number; y: number }
): React.CSSProperties {
	if (shape.props.direction === 'horizontal') {
		const x = point.x < shape.props.w / 2 ? 0 : shape.props.w
		return {
			left: x - 1,
			top: FLEX_CONTAINER_PADDING,
			width: 2,
			height: shape.props.h - FLEX_CONTAINER_PADDING * 2,
		}
	}

	const y = point.y < shape.props.h / 2 ? 0 : shape.props.h
	return {
		left: FLEX_CONTAINER_PADDING,
		top: y - 1,
		width: shape.props.w - FLEX_CONTAINER_PADDING * 2,
		height: 2,
	}
}

function getDropLineCoordinate(
	editor: Editor,
	children: TLShape[],
	dropIndex: number,
	axis: 'x' | 'y',
	size: number
) {
	if (children.length === 0) return size / 2
	if (dropIndex <= 0) return children[0][axis] - FLEX_CONTAINER_GAP / 2

	const previous = children[Math.min(dropIndex - 1, children.length - 1)]
	const previousBounds = editor.getShapeGeometry(previous).bounds
	const previousEnd = previous[axis] + (axis === 'x' ? previousBounds.width : previousBounds.height)

	if (dropIndex >= children.length) return previousEnd + FLEX_CONTAINER_GAP / 2

	const next = children[dropIndex]
	return (previousEnd + next[axis]) / 2
}
```

## flex-layout.css

```css
.flex-layout-shape {
	position: absolute;
	inset: 0;
	box-sizing: border-box;
	border: 2px solid #111;
	border-radius: 0;
	background: #e8e8e8;
}

.flex-layout-shape[data-drop-active='true'] {
	box-shadow: 0 0 0 2px var(--tl-color-selected);
}

.flex-layout-heading__label {
	padding: 0 10px;
	font-style: italic;
}

.flex-layout-shape__body {
	position: absolute;
	inset: 0;
	display: grid;
	place-items: center;
	color: var(--tl-color-text-3);
	font: var(--tl-font-body);
	pointer-events: none;
}

.flex-layout-shape__measure {
	position: absolute;
	inset: 0;
	box-sizing: border-box;
	display: flex;
	gap: 16px;
	padding: 24px;
	opacity: 0;
	pointer-events: none;
}

.flex-layout-shape__drop-line {
	position: absolute;
	border-radius: 999px;
	background: var(--tl-color-selected);
	pointer-events: none;
}

.flex-layout-shape__drop-line[data-drop-type='out'] {
	opacity: 0.5;
}
```

--------

# Arrow binding options

Category: Shapes & tools

Keywords: arrow, binding, isprecise, isexact, normalizedanchor, anchor point, arrow connections, technical diagrams

Control where a bound arrow lands on a shape with `isPrecise`, `isExact`, and `normalizedAnchor`.

Arrow bindings are records created with `editor.createBindings`. Three props on the binding decide where the arrow's terminal ends up:

- `normalizedAnchor` is a point on the target shape in normalized coordinates: `{x: 0.5, y: 0.5}` is the center, `{x: 0, y: 0}` the top-left, `{x: 1, y: 1}` the bottom-right.
- `isPrecise: false` ignores the anchor and aims at the shape's center. `isPrecise: true` aims at the anchor.
- `isExact: false` stops the arrow at the shape's edge. `isExact: true` lets the arrow continue into the shape until it reaches the anchor point.

The example creates four shape-and-arrow pairs, one for each combination. Try dragging the shapes around: the arrows stay bound and re-route according to their options. Select an arrow and drag its endpoint to see how the editor sets these props interactively (pausing over a shape makes the binding precise).

## 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',
						},
					})

					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,
							},
						},
					])

					// [2]
					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',
						},
					})

					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,
							},
						},
					])

					// [3]
					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',
						},
					})

					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,
							},
						},
					])

					// [4]
					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>
	)
}

/*
Each pair below creates a geo shape and an arrow, then binds the arrow's end terminal to the
shape with `editor.createBindings`. The arrow's `end` prop is only a fallback position; once
the binding exists, the arrow's endpoint is computed from the binding props.

[1]
`isPrecise: false`. The `normalizedAnchor` of (0.25, 0.5) is ignored and the arrow aims at
the shape's center, stopping at the edge. This is what you get when a user drags an arrow
onto a shape without pausing to pick a specific point.

[2]
`isPrecise: true` with the same anchor. Now the arrow aims at the anchor position (a quarter
of the way across, vertically centered), still stopping at the shape's edge because
`isExact` is false.

[3]
`isExact: true`. Instead of stopping at the edge, the arrow continues into the shape until it
reaches the anchor point itself, here the exact center.

[4]
Both flags together with an off-center anchor at (0.75, 0.75): the arrow enters the shape and
ends at that exact point.
*/
```

--------

# Custom geo types

Category: Shapes & tools

Keywords: geo, custom, shape, extend, configure, geometry, path, pathbuilder

Add new geo types (a rounded rectangle and a cross) to the built-in geo shape with `GeoShapeUtil.configure()`.

Instead of writing a whole new shape util, pass a `customGeoTypes` map to `GeoShapeUtil.configure()`. Each entry supplies a `getPath` function that returns a `PathBuilder` outline for a given width and height, plus a snap type, an icon, and an optional default size. The configured util replaces the default one in `shapeUtils`; the new types inherit labels, fill and dash styles, resizing, snapping, and SVG export, and they show up in the style panel's geo picker.

The example also registers icons for the new types through `assetUrls`, adds tool labels through the `translations` override, and puts the two new tools at the front of the toolbar with `ToolbarItem`.

Try selecting a shape and switching its geo type in the style panel, or use the new toolbar tools to draw more.

## App.tsx

```tsx
import {
	DefaultToolbar,
	DefaultToolbarContent,
	GeoShapeUtil,
	PathBuilder,
	TLComponents,
	TLUiAssetUrlOverrides,
	TLUiOverrides,
	Tldraw,
	ToolbarItem,
	toRichText,
} from 'tldraw'
import 'tldraw/tldraw.css'

// [1]
const CustomGeoShapeUtil = GeoShapeUtil.configure({
	customGeoTypes: {
		'rounded-rect': {
			getPath(w, h, shape) {
				// [a]
				const isFilled = shape.props.fill !== 'none'
				const r = Math.min(w, h) * 0.2
				return new PathBuilder()
					.moveTo(r, 0, { geometry: { isFilled } })
					.lineTo(w - r, 0)
					.circularArcTo(r, false, true, w, r)
					.lineTo(w, h - r)
					.circularArcTo(r, false, true, w - r, h)
					.lineTo(r, h)
					.circularArcTo(r, false, true, 0, h - r)
					.lineTo(0, r)
					.circularArcTo(r, false, true, r, 0)
					.close()
			},
			snapType: 'polygon',
			icon: 'geo-rounded-rect',
		},
		cross: {
			getPath(w, h, shape) {
				const isFilled = shape.props.fill !== 'none'
				const armW = w / 3
				const armH = h / 3
				return new PathBuilder()
					.moveTo(armW, 0, { geometry: { isFilled } })
					.lineTo(w - armW, 0)
					.lineTo(w - armW, armH)
					.lineTo(w, armH)
					.lineTo(w, h - armH)
					.lineTo(w - armW, h - armH)
					.lineTo(w - armW, h)
					.lineTo(armW, h)
					.lineTo(armW, h - armH)
					.lineTo(0, h - armH)
					.lineTo(0, armH)
					.lineTo(armW, armH)
					.close()
			},
			snapType: 'polygon',
			icon: 'geo-cross',
			defaultSize: { w: 200, h: 200 },
		},
	},
})

// [2]
const shapeUtils = [CustomGeoShapeUtil]

// [3]
const customAssetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'geo-rounded-rect': '/geo-rounded-rect.svg',
		'geo-cross': '/geo-cross.svg',
	},
}

// [4]
const uiOverrides: TLUiOverrides = {
	translations: {
		en: {
			'tool.rounded-rect': 'Rounded rectangle',
			'tool.cross': 'Cross',
		},
	},
}

// [5]
const components: TLComponents = {
	Toolbar: (props) => {
		return (
			<DefaultToolbar {...props}>
				<ToolbarItem tool="rounded-rect" />
				<ToolbarItem tool="cross" />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
}

export default function CustomGeoTypesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				overrides={uiOverrides}
				assetUrls={customAssetUrls}
				onMount={(editor) => {
					editor.createShapes([
						{
							type: 'geo',
							x: 100,
							y: 100,
							props: {
								w: 250,
								h: 150,
								// [6]
								geo: 'rounded-rect' as any,
								fill: 'solid',
								color: 'blue',
								richText: toRichText('Rounded rect'),
							},
						},
						{
							type: 'geo',
							x: 450,
							y: 100,
							props: {
								w: 200,
								h: 200,
								geo: 'cross' as any,
								fill: 'semi',
								color: 'red',
								richText: toRichText('Cross'),
							},
						},
						{
							type: 'geo',
							x: 100,
							y: 350,
							props: {
								w: 200,
								h: 200,
								geo: 'rectangle',
								fill: 'none',
								richText: toRichText('Built-in'),
							},
						},
					])
					editor.zoomToFit({ animation: { duration: 0 } })
					editor.zoomOut()
				}}
			/>
		</div>
	)
}

/*
[1]
`GeoShapeUtil.configure()` takes a `customGeoTypes` map. Each entry becomes a new value for the
geo style and gets the same treatment as the built-in types: labels, fill/dash/color styles,
resizing, SVG export, snapping, and a slot in the style panel's geo picker.
- getPath: returns a PathBuilder describing the outline, given the current width and height
- snapType: 'polygon' (other handles snap to vertices + center) or 'blobby' (center only)
- icon: icon name for the style panel's geo picker (the toolbar uses 'geo-' + the type name)
- defaultSize: optional creation size when clicking (not dragging); defaults to 200x200

	[a] `isFilled` on the first path segment tells the geometry whether the interior counts as
	part of the shape for hit-testing. Without it, a solid-filled shape could only be clicked
	on its outline.

[2]
Pass the configured util in place of the default. It's still `type: 'geo'`, so existing geo
shapes keep working, and it must be defined outside the component so the array is stable.

[3]
Icons need URLs. Register them under `assetUrls.icons`; the key must be 'geo-' followed by
the geo type name so the toolbar finds it, and using the same name for `icon` in [1] keeps
the style panel picker in sync.

[4]
Each custom geo type is registered as a tool automatically. Give it a label by translating
'tool.' followed by the geo type name.

[5]
Add the new tools to the toolbar with `ToolbarItem`, referencing them by geo type name.

[6]
The `geo` prop is typed as the built-in enum, so setting a custom value programmatically needs
a cast. Shapes created through the toolbar or the style panel don't have this problem.
*/
```

--------

# Custom shape geometry

Category: Shapes & tools

Keywords: custom geometry, getgeometry, polygon2d, rectangle2d, group2d, svg path, vertices, hit testing, shapeutil

Give a custom shape non-rectangular geometry with `Polygon2d`, `Rectangle2d`, and `Group2d`.

A shape's `getGeometry` method returns the geometry the editor uses for hit testing, selection bounds, snapping, and arrow bindings. This example draws a house with a door and builds matching geometry from a `Polygon2d` for the body and a `Rectangle2d` for the door, combined in a `Group2d`.

Try clicking just beside the roof: the pointer misses the shape because the geometry is a polygon, not the bounding box. Try binding an arrow to the shape to see it snap to the polygon's edges.

## App.tsx

```tsx
import {
	Group2d,
	Polygon2d,
	RecordPropsType,
	Rectangle2d,
	ShapeUtil,
	T,
	TLResizeInfo,
	TLShape,
	Tldraw,
	Vec,
	resizeBox,
} 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 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 getIndicatorPath(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 new Path2D(housePathData + doorPathData)
	}
	override onResize(shape: HouseShape, info: TLResizeInfo<HouseShape>) {
		return resizeBox(shape, info)
	}
}
// [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>
	)
}

/*
This file shows a shape with custom (non-rectangular) geometry: a house with a door.

[1]
getGeometry returns the geometry the editor uses for hit testing, selection bounds,
snapping, and arrow binding. It does not have to match a rectangle: here the house body
is a Polygon2d and the door is a Rectangle2d, combined into a Group2d. Because the
geometry is a polygon rather than the bounding box, clicking in the empty corners
either side of the roof does not select the shape.

[2]
The component draws the same vertices as an SVG path. Vec's toString() gives "x, y", so
joining the vertices produces valid path data. The tl-svg-container class sizes the svg
to the shape and turns off pointer events on it.

[3]
getIndicatorPath returns a Path2D for the same outline; tldraw strokes it onto the canvas
overlay as the blue selection outline.

[4]
Both the geometry and the rendering derive from getHouseVertices, so hit testing always
matches what the user sees. Keep them in sync when you change how a shape looks.
*/
```

--------

# Custom shape migrations

Category: Shapes & tools

Keywords: migrations, schema versioning, createshapepropsmigrationids, createshapepropsmigrationsequence, up, down, backwards compatibility, data migration

Migrate a custom shape's props between versions with a migration sequence.

When you change a custom shape's props, documents saved with the old version still contain the old shape data. Migrations let the editor upgrade (or downgrade) that data as it loads, so old documents keep working. This example loads a snapshot containing a shape saved before it had a `color` prop; the shape util's `migrations` (built with `createShapePropsMigrationIds` and `createShapePropsMigrationSequence`) add the missing prop when the snapshot loads.

Read the guide at the bottom of the example file for how the editor decides which migrations to run.

## 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 myShapeMigrations = createShapePropsMigrationSequence({
	sequence: [
		{
			id: versions.AddColor,
			up(props) {
				// props is a mutable copy, so it's safe to change it in place
				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 = myShapeMigrations

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

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

	override onResize(shape: IMyShape, info: TLResizeInfo<IMyShape>) {
		return resizeBox(shape, info)
	}
}

const customShapeUtils = [MigratedShapeUtil]

export default function ShapeWithMigrationsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				// [4]
				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
shipped a migration, it should not change again; add a new one instead.

[2] Next, we create a migration sequence. This is where we actually write our migration logic. Each
migration has three parts: an `id` (created in [1]), an `up` migration and a `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's static `migrations` property. This tells
tldraw about the migrations so they can be used with your shapes.

[4] To show the migration running, we load a snapshot that was saved before the `color` prop
existed. The migration runs as the snapshot loads, so the shape appears light blue.

How it works:

Each time the editor creates a snapshot (`editor.getSnapshot()`), 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": {
		...,
		"recordVersions": {
			"shape": {
				"subTypeVersions": {
					...,
					"myshapewithmigrations": 0
				}
			}
		}
	}
}
```

The shape in the snapshot doesn't have a 'color' prop, and 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: svg export, toSvg, toBackgroundSvg, custom shape export, SvgExportContext, export image, copy as svg, foreignObject, shapeutil

Control how a custom shape looks when exported or copied as SVG or PNG with `toSvg`.

The "export as SVG/PNG" and "copy as SVG/PNG" actions call a shape util's `toSvg` (and optional `toBackgroundSvg`) methods. If a shape defines neither, its component is placed inside a `<foreignObject>` in the exported SVG, which works but is less portable than a real SVG representation.

This shape's `toSvg` returns a `rect` matching its HTML component and reads `ctx.isDarkMode` from the `SvgExportContext` so the export uses the right fill for the requested mode. Select the shape and choose "Copy as SVG" or "Export as PNG" from the context menu to see it.

## App.tsx

```tsx
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 canResize(shape: ICustomShape) {
		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 }} />
	}

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

	// [1]
	override toSvg(shape: ICustomShape, ctx: SvgExportContext) {
		const fill = ctx.isDarkMode ? DARK_FILL : LIGHT_FILL
		return <rect width={shape.props.w} height={shape.props.h} fill={fill} />
	}
}

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 call a shape util's `toSvg` (and
`toBackgroundSvg`) methods. If a shape defines neither, its component is rendered inside a
`<foreignObject>` in the exported SVG instead. That works, but foreignObject content depends
on the viewer's browser and fonts, so a real SVG representation exports more reliably.

For more information on creating a custom shape, check out the custom shape example.

[1]
`toSvg` returns a React element to place in the export in the shape's own coordinate space
(the editor wraps it in a `<g>` with the shape's page transform and opacity). Here a `rect`
matches the HTML component. Read `ctx.isDarkMode` rather than the editor's user preference,
because exports can be requested in either mode regardless of the current UI.

If your shape needs shared resources such as fonts, patterns, or filters, add them once to
the export's `<defs>` with `ctx.addExportDef({ key, getElement })`; defs with the same key
are only added once. Fonts used via `getFontFaces` are embedded automatically. A shape can
also define `toBackgroundSvg` for a layer that exports behind every shape's foreground layer,
as the highlighter shape does.
*/
```

--------

# Custom snapping

Category: Shapes & tools

Keywords: snapping, snap mode, bounds snapping, custom snapping, getboundssnapgeometry, geometry, custom shape, playing cards

Give a custom shape its own snap points with `getBoundsSnapGeometry`.

When shapes are moved in snap mode, they snap to the bounding boxes of nearby shapes by default. A shape util can override `getBoundsSnapGeometry` to return different points, which are used both when this shape is dragged and when other shapes snap against it.

The playing card shape here returns the corners and center of the small square around its top-left suit icon. Cards therefore snap together so that each icon stays visible when they're fanned out, like a hand of cards.

Try dragging one card over another; snap mode is turned on for you in `onMount`, and you can hold cmd/ctrl while dragging to snap when it's off. Use the joker tool in the toolbar (or press `c`) to add more cards.

## 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 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, like 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 tool arrays outside of the component so that they don't change on
every render, which would cause the editor to re-register them.

[2]
Snap mode is off by default; the user can still snap by holding cmd/ctrl while dragging. We turn it
on in the user preferences on mount so the custom snapping is obvious right away.

[3]
This is where we pass all our customisations to the Tldraw component.

    [a] Our custom shape (playing-card-util.tsx) and tool (playing-card-tool.tsx).
    [b] The UI overrides and components (ui-overrides.tsx) that add the tool to the toolbar and
        the keyboard shortcuts dialog.
    [c] Our handleMount function.
    [d] A snapshot so that the editor starts with two cards in it. This isn't necessary, it just
        makes the example clearer at first glance.
*/
```

## ui-overrides.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	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.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>
		)
	},
}

// Same pattern as the custom-config example's ui-overrides.tsx; see the guide there.
```

## 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 click-to-create and drag-to-create for free by extending BaseBoxShapeTool, but we
could 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]
	getIndicatorPath(shape: IPlayingCard) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}
}

/*
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 [6].

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

[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. The validators make sure the store always has
shape data we can trust: width and height are numbers, and suit is a string.

[4]
We lock the aspect ratio so cards keep their proportions when resized.

[5]
getDefaultProps determines what our shape looks like when click-creating one. In this case, we
want the shape to be 270x370 pixels with a random suit.

[6]
This is the important part for custom snapping. getBoundsSnapGeometry returns the points that the
shape snaps to and that other shapes snap against, instead of the default bounding box. Here it's
the corners and center of the square in the top left that contains the suit, the same size as the
span defined in [7]. That's what lets a card snap into place just below or beside another card's
suit icon.

[7]
The component method controls what the shape looks like. It returns a div with the suit in the
center and a span with the suit in the top left. HTMLContainer is a div wrapper that the tldraw
library exports with the css needed to position it correctly.

[8]
getIndicatorPath returns a Path2D for the blue outline that appears around the shape when it's
selected or hovered. tldraw strokes it onto the canvas overlay.
*/
```

--------

# Frame layout modes

Category: Shapes & tools

Keywords: frame, container, layout, grid, spotlight, resize, video, reparent, onChildrenChange, BaseFrameLikeShapeUtil

A frame-like board shape that arranges its children in five swappable layouts.

This example shows how to give one frame-like container several ways to organize what's inside it. The board shape has a `layout` prop, and each mode is a small pure function from the children's boxes to new boxes, so adding an arrangement means adding one entry to a record.

Because a layout returns boxes rather than points, it sizes its children as well as placing them. A row gives every card the same height, a column the same width, and spotlight scales the left-most card up to a hero with the rest as thumbnails beside it. The `free` mode arranges nothing and behaves like a plain frame.

The board re-runs its layout from `onChildrenChange`, so it responds to cards being added, deleted, resized, or restored by undo. Select a board to switch its mode; drag cards between boards and they land wherever you drop them.

For a container that hands layout to the browser instead, see the [flex layout shape](https://tldraw.dev/examples/flex-layout) example.

## App.tsx

```tsx
import {
	BaseFrameLikeShapeUtil,
	Box,
	EASINGS,
	Editor,
	Geometry2d,
	Group2d,
	HTMLContainer,
	RecordProps,
	Rectangle2d,
	T,
	TLComponents,
	TLDragShapesOutInfo,
	TLShape,
	TLShapeId,
	TLShapePartial,
	Tldraw,
	TldrawUiContextualToolbar,
	TldrawUiToolbarButton,
	createShapeId,
	track,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import {
	BOARD_HEADER_HEIGHT,
	BOARD_LAYOUTS,
	BOARD_PADDING,
	BoardLayoutMode,
	arrangeBoard,
} from './BoardLayouts'
import {
	NOTE_CARD_SHAPE_TYPE,
	NoteCardShapeUtil,
	VIDEO_CARD_SHAPE_TYPE,
	VideoCardShapeUtil,
} from './MediaCardShapes'
import './frame-layouts.css'

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

const BOARD_SHAPE_TYPE = 'layout-board'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[BOARD_SHAPE_TYPE]: { w: number; h: number; name: string; layout: BoardLayoutMode }
	}
}

type BoardShape = TLShape<typeof BOARD_SHAPE_TYPE>

// [1]
class LayoutBoardShapeUtil extends BaseFrameLikeShapeUtil<BoardShape> {
	static override type = BOARD_SHAPE_TYPE
	static override props: RecordProps<BoardShape> = {
		w: T.nonZeroNumber,
		h: T.nonZeroNumber,
		name: T.string,
		layout: T.literalEnum('free', 'row', 'column', 'grid', 'spotlight'),
	}

	override getDefaultProps(): BoardShape['props'] {
		return { w: 320, h: 240, name: 'Board', layout: 'free' }
	}

	// [2]
	override canReceiveNewChildrenOfType(shape: BoardShape, type: TLShape['type']) {
		if (shape.isLocked) return false
		return type === VIDEO_CARD_SHAPE_TYPE || type === NOTE_CARD_SHAPE_TYPE
	}

	// [3]
	override canResize(shape: BoardShape) {
		return shape.props.layout === 'free'
	}

	override hideResizeHandles(shape: BoardShape) {
		return shape.props.layout !== 'free'
	}

	override canResizeChildren() {
		return false
	}

	// [4]
	override getGeometry(shape: BoardShape): Geometry2d {
		return new Group2d({
			children: [
				new Rectangle2d({ width: shape.props.w, height: shape.props.h, isFilled: false }),
				new Rectangle2d({
					width: shape.props.w,
					height: BOARD_HEADER_HEIGHT,
					isFilled: true,
					isLabel: true,
				}),
			],
		})
	}

	// [5]
	override onChildrenChange(shape: BoardShape) {
		if (this.editor.isIn('select.translating')) return
		return getBoardLayoutChanges(this.editor, shape)
	}

	// [6]
	override onDropShapesOver(shape: BoardShape) {
		animateBoardLayout(this.editor, shape.id)
	}

	override onDragShapesOut(shape: BoardShape, shapes: TLShape[], info: TLDragShapesOutInfo) {
		super.onDragShapesOut(shape, shapes, info)
		animateBoardLayout(this.editor, shape.id)
	}

	override component(shape: BoardShape) {
		return <BoardComponent shape={shape} />
	}

	override getText(shape: BoardShape) {
		return shape.props.name
	}

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

const EPSILON = 0.01

// [7]
function getBoardLayoutChanges(editor: Editor, board: BoardShape): TLShapePartial[] {
	const children = editor
		.getSortedChildIdsForParent(board.id)
		.map((id) => editor.getShape(id))
		.filter((child): child is TLShape => !!child)
		.map((child) => ({ child, size: editor.getShapeGeometry(child).bounds }))

	const byId = new Map(children.map((entry) => [entry.child.id, entry]))
	const originX = BOARD_PADDING
	const originY = BOARD_HEADER_HEIGHT + BOARD_PADDING

	const result = arrangeBoard(
		board.props.layout,
		children.map(({ child, size }) => ({
			id: child.id,
			x: child.x - originX,
			y: child.y - originY,
			w: size.width,
			h: size.height,
		}))
	)
	if (!result) return []

	const changes: TLShapePartial[] = []

	for (const box of result.boxes) {
		const { child, size } = byId.get(box.id)!
		const x = originX + box.x
		const y = originY + box.y
		const moved = Math.abs(child.x - x) > EPSILON || Math.abs(child.y - y) > EPSILON
		const resized =
			Math.abs(size.width - box.w) > EPSILON || Math.abs(size.height - box.h) > EPSILON
		if (!moved && !resized) continue
		changes.push({
			id: child.id,
			type: child.type,
			x,
			y,
			...(resized && { props: { w: box.w, h: box.h } }),
		} as TLShapePartial)
	}

	if (
		Math.abs(board.props.w - result.w) > EPSILON ||
		Math.abs(board.props.h - result.h) > EPSILON
	) {
		changes.push({ id: board.id, type: board.type, props: { w: result.w, h: result.h } })
	}

	return changes
}

function applyBoardLayout(editor: Editor, boardId: TLShapeId) {
	const board = editor.getShape<BoardShape>(boardId)
	if (board) editor.updateShapes(getBoardLayoutChanges(editor, board))
}

function animateBoardLayout(editor: Editor, boardId: TLShapeId) {
	const board = editor.getShape<BoardShape>(boardId)
	if (!board) return
	editor.animateShapes(getBoardLayoutChanges(editor, board), {
		animation: { duration: 220, easing: EASINGS.easeInOutCubic },
	})
}

function BoardComponent({ shape }: { shape: BoardShape }) {
	const editor = useEditor()
	const count = useValue('card count', () => editor.getSortedChildIdsForParent(shape.id).length, [
		editor,
		shape.id,
	])
	return (
		<HTMLContainer className="layout-board" style={{ width: shape.props.w, height: shape.props.h }}>
			<div className="layout-board__header" style={{ height: BOARD_HEADER_HEIGHT }}>
				<span className="layout-board__name">{shape.props.name}</span>
				<span className="layout-board__badge">
					{BOARD_LAYOUTS[shape.props.layout].label} · {count}
				</span>
			</div>
		</HTMLContainer>
	)
}

// [8]
const BoardLayoutToolbar = track(function BoardLayoutToolbar() {
	const editor = useEditor()
	const board = useValue(
		'selected board',
		() => {
			if (!editor.isIn('select.idle')) return null
			const shape = editor.getOnlySelectedShape()
			return shape?.type === BOARD_SHAPE_TYPE ? (shape as BoardShape) : null
		},
		[editor]
	)

	if (!board) return null

	const setLayout = (layout: BoardLayoutMode) => {
		editor.markHistoryStoppingPoint('change board layout')
		editor.run(() => {
			editor.updateShape({ id: board.id, type: board.type, props: { layout } })
			animateBoardLayout(editor, board.id)
		})
		editor.getContainer().focus()
	}

	const getSelectionBounds = () => {
		const bounds = editor.getSelectionRotatedScreenBounds()
		return bounds ? new Box(bounds.x, bounds.y, bounds.width, 0) : undefined
	}

	return (
		<TldrawUiContextualToolbar getSelectionBounds={getSelectionBounds} label="Board layout">
			{Object.entries(BOARD_LAYOUTS).map(([mode, { label }]) => (
				<TldrawUiToolbarButton
					key={mode}
					type="icon"
					title={label}
					isActive={board.props.layout === mode}
					onClick={() => setLayout(mode as BoardLayoutMode)}
				>
					{label}
				</TldrawUiToolbarButton>
			))}
		</TldrawUiContextualToolbar>
	)
})

const shapeUtils = [LayoutBoardShapeUtil, VideoCardShapeUtil, NoteCardShapeUtil]
const components: TLComponents = { InFrontOfTheCanvas: BoardLayoutToolbar }

// [9]
const video = (url = '/fluid.mp4') => ({ type: VIDEO_CARD_SHAPE_TYPE, props: { url } }) as const
const note = (text: string, color: string) =>
	({ type: NOTE_CARD_SHAPE_TYPE, props: { text, color } }) as const

const DEMO_BOARDS: Array<{
	name: string
	layout: BoardLayoutMode
	x: number
	y: number
	w?: number
	h?: number
	cards: Array<ReturnType<typeof video> | ReturnType<typeof note>>
}> = [
	{
		name: 'Video wall',
		layout: 'grid',
		x: 80,
		y: 100,
		cards: [video(), video('/bonk.webm'), video(), note('Pick a hero shot', '#ffd43b')],
	},
	{
		name: 'Up next',
		layout: 'column',
		x: 860,
		y: 100,
		cards: [video('/bonk.webm'), note('Intro cut', '#b2f2bb'), note('Color pass', '#ffc9c9')],
	},
	{
		name: 'Moodboard',
		layout: 'free',
		x: 1140,
		y: 100,
		w: 460,
		h: 340,
		cards: [video(), note('Loose vibes', '#eebefa')],
	},
	{
		name: 'Filmstrip',
		layout: 'row',
		x: 80,
		y: 560,
		cards: [video(), video('/bonk.webm'), note('End card', '#99e9f2')],
	},
	{
		name: 'Stage',
		layout: 'spotlight',
		x: 860,
		y: 560,
		cards: [video(), video('/bonk.webm'), video(), note('Now playing', '#ffd43b')],
	},
]

function createDemoContent(editor: Editor) {
	for (const { name, layout, cards, x, y, ...size } of DEMO_BOARDS) {
		const id = createShapeId(name)
		editor.createShape({ id, type: BOARD_SHAPE_TYPE, x, y, props: { name, layout, ...size } })
		// Cascaded from the top of the content area, so every layout's position sort agrees
		// with this order and a `free` board still looks hand-placed
		editor.createShapes(
			cards.map((card, i) => ({
				...card,
				parentId: id,
				x: BOARD_PADDING + i * 130,
				y: BOARD_HEADER_HEIGHT + BOARD_PADDING + i * 80,
			}))
		)
		applyBoardLayout(editor, id)
	}

	// A few loose cards, ready to be dragged onto a board
	editor.createShapes([
		{ ...video('/bonk.webm'), x: 80, y: 960 },
		{ ...note('Add captions', '#ffd43b'), x: 340, y: 940 },
		{ ...note('B-roll', '#b2f2bb'), x: 560, y: 1000 },
	])
	editor.zoomToFit()
}

export default function FrameLayoutsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size > 0) return
					createDemoContent(editor)
				}}
			/>
		</div>
	)
}

/*
This example shows one frame-like container arranging the same children in different ways. A
board shape has a `layout` prop, and swapping it swaps the arrangement. The layouts themselves
are pure functions over boxes and live in `BoardLayouts.ts`; this file is the SDK integration.

[1]
BaseFrameLikeShapeUtil gives the board its frame behavior: clipping children, providing their
background, and reparenting shapes in and out as they're dragged over it.

[2]
canReceiveNewChildrenOfType gates what the board picks up. This one takes cards only, so
dragging a drawn shape over it does nothing.

[3]
Only `free` boards are resizable by hand. The arranging layouts size the board to fit their
content, so its handles are hidden.

[4]
An unfilled body plus a filled header. Clicks inside the body pass through to the cards the way
a frame's interior does, while the header stays clickable for selecting and moving the board.
The header rectangle needs `isLabel` for that: frame-like shapes ignore interior fills so that
brush selection works inside them.

[5]
onChildrenChange is the main trigger. It runs whenever a child is added, removed, deleted,
restored by undo, moved, or resized, and whatever it returns gets applied. Re-running the
layout produces no further changes once everything sits in its slot, so this settles in a pass
rather than looping. The one case to skip is an in-progress drag, where correcting positions
would fight the pointer.

[6]
Drags finish through the frame-like callbacks instead: onDropShapesOver when cards land on the
board, onDragShapesOut when one leaves and the rest close the gap. Both animate, and because
every shape here extends BaseBoxShapeUtil, animateShapes tweens size as well as position.

[7]
Turn a layout into store changes: a new position for each card that has drifted from its slot,
new `w`/`h` for cards the layout resized, and a new size for the board so it hugs its content.

[8]
A contextual toolbar for the selected board, built from the same BOARD_LAYOUTS record that
defines the modes.

[9]
Seed a board per mode plus a few loose cards. The cards start on a diagonal and applyBoardLayout
snaps them into place, which is the same path the board takes at runtime.
*/
```

## BoardLayouts.ts

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

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

export const BOARD_PADDING = 16
export const BOARD_GAP = 12
export const BOARD_HEADER_HEIGHT = 36

const EMPTY_WIDTH = 240
const EMPTY_HEIGHT = 168
const CARD_HEIGHT = 120
const CARD_WIDTH = 180
const HERO_HEIGHT = 240
const THUMBNAIL_HEIGHT = 80

export type BoardLayoutMode = 'free' | 'row' | 'column' | 'grid' | 'spotlight'

/** A child's box, relative to the board's content area. */
export interface LayoutBox {
	id: TLShapeId
	x: number
	y: number
	w: number
	h: number
}

export interface BoardLayout {
	label: string
	/** `null` arranges nothing, so the board behaves like a plain frame. */
	arrange: ((children: LayoutBox[]) => { boxes: LayoutBox[]; w: number; h: number }) | null
}

const midX = (box: LayoutBox) => box.x + box.w / 2
const midY = (box: LayoutBox) => box.y + box.h / 2

/** Scale a box to a target height or width, keeping its aspect ratio. */
const toHeight = (box: LayoutBox, h: number) => ({ ...box, w: (box.w / box.h) * h, h })
const toWidth = (box: LayoutBox, w: number) => ({ ...box, w, h: (box.h / box.w) * w })

// [1]
export const BOARD_LAYOUTS: Record<BoardLayoutMode, BoardLayout> = {
	free: {
		label: 'Free',
		arrange: null,
	},
	// [2]
	row: {
		label: 'Row',
		arrange(children) {
			let x = 0
			const boxes = [...children]
				.sort((a, b) => midX(a) - midX(b))
				.map((box) => {
					const next = { ...toHeight(box, CARD_HEIGHT), x, y: 0 }
					x += next.w + BOARD_GAP
					return next
				})
			return { boxes, w: x - BOARD_GAP, h: CARD_HEIGHT }
		},
	},
	column: {
		label: 'Column',
		arrange(children) {
			let y = 0
			const boxes = [...children]
				.sort((a, b) => midY(a) - midY(b))
				.map((box) => {
					const next = { ...toWidth(box, CARD_WIDTH), x: 0, y }
					y += next.h + BOARD_GAP
					return next
				})
			return { boxes, w: CARD_WIDTH, h: y - BOARD_GAP }
		},
	},
	grid: {
		label: 'Grid',
		arrange(children) {
			const cells = children.map((box) => toHeight(box, CARD_HEIGHT))
			const cellW = Math.max(...cells.map((box) => box.w))
			// Read the cards in rows: group them into horizontal bands, then left to right
			const band = (box: LayoutBox) => Math.round(midY(box) / (CARD_HEIGHT + BOARD_GAP))
			const sorted = cells.sort((a, b) => band(a) - band(b) || midX(a) - midX(b))
			const columns = Math.ceil(Math.sqrt(sorted.length))
			const rows = Math.ceil(sorted.length / columns)
			const boxes = sorted.map((box, i) => ({
				...box,
				x: (i % columns) * (cellW + BOARD_GAP) + (cellW - box.w) / 2,
				y: Math.floor(i / columns) * (CARD_HEIGHT + BOARD_GAP),
			}))
			return {
				boxes,
				w: columns * cellW + (columns - 1) * BOARD_GAP,
				h: rows * CARD_HEIGHT + (rows - 1) * BOARD_GAP,
			}
		},
	},
	spotlight: {
		label: 'Spotlight',
		arrange(children) {
			const [first, ...rest] = [...children].sort((a, b) => midX(a) - midX(b))
			const hero = toHeight(first, HERO_HEIGHT)
			const thumbnails = rest
				.sort((a, b) => midY(a) - midY(b))
				.map((box) => toHeight(box, THUMBNAIL_HEIGHT))

			const stackH =
				thumbnails.length * THUMBNAIL_HEIGHT + Math.max(0, thumbnails.length - 1) * BOARD_GAP
			const h = Math.max(HERO_HEIGHT, stackH)
			const stackW = Math.max(0, ...thumbnails.map((box) => box.w))

			let y = (h - stackH) / 2
			const boxes = [{ ...hero, x: 0, y: (h - HERO_HEIGHT) / 2 }]
			for (const thumbnail of thumbnails) {
				boxes.push({ ...thumbnail, x: hero.w + BOARD_GAP, y })
				y += thumbnail.h + BOARD_GAP
			}

			return { boxes, w: hero.w + (thumbnails.length ? BOARD_GAP + stackW : 0), h }
		},
	},
}

// [3]
export function arrangeBoard(mode: BoardLayoutMode, children: LayoutBox[]) {
	const { arrange } = BOARD_LAYOUTS[mode]
	if (!arrange) return null
	const { boxes, w, h } = children.length ? arrange(children) : { boxes: [], w: 0, h: 0 }
	return {
		boxes,
		w: Math.max(EMPTY_WIDTH, w + BOARD_PADDING * 2),
		h: Math.max(EMPTY_HEIGHT, h + BOARD_HEADER_HEIGHT + BOARD_PADDING * 2),
	}
}

/*
This file is the layout engine, and it never touches the editor. A layout takes the boxes of
a board's children and returns where they should go, which is why the same code arranges
video cards, note cards, or any other shape the board accepts.

[1]
Each mode is one entry in a record: a label plus a function from boxes to boxes. Adding a
mode (masonry, ring, timeline) means adding an entry here and a value to the board's `layout`
prop validator.

Every mode sorts the cards by their current position before assigning slots, so wherever you
drop a card is where it lands in the order. There's no separate index to keep in sync.

[2]
Because a layout returns whole boxes rather than points, it sizes its children as well as
placing them, and each mode decides what that means: a row gives every card the same height,
a column the same width, and spotlight scales the left-most card up to a hero and the rest
down to thumbnails. Drop a card to the left of the hero to promote it.

Sizes come from constants rather than from the cards, so switching modes lands on the same
result every time instead of compounding. The trade-off is that hand-resizing a card only
sticks on a `free` board, where nothing else owns its size.

[3]
Arrange the children and add the board's padding and header back, with a minimum size so an
empty board is still a usable drop target. Returns `null` for `free`, which arranges nothing.
*/
```

## MediaCardShapes.tsx

```tsx
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape } from 'tldraw'

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

export const VIDEO_CARD_SHAPE_TYPE = 'video-card'
export const NOTE_CARD_SHAPE_TYPE = 'media-note-card'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[VIDEO_CARD_SHAPE_TYPE]: { w: number; h: number; url: string }
		[NOTE_CARD_SHAPE_TYPE]: { w: number; h: number; text: string; color: string }
	}
}

export type VideoCardShape = TLShape<typeof VIDEO_CARD_SHAPE_TYPE>
export type NoteCardShape = TLShape<typeof NOTE_CARD_SHAPE_TYPE>

// [1]
export class VideoCardShapeUtil extends BaseBoxShapeUtil<VideoCardShape> {
	static override type = VIDEO_CARD_SHAPE_TYPE
	static override props: RecordProps<VideoCardShape> = {
		w: T.nonZeroNumber,
		h: T.nonZeroNumber,
		url: T.string,
	}

	override getDefaultProps(): VideoCardShape['props'] {
		return { w: 192, h: 108, url: '/fluid.mp4' }
	}

	// [2]
	override isAspectRatioLocked() {
		return true
	}

	override component(shape: VideoCardShape) {
		return (
			<HTMLContainer
				className="media-card media-card--video"
				style={{ width: shape.props.w, height: shape.props.h }}
			>
				<video src={shape.props.url} autoPlay muted loop playsInline />
			</HTMLContainer>
		)
	}

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

export class NoteCardShapeUtil extends BaseBoxShapeUtil<NoteCardShape> {
	static override type = NOTE_CARD_SHAPE_TYPE
	static override props: RecordProps<NoteCardShape> = {
		w: T.nonZeroNumber,
		h: T.nonZeroNumber,
		text: T.string,
		color: T.string,
	}

	override getDefaultProps(): NoteCardShape['props'] {
		return { w: 144, h: 96, text: 'Note', color: '#ffd43b' }
	}

	override component(shape: NoteCardShape) {
		return (
			<HTMLContainer
				className="media-card media-card--note"
				style={{
					width: shape.props.w,
					height: shape.props.h,
					backgroundColor: shape.props.color,
				}}
			>
				{shape.props.text}
			</HTMLContainer>
		)
	}

	override getText(shape: NoteCardShape) {
		return shape.props.text
	}

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

/*
Two shape types for the board to organize, with different default sizes so you can see how
each layout handles a mix. Neither knows anything about the board: the board reads their
geometry and moves them, so any shape type it accepts works the same way.

[1]
Both extend BaseBoxShapeUtil, which gives them `w`/`h` geometry, resize handles, and a
`getInterpolatedProps` that tweens size. That last one is what lets the board animate a card
to a new size rather than snapping it.

[2]
The video keeps its aspect ratio when you resize it by hand, and the layouts scale cards
proportionally, so it never stretches.
*/
```

## frame-layouts.css

```css
.layout-board {
	box-sizing: border-box;
	background-color: var(--tl-color-low);
	border: 1px solid var(--tl-color-divider);
	border-radius: 10px;
}

.layout-board__header {
	box-sizing: border-box;
	display: flex;
	align-items: center;
	justify-content: space-between;
	gap: 8px;
	padding: 0 12px;
	background-color: var(--tl-color-panel);
	border-bottom: 1px solid var(--tl-color-divider);
	border-radius: 10px 10px 0 0;
	font: var(--tl-font-body);
	font-size: 13px;
}

.layout-board__name {
	font-weight: 500;
	color: var(--tl-color-text-1);
	overflow: hidden;
	white-space: nowrap;
	text-overflow: ellipsis;
}

.layout-board__badge {
	flex-shrink: 0;
	font-size: 11px;
	color: var(--tl-color-text-3);
	background-color: var(--tl-color-muted-2);
	border-radius: 99px;
	padding: 2px 8px;
	white-space: nowrap;
}

.media-card {
	box-sizing: border-box;
	border-radius: 8px;
	overflow: hidden;
	box-shadow: var(--tl-shadow-1);
}

.media-card--video {
	background-color: var(--tl-color-text);
}

.media-card--video video {
	display: block;
	width: 100%;
	height: 100%;
	object-fit: cover;
	pointer-events: none;
}

.media-card--note {
	display: grid;
	place-items: center;
	padding: 8px;
	text-align: center;
	font: var(--tl-font-body);
	font-size: 13px;
	color: hsl(0, 0%, 15%);
}
```

--------

# Shape that accepts dropped files

Category: Shapes & tools

Keywords: drop, drag and drop, files, image, custom shape, html, ondrop, upload

A custom shape with its own drop zone that shows an image dropped onto it.

Dropping a file onto the canvas normally creates an image or video shape. A shape can claim drops for itself instead: set `pointer-events: all` on its `HTMLContainer`, then handle React's `onDragOver` and `onDrop` on the element and call `stopPropagation()` so the canvas doesn't also handle the file.

Try dragging an image file from your desktop onto the dashed box. The image is kept in memory only, so it's not persisted or synced; a real app would upload the file and store a URL in the shape's props. See `drop-zone-shape-util.tsx` for the shape.

## App.tsx

```tsx
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import { DropZoneShapeUtil } from './drop-zone-shape-util'
import './drop-zone-shape.css'

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

// [1]
const customShapeUtils = [DropZoneShapeUtil]

export default function DropZoneShapeExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={customShapeUtils}
				onMount={(editor) => {
					editor.createShape({ type: 'drop-zone', x: 100, y: 100 })
				}}
			/>
		</div>
	)
}

/*
[1]
The shape util array is defined outside the component so it keeps the same identity across
renders. See drop-zone-shape-util.tsx for the shape itself, which shows how to let a shape
accept dropped files instead of the canvas.
*/
```

## drop-zone-shape-util.tsx

```tsx
import { useEffect, useState } from 'react'
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape } from 'tldraw'

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

const DROP_ZONE_SHAPE_TYPE = 'drop-zone'

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

export type IDropZoneShape = TLShape<typeof DROP_ZONE_SHAPE_TYPE>

export class DropZoneShapeUtil extends BaseBoxShapeUtil<IDropZoneShape> {
	static override type = DROP_ZONE_SHAPE_TYPE
	static override props: RecordProps<IDropZoneShape> = {
		w: T.number,
		h: T.number,
	}

	getDefaultProps(): IDropZoneShape['props'] {
		return { w: 300, h: 300 }
	}

	component(shape: IDropZoneShape) {
		return <DropZone shape={shape} />
	}

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

function DropZone({ shape }: { shape: IDropZoneShape }) {
	// [1]
	const [imageUrl, setImageUrl] = useState<string | null>(null)
	const [isDragOver, setIsDragOver] = useState(false)

	useEffect(() => {
		if (!imageUrl) return
		return () => URL.revokeObjectURL(imageUrl)
	}, [imageUrl])

	return (
		<HTMLContainer
			className={`drop-zone ${isDragOver ? 'drop-zone__over' : ''}`}
			style={{ width: shape.props.w, height: shape.props.h }}
			// [2]
			onDragOver={(e) => {
				e.preventDefault()
				e.stopPropagation()
				setIsDragOver(true)
			}}
			onDragLeave={() => setIsDragOver(false)}
			onDrop={(e) => {
				e.preventDefault()
				e.stopPropagation()
				setIsDragOver(false)
				// [3]
				const file = Array.from(e.dataTransfer.files).find((f) => f.type.startsWith('image/'))
				if (file) setImageUrl(URL.createObjectURL(file))
			}}
		>
			{imageUrl ? <img src={imageUrl} alt="" /> : <span>Drop an image here</span>}
		</HTMLContainer>
	)
}

/*
This is a custom shape, for a more in-depth look at how to create a custom shape,
see our custom shape example.

[1]
The dropped image lives in component state only, so it isn't persisted or synced and
disappears if the shape remounts. A real app would upload the file and store a URL in the
shape's props instead.

[2]
The shape's container has `pointer-events: all` (see drop-zone-shape.css) so it receives
drag events at all. The browser only fires `drop` on an element whose `dragover` called
`preventDefault`, and `stopPropagation` keeps the canvas from also handling the file and
creating an image shape from it.

[3]
Only the first image file is used; anything else dropped on the shape is ignored.
*/
```

## drop-zone-shape.css

```css
.drop-zone {
	pointer-events: all;
	display: flex;
	align-items: center;
	justify-content: center;
	overflow: hidden;
	border: 2px dashed var(--tl-color-text-3);
	border-radius: 8px;
	background-color: var(--tl-color-background);
	color: var(--tl-color-text-1);
	font-family: var(--tl-font-sans);
	font-size: 14px;
}

.drop-zone__over {
	border-color: var(--tl-color-selected);
	border-style: solid;
}

.drop-zone img {
	width: 100%;
	height: 100%;
	object-fit: contain;
	pointer-events: none;
}
```

--------

# Stamp tool

Category: Shapes & tools

Keywords: stamp, emoji, custom tool, statenode, assets, image shape, png, toppanel, picker, sticker, upload, drag

Pick an emoji or upload an image, then click or drag on the canvas to stamp it as image shapes.

This example builds a stamp tool from a custom `StateNode`. A panel in the `TopPanel` slot lists the available stamps — clicking one activates the tool, and each click on the canvas places a stamp centered on the pointer. Holding the pointer down and dragging lays a trail of stamps spaced by the stamp size, and the whole drag undoes as a single step.

Every stamp is placed as an image shape backed by a shared asset created with `editor.createAssets`. Emoji stamps are drawn once to a PNG using a canvas element, which keeps them consistent in exports and across platforms; stamping the same stamp many times reuses a single asset.

The stamp options are plain data in an `atom` — to ship a new default stamp, add an entry to the array. The panel's upload button shows the runtime version: it reads an image file as a data URL, adds it as a new stamp option, and activates the tool with it.

## App.tsx

```tsx
import {
	AssetRecordType,
	DEFAULT_SUPPORTED_IMAGE_TYPES,
	Editor,
	FileHelpers,
	MediaHelpers,
	StateNode,
	TLAssetId,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	Vec,
	VecLike,
	atom,
	track,
	uniqueId,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './stamp-tool.css'

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

const STAMP_SIZE = 64
const STAMP_SPACING = STAMP_SIZE
const PNG_SIZE = 128

// [1]
type Stamp =
	| { type: 'emoji'; emoji: string }
	| { type: 'image'; id: string; src: string; w: number; h: number; mimeType: string }

const stamps = atom<Stamp[]>('stamps', [
	{ type: 'emoji', emoji: '👍' },
	{ type: 'emoji', emoji: '❤️' },
	{ type: 'emoji', emoji: '🔥' },
	{ type: 'emoji', emoji: '⭐' },
	{ type: 'emoji', emoji: '😂' },
	{ type: 'emoji', emoji: '🎉' },
])
const currentStamp = atom<Stamp>('current stamp', stamps.get()[0])

function getStampId(stamp: Stamp) {
	return stamp.type === 'emoji'
		? 'emoji-' +
				Array.from(stamp.emoji)
					.map((char) => char.codePointAt(0)!.toString(16))
					.join('-')
		: stamp.id
}

// [2]
class StampTool extends StateNode {
	static override id = 'stamp'

	lastStampPoint = new Vec()

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

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

	override onPointerDown() {
		this.editor.markHistoryStoppingPoint('stamping')
		this.stamp()
	}

	// [3]
	override onPointerMove() {
		if (!this.editor.inputs.getIsPointing()) return
		const distance = Vec.Dist(this.editor.inputs.getCurrentPagePoint(), this.lastStampPoint)
		if (distance < STAMP_SPACING) return
		this.stamp()
	}

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

	private stamp() {
		const point = this.editor.inputs.getCurrentPagePoint()
		this.lastStampPoint = Vec.From(point)
		stampAtPoint(this.editor, point, currentStamp.get())
	}
}

function renderEmojiToPng(emoji: string) {
	const canvas = document.createElement('canvas')
	canvas.width = PNG_SIZE
	canvas.height = PNG_SIZE
	const ctx = canvas.getContext('2d')!
	ctx.font = `${PNG_SIZE * 0.8}px sans-serif`
	ctx.textAlign = 'center'
	ctx.textBaseline = 'middle'
	ctx.fillText(emoji, PNG_SIZE / 2, PNG_SIZE / 2 + PNG_SIZE * 0.05)
	return {
		src: canvas.toDataURL('image/png'),
		w: PNG_SIZE,
		h: PNG_SIZE,
		mimeType: 'image/png',
	}
}

// [4]
function getStampAssetId(editor: Editor, stamp: Stamp): TLAssetId {
	const assetId = AssetRecordType.createId(getStampId(stamp))
	if (editor.getAsset(assetId)) return assetId

	const { src, w, h, mimeType } = stamp.type === 'emoji' ? renderEmojiToPng(stamp.emoji) : stamp

	editor.createAssets([
		{
			id: assetId,
			type: 'image',
			typeName: 'asset',
			props: { name: 'stamp', src, w, h, mimeType, isAnimated: false },
			meta: {},
		},
	])
	return assetId
}

// [5]
function stampAtPoint(editor: Editor, point: VecLike, stamp: Stamp) {
	let w = STAMP_SIZE
	let h = STAMP_SIZE
	if (stamp.type === 'image') {
		const scale = STAMP_SIZE / Math.max(stamp.w, stamp.h)
		w = stamp.w * scale
		h = stamp.h * scale
	}

	editor.run(() => {
		const assetId = getStampAssetId(editor, stamp)
		editor.createShape({
			type: 'image',
			x: point.x - w / 2,
			y: point.y - h / 2,
			props: { assetId, w, h },
		})
	})
}

// [6]
function uploadStamp(editor: Editor) {
	const input = document.createElement('input')
	input.type = 'file'
	input.accept = DEFAULT_SUPPORTED_IMAGE_TYPES.join(',')
	input.addEventListener('change', async (e) => {
		const file = (e.target as HTMLInputElement).files?.[0]
		if (!file) return

		const src = await FileHelpers.blobToDataUrl(file)
		const { w, h } = await MediaHelpers.getImageSize(file)
		const stamp: Stamp = { type: 'image', id: uniqueId(), src, w, h, mimeType: file.type }

		stamps.update((s) => [...s, stamp])
		currentStamp.set(stamp)
		editor.setCurrentTool('stamp')
	})
	input.click()
}

// [7]
const StampPanel = track(() => {
	const editor = useEditor()
	const isStampToolActive = editor.getCurrentToolId() === 'stamp'
	const currentStampId = getStampId(currentStamp.get())

	return (
		<div className="tlui-menu stamp-panel">
			{stamps.get().map((stamp) => (
				<TldrawUiButton
					key={getStampId(stamp)}
					type="icon"
					className="stamp-panel-button"
					data-active={isStampToolActive && currentStampId === getStampId(stamp)}
					onClick={() => {
						currentStamp.set(stamp)
						editor.setCurrentTool('stamp')
					}}
				>
					{stamp.type === 'emoji' ? (
						stamp.emoji
					) : (
						<img className="stamp-panel-thumbnail" src={stamp.src} alt="custom stamp" />
					)}
				</TldrawUiButton>
			))}
			<TldrawUiButton
				type="icon"
				className="stamp-panel-button stamp-panel-upload"
				title="Upload a stamp"
				onClick={() => uploadStamp(editor)}
			>
				+
			</TldrawUiButton>
		</div>
	)
})

const components: TLComponents = {
	TopPanel: StampPanel,
}

const tools = [StampTool]

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

/*
This example shows how to build a stamp tool: pick a stamp from a panel, then
click the canvas to place it, or hold and drag to lay down a trail of stamps.
Each stamp is placed as an image shape — emoji stamps are rendered to a PNG,
and you can also upload your own image to use as a stamp.

[1]
Stamps are plain data held in an `atom` from tldraw's signals library: either
an emoji, or an uploaded image with a data URL source. This is the extension
point — to ship a new default stamp, add an entry to the array. Because the
panel reads the atom inside a `track`ed component, stamps added at runtime
(see [6]) show up automatically.

[2]
The stamp tool is a `StateNode`, the same state machine primitive tldraw's own
tools are built from. It sets a crosshair cursor while active and stamps at
the click point on pointer down. The tool stays active after stamping so you
can stamp repeatedly; pressing Escape cancels back to the select tool.

[3]
Dragging stamps a trail: on each pointer move while pointing, the tool places
the next stamp once the pointer has travelled far enough from the last one.
Distance is measured in page space, so trail density stays consistent at any
zoom level. The history stopping point is marked once on pointer down, so a
whole drag is a single undo step.

[4]
Every stamp becomes a shared image asset, created once via
`editor.createAssets`. Emoji are drawn to a PNG with a canvas element, so
stamps look identical in exports and for collaborators regardless of platform
emoji fonts. The asset id is derived from the stamp's id, so stamping the
same stamp twice reuses one asset.

[5]
Stamping creates an image shape centered on the pointer, linked to the asset.
Uploaded images are scaled to fit the stamp size while keeping their aspect
ratio.

[6]
The upload button opens a file picker and adds the chosen image as a new
stamp option. The image is stored as a data URL so stamps survive in the
document; the new stamp is selected and the tool activated right away.

[7]
The picker panel goes in the `TopPanel` component slot. Clicking a stamp sets
the current stamp atom and switches to the stamp tool. The active stamp is
highlighted by checking `editor.getCurrentToolId()`.
*/
```

## stamp-tool.css

```css
.stamp-panel {
	display: flex;
	align-items: center;
	gap: 2px;
	margin: 8px;
	padding: 4px;
}

.stamp-panel-button {
	font-size: 18px;
}

.stamp-panel-button[data-active='true'] {
	background: var(--tl-color-muted-2);
}

.stamp-panel-thumbnail {
	width: 22px;
	height: 22px;
	object-fit: contain;
}

.stamp-panel-upload {
	color: var(--tl-color-text-3);
}
```

--------

# Custom validators for shape props

Category: Shapes & tools

Keywords: validation, validators, check, refine, constraints, props, shapeutil, recordprops, error handling

Add constraints to shape props with the `.check()` and `.refine()` validator methods.

Shape props are validated whenever a shape record is written to the store. The validators from `T` (re-exported from `@tldraw/validate`) can be extended: `.check(name, fn)` adds a step that throws on invalid input without changing the value, and `.refine(fn)` returns a new value, so it can transform as well as validate.

The example shape has two constrained props:

- `percentage` chains two `.check()` calls so values below 0 or above 100 throw. The check name appears in the error message.
- `rating` uses `.refine()` to clamp values into the 1-5 range instead of rejecting them.

On load, the example creates a valid shape, then tries to create one with `percentage: 150` (which throws; see the browser console), then creates one with `rating: 10` (which succeeds and is stored as 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.number
		.check('min-value', (value) => {
			if (value < 0) throw new Error('Percentage cannot be negative')
		})
		.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>
		)
	}

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

// [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 },
					})
				}}
			/>
		</div>
	)
}

/*
[1]
Extend TLGlobalShapePropsMap to register your custom shape's props with the type system.

[2]
Define validators for each prop. `T.positiveNumber` already rejects negative sizes; the other
two add constraints of their own.

[3]
`.check()` adds a validation step without changing the value: the function throws for invalid
input and returns nothing. Checks chain, and the name (e.g. 'max-value') is included in the
error message so you can tell which one failed.

[4]
`.refine()` returns a new value, so it can transform as well as validate. Here it clamps the
rating to 1-5 instead of throwing. The store keeps the refined value, not the one you passed in.

[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]
Creating a shape with `percentage: 150` fails the 'max-value' check. Validation runs when the
record is written to the store, so `createShape` throws. Open the browser console to see the
error message.

[8]
Creating a shape with `rating: 10` succeeds because `.refine()` clamps it: the shape on the
canvas shows a rating of 5.
*/
```

--------

# Programmatic text shape creation

Category: Shapes & tools

Keywords: text shape, create text, programmatic, autoSize, font, textAlign, richText, toRichText, bold, marks, formatting, createShape

Create text shapes with `editor.createShape`, covering auto-size, fixed width, alignment, fonts, and rich text marks.

Text shapes store their content as rich text, so pass `toRichText('...')` for plain strings or build the document with marks for formatting like bold. The example creates five shapes on mount:

- Auto-sized text (`autoSize: true`) that grows to fit its content
- Fixed-width text (`autoSize: false`, `w`) that wraps
- Center-aligned text (`textAlign: 'middle'`)
- Bold text using a `bold` mark
- Monospace text (`font: 'mono'`)

Double-click any of them to edit and see the same options in the style panel.

## App.tsx

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

export default function TextShapeConfigurationExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [1]
					editor.createShape({
						type: 'text',
						x: 100,
						y: 100,
						props: {
							richText: toRichText('Auto-sized text'),
							size: 'l',
							color: 'blue',
							autoSize: true,
						},
					})

					// [2]
					editor.createShape({
						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({
						type: 'text',
						x: 100,
						y: 400,
						props: {
							richText: toRichText('Center aligned'),
							size: 's',
							color: 'red',
							textAlign: 'middle',
							w: 200,
							autoSize: false,
						},
					})

					// [4]
					editor.createShape({
						type: 'text',
						x: 100,
						y: 500,
						props: {
							richText: {
								type: 'doc',
								content: [
									{
										type: 'paragraph',
										content: [{ type: 'text', text: 'Bold text', marks: [{ type: 'bold' }] }],
									},
								],
							},
							size: 'xl',
							color: 'orange',
							autoSize: true,
						},
					})

					// [5]
					editor.createShape({
						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>
	)
}

/*
Text shapes store their content as rich text (a TipTap/ProseMirror document), so the
`richText` prop takes a TLRichText object rather than a string. `toRichText()` converts
a plain string; for formatting, build the document yourself as in [4].

[1]
An auto-sized text shape (autoSize: true, the default) grows its width to fit the content.
Any `w` you pass is ignored.

[2]
With autoSize: false the shape keeps the given `w` and wraps text inside it. There is no
`h` prop; the height is measured from the wrapped content.

[3]
textAlign controls horizontal alignment within the shape's width: 'start', 'middle', or
'end'. It only has a visible effect on fixed-width shapes, since an auto-sized shape is
exactly as wide as its text.

[4]
Formatting is expressed with marks on text nodes. Marks available in the default rich text
extensions include 'bold', 'italic', 'code', 'strike', 'underline', 'link', and
'highlight'.

[5]
The font style is 'draw', 'sans', 'serif', or 'mono'; size is 's', 'm', 'l', or 'xl'.
These are tldraw's default style props, so the style panel shows and edits them when the
shape is selected.
*/
```

--------

# Data grid shape

Category: Shapes & tools

Keywords: custom shape, shapeutil, baseboxshapeutil, ag grid, data grid, table, spreadsheet, canedit, canscroll, usedelaysvgexport

Embed an AG Grid data table inside a custom shape.

The `AgGridShapeUtil` extends `BaseBoxShapeUtil` and renders an `AgGridReact` component sized to the shape. Two overrides make the grid usable on the canvas: `canEdit` so double-clicking enters the editing state, which is when the shape turns on pointer events for the grid's filters and sorting, and `canScroll` so wheel events over the shape scroll the rows instead of panning while it's being edited.

Because AG Grid renders asynchronously, the shape uses `useDelaySvgExport` and resolves it from `onGridReady`, so exporting the shape as an image waits until the rows are actually on screen.

Try double-clicking the grid, then sorting a column or typing in a filter. Press Escape to leave editing mode and drag the shape around like any other.

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

	// [1]
	override canScroll(): boolean {
		return true
	}

	override canEdit(): boolean {
		return true
	}

	override getDefaultProps() {
		return {
			w: 300,
			h: 200,
			rowData: [],
			columnDefs: [],
		}
	}

	override component(shape: AgGridShape) {
		// [2]
		const isEditing = this.editor.getEditingShapeId() === shape.id
		// [3]
		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}
				/>
			</div>
		)
	}

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

const shapeUtils = [AgGridShapeUtil]

export default function DataGridExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="ag-grid-example"
				shapeUtils={shapeUtils}
				onMount={(editor) => {
					// [4]
					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>
	)
}

/*
[1]
`canEdit` lets the shape enter the editing state on double-click, which is when we turn on
pointer events so the grid's filters and sorting are usable. While the shape is being edited,
`canScroll` lets wheel events reach the grid so it scrolls its own rows instead of panning
the canvas.

[2]
Reading `getEditingShapeId()` in the component re-renders the shape when editing starts or stops.

[3]
AG Grid renders its rows asynchronously. `useDelaySvgExport` returns a callback that
holds up SVG/image export until it's called, so we wire it to `onGridReady` and exports
don't capture an empty grid.

[4]
The example uses a `persistenceKey`, so the shape survives reloads. Using a fixed id
lets us skip creating a second grid when one already exists.
*/
```

--------

# Drag and drop shape

Category: Shapes & tools

Keywords: reparent, ondragshapesin, ondragshapesout, parent, children, shape hierarchy, baseframelikeshapeutil, canreceivenewchildrenoftype, canremovechildrenoftype

Build a container shape that accepts dropped shapes with `BaseFrameLikeShapeUtil`.

`BaseFrameLikeShapeUtil` gives a custom shape the same drag-and-drop behaviour as the built-in frame: shapes dragged onto it become its children (`onDragShapesIn`), shapes dragged out return to the page (`onDragShapesOut`), and children are clipped to its geometry. Two hooks control what's allowed: `canReceiveNewChildrenOfType` decides which shape types can be dropped in, and `canRemoveChildrenOfType` decides which children can be dragged back out.

The grid shape here accepts only the red counter shapes and never lets them leave. Try dragging a counter onto the grid, then try dragging it back out: it stays a child and is clipped at the grid's edge. Draw a geo shape and drag it over the grid to see it rejected.

## App.tsx

```tsx
import {
	BaseFrameLikeShapeUtil,
	Circle2d,
	Geometry2d,
	Group2d,
	HTMLContainer,
	Rectangle2d,
	ShapeUtil,
	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]: { w: number; h: number }
		[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(shape: MyCounterShape) {
		return false
	}
	override hideResizeHandles(shape: MyCounterShape) {
		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%',
				}}
			/>
		)
	}

	getIndicatorPath() {
		const path = new Path2D()
		path.arc(SLOT_SIZE / 2 - 10, SLOT_SIZE / 2 - 10, SLOT_SIZE / 2 - 10, 0, Math.PI * 2)
		return path
	}
}

// [4]
class MyGridShapeUtil extends BaseFrameLikeShapeUtil<MyGridShape> {
	static override type = MY_GRID_SHAPE_TYPE

	getDefaultProps(): MyGridShape['props'] {
		return {
			w: SLOT_SIZE * 5,
			h: SLOT_SIZE * 2,
		}
	}

	// Frame-like shapes must return a Group2d: the editor's hit testing walks its children.
	override getGeometry(shape: MyGridShape): Geometry2d {
		return new Group2d({
			children: [new Rectangle2d({ width: shape.props.w, height: shape.props.h, isFilled: true })],
		})
	}

	override canResize(_shape: MyGridShape) {
		return false
	}

	override hideResizeHandles(_shape: MyGridShape) {
		return true
	}

	// [5]
	override canReceiveNewChildrenOfType(_shape: MyGridShape, type: TLShape['type']) {
		return type === MY_COUNTER_SHAPE_TYPE
	}

	// [6]
	override canRemoveChildrenOfType(_shape: MyGridShape, type: TLShape['type']) {
		return type !== MY_COUNTER_SHAPE_TYPE
	}

	// [7]
	component(shape: MyGridShape) {
		return (
			<HTMLContainer
				style={{
					backgroundColor: '#efefef',
					borderRight: '1px solid #ccc',
					borderBottom: '1px solid #ccc',
					backgroundSize: `${SLOT_SIZE}px ${SLOT_SIZE}px`,
					width: shape.props.w,
					height: shape.props.h,
					backgroundImage: `
						linear-gradient(to right, #ccc 1px, transparent 1px),
						linear-gradient(to bottom, #ccc 1px, transparent 1px)
					`,
				}}
			/>
		)
	}

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

const shapeUtils = [MyGridShapeUtil, MyCounterShapeUtil]

export default function DragAndDropExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				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 extend TLGlobalShapePropsMap to add our shapes' props to the global type system. The grid
has a width and height; the counter has no props at all, so we use Record<string, never>.

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

[3]
The counter is a plain ShapeUtil with fixed size: resizing is disabled and the geometry is a filled
Circle2d, so hit-testing follows the circle rather than its bounding box.

[4]
The grid extends BaseFrameLikeShapeUtil, which provides everything a container needs: it reparents
shapes dropped onto it in onDragShapesIn, reparents them back to the page in onDragShapesOut, clips
its children to its geometry, and treats itself as a frame for selection and erasing.

[5]
canReceiveNewChildrenOfType gates which shape types can be dropped in. The editor only calls
onDragShapesIn for shapes that pass this check. Here only counters are accepted, so dragging a geo
shape over the grid does nothing.

[6]
canRemoveChildrenOfType gates which children can be dragged out. When it returns false the editor
doesn't call onDragShapesOut and doesn't reparent the child when it's moved outside the parent's
geometry, so counters are pinned to the grid once dropped.

[7]
The grid draws its slots with CSS gradients. Because BaseFrameLikeShapeUtil clips children to the
grid's geometry, a pinned counter dragged past the edge stays a child and is clipped at the border,
which makes it obvious that it still belongs to the grid.
*/
```

--------

# Portal shapes

Category: Shapes & tools

Keywords: frame, portal, BaseFrameLikeShapeUtil, reparent, drag

Frame-like shapes built on `BaseFrameLikeShapeUtil` that teleport dropped shapes to a linked portal.

`BaseFrameLikeShapeUtil` gives a custom box shape everything the built-in frame does: it clips children to the shape's geometry, accepts shapes dragged into it, and releases shapes dragged out. Here the geometry is an ellipse, so children clip to an oval, and `onDropShapesOver` is overridden so that dropping shapes into one portal reparents them into the other portal at the same local offset.

Try dragging the companion cube into the blue portal and watch it come out of the orange one. Resize a portal to see its children clip to the new oval.

## App.tsx

```tsx
import { createShapeId, TLContent, TLRichText, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import companionCube from './companion-cube.json'
import { PortalShapeUtil } from './PortalShapeUtil'

// [1]
const shapeUtils = [PortalShapeUtil]

const tagline: TLRichText = {
	type: 'doc',
	content: [
		{
			type: 'paragraph',
			content: [
				{ type: 'text', text: "Now you're thinking with " },
				{ type: 'text', marks: [{ type: 'strike' }], text: 'portals' },
				{ type: 'text', text: ' frames' },
			],
		},
	],
}

export default function PortalShapesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				onMount={(editor) => {
					// [2]
					editor.createShapes([
						{
							id: createShapeId('blue-portal'),
							type: 'portal',
							x: 100,
							y: 150,
							props: { w: 200, h: 300, color: 'blue' },
						},
						{
							id: createShapeId('orange-portal'),
							type: 'portal',
							x: 500,
							y: 150,
							props: { w: 200, h: 300, color: 'orange' },
						},
					])

					editor.createShape({
						type: 'text',
						x: 100,
						y: 500,
						props: { size: 'l', richText: tagline },
					})

					// [3]
					editor.putContentOntoCurrentPage(companionCube as unknown as TLContent, {
						point: { x: 300, y: 20 },
					})
					editor.selectNone()

					editor.zoomToFit({ animation: { duration: 0 } })
					editor.zoomOut(undefined, { animation: { duration: 0 } })
				}}
			/>
		</div>
	)
}

/*
[1]
The shape util array is defined outside the component so it keeps the same identity across
renders.

[2]
Create a pair of linked portals, one blue and one orange. They find each other by color, so
only one of each should exist on a page.

[3]
The companion cube is a group of shapes saved as `TLContent` (the format used by copy/paste).
`putContentOntoCurrentPage` places it on the canvas for the user to drag into the portals.
*/
```

## PortalShapeUtil.tsx

```tsx
import {
	BaseFrameLikeShapeUtil,
	Ellipse2d,
	Group2d,
	RecordProps,
	SVGContainer,
	T,
	TLShape,
	TLShapePartial,
	toDomPrecision,
	toRichText,
} from 'tldraw'

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

const PORTAL_SHAPE_TYPE = 'portal'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[PORTAL_SHAPE_TYPE]: { w: number; h: number; color: 'blue' | 'orange' }
	}
}

export type PortalShape = TLShape<typeof PORTAL_SHAPE_TYPE>

const COLORS = {
	blue: {
		fill: 'rgba(60, 130, 246, 0.08)',
		stroke: '#3b82f6',
		glow: 'rgba(59, 130, 246, 0.4)',
	},
	orange: {
		fill: 'rgba(249, 115, 22, 0.08)',
		stroke: '#f97316',
		glow: 'rgba(249, 115, 22, 0.4)',
	},
} as const

let teleportCount = 0

// [1]
export class PortalShapeUtil extends BaseFrameLikeShapeUtil<PortalShape> {
	static override type = PORTAL_SHAPE_TYPE
	static override props: RecordProps<PortalShape> = {
		w: T.number,
		h: T.number,
		color: T.literalEnum('blue', 'orange'),
	}

	override getDefaultProps(): PortalShape['props'] {
		return { w: 250, h: 300, color: 'blue' }
	}

	// [2]
	override getGeometry(shape: PortalShape) {
		return new Group2d({
			children: [
				new Ellipse2d({
					width: shape.props.w,
					height: shape.props.h,
					isFilled: true,
				}),
			],
		})
	}

	private findLinkedPortal(shape: PortalShape): PortalShape | undefined {
		const otherColor = shape.props.color === 'blue' ? 'orange' : 'blue'
		return this.editor
			.getCurrentPageShapes()
			.find(
				(s): s is PortalShape =>
					this.editor.isShapeOfType(s, PORTAL_SHAPE_TYPE) && s.props.color === otherColor
			)
	}

	// [3]
	override onDropShapesOver(shape: PortalShape, shapes: TLShape[]) {
		const linked = this.findLinkedPortal(shape)
		if (!linked) return

		const { editor } = this

		// Shapes dragged in during the drag are already children of this portal (via
		// onDragShapesIn), but shapes dropped directly may not be. Reparent first so every
		// shape's x/y is a local offset inside this portal.
		editor.reparentShapes(
			shapes.filter((s) => s.parentId !== shape.id),
			shape.id
		)

		// Reparenting to the linked portal keeps the shapes' page positions, so restore the
		// local offsets they had in this portal to make them appear at the same spot in the other.
		const localPositions = shapes.map((s) => {
			const fresh = editor.getShape(s.id)!
			return { id: s.id, type: s.type, x: fresh.x, y: fresh.y } as TLShapePartial
		})

		editor.reparentShapes(shapes, linked.id)
		editor.updateShapes(localPositions)

		teleportCount++
		if (teleportCount === 3) {
			editor.createShape({
				type: 'text',
				x: linked.x + linked.props.w + 40,
				y: linked.y + linked.props.h / 2 - 20,
				props: { size: 'xl', richText: toRichText('🍰') },
			})
		}
	}

	override component(shape: PortalShape) {
		const theme = COLORS[shape.props.color]
		const cx = shape.props.w / 2
		const cy = shape.props.h / 2
		const rx = shape.props.w / 2
		const ry = shape.props.h / 2

		return (
			<SVGContainer>
				<ellipse
					cx={toDomPrecision(cx)}
					cy={toDomPrecision(cy)}
					rx={toDomPrecision(rx)}
					ry={toDomPrecision(ry)}
					fill={theme.fill}
					stroke={theme.stroke}
					strokeWidth={3}
					style={{ filter: `drop-shadow(0 0 12px ${theme.glow})` }}
				/>
			</SVGContainer>
		)
	}

	override getIndicatorPath(shape: PortalShape) {
		const path = new Path2D()
		path.ellipse(
			shape.props.w / 2,
			shape.props.h / 2,
			shape.props.w / 2,
			shape.props.h / 2,
			0,
			0,
			Math.PI * 2
		)
		return path
	}
}

/*
[1]
`BaseFrameLikeShapeUtil` gives a box shape the full frame behavior for free: it clips its
children, accepts dropped shapes (`onDragShapesIn` reparents them into the shape), releases
them when dragged out, and requires a full brush selection. Override only what should differ.

[2]
The base class clips children to the shape geometry's vertices, so returning an ellipse here
makes the portal clip in an oval without any extra work. Frame-like shapes must return a
`Group2d` (the editor's hit testing walks its `children`), so the ellipse is wrapped in one.

[3]
`onDropShapesOver` fires when the user releases shapes over this shape. By this point the base
class has usually already reparented them in; we reparent them again into the linked portal
and restore their local offsets so they appear at the same spot on the other side.
*/
```

--------

# Attach shapes together (bindings)

Category: Shapes & tools

Keywords: bindings, bindingutil, relationships, attach, stick, canbind, createbinding, onafterchangetoshape, anchor, relative position

Stick a sticker shape onto other shapes with a custom binding that keeps it attached.

Bindings are records that connect two shapes; a `BindingUtil` decides what happens when either side changes. Here a sticker dropped onto a shape creates a `sticker` binding storing where on the target it landed. `onAfterChangeToShape` moves the sticker as the target moves, resizes, or rotates, and `onBeforeDeleteToShape` deletes the sticker with its target.

Draw a shape, pick the sticker tool (or press P), and drop a sticker on it. Then move or resize the shape and watch the sticker stay put. Drag the sticker off to unstick it.

## App.tsx

```tsx
import {
	BindingOnShapeChangeOptions,
	BindingOnShapeDeleteOptions,
	BindingUtil,
	Box,
	DefaultToolbar,
	DefaultToolbarContent,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	StateNode,
	TLBinding,
	TLComponents,
	TLPointerEventInfo,
	TLShape,
	TLUiAssetUrlOverrides,
	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>
	}
}

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

type StickerShape = TLShape<typeof STICKER_TYPE>

// [1]
const offsetX = -16
const offsetY = -26
class StickerShapeUtil extends ShapeUtil<StickerShape> {
	static override type = STICKER_TYPE
	static override props: RecordProps<StickerShape> = {}

	override getDefaultProps() {
		return {}
	}

	// [2]
	override canBind() {
		return true
	}
	override canResize(shape: StickerShape) {
		return false
	}
	override canSnap(shape: StickerShape) {
		return false
	}
	override hideRotateHandle(shape: StickerShape) {
		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 getIndicatorPath() {
		const path = new Path2D()
		path.rect(offsetX, offsetY, 32, 32)
		return path
	}

	// [3]
	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 },
		}
	}

	// [4]
	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,
		})
	}

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

// [5]
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, tools) {
		tools['sticker'] = {
			id: 'sticker',
			label: 'Sticker',
			icon: 'heart-icon',
			kbd: 'p',
			onSelect: () => {
				editor.setCurrentTool('sticker')
			},
		}
		return tools
	},
}

const assetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'heart-icon': '/heart-icon.svg',
	},
}

const components: TLComponents = {
	Toolbar: (props) => {
		const sticker = useTools().sticker
		const isStickerSelected = useIsToolSelected(sticker)
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...sticker} isSelected={isStickerSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
}

const shapeUtils = [StickerShapeUtil]
const bindingUtils = [StickerBindingUtil]
const tools = [StickerTool]

export default function StickerExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				bindingUtils={bindingUtils}
				tools={tools}
				overrides={overrides}
				assetUrls={assetUrls}
				components={components}
			/>
		</div>
	)
}

/*
A sticker is a small shape that, when dropped on another shape, creates a `sticker` binding
to it. The binding keeps the sticker in place on the target as the target moves, resizes, or
rotates, and deletes the sticker when the target is deleted.

[1]
The sticker shape has no props. Its geometry, component, and indicator are offset so the
shape's origin (0,0) sits at the bottom of the heart, which is the point that gets bound to
the target shape.

[2]
`canBind` returning true lets stickers bind to (and be bound by) anything. The other overrides
make the sticker behave like a decal: no resizing, rotating, or snapping.

[3]
Dragging a sticker unsticks it: `onTranslateStart` deletes its bindings. On `onTranslateEnd`
we look for a shape under the sticker's origin and, if there is one, create a binding to it.
The sticker's position is stored as a normalized anchor within the target's bounds so it
survives resizing.

[4]
When the target shape changes, convert the stored anchor back to a page point and move the
sticker there (in the sticker's parent space, in case it lives in a frame or group).

[5]
The sticker tool creates a sticker at the pointer and immediately hands off to the select
tool's translating state, so the sticker follows the pointer until pointer up. `onInteractionEnd:
'sticker'` masks the current tool id as 'sticker' during the drag (and returns to the sticker
tool afterwards when the tool is locked); `onTranslateEnd` in the shape util does the binding.
*/
```

--------

# DOM-based shape size

Category: Shapes & tools

Keywords: dom sizing, dynamic size, resizeobserver, editoratom, atommap, getgeometry, measure, htmlcontainer, responsive

Size a custom shape from its rendered DOM instead of from `w` and `h` props.

Most shapes store their size as props. This shape has none: its component measures its own DOM element (with a `ResizeObserver`) and writes the result into an `EditorAtom` holding an `AtomMap` of shape id to size. `getGeometry` reads that atom, so selection bounds, hit testing, and the indicator update reactively as the content changes.

The shape's text animates in and out so you can watch the selection bounds follow it. Select the shape to see the indicator track the measured height.

## 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(shape: DynamicSizeShape) {
		return false
	}

	// [d]
	override canResize(shape: DynamicSizeShape) {
		return false
	}

	// [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]
	getIndicatorPath(shape: DynamicSizeShape) {
		const { width, height } = this.editor.getShapeGeometry(shape).bounds
		const path = new Path2D()
		path.rect(0, 0, width, height)
		return path
	}
}

// [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>
	)
}

/*
Two pieces do the work and can be reused for other shapes: the ShapeSizes atom and the
useDynamicShapeSize hook.

[1]
Extend TLGlobalShapePropsMap to add our shape's props to the global type system.

[2]
The shape only stores content. Its size is measured from the DOM element that renders it.

[3]
ShapeSizes is an EditorAtom holding an AtomMap from shape id to measured size. Using an
EditorAtom (rather than a module-level atom) scopes the sizes to one editor instance, and
AtomMap makes each shape's entry its own signal, so getGeometry for one shape doesn't
recompute when a different shape's size changes.

	[a] Delete a shape's entry when the shape is deleted, so the map doesn't grow forever.

[4]
useDynamicShapeSize measures a DOM element and writes its size to ShapeSizes:

	[a] offsetWidth/offsetHeight report layout size and ignore CSS transforms, so they're already
	    in shape space regardless of the camera zoom.

	[b] Writing to the atom invalidates getGeometry (see [e]) so selection bounds, hit testing,
	    and the indicator all follow the new size. We bail if nothing changed to avoid a redundant
	    store update.

	[c] Measure on every render, so the first paint already has a real size rather than the fallback.

	[d] ResizeObserver catches changes that don't go through React, such as fonts loading.

[5]
The shape util:

	[a] Standard type and props. Note there is no w or h prop.

	[b] Default props with some sample content.

	[c] Never cull the shape. Culled shapes are hidden with display: none, so its element would
	    measure 0×0 and the stored size would go stale until it scrolled back into view.

	[d] Resizing is disabled because the size is not something the user controls.

	[e] getGeometry reads from ShapeSizes. Because the read happens inside a computed, the geometry
	    updates reactively when the measured size changes. Before the first measurement we fall back
	    to a fixed height.

	[f] The component renders the content and attaches the ref from useDynamicShapeSize:

		[i] The text is animated so you can watch the selection bounds track the DOM.

		[ii] The measured element is given the shape width explicitly; only the height is dynamic.

	[g] The indicator uses the shape's geometry bounds, so it matches the measured size.

[6]
Standard setup: pass the shape util to Tldraw and create one shape on mount.

To reuse this in your own shape:
1. Call useDynamicShapeSize(shape) in your component and attach the returned ref.
2. Read ShapeSizes.get(this.editor).get(shape.id) in getGeometry.
3. Don't also store w/h props for the same dimension, or decide which one wins.
*/
```

## 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: bindings, constraints, layout, position, container, drag, drop, bindingutil, ontranslate, ontranslatestart, ontranslateend, relationships, custom binding

Lay out shapes in a row using bindings that hold each shape's position in a container.

Bindings let one shape respond to changes in another. Here a container shape and its element shapes are related by `layout` bindings, each carrying a fractional `index`. `LayoutBindingUtil` re-runs the layout whenever a binding is created, changed, or deleted, or the container moves: elements snap into their slots and the container resizes to fit. The element shape util's `onTranslateStart`, `onTranslate`, and `onTranslateEnd` create and move a placeholder binding while dragging so the row makes room before the drop.

Try dragging an element to a different slot in the container, or out onto the page and back in.

## App.tsx

```tsx
import {
	BindingOnChangeOptions,
	BindingOnCreateOptions,
	BindingOnDeleteOptions,
	BindingOnShapeChangeOptions,
	BindingUtil,
	HTMLContainer,
	IndexKey,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	T,
	TLBinding,
	TLShape,
	TLShapeUtilCanBindOpts,
	TLStoreSnapshot,
	Tldraw,
	Vec,
	clamp,
	getIndexBetween,
} from 'tldraw'
import 'tldraw/tldraw.css'
import snapshot from './snapshot.json'

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

const CONTAINER_TYPE = 'container'
const ELEMENT_TYPE = 'element'
const LAYOUT_TYPE = 'layout'
const ELEMENT_SIZE = 100
const CONTAINER_PADDING = 24

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[CONTAINER_TYPE]: { height: number; width: number }
		[ELEMENT_TYPE]: { color: string }
	}
}

// [1]
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: ELEMENT_SIZE + CONTAINER_PADDING * 2,
			height: ELEMENT_SIZE + CONTAINER_PADDING * 2,
		}
	}

	// [2]
	override canBind({ fromShape, toShape, bindingType }: TLShapeUtilCanBindOpts<ContainerShape>) {
		return (
			fromShape.type === CONTAINER_TYPE &&
			toShape.type === ELEMENT_TYPE &&
			bindingType === LAYOUT_TYPE
		)
	}
	override canEdit(shape: ContainerShape) {
		return false
	}
	override canResize(shape: ContainerShape) {
		return false
	}
	override hideRotateHandle(shape: ContainerShape) {
		return true
	}
	override isAspectRatioLocked(shape: ContainerShape) {
		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 getIndicatorPath(shape: ContainerShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.width, shape.props.height)
		return path
	}
}

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 canBind({ fromShape, toShape, bindingType }: TLShapeUtilCanBindOpts<ElementShape>) {
		return (
			fromShape.type === CONTAINER_TYPE &&
			toShape.type === ELEMENT_TYPE &&
			bindingType === LAYOUT_TYPE
		)
	}
	override canEdit(shape: ElementShape) {
		return false
	}
	override canResize(shape: ElementShape) {
		return false
	}
	override hideRotateHandle(shape: ElementShape) {
		return true
	}
	override isAspectRatioLocked(shape: ElementShape) {
		return true
	}

	override getGeometry() {
		return new Rectangle2d({
			width: ELEMENT_SIZE,
			height: ELEMENT_SIZE,
			isFilled: true,
		})
	}

	override component(shape: ElementShape) {
		return <HTMLContainer style={{ backgroundColor: shape.props.color }}></HTMLContainer>
	}

	override getIndicatorPath() {
		const path = new Path2D()
		path.rect(0, 0, ELEMENT_SIZE, ELEMENT_SIZE)
		return path
	}

	private getElementCenter(shape: ElementShape) {
		return this.editor
			.getShapePageTransform(shape)
			.applyToPoint({ x: ELEMENT_SIZE / 2, y: ELEMENT_SIZE / 2 })
	}

	private getTargetContainer(shape: ElementShape, pageAnchor: Vec) {
		return this.editor.getShapeAtPoint(pageAnchor, {
			hitInside: true,
			filter: (otherShape) =>
				this.editor.canBindShapes({ fromShape: otherShape, toShape: shape, binding: LAYOUT_TYPE }),
		}) as ContainerShape | undefined
	}

	// [3]
	private getBindingIndexForPosition(
		shape: ElementShape,
		container: ContainerShape,
		pageAnchor: Vec
	) {
		const allBindings = this.editor
			.getBindingsFromShape(container, LAYOUT_TYPE)
			.sort((a, b) => (a.props.index > b.props.index ? 1 : -1))

		const siblings = allBindings.filter((b) => b.toId !== shape.id)

		// Which slot is the element's center closest to?
		const order = clamp(
			Math.round(
				(pageAnchor.x - container.x - CONTAINER_PADDING) / (ELEMENT_SIZE + CONTAINER_PADDING)
			),
			0,
			siblings.length + 1
		)

		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
	}

	// [4]
	override onTranslateStart(shape: ElementShape) {
		this.editor.updateBindings(
			this.editor.getBindingsToShape(shape, LAYOUT_TYPE).map((binding) => ({
				...binding,
				props: { ...binding.props, placeholder: true },
			}))
		)
	}

	override onTranslate(_: ElementShape, shape: ElementShape) {
		const pageAnchor = this.getElementCenter(shape)
		const targetContainer = this.getTargetContainer(shape, pageAnchor)

		if (!targetContainer) {
			this.editor.deleteBindings(this.editor.getBindingsToShape(shape, LAYOUT_TYPE))
			return
		}

		const index = this.getBindingIndexForPosition(shape, targetContainer, pageAnchor)

		const existingBinding = this.editor
			.getBindingsFromShape(targetContainer, LAYOUT_TYPE)
			.find((b) => b.toId === shape.id)

		if (existingBinding) {
			if (existingBinding.props.index === index) return
			this.editor.updateBinding({
				...existingBinding,
				props: {
					...existingBinding.props,
					placeholder: true,
					index,
				},
			})
		} else {
			this.editor.createBinding({
				type: LAYOUT_TYPE,
				fromId: targetContainer.id,
				toId: shape.id,
				props: {
					index,
					placeholder: true,
				},
			})
		}
	}

	// [5]
	override onTranslateEnd(_: ElementShape, shape: ElementShape) {
		const pageAnchor = this.getElementCenter(shape)
		const targetContainer = this.getTargetContainer(shape, pageAnchor)
		if (!targetContainer) return

		const index = this.getBindingIndexForPosition(shape, targetContainer, pageAnchor)

		this.editor.deleteBindings(this.editor.getBindingsToShape(shape, LAYOUT_TYPE))
		this.editor.createBinding({
			type: LAYOUT_TYPE,
			fromId: targetContainer.id,
			toId: shape.id,
			props: {
				index,
				placeholder: false,
			},
		})
	}
}

// [6]
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)
	}

	// [7]
	private updateElementsForContainer({
		props: { placeholder },
		fromId: containerId,
		toId,
	}: LayoutBinding) {
		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]

			// The element being dragged keeps following the pointer; only its slot is reserved
			if (toId === binding.toId && placeholder) continue

			const offset = new Vec(
				CONTAINER_PADDING + i * (ELEMENT_SIZE + 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_TYPE,
					x: point.x,
					y: point.y,
				})
			}
		}

		const width =
			CONTAINER_PADDING +
			(bindings.length * ELEMENT_SIZE + (bindings.length - 1) * CONTAINER_PADDING) +
			CONTAINER_PADDING

		const height = CONTAINER_PADDING + ELEMENT_SIZE + CONTAINER_PADDING

		if (width !== container.props.width || height !== container.props.height) {
			this.editor.updateShape({
				id: container.id,
				type: CONTAINER_TYPE,
				props: { width, height },
			})
		}
	}
}

const shapeUtils = [ContainerShapeUtil, ElementShapeUtil]
const bindingUtils = [LayoutBindingUtil]

export default function LayoutExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				snapshot={snapshot as unknown as TLStoreSnapshot}
				shapeUtils={shapeUtils}
				bindingUtils={bindingUtils}
			/>
		</div>
	)
}

/*
Introduction:

A container shape lays out element shapes in a row. The relationship between a container and
each element is a `layout` binding whose `index` prop is a fractional index giving the
element's position in the row. The binding util reacts to changes by re-laying-out the row.

[1]
The container has no children in the tldraw parent/child sense; the elements stay on the page
and are related to it only through bindings. Its size is derived from how many bindings it has.

[2]
`canBind` on both shapes only allows `layout` bindings from a container to an element. The
element util's translate handlers use `editor.canBindShapes` (which consults both sides) to
find drop targets, so this is the single source of truth for what can go where.

[3]
Turn a drop position into a fractional index: work out which slot the element's center is
nearest, then use `getIndexBetween` on the neighbouring bindings. Reusing the element's own
index when it hasn't moved slots avoids churning bindings while dragging.

[4]
While an element is being dragged its binding is marked `placeholder`, which tells the layout
to reserve the slot but not snap the element into it, so it keeps following the pointer.
`onTranslate` moves the placeholder between containers and slots as the pointer moves.

[5]
On drop, replace whatever bindings the element has with a single non-placeholder binding to
the container under it. Creating the binding triggers `onAfterCreate`, which snaps the element
into place.

[6]
The binding props: `index` orders the elements, `placeholder` marks an in-progress drag.

[7]
Every binding lifecycle hook that can affect a row (create, change, container moved, delete)
runs the same layout: position each bound element in its slot and resize the container to fit.
Comparing before updating keeps this idempotent so it doesn't loop.
*/
```

--------

# Persistent iframe shape

Category: Shapes & tools

Keywords: iframe, embed, content element, moveBefore, unmount, persistent, lifecycle

An iframe shape whose content survives unmounting the editor.

Shape content normally lives inside the editor's React tree, so unmounting the editor destroys it — an embedded iframe loses its scroll position, in-app state, and connections. This example uses `getAppOwnedElement` and `onReleaseAppOwnedElement` to keep an app-owned iframe alive across editor sessions: tldraw adopts the element into the shape with `Node.moveBefore` (which preserves iframe state, in Chromium 133+ and Firefox 144+) and hands it back to the app before the editor unmounts. Interact with the iframe, unmount the editor, then mount it again — the iframe keeps its state.

## App.tsx

```tsx
import { useMemo, useState } from 'react'
import {
	BaseBoxShapeUtil,
	createTLStore,
	defaultBindingUtils,
	defaultShapeUtils,
	moveElementInto,
	RecordProps,
	T,
	Tldraw,
	TLShape,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

const PERSISTENT_IFRAME_SHAPE_TYPE = 'persistent-iframe'

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

type IPersistentIframeShape = TLShape<typeof PERSISTENT_IFRAME_SHAPE_TYPE>

// [1]
const iframes = new Map<string, HTMLIFrameElement>()

let parkingLot: HTMLDivElement | undefined
function getParkingLot() {
	if (!parkingLot) {
		parkingLot = document.createElement('div')
		parkingLot.style.position = 'fixed'
		parkingLot.style.top = '-10000px'
		parkingLot.style.left = '-10000px'
		parkingLot.style.visibility = 'hidden'
		document.body.appendChild(parkingLot)
	}
	return parkingLot
}

// [2]
// We shuttle iframes between the parking lot and the shape's slot with tldraw's `moveElementInto`
// (imported above), which uses Node.moveBefore where available to preserve iframe state and falls
// back to appendChild otherwise — the same primitive tldraw uses to adopt the element.

const IFRAME_CONTENT = `
<style>body { font-family: sans-serif; margin: 16px; }</style>
<h3>I keep my state</h3>
<p>Count: <output id="count">0</output></p>
<button onclick="count.value = Number(count.value) + 1">Increment</button>
<p><input placeholder="Type something…" /></p>
<p>Unmount the editor, then mount it again. In a browser with Node.moveBefore
(Chromium 133+, Firefox 144+) this document never reloads.</p>
`

// [3]
class PersistentIframeShapeUtil extends BaseBoxShapeUtil<IPersistentIframeShape> {
	static override type = PERSISTENT_IFRAME_SHAPE_TYPE
	static override props: RecordProps<IPersistentIframeShape> = {
		w: T.number,
		h: T.number,
	}

	getDefaultProps(): IPersistentIframeShape['props'] {
		return { w: 360, h: 280 }
	}

	component() {
		// The shape's chrome; the iframe itself is slotted in by the editor.
		return null
	}

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

	// [4]
	override getAppOwnedElement(shape: IPersistentIframeShape) {
		let iframe = iframes.get(shape.id)
		if (!iframe) {
			iframe = document.createElement('iframe')
			iframe.srcdoc = IFRAME_CONTENT
			iframe.style.width = '100%'
			iframe.style.height = '100%'
			iframe.style.border = '1px solid #ccc'
			iframe.style.borderRadius = '8px'
			iframe.style.backgroundColor = 'white'
			iframe.style.pointerEvents = 'all'
			iframes.set(shape.id, iframe)
		}
		return iframe
	}

	// [5]
	override onReleaseAppOwnedElement(shape: IPersistentIframeShape, element: HTMLElement) {
		// onReleaseAppOwnedElement fires both when the shape goes away for good (deletion) and
		// when the slot is torn down but the shape lives on (page change, editor unmount). If the
		// shape is still in the store we park the iframe to reuse it later; otherwise it was
		// deleted, so we destroy the iframe and drop it from the registry to avoid leaking it.
		if (this.editor.getShape(shape.id)) {
			moveElementInto(getParkingLot(), element)
		} else {
			iframes.delete(shape.id)
			element.remove()
		}
	}
}

const customShapeUtils = [PersistentIframeShapeUtil]

export default function PersistentIframeExample() {
	// [6]
	const store = useMemo(
		() =>
			createTLStore({
				shapeUtils: [...defaultShapeUtils, ...customShapeUtils],
				bindingUtils: defaultBindingUtils,
			}),
		[]
	)
	const [isEditorMounted, setIsEditorMounted] = useState(true)

	return (
		<div style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column' }}>
			<div style={{ padding: 8 }}>
				<button onClick={() => setIsEditorMounted((mounted) => !mounted)}>
					{isEditorMounted ? 'Unmount editor' : 'Mount editor'}
				</button>
			</div>
			<div style={{ flex: 1, position: 'relative' }}>
				{isEditorMounted ? (
					<Tldraw
						store={store}
						shapeUtils={customShapeUtils}
						onMount={(editor) => {
							const hasIframeShape = editor
								.getCurrentPageShapes()
								.some((shape) => shape.type === PERSISTENT_IFRAME_SHAPE_TYPE)
							if (!hasIframeShape) {
								editor.createShape({ type: PERSISTENT_IFRAME_SHAPE_TYPE, x: 200, y: 100 })
							}
						}}
					/>
				) : (
					<div style={{ padding: 16 }}>The editor is unmounted. The iframe is parked.</div>
				)}
			</div>
		</div>
	)
}

/*
Introduction:

Shape content renders inside the editor's React tree, so unmounting the editor — to lazy-mount
the canvas, reclaim memory, or recover from a crash — normally destroys any embedded content.
This example keeps an iframe alive across editor sessions using the shape util's app-owned
element lifecycle: `getAppOwnedElement` and `onReleaseAppOwnedElement`.

[1]
The app owns the elements. We keep one iframe per shape in a registry, and a hidden "parking
lot" div on document.body where iframes live while no editor is mounted. The parking lot is
hidden with `visibility: hidden` rather than removed from the DOM: `Node.moveBefore` only
preserves state when the element stays connected to the document.

[2]
We move iframes with tldraw's `moveElementInto` helper. It uses `Node.moveBefore` (Chromium 133+,
Firefox 144+) to move an element to a new parent without resetting its state — iframes don't
reload, videos keep playing — and falls back to `appendChild` (which reloads the iframe) in
browsers without it. tldraw uses the same helper to adopt the element, so the example doesn't
reimplement it.

[3]
A regular shape util. The shape stays a normal canvas citizen: geometry, hit-testing,
z-ordering, and the indicator all work as usual.

[4]
`getAppOwnedElement` returns the app-owned element for a shape. While the shape is mounted,
tldraw guarantees the element is never unmounted, recreated, or relocated — reorders,
reparenting, and culling never move it, so the iframe never reloads. tldraw adopts the
element with `moveBefore` where available, so re-mounting the editor picks the iframe up
from the parking lot without a reload.

[5]
`onReleaseAppOwnedElement` is called before the element's slot is destroyed: when the shape
is deleted, when the page changes, and when the editor unmounts (including error teardown).
It runs while the slot is still connected to the document, so moving the element to the
parking lot here preserves its state. The callback fires for all of those cases, so we use
the store to tell them apart: if the shape is gone it was deleted, and we destroy the iframe
and drop it from the registry instead of parking it — otherwise parked iframes for deleted
shapes would leak forever.

[6]
The store is created outside the Tldraw component so the document survives unmounting the
editor. Toggle the button: the editor unmounts, the iframe moves to the parking lot, and on
re-mount the same iframe is adopted back into the shape with its state intact.

Note: the iframe sets `pointer-events: all`, so you interact with its content directly and
move the shape by its edges or the selection handles. A production shape would gate
interaction the way tldraw's embed shape does (interact when selected or editing).
*/
```

--------

# Pin (bindings)

Category: Shapes & tools

Keywords: bindings, bindingutil, custom binding, relationships, connections, network, custom tool, statenode, onafterchangetoshape, shape relationships, pin together

Pin overlapping shapes together with a custom binding that keeps the whole network aligned.

The pin is a custom shape; the interesting part is `PinBindingUtil`. Dropping a pin over shapes creates a `pin` binding to each one, storing where on the shape the pin landed. When any pinned shape changes, `onAfterChangeToShape` records it and `onOperationComplete` solves the connected network once per operation, moving the other shapes so every pin stays put. Deleting a pinned shape deletes its pin, and reparenting one drags the pin along.

Try drawing two overlapping shapes, selecting the pin tool (or press P), and clicking where they overlap. Then drag one of the shapes: the other follows. Drag the pin itself to unpin.

## App.tsx

```tsx
import {
	BindingOnShapeChangeOptions,
	BindingOnShapeDeleteOptions,
	BindingUtil,
	Box,
	DefaultFillStyle,
	DefaultToolbar,
	DefaultToolbarContent,
	RecordProps,
	Rectangle2d,
	ShapeUtil,
	StateNode,
	TLBinding,
	TLComponents,
	TLPointerEventInfo,
	TLShape,
	TLShapeId,
	TLShapePartial,
	TLShapeUtilCanBindOpts,
	TLUiAssetUrlOverrides,
	TLUiOverrides,
	Tldraw,
	TldrawUiMenuItem,
	Vec,
	VecModel,
	createShapeId,
	invLerp,
	lerp,
	useIsToolSelected,
	useTools,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

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

// [1]
class PinShapeUtil extends ShapeUtil<PinShape> {
	static override type = PIN_TYPE
	static override props: RecordProps<PinShape> = {}

	override getDefaultProps() {
		return {}
	}

	// [2]
	override canBind({ toShape, bindingType }: TLShapeUtilCanBindOpts<PinShape>) {
		if (bindingType === PIN_TYPE) {
			return toShape.type !== PIN_TYPE
		}
		return true
	}
	override canEdit(shape: PinShape) {
		return false
	}
	override canResize(shape: PinShape) {
		return false
	}
	override hideRotateHandle(shape: PinShape) {
		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 getIndicatorPath() {
		const path = new Path2D()
		path.rect(offsetX, offsetY, 32, 32)
		return path
	}

	// [3]
	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>()

	// [4]
	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)
				}
			}
		}

		// [5]
		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)
		}
	}

	// [6]
	override onAfterChangeToShape({
		binding,
		shapeAfter,
	}: BindingOnShapeChangeOptions<PinBinding>): void {
		this.changedToShapes.add(binding.toId)
		const pin = this.editor.getShape(binding.fromId)
		if (!pin) return

		if (pin.parentId !== shapeAfter.parentId) {
			this.editor.reparentShapes([pin.id], shapeAfter.parentId)
		}
	}

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

// [7]
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 assetUrls: TLUiAssetUrlOverrides = {
	icons: {
		'heart-icon': '/heart-icon.svg',
	},
}

const components: TLComponents = {
	Toolbar: (...props) => {
		const pin = useTools().pin
		const isPinSelected = useIsToolSelected(pin)
		return (
			<DefaultToolbar {...props}>
				<TldrawUiMenuItem {...pin} isSelected={isPinSelected} />
				<DefaultToolbarContent />
			</DefaultToolbar>
		)
	},
}

const shapeUtils = [PinShapeUtil]
const bindingUtils = [PinBindingUtil]
const tools = [PinTool]

export default function PinExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="pin-example"
				onMount={(editor) => {
					editor.setStyleForNextShapes(DefaultFillStyle, 'semi')
				}}
				shapeUtils={shapeUtils}
				bindingUtils={bindingUtils}
				tools={tools}
				overrides={overrides}
				assetUrls={assetUrls}
				components={components}
			/>
		</div>
	)
}

/*
Introduction:

A pin is a small shape that, when dropped over other shapes, creates a `pin` binding from
itself to each shape underneath. When any pinned shape moves, the binding util moves the rest
of the network so every pin stays at the same relative spot on each shape it's stuck to.

[1]
The pin shape has no props. Its geometry and indicator are offset so the pin's origin (0,0)
sits at the tip of the emoji, which is the point that gets bound to other shapes.

[2]
`canBind` is asked for every binding that would touch this shape. Pins can't be pinned to
other pins, but they can still be the target of other binding types (e.g. arrows).

[3]
Dragging a pin unpins it: `onTranslateStart` removes its bindings. On `onTranslateEnd` we look
at every shape under the pin's tip (excluding shapes above the pin in z-order and shapes in a
different parent) and create a binding to each, storing the pin's position as a normalized
anchor inside the target's bounds so it survives resizing.

[4]
`onAfterChangeToShape` fires once per changed shape, but a network may involve many shapes
changing in one operation. We only record which target shapes changed and do the real work in
`onOperationComplete`, which runs once after the whole operation, so the network is solved
once rather than once per shape.

[5]
Solving the network: walk out from the changed shapes across pin bindings to gather every
connected shape and the page-space delta each pin should have from each shape it's stuck to.
Changed shapes are fixed; everything else is relaxed toward its target deltas over a few
iterations (a simple constraint solver). Shapes that ended up moving get one `updateShapes`
call, which itself triggers `onAfterChangeToShape` and another `onOperationComplete` pass; the
`changedToShapes` set is cleared only when a pass produces no movement, so this settles.

[6]
A reparented pinned shape takes its pin with it so both stay in one coordinate space; a deleted
one takes its pin too.

[7]
The pin tool creates a pin at the pointer and immediately hands off to the select tool's
translating state, so the pin follows the pointer until pointer up. `onInteractionEnd: 'pin'`
masks the current tool id as 'pin' during the drag (and returns to the pin tool afterwards when
the tool is locked); `onTranslateEnd` in the shape util does the binding.
*/
```

--------

# Rich text with custom extension and toolbar

Category: Shapes & tools

Keywords: tiptap, rich text, custom extension, text editor, mark, toolbar button, textoptions, wavy text, text effects, defaultrichtexttoolbar

Add a custom TipTap mark and a toolbar button that toggles it.

tldraw's rich text is built on TipTap, so you can extend it with any TipTap extension. This example adds a `wavy` mark that renders a wavy underline, passes it in through `options.text.tipTapConfig.extensions` (spread `tipTapDefaultExtensions` first so tldraw's defaults stay in place), and overrides the `RichTextToolbar` component to add a button that runs the mark's `toggleWavy` command.

Try creating a text shape, selecting some text, and clicking the 〰️ button in the toolbar.

## App.tsx

```tsx
import { Mark, mergeAttributes } from '@tiptap/core'
import { useEffect, useState } from 'react'
import {
	DefaultRichTextToolbar,
	DefaultRichTextToolbarContent,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	preventDefault,
	tipTapDefaultExtensions,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './RichTextCustomExtension.css'

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

interface WavyExtensionOptions {
	HTMLAttributes: object
}

declare module '@tiptap/core' {
	interface Commands<ReturnType> {
		wavy: {
			setWavy(): ReturnType
			toggleWavy(): ReturnType
			unsetWavy(): ReturnType
		}
	}
}

// [1]
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 }) =>
					commands.toggleMark(this.name),
			unsetWavy:
				() =>
				({ commands }) =>
					commands.unsetMark(this.name),
		}
	},
})

// [2]
const components: TLComponents = {
	RichTextToolbar: () => {
		const editor = useEditor()
		const textEditor = useValue('textEditor', () => editor.getRichTextEditor(), [editor])

		// [3]
		const [, forceUpdate] = useState(0)
		useEffect(() => {
			if (!textEditor) return
			const handleUpdate = () => forceUpdate((n) => n + 1)
			textEditor.on('transaction', handleUpdate)
			return () => {
				textEditor.off('transaction', handleUpdate)
			}
		}, [textEditor])

		if (!textEditor) return null

		return (
			<DefaultRichTextToolbar>
				<TldrawUiButton
					type="icon"
					title="Toggle wavy underline"
					onClick={() => {
						textEditor.chain().focus().toggleWavy().run()
					}}
					isActive={textEditor.isActive('wavy')}
					// [4]
					onPointerDown={preventDefault}
				>
					〰️
				</TldrawUiButton>
				<DefaultRichTextToolbarContent textEditor={textEditor} />
			</DefaultRichTextToolbar>
		)
	},
}

// [5]
const options = {
	text: {
		tipTapConfig: {
			extensions: [...tipTapDefaultExtensions, Wavy],
		},
	},
}

export default function RichTextCustomExtensionExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="rich-text-custom-extension"
				components={components}
				options={options}
			/>
		</div>
	)
}

/*
[1]
A TipTap mark extension. It renders as a `<span class="wavy">` (styled in
RichTextCustomExtension.css) and adds `setWavy` / `toggleWavy` / `unsetWavy` commands. The
`declare module '@tiptap/core'` block above tells TypeScript about those commands so
`textEditor.chain().toggleWavy()` type checks.

[2]
Replace the rich text toolbar with our own. `DefaultRichTextToolbar` handles positioning the
toolbar over the text selection; we render our custom button plus the default bold/italic/etc
buttons via `DefaultRichTextToolbarContent`. `editor.getRichTextEditor()` is the TipTap editor
for the text currently being edited, or null when no text is being edited.

[3]
The TipTap editor isn't a tldraw signal, so `isActive` wouldn't otherwise refresh as the
selection moves in and out of marked text. Re-render on every TipTap transaction so the
button's active state stays in sync.

[4]
Preventing the default on pointer down keeps the toolbar button from taking focus away from
the text editor, which would collapse the selection before the command runs.

[5]
Pass the extension list through `options.text.tipTapConfig`. Spread `tipTapDefaultExtensions`
so tldraw's own configuration (StarterKit settings, highlight, keyboard tweaks) stays in place;
passing a bare `StarterKit` instead would drop those.
*/
```

## RichTextCustomExtension.css

```css
.wavy {
	text-decoration: wavy underline hotpink;
}
```

--------

# Rich text with font options

Category: Shapes & tools

Keywords: tiptap, rich text, font family, font size, text editor, custom fonts, textoptions, google fonts, fontface, addfontsfromnode, typography

Add font family and font size selects to the rich text toolbar.

tldraw's rich text is built on TipTap, so it can use TipTap's `FontFamily` and `TextStyleKit` extensions plus a small custom `FontSize` extension. The extensions are passed through `options.text.tipTapConfig.extensions`, and a custom `RichTextToolbar` component adds two selects that run `setFontFamily` and `setFontSize`.

Fonts that aren't already on the page (Inter and Exo 2 from Google Fonts here) need two extra pieces: `options.text.addFontsFromNode` tells tldraw which `TLFontFace` a piece of text uses so it can load the font and embed it in exports, and `editor.fonts.requestFonts()` on mount preloads them so switching families doesn't flash.

Try creating a text shape, selecting some text, and picking a font or size from the toolbar.

## App.tsx

```tsx
import { FontFamily } from '@tiptap/extension-font-family'
import { TextStyleKit } from '@tiptap/extension-text-style'
import { useEffect, useState } from 'react'
import {
	DefaultRichTextToolbar,
	DefaultRichTextToolbarContent,
	Editor,
	TLComponents,
	TLTextOptions,
	Tldraw,
	defaultAddFontsFromNode,
	tipTapDefaultExtensions,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { extensionFontFamilies } from './fonts'
import './RichTextFontExtension.css'
import { FontSize } from './FontSizeExtension'

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

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' },
]

// [1]
const components: TLComponents = {
	RichTextToolbar: () => {
		const editor = useEditor()
		const textEditor = useValue('textEditor', () => editor.getRichTextEditor(), [editor])

		// [2]
		const [, forceUpdate] = useState(0)
		useEffect(() => {
			if (!textEditor) return
			const handleTransaction = () => forceUpdate((n) => n + 1)
			textEditor.on('transaction', handleTransaction)
			return () => {
				textEditor.off('transaction', handleTransaction)
			}
		}, [textEditor])

		if (!textEditor) return null

		const currentFontFamily = textEditor.getAttributes('textStyle').fontFamily ?? 'DEFAULT'
		const currentFontSize = textEditor.getAttributes('textStyle').fontSize ?? '16px'

		return (
			<DefaultRichTextToolbar>
				<select
					className="rich-text-font-extension-select"
					value={currentFontFamily}
					// [3]
					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>
				<DefaultRichTextToolbarContent textEditor={textEditor} />
			</DefaultRichTextToolbar>
		)
	},
}

// [4]
const textOptions: Partial<TLTextOptions> = {
	tipTapConfig: {
		extensions: [...tipTapDefaultExtensions, FontFamily, FontSize, TextStyleKit],
	},
	// [5]
	addFontsFromNode(node, state, addFont) {
		state = defaultAddFontsFromNode(node, state, addFont)

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

		const font = extensionFontFamilies[state.family]?.[state.style]?.[state.weight]
		if (font) addFont(font)

		return state
	},
}

const options = { text: textOptions }

// [6]
const fontFaces = Object.values(extensionFontFamilies)
	.flatMap((fontFamily) => Object.values(fontFamily))
	.flatMap((fontStyle) => Object.values(fontStyle))

function onMount(editor: Editor) {
	editor.fonts.requestFonts(fontFaces)
}

// [7]
const assetUrls = {
	fonts: {
		tldraw_mono: extensionFontFamilies["'Exo 2'"].normal.normal.src.url,
	},
}

export default function RichTextFontExtensionExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="rich-text-font-extension"
				components={components}
				options={options}
				assetUrls={assetUrls}
				onMount={onMount}
			/>
		</div>
	)
}

/*
[1]
Replace the rich text toolbar. `DefaultRichTextToolbar` positions the toolbar over the text
selection; inside it we add two `<select>`s and keep the default buttons with
`DefaultRichTextToolbarContent`. `editor.getRichTextEditor()` is the TipTap editor for the text
being edited, or null when nothing is being edited.

[2]
The TipTap editor isn't a tldraw signal, so the selects wouldn't otherwise update as the caret
moves between differently styled text. Re-render on every TipTap transaction so
`getAttributes('textStyle')` reflects the current selection.

[3]
Marking the pointer down as handled keeps the canvas from treating a click on the select as a
click on the shape behind it, which would end text editing.

[4]
The font extensions are TipTap's stock `FontFamily` and `TextStyleKit` plus a small `FontSize`
extension (see FontSizeExtension.ts). Spread `tipTapDefaultExtensions` first so tldraw's own
StarterKit configuration and extras stay in place.

[5]
`addFontsFromNode` is how tldraw finds out which fonts a piece of rich text uses, so it can
load them before rendering and embed them in SVG exports. The default handles tldraw's own
fonts; we extend it to walk the `textStyle` mark for a `fontFamily` attribute and, when it
matches one of our font families, add the matching `TLFontFace` to the document.

[6]
Preload every custom font on mount so switching families in the toolbar doesn't flash
unstyled text while the font downloads.

[7]
`assetUrls.fonts` overrides tldraw's built-in fonts. Here we point the mono font at Exo 2 to
show that the same font files can also replace a default font.
*/
```

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

Category: Shapes & tools

Keywords: tiptap, text styling, text stroke, custom extension, rich text toolbar, mark, css styling, text effects

Add an outlined text style with a custom TipTap mark and toolbar button.

The `Outline` mark wraps selected text in a `<span class="outlined">`, and a few lines of CSS (`-webkit-text-stroke`) draw the outline. The mark is passed to the text editor through `options.text.tipTapConfig.extensions`, and a custom `RichTextToolbar` component adds a button that runs the mark's `toggleOutline` command.

Try creating a text shape, selecting some text, and clicking the ⬜ button in the toolbar. See the "Rich text with custom extension and toolbar" example for the same pattern with a wavy underline.

## App.tsx

```tsx
import { Mark, mergeAttributes } from '@tiptap/core'
import { useEffect, useState } from 'react'
import {
	DefaultRichTextToolbar,
	DefaultRichTextToolbarContent,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	preventDefault,
	tipTapDefaultExtensions,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './OutlinedTextExample.css'

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

interface OutlineExtensionOptions {
	HTMLAttributes: object
}

declare module '@tiptap/core' {
	interface Commands<ReturnType> {
		outline: {
			setOutline(): ReturnType
			toggleOutline(): ReturnType
			unsetOutline(): ReturnType
		}
	}
}

// [1]
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 }) =>
					commands.toggleMark(this.name),
			unsetOutline:
				() =>
				({ commands }) =>
					commands.unsetMark(this.name),
		}
	},
})

// [2]
const components: TLComponents = {
	RichTextToolbar: () => {
		const editor = useEditor()
		const textEditor = useValue('textEditor', () => editor.getRichTextEditor(), [editor])

		// [3]
		const [, forceUpdate] = useState(0)
		useEffect(() => {
			if (!textEditor) return
			const handleUpdate = () => forceUpdate((n) => n + 1)
			textEditor.on('transaction', handleUpdate)
			return () => {
				textEditor.off('transaction', handleUpdate)
			}
		}, [textEditor])

		if (!textEditor) return null

		return (
			<DefaultRichTextToolbar>
				<TldrawUiButton
					type="icon"
					title="Toggle text outline"
					onClick={() => {
						textEditor.chain().focus().toggleOutline().run()
					}}
					isActive={textEditor.isActive('outline')}
					onPointerDown={preventDefault}
				>
					⬜
				</TldrawUiButton>
				<DefaultRichTextToolbarContent textEditor={textEditor} />
			</DefaultRichTextToolbar>
		)
	},
}

// [4]
const options = {
	text: {
		tipTapConfig: {
			extensions: [...tipTapDefaultExtensions, Outline],
		},
	},
}

export default function OutlinedTextExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="outlined-text-example" components={components} options={options} />
		</div>
	)
}

/*
[1]
A TipTap mark extension. It renders as `<span class="outlined filled">`, and the outline effect
itself is plain CSS (`-webkit-text-stroke`) in OutlinedTextExample.css. The `declare module`
block above registers the mark's commands with TypeScript.

[2]
Override the `RichTextToolbar` component. `DefaultRichTextToolbar` positions the toolbar over
the selection; inside it we add our toggle button and keep the default buttons via
`DefaultRichTextToolbarContent`. `editor.getRichTextEditor()` is the TipTap editor for the
text being edited, or null when nothing is being edited.

[3]
The transaction re-render and the pointer-down `preventDefault` are the same as in the
rich text custom extension example; see its footnotes [3] and [4] for why.

[4]
Pass extensions through `options.text.tipTapConfig`. Spread `tipTapDefaultExtensions` so
tldraw's own StarterKit configuration and extras stay in place.
*/
```

## OutlinedTextExample.css

```css
.outlined {
	-webkit-text-stroke: 2px #000000;
	text-stroke: 2px #000000;
	color: transparent;
	font-weight: bold;
}

.outlined.filled {
	color: #ffffff;
}
```

--------

# Globs

Category: Shapes & tools

Keywords: custom shape, custom tool, bindings, bindingutil, handles, custom handles, statenode, vector editor, bezier, tension handles

A vector editor built from globs: skins stretched between circular nodes and edited with handles.

Globs are the shape primitive from [this paper](https://jcgt.org/published/0004/03/01/paper-lowres.pdf). This example builds them from three SDK pieces: a `node` shape (a circle with a radius handle), a `glob` shape whose geometry is derived from the two nodes it spans plus its own `d` and tension handles, and a `glob` binding that keeps the glob attached as its nodes move. A custom `glob` tool with `node` and `connect` states places nodes and stretches globs between them.

**Parts of this example are hacky.** `GlobsExample.tsx` patches the select tool's `pointing_handle` state at runtime and overrides `editor.getContentFromCurrentPage` so copies include the nodes a glob depends on. Neither is public API and both can break between releases. The shape utils, binding util, and tool are all built on supported APIs.

Shortcuts:

- Press N to place a node.
- Select a node and press C, then click to place a new node or click an existing one to connect them with a glob.
- Hold cmd while dragging a `d` handle to move its opposite handle too.
- Hold cmd while dragging a tension handle to move its opposite handle too.
- Hold cmd and shift to drag all four tension handles on a glob together.
- Hold space to preview the glob filled.

## App.tsx

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

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

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

// [1]
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: () => {
				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
	},
}

// [2]
const GlobToolWithPopover = track(function GlobToolWithPopover() {
	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]
	)

	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>
		)
	},
}

type PointingHandleState = StateNode & {
	info?: TLPointerEventInfo & { target: 'handle' }
}

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) => {
					// [3]
					const pointingHandleState =
						editor.getStateDescendant<PointingHandleState>('select.pointing_handle')

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

					const originalOnPointerMove = pointingHandleState.onPointerMove?.bind(pointingHandleState)

					// The live move event has target 'canvas' (no shape/handle), so read the shape and
					// handle from the info the state stored when the user pointed down on the handle.
					pointingHandleState.onPointerMove = (info: TLPointerEventInfo) => {
						if (!editor.inputs.getIsDragging()) {
							originalOnPointerMove?.(info)
							return
						}

						const handleInfo = pointingHandleState.info
						if (handleInfo?.target !== 'handle') {
							originalOnPointerMove?.(info)
							return
						}

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

						originalOnPointerMove?.(info)
					}

					// [4]
					const originalGetContent = editor.getContentFromCurrentPage.bind(editor)
					editor.getContentFromCurrentPage = (shapes) => {
						const ids =
							typeof shapes[0] === 'string'
								? (shapes as TLShapeId[])
								: (shapes as TLShape[]).map((s) => s.id)

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

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

/*
Introduction:

A small vector editor built from globs, the shape primitive from the paper linked in the
README. A `node` is a circle; a `glob` is a skin stretched between two nodes, attached to them
with `glob` bindings so the glob follows when a node moves, and edited through handles on the
glob shape. See NodeShapeUtil.tsx, GlobShapeUtil.tsx, GlobBindingUtil.tsx, and GlobTool/ for
those pieces; this file wires the tool into the UI.

[1]
The glob tool has two child states, `glob.node` and `glob.connect`. Registering both in the
`tools` override gives them labels, icons, and shortcuts (N and C). Connect only makes sense
with nodes selected, so its `onSelect` checks the selection first.

[2]
A toolbar item that opens a popover with the two variants, built from `TldrawUiPopover` and
`TldrawUiToolbar`. The main item shows whichever glob state is current so the toolbar
highlights it while active.

[3]
Patching the select tool's `pointing_handle` state so dragging a glob handle starts the drag
immediately, even with modifier keys held (which would otherwise start brushing). This is
reaching into the SDK's internals and is fragile across versions; a custom select tool would be
the sturdier approach, but this is far less code for an example.

[4]
When globs are copied or duplicated, include the nodes they're bound to. Otherwise a pasted
glob has bindings to nodes that don't exist in the paste and gets cleaned up.
*/
```

## 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 {
	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 getIndicatorPath(shape: GlobShape) {
		const globPoints = getGlobInfo(this.editor, shape)
		if (!globPoints) return undefined

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

		return new Path2D(pathBuilder.toD())
	}

	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 (Math.round(distance) <= Math.round(minDistance)) {
				if (Math.round(distance) < Math.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 (Math.round(outerLineDistance) <= Math.round(minDistance)) {
			if (Math.round(outerLineDistance) < Math.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 (Math.round(perpLineDistance) <= Math.round(minDistance)) {
			if (Math.round(perpLineDistance) < Math.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 isSelected = useValue(
		'is glob selected',
		() => editor.getSelectedShapeIds().includes(shape.id),
		[editor, shape.id]
	)

	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)

	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 (
		<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}
			/>
			{isSelected && <path d={pathBuilder.toD()} pointerEvents="none" fill="blue" opacity={0.25} />}
		</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 function 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,
	getIndicesAbove,
	RecordProps,
	ShapeUtil,
	SVGContainer,
	T,
	TLHandle,
	TLHandleDragInfo,
	TLResizeInfo,
	TLShape,
	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 getIndicatorPath(shape: NodeShape) {
		const path = new Path2D()
		path.arc(0, 0, shape.props.radius, 0, Math.PI * 2)
		return path
	}

	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 function 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 function 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 function 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 function 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 function 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 function 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 function circleCentresOverlap(c0: VecModel, r0: number, c1: VecModel) {
	const d = Vec.Dist(c0, c1)
	return d <= r0
}

export function 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')
	}
}
```

--------

# Popup shape

Category: Shapes & tools

Keywords: 3d effect, css transform, perspective, shadows, animation, interaction, double click, htmlcontainer, transform origin, visual effects

Cards that pop up in 3D using CSS perspective anchored to the viewport center.

Each shape renders a card tilted with a CSS `rotateX` transform inside an `HTMLContainer` that sets `perspective`. The trick is the perspective origin: it's computed from `editor.getViewportPageBounds()` relative to the shape, so every card shares one vanishing point at the center of the screen. Shape components are reactive, so reading the bounds during render keeps that origin updated as you pan and zoom.

Try panning around and double-clicking a card to pop it upright.

## App.tsx

```tsx
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
import './popup-shape.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 { useState } from 'react'
import { BaseBoxShapeUtil, HTMLContainer, RecordProps, T, TLShape } from 'tldraw'

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

const MY_POPUP_SHAPE_TYPE = 'my-popup-shape'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[MY_POPUP_SHAPE_TYPE]: { w: number; h: 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,
	}

	getDefaultProps(): IMyPopupShape['props'] {
		return {
			w: 200,
			h: 200,
		}
	}

	component(shape: IMyPopupShape) {
		// [1]
		const [popped, setPopped] = useState(false)

		// [2]
		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`,
				}}
				// [3]
				onPointerDown={this.editor.markEventAsHandled}
				onDoubleClick={(e) => {
					setPopped((p) => !p)
					this.editor.markEventAsHandled(e)
				}}
			>
				<div className="popup-shape-shadow" />
				<div
					className="popup-shape-card"
					style={{ transform: popped ? 'rotateX(0deg)' : 'rotateX(20deg)' }}
				/>
			</HTMLContainer>
		)
	}

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

/*
[1]
Whether the card is standing up or lying flat is purely visual, so it lives in React state
rather than in the shape's props. Double-clicking toggles it; the CSS transition animates it.

[2]
The 3D effect comes from CSS `perspective`. To make every card appear lit from the same
vantage point, the perspective origin is the viewport's center expressed in this shape's local
coordinates. A shape's `component` renders inside a reactive tracking scope, so reading the
viewport bounds here re-renders the shape as the camera moves and the vanishing point stays put.

[3]
The shape opts in to pointer events so it can receive the double click. Marking the events as
handled keeps the editor from treating them as a canvas click (which would select the shape or
start editing it).
*/
```

## popup-shape.css

```css
.popup-shape-shadow,
.popup-shape-card {
	position: absolute;
	top: 0;
	left: 0;
	width: 100%;
	height: 100%;
	transition: all 0.5s;
}

.popup-shape-shadow {
	background-color: rgba(0, 0, 0, 0.5);
}

.popup-shape-card {
	transform-origin: top center;
	background: gold;
	border: 1px solid goldenrod;
}
```

--------

# Commenting

Category: Collaboration

Keywords: comments, commenting, comment thread, annotations, feedback, review, collaboration, pins

Add comment threads to the canvas with the commenting toolkit.

Comment threads are records in the editor's store, so they persist and sync exactly like shapes. Register `commentSchemaRecords` on the schema, add `CommentTool` and `commentToolOverrides` to the editor, then render `CanvasComments` in the `InFrontOfTheCanvas` slot. That is the whole integration.

Press `c` or pick the comment tool, then click anywhere to start a thread, click a shape to attach one to it, or drag to comment on a region (turned on here with `CommentTool.configure({ enableRegions: true })`). Type `@` in a composer to mention someone; the suggestions come from `getMentionSuggestions`.

Commenting is a licensed feature. Everything works in local development, but a deployed app needs a license key that includes commenting.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	CommentTool,
	commentToolOverrides,
	filterMentionMembers,
	MentionMember,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo } from 'react'
import { commentSchemaRecords, createTLSchema, createTLStore, TLComponents, Tldraw } from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'

// A demo avatar image (inline SVG) so one author shows an image instead of a colored initial.
const ADA_AVATAR =
	'data:image/svg+xml,' +
	encodeURIComponent(
		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28"><rect width="28" height="28" fill="#0E9F6E"/><circle cx="14" cy="11" r="5" fill="#fff"/><ellipse cx="14" cy="24" rx="9" ry="7" fill="#fff"/></svg>`
	)

// The people who can be @-mentioned. A real app would pull this from its own roster; the composer
// filters this list as you type after `@`. Ids match the author directory below.
const MEMBERS: MentionMember[] = [
	{ id: 'me', name: 'You', color: '#EC5E41', you: true },
	{ id: 'ada', name: 'Ada Lovelace', color: '#0E9F6E', image: ADA_AVATAR },
	{ id: 'grace', name: 'Grace Hopper', color: '#4465E9' },
	{ id: 'alan', name: 'Alan Turing', color: '#9C1FBE' },
]

// A tiny local user directory so the flow shows names, colors, and images instead of ids. A real
// app would resolve these from its own identity system.
const AUTHORS: Record<string, CommentAuthor> = Object.fromEntries(MEMBERS.map((m) => [m.id, m]))
const resolveAuthor = (id: string): CommentAuthor => AUTHORS[id] ?? { name: id }

// Region comments are off by default. With `enableRegions`, dragging the comment tool out draws a
// rectangle and anchors the comment to that area instead of a point or shape.
const COMMENT_TOOLS = [CommentTool.configure({ enableRegions: true })]

export default function CommentingExample() {
	// Comments are stored as `comment-thread` and `comment` records in the editor's own store.
	// Registering `commentSchemaRecords` on the schema is all it takes to persist and sync them
	// alongside shapes — no separate backend, so the whole flow runs in-memory here.
	const store = useMemo(
		() => createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
		[]
	)

	// `CanvasComments` reads those records reactively and draws the pins, threads, and composer.
	// Mounting it in front of the canvas is the entire UI layer.
	const components = useMemo<TLComponents>(
		() => ({
			InFrontOfTheCanvas: () => (
				<CanvasComments
					currentUserId="me"
					resolveAuthor={resolveAuthor}
					getMentionSuggestions={(query) => filterMentionMembers(MEMBERS, query)}
				/>
			),
		}),
		[]
	)

	return (
		<div className="tldraw__editor">
			<Tldraw
				// Commenting is a licensed feature. Every feature is enabled in local development, but a
				// deployed app needs a license key that includes commenting — swap in your own key here.
				licenseKey={getLicenseKey()}
				store={store}
				tools={COMMENT_TOOLS}
				overrides={[commentToolOverrides]}
				components={components}
			/>
		</div>
	)
}
```

--------

# Multiplayer sync

Category: Collaboration

Keywords: multiplayer, sync, useSyncDemo, collaboration, real-time, websocket, co-editing

Connect to a shared room with `useSyncDemo` for instant multiplayer.

`useSyncDemo` returns a store connected to a demo sync backend that tldraw hosts, so you can prototype multiplayer without running a server. Pass the store to `<Tldraw>` and every client with the same `roomId` edits the same document. Data on the demo server is wiped after one day.

Open the example in two tabs to see cursors and edits sync. For a self-hosted backend, see the `useSync` hook in `@tldraw/sync` and the sync template.

## 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} options={{ deepLinks: true }} />
		</div>
	)
}
```

--------

# Commenting sidebar

Category: Collaboration

Keywords: comments, commenting, sidebar, list, panel, threads, filters

List every thread in a sidebar beside the canvas, with filters and a host-supplied toggle button.

`CanvasCommentsSidebar` is a batteries-included thread list that reads the same comment records as `CanvasComments`. It renders while the `commentsSidebarOpen` editor atom is set, so the host owns the open/close affordance: here a `TldrawUiButton` in the `SharePanel` slot calls `toggleCommentsSidebar`. Both components take the same `CommentingContext` fields, so one object is spread into each.

The example seeds a thread on each of two pages plus a resolved thread. By default the list shows every page's unresolved threads, labelling the ones on other pages; use the filter menu to show resolved threads or scope the list to the current page. Click a row to jump to its pin.

Activating the comment tool closes the sidebar, so the toggle button is how it comes back.

## App.tsx

```tsx
import {
	CanvasComments,
	CanvasCommentsSidebar,
	CommentAuthor,
	CommentingContext,
	commentsSidebarOpen,
	commentToolOverrides,
	commentTools,
	getCommentThreads,
	putCommentRecords,
	toggleCommentsSidebar,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo } from 'react'
import {
	commentSchemaRecords,
	createComment,
	createCommentThread,
	createShapeId,
	createTLSchema,
	createTLStore,
	Editor,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	toRichText,
	useEditor,
	useValue,
} from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'

// A tiny local user directory so the list shows names instead of ids.
const AUTHORS: Record<string, CommentAuthor> = {
	me: { name: 'You', color: '#EC5E41' },
	ada: { name: 'Ada Lovelace', color: '#0E9F6E' },
	grace: { name: 'Grace Hopper', color: '#4465E9' },
}
const resolveAuthor = (id: string): CommentAuthor => AUTHORS[id] ?? { name: id }

// The canvas layer and the sidebar read the same context — who you are, and how author ids become
// names — so it's built once and spread into each rather than repeated on both.
const commenting: CommentingContext = { currentUserId: 'me', resolveAuthor }

// Two pages with a thread each (so the sidebar's every-page default and page labels have
// something to show) plus a resolved thread, hidden until "show resolved" is toggled on.
function seed(editor: Editor) {
	// Hot reload and remounts re-run onMount — never seed twice.
	if (getCommentThreads(editor).length > 0) return

	const pageOne = editor.getCurrentPageId()
	const boxOne = createShapeId('sidebar-box-one')
	editor.createShape({ id: boxOne, type: 'geo', x: 180, y: 140, props: { w: 320, h: 220 } })

	editor.createPage({ name: 'Page 2' })
	const pageTwo = editor.getPages()[1].id
	editor.setCurrentPage(pageTwo)
	const boxTwo = createShapeId('sidebar-box-two')
	editor.createShape({
		id: boxTwo,
		type: 'geo',
		x: 240,
		y: 200,
		props: { w: 280, h: 200, geo: 'ellipse' },
	})
	editor.setCurrentPage(pageOne)

	const now = Date.now()
	const records = [
		{
			pageId: pageOne,
			shapeId: boxOne,
			author: 'ada',
			text: 'Is this the final position for this box?',
			minutesAgo: 45,
		},
		{
			pageId: pageTwo,
			shapeId: boxTwo,
			author: 'grace',
			text: 'The ellipse reads better than the rectangle did.',
			minutesAgo: 20,
		},
	].flatMap(({ pageId, shapeId, author, text, minutesAgo }) => {
		const thread = createCommentThread({
			pageId,
			anchor: { type: 'shape', shapeId, x: 0.5, y: 0.5, isPrecise: false },
			createdBy: author,
		})
		const comment = createComment({
			threadId: thread.id,
			pageId,
			authorId: author,
			body: toRichText(text),
		})
		const createdAt = now - minutesAgo * 60_000
		return [
			{ ...thread, createdAt },
			{ ...comment, createdAt },
		]
	})

	const resolvedThread = createCommentThread({
		pageId: pageOne,
		anchor: { type: 'point', x: 620, y: 420 },
		createdBy: 'me',
	})
	const resolvedComment = createComment({
		threadId: resolvedThread.id,
		pageId: pageOne,
		authorId: 'me',
		body: toRichText('Fixed the spacing here.'),
	})
	records.push(
		{
			...resolvedThread,
			createdAt: now - 90 * 60_000,
			resolved: { at: now - 60 * 60_000, by: 'me' },
		},
		{ ...resolvedComment, createdAt: now - 90 * 60_000 }
	)

	putCommentRecords(editor, records)
	commentsSidebarOpen.set(editor, true)
}

// The host supplies the sidebar's open/close affordance. Here it's a button in the share-panel
// slot. The comment tool closes the sidebar when it activates, so the button is how it comes back.
function SidebarToggle() {
	const editor = useEditor()
	const open = useValue('sidebar open', () => commentsSidebarOpen.get(editor), [editor])
	return (
		<div style={{ pointerEvents: 'all', display: 'flex', padding: 4 }}>
			<TldrawUiButton type="normal" onClick={() => toggleCommentsSidebar(editor)}>
				<TldrawUiButtonLabel>{open ? 'Hide comments' : 'Comments'}</TldrawUiButtonLabel>
			</TldrawUiButton>
		</div>
	)
}

export default function CommentingSidebarExample() {
	// Comments are stored as records in the editor's own store — registering the comment schema
	// records is all it takes to persist and sync them alongside shapes.
	const store = useMemo(
		() => createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
		[]
	)

	const components = useMemo<TLComponents>(
		() => ({
			InFrontOfTheCanvas: () => (
				<>
					<CanvasComments {...commenting} />
					<CanvasCommentsSidebar {...commenting} />
				</>
			),
			SharePanel: SidebarToggle,
		}),
		[]
	)

	return (
		<div className="tldraw__editor">
			<Tldraw
				licenseKey={getLicenseKey()}
				store={store}
				tools={commentTools}
				overrides={[commentToolOverrides]}
				components={components}
				onMount={seed}
			/>
		</div>
	)
}
```

--------

# Comment clustering

Category: Collaboration

Keywords: comments, commenting, clustering, pins, zoom, count badge, collaboration

Merge nearby comment pins into a count badge as you zoom out.

When a board fills with comments, pins that sit close together overlap and become unreadable at low zoom. Clustering merges nearby anchors into a single count badge as you zoom out, and splits them back into pins as you zoom in. Splits happen at a wider spacing than merges, so pins don't flicker at the threshold, and clicking a badge zooms to just past the point where it splits.

`CanvasComments` does this for you — clustering is on by default and needs no configuration. Turn it off with `CommentTool.configure({ enableClustering: false })` and every pin renders individually at every zoom.

This example seeds two loose groups of threads. Zoom out with `⌘`/`ctrl`-scroll or a pinch gesture to watch each group collapse.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	commentToolOverrides,
	commentTools,
	putCommentRecords,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo } from 'react'
import {
	commentSchemaRecords,
	createComment,
	createCommentThread,
	createTLSchema,
	createTLStore,
	Editor,
	TLComponents,
	Tldraw,
	toRichText,
	VecLike,
} from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'
import './comment-clustering.css'

const AUTHORS: Record<string, CommentAuthor> = {
	ada: { name: 'Ada Lovelace', color: '#0E9F6E' },
	grace: { name: 'Grace Hopper', color: '#4465E9' },
	me: { name: 'You', color: '#EC5E41' },
}
const resolveAuthor = (id: string): CommentAuthor => AUTHORS[id] ?? { name: id }

// [1]
const THREADS: { point: VecLike; by: string; text: string }[] = [
	{ point: { x: 250, y: 140 }, by: 'ada', text: 'Should this column be wider?' },
	{ point: { x: 300, y: 170 }, by: 'grace', text: 'Agreed, it wraps on mobile.' },
	{ point: { x: 265, y: 220 }, by: 'ada', text: 'Same for the row beneath it.' },
	{ point: { x: 800, y: 250 }, by: 'grace', text: 'This label reads as a button.' },
	{ point: { x: 845, y: 285 }, by: 'ada', text: 'Let’s make it a link instead.' },
]

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

	const handleMount = (editor: Editor) => {
		const pageId = editor.getCurrentPageId()
		for (const { point, by, text } of THREADS) {
			const thread = createCommentThread({
				pageId,
				anchor: { type: 'point', x: point.x, y: point.y },
				createdBy: by,
			})
			const comment = createComment({
				threadId: thread.id,
				pageId,
				authorId: by,
				body: toRichText(text),
			})
			putCommentRecords(editor, [thread, comment])
		}
	}

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

	return (
		<div className="tldraw__editor">
			<Tldraw
				licenseKey={getLicenseKey()}
				store={store}
				tools={commentTools}
				overrides={[commentToolOverrides]}
				components={components}
				onMount={handleMount}
			/>
			<div className="comment-clustering__hint">Zoom out to cluster (⌘/ctrl-scroll or pinch)</div>
		</div>
	)
}

/*
[1]
Two clusters of pins, far enough apart that they stay separate while the ones within each group
merge. Zoom out and each group folds into a single count badge; zoom back in and they split apart.
Splits happen at a wider spacing than merges, so pins don't flicker at the threshold, and clicking a
badge zooms to just past the point where it splits.

Clustering is on by default and needs no configuration. Turn it off with
`CommentTool.configure({ enableClustering: false })` and every pin renders individually at every
zoom.
*/
```

## comment-clustering.css

```css
.comment-clustering__hint {
	position: absolute;
	top: 12px;
	left: 50%;
	transform: translateX(-50%);
	z-index: 400;
	padding: 5px 10px;
	border-radius: 8px;
	background: rgba(0, 0, 0, 0.7);
	color: #fff;
	font-size: 12px;
	pointer-events: none;
}
```

--------

# Multiplayer sync with a custom shape

Category: Collaboration

Keywords: multiplayer, sync, useSyncDemo, shapeUtils, custom shape, shapeutil, collaboration, real-time

Sync a custom shape between clients by registering its shape util with the store.

A synced store validates and migrates records for every shape type it holds, so a custom shape's `ShapeUtil` has to be passed to `useSyncDemo` (as `shapeUtils`) as well as to `<Tldraw>`. Without it the store rejects the shape when it arrives from another client.

The `counter` shape here has a `count` prop with `+` and `-` buttons. Open the example in two tabs and click a button; the count updates everywhere because the change is an ordinary `editor.updateShape` on a synced record.

## 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 }) {
	// The store needs the shape utils too, so it can validate and migrate counter shapes that arrive
	// from other clients.
	const store = useSyncDemo({ roomId, shapeUtils: customShapes })
	return (
		<div className="tldraw__editor">
			<Tldraw
				store={store}
				shapeUtils={customShapes}
				tools={customTools}
				overrides={uiOverrides}
				components={components}
				options={{ deepLinks: true }}
			/>
		</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 getIndicatorPath(shape: CounterShape) {
		const path = new Path2D()
		path.rect(0, 0, shape.props.w, shape.props.h)
		return path
	}
}

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) {
		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, collaboration, presence, facepile, people menu, getcollaborators, tlinstancepresence, cursor position, custom ui

Build a custom people menu that lists connected collaborators and their cursor positions.

Replace the `SharePanel` slot with your own component and read `editor.getCollaborators()` inside `useValue`. Each entry is a `TLInstancePresence` record with the collaborator's name, color, cursor, camera, and selection, so you can render a richer or differently styled presence indicator than the default facepile.

Open the example in two tabs to see the other user appear in the list.

## App.tsx

```tsx
import { useSyncDemo } from '@tldraw/sync'
import { TLComponents, Tldraw, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import './sync-custom-people-menu.css'

// [1]
const components: TLComponents = {
	SharePanel: () => (
		<div className="tlui-share-zone" draggable={false}>
			<CustomPeopleMenu />
		</div>
	),
}

export default function SyncCustomPeopleMenuExample({ roomId }: { roomId: string }) {
	const store = useSyncDemo({ roomId })
	return (
		<div className="tldraw__editor">
			<Tldraw store={store} options={{ deepLinks: true }} components={components} />
		</div>
	)
}

function CustomPeopleMenu() {
	const editor = useEditor()

	// [2]
	const myUserColor = useValue('user color', () => editor.user.getColor(), [editor])
	const myUserName = useValue('user name', () => editor.user.getName() || 'Guest', [editor])
	const myUserId = useValue('user id', () => editor.user.getExternalId(), [editor])

	// [3]
	const collaborators = useValue('collaborators', () => editor.getCollaborators(), [editor])

	return (
		<div className="custom-people-menu">
			<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>

			{collaborators.length > 0 && (
				<div className="other-users-section">
					<h4 className="section-title">Other connected users</h4>
					<div className="other-users-list">
						{collaborators.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 }}>
									{userName || `ID: ${userId}`}
								</span>
								<span className="cursor-info">
									Cursor
									<br />
									{cursor ? `(${Math.round(cursor.x)}, ${Math.round(cursor.y)})` : 'unavailable'}
								</span>
							</div>
						))}
					</div>
				</div>
			)}
		</div>
	)
}

/*
[1]
Replace the `SharePanel` slot (the top-right area where the default people menu lives) with a
custom component. Wrapping it in `tlui-share-zone` keeps the default panel styling.

[2]
The current user's own details come from `editor.user`. Reading them inside `useValue` keeps them
reactive, so the panel updates if the name or color changes.

[3]
`editor.getCollaborators()` returns a `TLInstancePresence` record for every other connected user:
name, color, cursor, camera, selection, and more. It's reactive, so calling it inside `useValue`
re-renders the panel as people join, leave, or move their cursor.
*/
```

## sync-custom-people-menu.css

```css
.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: multiplayer, collaboration, presence, custom data, sync, tlinstancepresence, user state, real-time

Change the presence data synced to other users with `getUserPresence`.

Presence is the per-user state (cursor, camera, selection, chat message) that sync broadcasts to every other client. Pass `getUserPresence` to `useSyncDemo` (or `useSync`) to control what is sent: start from `getDefaultUserPresence`, then remove fields you don't want shared or change them.

This example drops the camera, so other users can't follow this viewport, and makes the cursor orbit its real position. Open the example in two tabs to see the effect.

## 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 SyncCustomPresenceExample({ roomId }: { roomId: string }) {
	// [1]
	const timer = useAtom('timer', Date.now())
	useEffect(() => {
		let frame = requestAnimationFrame(function tick() {
			timer.set(Date.now())
			frame = requestAnimationFrame(tick)
		})
		return () => cancelAnimationFrame(frame)
	}, [timer])

	// [2]
	const store = useSyncDemo({
		roomId,
		getUserPresence(store, user) {
			// [3]
			const defaults = getDefaultUserPresence(store, user)
			if (!defaults) return null

			return {
				...defaults,

				// [4]
				camera: undefined,

				// [5]
				cursor: {
					...defaults.cursor,
					x: defaults.cursor.x + 20 * Math.sin(timer.get() / 200),
					y: defaults.cursor.y + 20 * Math.cos(timer.get() / 200),
				},
			}
		},
	})

	return (
		<div className="tldraw__editor">
			<Tldraw store={store} options={{ deepLinks: true }} />
		</div>
	)
}

/*
Presence is the per-user state (cursor, camera, selection, and so on) that sync broadcasts to every
other client. `getUserPresence` lets you change what gets sent: strip out fields your app doesn't
need, or add to them.

[1]
A timer that ticks every frame, held in an atom. `getUserPresence` runs inside a computed signal, so
reading the atom there re-derives the presence whenever it changes. You don't need this in a real
app; it's only here to animate the cursor.

[2]
`useSyncDemo` accepts a `getUserPresence` function that replaces the default derivation.

[3]
Start from `getDefaultUserPresence` so the usual fields are still sent. It returns null before the
editor's instance state exists, so pass that through.

[4]
Setting a field to `undefined` drops it, and the record falls back to its default (`null` here). Other
clients won't be able to follow this user's viewport.

[5]
Offset the cursor by the timer, so it orbits its true position on other clients' screens.
*/
```

--------

# Comment anchors

Category: Collaboration

Keywords: comments, commenting, anchors, shape, region, point, collaboration

Seed threads with each kind of anchor: a point, a shape (precise and imprecise), and a region.

Every `TLCommentThread` carries an `anchor` that says where on the page it lives: a `point` at fixed page coordinates, a `shape` that tracks the shape as it moves and resizes, or a `region` covering a rectangular area. A fourth kind, `page`, has no pin and surfaces only in a list.

Shape anchors store a normalized `x`/`y` inside the shape's bounds. When `isPrecise` is true the pin sits exactly there; when false the pin sits at the `impreciseShapeAnchor` option (the top-right corner by default) and the anchor addresses the shape as a whole.

The example creates each thread with `createCommentThread` and `createComment`, then writes them with `putCommentRecords`. Drag the shape to watch its pins follow it.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	commentToolOverrides,
	commentTools,
	putCommentRecords,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo } from 'react'
import {
	commentSchemaRecords,
	createComment,
	createCommentThread,
	createShapeId,
	createTLSchema,
	createTLStore,
	Editor,
	TLCommentAnchor,
	TLComponents,
	Tldraw,
	toRichText,
} from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'

// A demo avatar image (inline SVG) so Ada's comments show an image instead of a colored initial.
const ADA_AVATAR =
	'data:image/svg+xml,' +
	encodeURIComponent(
		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28"><rect width="28" height="28" fill="#0E9F6E"/><circle cx="14" cy="11" r="5" fill="#fff"/><ellipse cx="14" cy="24" rx="9" ry="7" fill="#fff"/></svg>`
	)

const AUTHORS: Record<string, CommentAuthor> = {
	ada: { name: 'Ada Lovelace', color: '#0E9F6E', image: ADA_AVATAR },
	me: { name: 'You', color: '#EC5E41' },
}
const resolveAuthor = (id: string): CommentAuthor => AUTHORS[id] ?? { name: id }

// A thread plus its opening comment, anchored however the caller specifies. Every `TLCommentThread`
// carries an `anchor` — a discriminated union — and `CanvasComments` renders each kind in the right
// place: shape pins track the shape, point/region pins sit at fixed page coordinates.
function seedThread(editor: Editor, anchor: TLCommentAnchor, text: string) {
	const pageId = editor.getCurrentPageId()
	const thread = createCommentThread({ pageId, anchor, createdBy: 'ada' })
	const comment = createComment({
		threadId: thread.id,
		pageId,
		authorId: 'ada',
		body: toRichText(text),
	})
	putCommentRecords(editor, [thread, comment])
}

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

	const handleMount = (editor: Editor) => {
		// A rectangle to anchor shape comments against.
		const boxId = createShapeId()
		editor.run(
			() => {
				editor.createShapes([
					{ id: boxId, type: 'geo', x: 120, y: 100, props: { geo: 'rectangle', w: 200, h: 140 } },
				])

				// shape (imprecise): normalized x/y ignored for the pin, which sits at the shape's
				// top-right badge spot. The anchor still tracks the shape as it moves and resizes.
				seedThread(
					editor,
					{ type: 'shape', shapeId: boxId, x: 1, y: 0, isPrecise: false },
					'Anchored to this shape (imprecise — sits at the corner).'
				)
				// shape (precise): the pin sits exactly at the stored normalized spot inside the shape.
				seedThread(
					editor,
					{ type: 'shape', shapeId: boxId, x: 0.5, y: 0.6, isPrecise: true },
					'Anchored to a precise spot inside the shape.'
				)
				// point: a bare page coordinate, unattached to any shape.
				seedThread(editor, { type: 'point', x: 200, y: 340 }, 'Anchored to a point on the page.')
				// region: a rectangular area; the pin sits on its corner and the box is drawn.
				seedThread(
					editor,
					{ type: 'region', x: 380, y: 300, w: 200, h: 130 },
					'Anchored to a region of the page.'
				)
			},
			{ history: 'ignore' }
		)

		editor.zoomToBounds({ x: 60, y: 60, w: 600, h: 420 }, { immediate: true })
	}

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

	return (
		<div className="tldraw__editor">
			<Tldraw
				// Commenting is a licensed feature. Every feature is enabled in local development, but a
				// deployed app needs a license key that includes commenting — swap in your own key here.
				licenseKey={getLicenseKey()}
				store={store}
				onMount={handleMount}
				tools={commentTools}
				overrides={[commentToolOverrides]}
				components={components}
			/>
		</div>
	)
}
```

--------

# Multiplayer sync with private content

Category: Collaboration

Keywords: multiplayer, sync, private, visibility, getShapeVisibility, permissions, ownership, meta, side effects, registerBeforeCreateHandler

Hide shapes from other users in a multiplayer session with `getShapeVisibility` and shape meta.

A store side effect stamps every new shape with the creator's id and a `private` flag, and `getShapeVisibility` hides shapes whose flag is set unless you own them. The shapes still sync; they're just not rendered for anyone else. Selecting your own private shapes offers to make them public.

Open the example in two tabs, turn on private mode in one, and draw. Note this is client-side visibility only, not access control: a private shape is still in every client's store.

## 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.getExternalId(), [editor])
		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}
				options={{ deepLinks: true }}
				// [4]
				getShapeVisibility={(shape, editor) => {
					const userId = editor.user.getExternalId()
					if (!!shape.meta.private && shape.meta.ownerId !== userId) {
						return 'hidden'
					}
					return 'inherit'
				}}
				onMount={(editor) => {
					// [5]
					const removeCreateHandler = editor.store.sideEffects.registerBeforeCreateHandler(
						'shape',
						(shape) => {
							if ('private' in shape.meta) return shape
							return {
								...shape,
								meta: {
									...shape.meta,
									private: isPrivateMode$.get(),
									ownerId: editor.user.getExternalId(),
								},
							}
						}
					)

					// [6]
					const stopCleaningSelection = react('clean up selection', () => {
						const selectedShapes = editor.getSelectedShapes()
						const filteredSelectedShapes = selectedShapes.filter((s) => !editor.isShapeHidden(s))
						if (filteredSelectedShapes.length !== selectedShapes.length) {
							editor.select(...filteredSelectedShapes)
						}
					})

					return () => {
						removeCreateHandler()
						stopCleaningSelection()
					}
				}}
				components={components}
			/>
		</div>
	)
}

export default function SyncPrivateContentExample({ roomId }: { roomId: string }) {
	return (
		<PrivateModeContext.Provider value={useAtom('isPrivateDrawingMode', false)}>
			<App roomId={roomId} />
		</PrivateModeContext.Provider>
	)
}

/*
A 'private' drawing mode: shapes created while it is on are tagged with the creator's id and hidden
from everyone else. Selecting your own private shapes offers to make them public.

[1]
A context holding the atom for the private-mode flag. Signals are used here, but any state
container works.

[2]
The `InFrontOfTheCanvas` slot hosts a small panel that toggles private mode, or, when private shapes
are selected, offers to make them public.

[3]
`useValue` on the atom gives the panel a reactive read of the flag.

[4]
`getShapeVisibility` hides shapes that are private and owned by someone else. Hidden shapes are
still in the store and still sync; they're just not rendered or hittable for this user.

[5]
A before-create side effect stamps every new shape with `private` and `ownerId` meta. Because it
runs in the store, it covers every creation path (tools, paste, duplicate), not just the ones this
UI knows about. `onMount` returns a cleanup so the handler and the reaction below are removed when
the editor unmounts.

[6]
A reaction that drops hidden shapes from the selection. Without it, toggling private mode while a
now-hidden shape is selected would leave an invisible selection.

[7]
Child shapes inside groups and frames don't inherit their parent's `private` meta, so making a
shape public also makes its descendants public, which is what the user almost certainly meant.
*/
```

## 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;
	pointer-events: auto;
}

.toggle-panel button {
	cursor: pointer;
}

.toggle-panel.pointer {
	cursor: pointer;
}
```

--------

# Commenting on mobile

Category: Collaboration

Keywords: comments, commenting, mobile, responsive, breakpoint, forceMobile, thread, composer, placement, keyboard

Commenting with the mobile layout, where the thread popover and composer place themselves to stay on-screen above the keyboard.

The same setup as the [Commenting](/examples/commenting) example, with `forceMobile` on the editor so the mobile layout shows on any screen size.

In mobile mode the thread popover and the new-comment composer position themselves relative to the pin and the visual viewport rather than sitting at a fixed offset. They pick a side of the pin that keeps the whole panel on-screen, and ride up when the software keyboard shrinks the viewport instead of hiding behind it. Place a comment near an edge to see the placement adapt.

Drop `forceMobile` and the layout switches on the viewport width, the way it does on a real device.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	CommentTool,
	commentToolOverrides,
	filterMentionMembers,
	MentionMember,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo } from 'react'
import { commentSchemaRecords, createTLSchema, createTLStore, TLComponents, Tldraw } from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'

// A demo avatar image (inline SVG) so one author shows an image instead of a colored initial.
const ADA_AVATAR =
	'data:image/svg+xml,' +
	encodeURIComponent(
		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28"><rect width="28" height="28" fill="#0E9F6E"/><circle cx="14" cy="11" r="5" fill="#fff"/><ellipse cx="14" cy="24" rx="9" ry="7" fill="#fff"/></svg>`
	)

// The people who can be @-mentioned. A real app would pull this from its own roster; the composer
// filters this list as you type after `@`. Ids match the author directory below.
const MEMBERS: MentionMember[] = [
	{ id: 'me', name: 'You', color: '#EC5E41', you: true },
	{ id: 'ada', name: 'Ada Lovelace', color: '#0E9F6E', image: ADA_AVATAR },
	{ id: 'grace', name: 'Grace Hopper', color: '#4465E9' },
	{ id: 'alan', name: 'Alan Turing', color: '#9C1FBE' },
]

// A tiny local user directory so the flow shows names, colors, and images instead of ids. A real
// app would resolve these from its own identity system.
const AUTHORS: Record<string, CommentAuthor> = Object.fromEntries(MEMBERS.map((m) => [m.id, m]))
const resolveAuthor = (id: string): CommentAuthor => AUTHORS[id] ?? { name: id }

// Region comments are off by default. With `enableRegions`, dragging the comment tool out draws a
// rectangle and anchors the comment to that area instead of a point or shape.
const COMMENT_TOOLS = [CommentTool.configure({ enableRegions: true })]

export default function CommentingMobileExample() {
	// Comments are stored as `comment-thread` and `comment` records in the editor's own store.
	// Registering `commentSchemaRecords` on the schema is all it takes to persist and sync them
	// alongside shapes — no separate backend, so the whole flow runs in-memory here.
	const store = useMemo(
		() => createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
		[]
	)

	// `CanvasComments` reads those records reactively and draws the pins, threads, and composer.
	// Mounting it in front of the canvas is the entire UI layer.
	const components = useMemo<TLComponents>(
		() => ({
			InFrontOfTheCanvas: () => (
				<CanvasComments
					currentUserId="me"
					resolveAuthor={resolveAuthor}
					getMentionSuggestions={(query) => filterMentionMembers(MEMBERS, query)}
				/>
			),
		}),
		[]
	)

	return (
		<div className="tldraw__editor">
			<Tldraw
				// `forceMobile` pins the mobile breakpoint on any screen size, so the mobile thread and
				// composer placement is visible here on desktop. On a real device the same layout comes
				// from the narrow viewport — the thread popover and composer position themselves against
				// the visual viewport, riding up rather than hiding behind the software keyboard.
				forceMobile
				// Commenting is a licensed feature. Every feature is enabled in local development, but a
				// deployed app needs a license key that includes commenting — swap in your own key here.
				licenseKey={getLicenseKey()}
				store={store}
				tools={COMMENT_TOOLS}
				overrides={[commentToolOverrides]}
				components={components}
			/>
		</div>
	)
}
```

--------

# Manually update user presence

Category: Collaboration

Keywords: presence, cursors, InstancePresenceRecordType, collaboration cursors, fake users, cursor position, chat message, cursor animation, mergeRemoteChanges

Show another user's cursor and chat bubble by writing an `instance_presence` record to the store.

Collaborator cursors, names, and chat messages are rendered from `instance_presence` records. This example creates one for a fake peer with `InstancePresenceRecordType.create`, writes it inside `store.mergeRemoteChanges`, and updates its cursor and `lastActivityTimestamp` every frame so the cursor stays visible and moves in a circle.

If you have your own presence system, you can write real records the same way. For a full multiplayer setup, see the sync examples.

## App.tsx

```tsx
import { createUserId, Editor, InstancePresenceRecordType, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

// [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.'

function handleMount(editor: Editor) {
	// [2]
	const peerPresence = InstancePresenceRecordType.create({
		id: InstancePresenceRecordType.createId(editor.store.id),
		currentPageId: editor.getCurrentPageId(),
		userId: createUserId('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])
	})

	// [3]
	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 }])
		})

		editor.timers.requestAnimationFrame(loop)
	}

	editor.timers.requestAnimationFrame(loop)
}

export default function UserPresenceExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="user-presence-example" onMount={handleMount} />
		</div>
	)
}

/*
Other users' cursors, names, and chat bubbles are driven by `instance_presence` records in the
store. This example puts a fake one in by hand. It is not a multiplayer implementation; see the sync
examples for that. If you have your own presence transport, you can write real records the same way.

[1]
The fake peer's name, cursor path, and chat message.

[2]
One `instance_presence` record per connected peer, created with `InstancePresenceRecordType.create`.
Writing it inside `store.mergeRemoteChanges` marks the change as coming from a remote source, so it
doesn't land on the undo stack or get treated as a local edit.

[3]
Move the cursor in a circle and type out the chat message, updating the record every frame.
`lastActivityTimestamp` is what keeps the cursor visible: the editor hides collaborators who go
quiet. `editor.timers.requestAnimationFrame` is cancelled automatically when the editor is disposed,
so there's nothing to clean up.
*/
```

--------

# Shape comment precision

Category: Collaboration

Keywords: comments, commenting, precise, imprecise, shape, anchor, alt, collaboration

Pin a comment to the exact spot you clicked on a shape, or to the shape as a whole.

A comment on a shape anchors either precisely, at the clicked spot, or imprecisely, addressing the shape as a whole with its pin at `impreciseShapeAnchor`. Both track the shape as it moves and resizes.

`shouldBePrecise` makes the call, and receives the target shape's id, the release point, and whether Alt was held. Use the buttons to switch modes, then comment on the rectangle and the note to feel the difference.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	CommentTool,
	commentToolOverrides,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo, useState } from 'react'
import {
	commentSchemaRecords,
	createTLSchema,
	createTLStore,
	Editor,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	toRichText,
} from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'
import './comment-shape-precision.css'

// [1]
const MODE_TOOLS = {
	always: [CommentTool],
	never: [CommentTool.configure({ shouldBePrecise: () => false })],
	alt: [CommentTool.configure({ shouldBePrecise: (_editor, { altKey }) => altKey })],
	notes: [
		CommentTool.configure({
			shouldBePrecise: (editor, { shapeId }) => editor.getShape(shapeId)?.type === 'note',
		}),
	],
}

type PrecisionMode = keyof typeof MODE_TOOLS

const MODE_LABELS: Record<PrecisionMode, string> = {
	always: 'Always precise (default)',
	never: 'Shape only',
	alt: 'Alt for precise',
	notes: 'Notes precise',
}

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

const handleMount = (editor: Editor) => {
	// A shape and a note to comment on. The store survives mode switches, so only seed once.
	if (editor.getCurrentPageShapeIds().size === 0) {
		editor.run(
			() => {
				editor.createShapes([
					{
						type: 'geo',
						x: 100,
						y: 160,
						props: { geo: 'rectangle', w: 280, h: 180, richText: toRichText('A shape') },
					},
					{
						type: 'note',
						x: 460,
						y: 150,
						props: { richText: toRichText('A note') },
					},
				])
			},
			{ history: 'ignore' }
		)
	}
	editor.zoomToBounds({ x: 40, y: 60, w: 700, h: 400 }, { immediate: true })
}

export default function CommentShapePrecisionExample() {
	const [mode, setMode] = useState<PrecisionMode>('always')

	// Comments live in the editor's own store as records; sharing one store across mode switches
	// keeps every placed thread visible while the tool is reconfigured.
	const store = useMemo(
		() => createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
		[]
	)

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

	return (
		<div className="tldraw__editor">
			<Tldraw
				// [2]
				key={mode}
				// Commenting is a licensed feature. Every feature is enabled in local development, but a
				// deployed app needs a license key that includes commenting — swap in your own key here.
				licenseKey={getLicenseKey()}
				store={store}
				onMount={handleMount}
				tools={MODE_TOOLS[mode]}
				overrides={[commentToolOverrides]}
				components={components}
			>
				<div className="tlui-menu comment-precision-panel">
					{(Object.keys(MODE_LABELS) as PrecisionMode[]).map((id) => (
						<TldrawUiButton
							key={id}
							type={mode === id ? 'primary' : 'normal'}
							onClick={() => setMode(id)}
						>
							<TldrawUiButtonLabel>{MODE_LABELS[id]}</TldrawUiButtonLabel>
						</TldrawUiButton>
					))}
				</div>
			</Tldraw>
		</div>
	)
}

/*
[1]
One configured comment tool per mode, built once at module level so each array keeps a stable
identity. `shouldBePrecise` decides what commenting on a shape produces: a precise anchor, pinned to
the exact clicked spot within the shape (the default), or an imprecise one, pinned to the shape as
a whole and rendered at `impreciseShapeAnchor`. It's called with the target shape's id, the
release point, and the Alt key's state, so it can be a constant, an Alt-gated choice, or a decision
from the shape itself, like "precise only on notes".

[2]
Commenting options are fixed at tool registration (`CommentTool.configure`), so switching modes
remounts the editor with the newly configured tool. The shared store carries the comments across.
*/
```

## comment-shape-precision.css

```css
.comment-precision-panel {
	position: absolute;
	top: 60px;
	left: 8px;
	z-index: 1000;
	display: flex;
	flex-wrap: wrap;
	gap: 4px;
	padding: 4px;
	pointer-events: all;
}
```

--------

# Comments and undo

Category: Collaboration

Keywords: comments, commenting, history, undo, redo, dragHistory, multiplayer, collaboration

Decide whether comment writes land on the editor's undo stack.

`CommentingOptions.history` governs every comment write — posting, replying, editing, resolving, deleting — and defaults to `'ignore'`. In a shared document an undoable delete would resurrect a thread a collaborator already removed.

Pin drags are the exception, since re-anchoring may reasonably undo alongside a shape move. `dragHistory` overrides `history` for drags alone.

Move the shape, post a comment, drag its pin, then press undo and watch the counts.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	CommentTool,
	commentToolOverrides,
	useComments,
	useCommentThreads,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo, useState } from 'react'
import {
	commentSchemaRecords,
	createTLSchema,
	createTLStore,
	Editor,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	toRichText,
	useEditor,
	useValue,
} from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'
import './comment-history.css'

// [1]
const MODE_TOOLS = {
	ignore: [CommentTool],
	record: [CommentTool.configure({ history: 'record' })],
	drag: [CommentTool.configure({ dragHistory: 'record' })],
}

type HistoryMode = keyof typeof MODE_TOOLS

const MODE_LABELS: Record<HistoryMode, string> = {
	ignore: 'Ignore (default)',
	record: 'Record everything',
	drag: 'Record pin drags only',
}

const MODE_HINTS: Record<HistoryMode, string> = {
	ignore: 'Undo rewinds the shape. Comments and pin positions stay put.',
	record: 'Undo rewinds comments too — the last thing you did, whatever it was.',
	drag: 'Undo rewinds the shape and pin drags, but never a posted comment.',
}

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

function handleMount(editor: Editor) {
	// The store outlives a mode switch, so only seed on the first mount.
	if (editor.getCurrentPageShapeIds().size === 0) {
		editor.run(
			() => {
				editor.createShapes([
					{
						type: 'geo',
						x: 180,
						y: 180,
						props: { geo: 'rectangle', w: 300, h: 200, richText: toRichText('Move me') },
					},
				])
			},
			// [2]
			{ history: 'ignore' }
		)
	}
	editor.zoomToBounds({ x: 100, y: 100, w: 620, h: 380 }, { immediate: true })
}

// [3]
function HistoryPanel({
	mode,
	onModeChange,
}: {
	mode: HistoryMode
	onModeChange(mode: HistoryMode): void
}) {
	const editor = useEditor()
	const threads = useCommentThreads(editor)
	const comments = useComments(editor)
	const canUndo = useValue('can undo', () => editor.getCanUndo(), [editor])
	const canRedo = useValue('can redo', () => editor.getCanRedo(), [editor])

	return (
		<div className="tlui-menu comment-history-panel">
			<div className="comment-history-panel__row">
				{(Object.keys(MODE_LABELS) as HistoryMode[]).map((id) => (
					<TldrawUiButton
						key={id}
						type={mode === id ? 'primary' : 'normal'}
						onClick={() => onModeChange(id)}
					>
						<TldrawUiButtonLabel>{MODE_LABELS[id]}</TldrawUiButtonLabel>
					</TldrawUiButton>
				))}
			</div>
			<div className="comment-history-panel__row">
				<TldrawUiButton type="normal" disabled={!canUndo} onClick={() => editor.undo()}>
					<TldrawUiButtonLabel>Undo</TldrawUiButtonLabel>
				</TldrawUiButton>
				<TldrawUiButton type="normal" disabled={!canRedo} onClick={() => editor.redo()}>
					<TldrawUiButtonLabel>Redo</TldrawUiButtonLabel>
				</TldrawUiButton>
				<span className="comment-history-panel__count">
					{threads.length} {threads.length === 1 ? 'thread' : 'threads'}, {comments.length}{' '}
					{comments.length === 1 ? 'comment' : 'comments'}
				</span>
			</div>
			<p className="comment-history-panel__hint">{MODE_HINTS[mode]}</p>
		</div>
	)
}

export default function CommentHistoryExample() {
	const [mode, setMode] = useState<HistoryMode>('ignore')

	// Comments are records in the editor's own store. Sharing one store across mode switches keeps
	// every thread you place while the tool is reconfigured.
	const store = useMemo(
		() => createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
		[]
	)

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

	return (
		<div className="tldraw__editor">
			<Tldraw
				// [4]
				key={mode}
				// Commenting is a licensed feature. Every feature is enabled in local development, but a
				// deployed app needs a license key that includes commenting — swap in your own key here.
				licenseKey={getLicenseKey()}
				store={store}
				onMount={handleMount}
				tools={MODE_TOOLS[mode]}
				overrides={[commentToolOverrides]}
				components={components}
			>
				<HistoryPanel mode={mode} onModeChange={setMode} />
			</Tldraw>
		</div>
	)
}

/*
[1]
One configured comment tool per mode. `history` governs how every comment write — posting,
replying, editing, resolving, deleting — interacts with the editor's undo stack, and `dragHistory`
overrides it for pin drags alone.

`'ignore'` is the default, and it's the right one for a shared document: an undoable delete
resurrects a thread a collaborator already removed, and an undoable resolve reverts their newer
state. `'record'` is safe single-player, or against a comment store that isn't synced.

Pin drags are the interesting exception. Re-anchoring a comment is a spatial edit that may
reasonably undo alongside a shape move, so it can be recorded while posts stay ignored — the third
mode here.

[2]
The same option, used directly. Seeded shapes shouldn't be undoable either, so the seeding run is
wrapped in `history: 'ignore'` — otherwise the first undo would delete the shape the example is
about.

[3]
The counts come from `useCommentThreads` and `useComments`, which read the comment records
reactively. Watching them while you press undo is the whole point: in `'ignore'` mode they never
move, and in `'record'` mode they tick down.

[4]
Commenting options are fixed when the tool is registered, so switching modes remounts the editor
with a newly configured tool. The shared store carries the comments across, but the undo stack is
part of the editor, not the store — so it starts empty after every switch.
*/
```

## comment-history.css

```css
.comment-history-panel {
	position: absolute;
	top: 60px;
	left: 8px;
	z-index: 1000;
	display: flex;
	flex-direction: column;
	gap: 4px;
	padding: 8px;
	max-width: 420px;
	pointer-events: all;
}

.comment-history-panel__row {
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 4px;
}

.comment-history-panel__count {
	padding-left: 4px;
	font-size: 12px;
	color: var(--tl-color-text-3);
	font-variant-numeric: tabular-nums;
}

.comment-history-panel__hint {
	margin: 0;
	padding: 0 4px;
	font-size: 12px;
	line-height: 1.4;
	color: var(--tl-color-text-1);
}
```

--------

# Region comments

Category: Collaboration

Keywords: comments, commenting, region, area, drag, resize, collaboration

Comment on a rectangular area of the canvas.

A region anchor attaches a thread to a rectangular area rather than to a point or a shape. Regions are off by default; `CommentTool.configure({ enableRegions: true })` turns them on, and that's the whole configuration.

A region reveals its dashed box while the pointer is inside it, moves by its pin, and resizes from its corners. The pin sits on whichever corner the creating drag released on. Select the comment tool (or press `c`) and drag to create one.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	CommentTool,
	commentToolOverrides,
	putCommentRecords,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo } from 'react'
import {
	commentSchemaRecords,
	createComment,
	createCommentThread,
	createTLSchema,
	createTLStore,
	Editor,
	TLComponents,
	Tldraw,
	toRichText,
} from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'

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

// [1]
const COMMENT_TOOLS = [CommentTool.configure({ enableRegions: true })]

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

// [2]
const handleMount = (editor: Editor) => {
	editor.run(
		() => {
			editor.createShapes([
				{
					type: 'geo',
					x: 150,
					y: 150,
					props: { geo: 'rectangle', w: 160, h: 100, richText: toRichText('A shape') },
				},
				{
					type: 'geo',
					x: 350,
					y: 180,
					props: { geo: 'ellipse', w: 120, h: 120, richText: toRichText('Another') },
				},
			])
			const pageId = editor.getCurrentPageId()
			const thread = createCommentThread({
				pageId,
				anchor: { type: 'region', x: 120, y: 120, w: 380, h: 210 },
				createdBy: 'ada',
			})
			const comment = createComment({
				threadId: thread.id,
				pageId,
				authorId: 'ada',
				body: toRichText(
					'This thread is anchored to a region covering both shapes. Move it by its pin, or resize it from a corner.'
				),
			})
			putCommentRecords(editor, [thread, comment])
		},
		{ history: 'ignore' }
	)
	editor.zoomToBounds({ x: 40, y: 40, w: 600, h: 420 }, { immediate: true })
}

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

	return (
		<div className="tldraw__editor">
			<Tldraw
				// Commenting is a licensed feature. Every feature is enabled in local development, but a
				// deployed app needs a license key that includes commenting — swap in your own key here.
				licenseKey={getLicenseKey()}
				store={store}
				onMount={handleMount}
				tools={COMMENT_TOOLS}
				overrides={[commentToolOverrides]}
				components={components}
			/>
		</div>
	)
}

/*
A region anchor attaches a thread to a rectangular area of the page rather than to a point or a
shape.

[1]
Regions are off by default — the comment tool places points and shape anchors, and a drag just
trails the composer. `enableRegions` turns them on, and that's the whole configuration: a region
reveals its dashed box while the pointer is inside it, moves by its pin, and resizes from its
corners. The pin sits on whichever corner the creating drag released on.

[2]
Seed a region thread covering two shapes so there's one to play with immediately. A region anchor
is a page-fixed rectangle — it covers the shapes visually but isn't attached to them, so moving a
shape doesn't move the region. Select the comment tool (or press `c`) and drag to create more.
*/
```

--------

# Drawn comment reactions

Category: Collaboration

Keywords: comments, commenting, reactions, emoji, custom, drawing, collaboration

Replace the emoji reaction picker with one you draw in.

A reaction's token is a free-form string, capped at 64 characters, and the commenting layer never assumes it is an emoji glyph. So a custom reaction can be anything, as long as the token names the content rather than contains it: store the content in a custom synced record, and react with the record's id.

`drawing-reactions.tsx` implements that recipe. A `reaction-drawing` record type holds each distinct drawing's image, content-addressed so its id is a short hash. The palette is a small locked-down tldraw canvas with a pen and an eraser; it saves what you drew as a record and emits its id as the token. The renderer resolves a token back through the store and draws the image, letting anything else fall through, so drawn reactions and plain emoji coexist on the same comment.

The three pieces are wired together with `CommentTool.configure({ components: { ReactionPalette, ReactionContent }, isAllowedReaction })`, and the record type is registered on the schema next to `commentSchemaRecords`.

Post a comment, then open its reaction picker and draw something.

## App.tsx

```tsx
import {
	CanvasComments,
	CommentAuthor,
	CommentTool,
	commentToolOverrides,
	isAllowedReactionEmoji,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useCallback, useMemo } from 'react'
import {
	commentSchemaRecords,
	createTLSchema,
	createTLStore,
	TLComponents,
	Tldraw,
	useEditor,
} from 'tldraw'
import {
	DrawingReactionContent,
	DrawingReactionPalette,
	DrawingReactionPaletteProps,
	isDrawingReactionToken,
	reactionDrawingRecords,
	saveDrawingReaction,
} from './drawing-reactions'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'

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

// [1]
function ReactionPalette(props: DrawingReactionPaletteProps) {
	const editor = useEditor()
	const saveDrawing = useCallback((src: string) => saveDrawingReaction(editor, src), [editor])
	return (
		<DrawingReactionPalette {...props} licenseKey={getLicenseKey()} saveDrawing={saveDrawing} />
	)
}

// [2]
const COMMENT_TOOLS = [
	CommentTool.configure({
		components: {
			ReactionPalette,
			ReactionContent: DrawingReactionContent,
		},
		isAllowedReaction: (token) => isDrawingReactionToken(token) || isAllowedReactionEmoji(token),
	}),
]

export default function CommentDrawingReactionsExample() {
	const store = useMemo(
		() =>
			createTLStore({
				// [3]
				schema: createTLSchema({
					records: { ...commentSchemaRecords, ...reactionDrawingRecords },
				}),
			}),
		[]
	)

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

	return (
		<div className="tldraw__editor">
			<Tldraw
				licenseKey={getLicenseKey()}
				store={store}
				tools={COMMENT_TOOLS}
				overrides={[commentToolOverrides]}
				components={components}
			/>
		</div>
	)
}

/*
A reaction token is a free-form string, capped at 64 characters because it is embedded in the
reaction's record id. So a custom reaction can be anything, as long as the token *names* the content
rather than contains it. `drawing-reactions.tsx` implements that recipe: a `reaction-drawing` record
holds the image, the palette saves one and emits its id, and the renderer resolves the id back to
the image. The same shape works for stickers or sounds — for heavyweight content, have the record
hold an uploaded asset's URL instead of inline bytes, since document records replicate to every
client on the file.

[1]
`DrawingReactionPalette` renders a nested `<Tldraw>`, which is a second editor and wants its own
license key. The wrapper also binds `saveDrawing` to the host editor (this component renders in
the host's UI, so `useEditor` is the host), which is how a submitted drawing lands in the host
document rather than the palette's scratch canvas.

[2]
The pieces are configured together on the comment tool, and they have to agree: the palette emits
record-id tokens, `ReactionContent` resolves and draws them, and `isAllowedReaction` lets them
through. Emoji stay allowed alongside drawings, so both kinds coexist on the same comment.
`isAllowedReaction` can only check a token's shape — a token is a claim, not proof the record
exists — so the renderer treats a missing record as "render nothing".

[3]
The drawing record type registers next to the commenting records. With multiplayer sync, register
it on the server's schema too, or validation fails on connect. The record's own validator enforces
the data:image allowlist and a size cap, so those limits hold against any writer, not just this
palette. Drawings are never garbage-collected here; a real app might sweep records no reaction
references.
*/
```

## comment-drawing-reactions.css

```css
.tlui-cmt-drawing-palette {
	display: flex;
	flex-direction: column;
	gap: 6px;
	padding: 6px;
	color: var(--tl-color-text-1);
	font-size: 12px;
}
.tlui-cmt-drawing-palette__reuse {
	display: flex;
	flex-wrap: wrap;
	gap: 2px;
	padding-bottom: 2px;
	border-bottom: 1px solid var(--tl-color-divider);
}
.tlui-cmt-drawing-palette__reuse-item {
	display: flex;
	align-items: center;
	justify-content: center;
	width: 34px;
	height: 34px;
	border: none;
	border-radius: var(--tl-radius-2);
	background: none;
	color: inherit;
	font: inherit;
	font-size: 21px;
	line-height: 1;
	cursor: pointer;
}
.tlui-cmt-drawing-palette__reuse-item:hover {
	background: var(--tl-color-muted-2);
}
.tlui-cmt-drawing-palette__reuse-item--active {
	background: color-mix(in srgb, var(--tl-color-selected) 28%, var(--tl-color-panel));
}
.tlui-cmt-drawing-palette__canvas {
	position: relative;
	overflow: hidden;
	border: 1px solid var(--tl-color-divider);
	border-radius: var(--tl-radius-3);
}
/* Sits over the bottom of the drawing box. The z-index is what keeps it above the canvas — it's a
   sibling of the canvas inside the editor's container, not a panel the editor knows about. */
.tlui-cmt-drawing-palette__toolbar {
	position: absolute;
	bottom: 0;
	left: 0;
	right: 0;
	z-index: var(--tl-layer-panels, 300);
	display: flex;
	align-items: center;
	gap: 2px;
	padding: 3px;
	border-top: 1px solid var(--tl-color-divider);
	background: var(--tl-color-panel);
}
.tlui-cmt-drawing-palette__spacer {
	flex: 1;
}
.tlui-cmt-drawing-palette__tool {
	display: flex;
	align-items: center;
	justify-content: center;
	width: 28px;
	height: 28px;
	border: none;
	border-radius: var(--tl-radius-2);
	background: none;
	color: var(--tl-color-text-1);
	cursor: pointer;
}
.tlui-cmt-drawing-palette__tool:hover {
	background: var(--tl-color-muted-2);
}
.tlui-cmt-drawing-palette__tool--active {
	background: color-mix(in srgb, var(--tl-color-selected) 28%, var(--tl-color-panel));
}
.tlui-cmt-drawing-palette__text-button,
.tlui-cmt-drawing-palette__submit {
	height: 28px;
	padding: 0 10px;
	border: none;
	border-radius: var(--tl-radius-2);
	background: none;
	color: var(--tl-color-text-1);
	font: inherit;
	cursor: pointer;
}
.tlui-cmt-drawing-palette__text-button:hover:not(:disabled) {
	background: var(--tl-color-muted-2);
}
.tlui-cmt-drawing-palette__submit {
	background: var(--tl-color-selected);
	color: var(--tl-color-selected-contrast, #fff);
	font-weight: 500;
}
.tlui-cmt-drawing-palette__submit:hover:not(:disabled) {
	filter: brightness(1.08);
}
.tlui-cmt-drawing-palette__text-button:disabled,
.tlui-cmt-drawing-palette__submit:disabled {
	opacity: 0.4;
	cursor: default;
}
.tlui-cmt-drawing-palette__error {
	position: absolute;
	bottom: 34px;
	left: 0;
	right: 0;
	z-index: var(--tl-layer-panels, 300);
	padding: 4px 6px;
	background: var(--tl-color-panel);
	color: var(--tl-color-danger);
	text-align: center;
}
```

## drawing-reactions.tsx

```tsx
import { RenderReaction } from '@tldraw/commenting'
import { ReactNode, useCallback, useState } from 'react'
import {
	BaseRecord,
	createCustomRecordId,
	CustomRecordInfo,
	DefaultSizeStyle,
	Editor,
	idValidator,
	RecordId,
	T,
	TLRecord,
	TldrawOptions,
	TLUiOverrides,
	Tldraw,
	useEditor,
	useValue,
} from 'tldraw'
import './comment-drawing-reactions.css'

// Draw-your-own reactions, in three pieces: a `reaction-drawing` record type that holds each
// drawing's image (content-addressed, so the record id is the reaction token), a palette that saves
// a drawing and emits its id, and a renderer that resolves a token back to its image. See the README
// and `CommentDrawingReactionsExample.tsx` for the wiring.

/** The image format a drawn reaction is exported as. */
export type DrawingReactionFormat = 'svg' | 'png'

/**
 * The `data:` URL prefixes a drawing record's `src` may use. Validation is gated on this list
 * rather than on a bare `data:` check: a record arrives over sync from another user, and this is
 * what keeps an `<img src>` pointed at an image and nothing else.
 */
const SRC_PREFIXES = ['data:image/svg+xml,', 'data:image/svg+xml;', 'data:image/png;base64,']

/**
 * The most characters a drawing's `data:` URL may hold. A drawing record is synced document data,
 * paid for by every client on the file — and because this cap lives in the record's schema
 * validator, it holds against any writer, not just this palette's export path.
 */
export const MAX_DRAWING_SRC_LENGTH = 32_000

/** One distinct drawn reaction. Content-addressed: the id is derived from a hash of `src`. */
export interface ReactionDrawingRecord extends BaseRecord<'reaction-drawing', ReactionDrawingId> {
	/** The drawing, as a `data:` image URL. */
	src: string
}

/** @see ReactionDrawingRecord */
export type ReactionDrawingId = RecordId<ReactionDrawingRecord>

const drawingSrcValidator = T.string.check((value) => {
	if (!SRC_PREFIXES.some((prefix) => value.startsWith(prefix))) {
		throw new T.ValidationError('Expected a data: image URL')
	}
	if (value.length > MAX_DRAWING_SRC_LENGTH) {
		throw new T.ValidationError(
			`Expected a src of at most ${MAX_DRAWING_SRC_LENGTH} characters, got ${value.length}`
		)
	}
})

/**
 * The `records` entry that registers the drawing record type. Spread into `createTLSchema`
 * alongside `commentSchemaRecords` — and, as with those, register it on every peer (client and
 * server) or schema validation fails on one side of the connection.
 */
export const reactionDrawingRecords: Record<string, CustomRecordInfo> = {
	'reaction-drawing': {
		scope: 'document',
		validator: T.object({
			id: idValidator<ReactionDrawingId>('reaction-drawing'),
			typeName: T.literal('reaction-drawing'),
			src: drawingSrcValidator,
		}),
	},
}

/**
 * Whether `token` is a drawn reaction (as opposed to a plain emoji glyph) — i.e. a
 * `reaction-drawing` record id. Use it anywhere you need to tell the two kinds apart —
 * validation before a write, or picking a renderer.
 */
export function isDrawingReactionToken(token: string): boolean {
	return token.startsWith('reaction-drawing:')
}

/**
 * Save a drawing to the document and return the token to react with — the drawing record's id.
 *
 * Content-addressed: the id is a hash of the image, so saving the same drawing twice (or two
 * people reusing one) lands on the same record instead of accumulating copies. Records are never
 * removed here — a real app might garbage-collect drawings no reaction references, but a
 * content-addressed record is small and reusable, so this example leaves them be.
 */
export async function saveDrawingReaction(editor: Editor, src: string): Promise<string> {
	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(src))
	const hash = Array.from(new Uint8Array(digest).slice(0, 16), (byte) =>
		byte.toString(16).padStart(2, '0')
	).join('')
	const id = createCustomRecordId('reaction-drawing', hash) as ReactionDrawingId
	// The store is typed over the built-in record union, so custom records cast through it — the
	// same idiom the commenting package uses for its own records.
	if (!editor.store.has(id as unknown as TLRecord['id'])) {
		const record: ReactionDrawingRecord = { id, typeName: 'reaction-drawing', src }
		editor.store.put([record] as unknown as TLRecord[])
	}
	return id
}

/**
 * A fixed size rather than `em`: the reaction pill's font is 10px, and a drawing at emoji scale
 * is an illegible smudge. Only drawn reactions render through this style, so emoji keep their
 * hosts' font size; a pill holding a drawing grows taller than its emoji neighbours, which is
 * the point — you drew it to be seen.
 */
const drawingTokenImageStyle = {
	width: '22px',
	height: '22px',
	objectFit: 'contain',
	display: 'inline-block',
	verticalAlign: 'middle',
} as const

/**
 * Draws a reaction token, for the `ReactionContent` slot of the commenting options:
 * `CommentTool.configure({ components: { ReactionContent: DrawingReactionContent } })`.
 *
 * A drawing token is resolved through the store — the token is a `reaction-drawing` record id,
 * and the record holds the image. Any other token falls through to the token string (the default
 * behaviour, i.e. an emoji glyph drawn by the OS emoji font). A drawing token whose record isn't
 * in the store renders as nothing: over sync, a reaction can arrive before its drawing, and a
 * token is only ever a claim — the renderer can't assume it names a real record.
 *
 * The image is rendered via `<img>`, never inlined — an `<img>`-hosted SVG can't run script or
 * reach out to the network, which matters because drawings arrive from other users over sync.
 * Resolution reads the editor from context, so this only renders inside the host editor's tree
 * (everywhere the commenting UI puts it).
 */
export function DrawingReactionContent({ token }: { token: string }) {
	const editor = useEditor()
	const src = useValue(
		'reaction drawing src',
		() => {
			if (!isDrawingReactionToken(token)) return null
			const record = editor.store.get(token as TLRecord['id']) as unknown as
				| ReactionDrawingRecord
				| undefined
			return record?.src ?? null
		},
		[editor, token]
	)
	if (!isDrawingReactionToken(token)) return <>{token}</>
	if (!src) return null
	return <img src={src} alt="" draggable={false} style={drawingTokenImageStyle} />
}

/**
 * {@link DrawingReactionContent} shaped as a `RenderReaction`, for the `renderReaction` prop of
 * `Reaction`, `Reactions`, `EmojiPicker`, or `ReactionPicker`.
 */
export function renderDrawingReaction(token: string): ReactNode {
	return <DrawingReactionContent token={token} />
}

export interface DrawingReactionExportOptions {
	/**
	 * `'svg'` (default) keeps the drawing crisp at any size and usually makes a smaller token for a
	 * simple doodle. `'png'` gives a fixed-cost token whatever the drawing's complexity.
	 */
	format?: DrawingReactionFormat
	/** Longest side of the exported image in px. PNG only; SVG scales itself. Defaults to 96. */
	size?: number
	/**
	 * Reject an image longer than this many characters. The drawing record's schema validator
	 * enforces {@link MAX_DRAWING_SRC_LENGTH} regardless — this exists so an oversized scribble is
	 * refused at the palette with a friendly message rather than thrown out by the store. Defaults
	 * to {@link MAX_DRAWING_SRC_LENGTH}; lower it to be stricter, but raising it past the schema's
	 * cap only trades a palette error for a validation error.
	 */
	maxSrcLength?: number
	/** Export in dark mode. Defaults to false, so a reaction looks the same for every viewer. */
	darkMode?: boolean
}

/** Thrown by {@link exportDrawingImage} when the drawing doesn't fit in a record. */
export class DrawingReactionTooLargeError extends Error {
	constructor(
		readonly length: number,
		readonly maxLength: number
	) {
		super(`Drawing is too detailed to store as a reaction (${length}/${maxLength} characters).`)
		this.name = 'DrawingReactionTooLargeError'
	}
}

/**
 * Export everything on an editor's current page as a drawing image — a transparent `data:` URL,
 * cropped to the ink with no canvas background. This is the `src` a drawing record holds; pass it
 * to {@link saveDrawingReaction} to get the token to react with.
 *
 * Returns null when there's nothing drawn. Throws {@link DrawingReactionTooLargeError} when the
 * result exceeds `maxSrcLength`.
 */
export async function exportDrawingImage(
	editor: Editor,
	opts: DrawingReactionExportOptions = {}
): Promise<string | null> {
	const {
		format = 'svg',
		size = 96,
		maxSrcLength = MAX_DRAWING_SRC_LENGTH,
		darkMode = false,
	} = opts

	const ids = [...editor.getCurrentPageShapeIds()]
	if (ids.length === 0) return null

	// `padding: 'auto'` trims to the visual bounds of the ink — including stroke overflow — which is
	// what makes the result read as a glyph rather than as a screenshot of a canvas.
	const exportOpts = { background: false, padding: 'auto', darkMode } as const

	let src: string
	if (format === 'svg') {
		const result = await editor.getSvgString(ids, exportOpts)
		if (!result) return null
		// Percent-encoded rather than base64: it's smaller for markup, and stays greppable in the
		// store when you're debugging what a reaction actually holds.
		src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(result.svg)}`
	} else {
		// Scale so the drawing's longest side lands near `size`. The auto-trim above shifts this a
		// little; near enough, since the pill draws the image at a CSS size anyway.
		const bounds = editor.getCurrentPageBounds()
		const longest = bounds ? Math.max(bounds.width, bounds.height) : size
		const result = await editor.toImageDataUrl(ids, {
			...exportOpts,
			format: 'png',
			pixelRatio: 1,
			scale: longest > 0 ? size / longest : 1,
		})
		src = result.url
	}

	if (src.length > maxSrcLength) {
		throw new DrawingReactionTooLargeError(src.length, maxSrcLength)
	}
	return src
}

/**
 * Keyboard shortcuts stay mounted when `hideUi` is set, so hiding the toolbar isn't enough on its
 * own: `v` would still put the canvas into select, `cmd+a` would still select all. Removing the
 * tools and actions from the UI context removes their shortcuts with them, which leaves the canvas
 * genuinely two-tool rather than two-tool-until-you-touch-the-keyboard.
 */
const DRAWING_EDITOR_OVERRIDES: TLUiOverrides = {
	tools: (_editor, tools) => ({ draw: tools.draw, eraser: tools.eraser }),
	actions: () => ({}),
}

/**
 * A locked camera makes the box a fixed sheet of paper: what you see is the whole drawing, so the
 * export can't come back cropped or surprise you with ink parked off-screen. The panning options go
 * with it — a locked camera already refuses their moves, but leaving them on means spacebar and
 * right-drag do nothing visible, which reads as broken.
 */
const DRAWING_EDITOR_OPTIONS: Partial<TldrawOptions> = {
	camera: { isLocked: true },
	spacebarPanning: false,
	rightClickPanning: false,
	maxPages: 1,
}

export interface DrawingReactionPaletteProps {
	/**
	 * Tokens to offer for one-click reuse, above the canvas — typically the reactions already on the
	 * comment, so a second person can add to a drawing rather than redraw it. Same slot as
	 * `EmojiPicker`'s `emoji` prop.
	 */
	emoji?: string[]
	/** Tokens the current user has already reacted with; shown pressed in the reuse row. */
	selected?: string[]
	/** Called with the new token when a drawing is submitted, or with an existing token when reused. */
	onSelect?(token: string): void
	/**
	 * Turns a submitted drawing (a `data:` image URL) into the token passed to `onSelect` —
	 * typically {@link saveDrawingReaction} bound to the host editor, which stores the drawing as a
	 * record and returns its id. Without it, the raw image URL is passed through as the token,
	 * which only suits staging the palette standalone: the commenting schema caps a token at 64
	 * characters, so an unsaved drawing can't actually be reacted with.
	 */
	saveDrawing?(src: string): string | Promise<string>
	/** How to draw each token in the reuse row. Defaults to {@link renderDrawingReaction}. */
	renderReaction?: RenderReaction
	/**
	 * Side of the (square) drawing box: any CSS length. Defaults to a quarter of the viewport's
	 * short side, clamped so it stays usable on a phone and doesn't swallow a desktop.
	 */
	size?: number | string
	/** Export settings for the drawing. See {@link DrawingReactionExportOptions}. */
	exportOptions?: DrawingReactionExportOptions
	/** Passed to the nested `<Tldraw>`, which is a second editor and wants its own license. */
	licenseKey?: string
	/** Label on the button that commits the drawing. Defaults to "React". */
	submitLabel?: string
}

/**
 * A palette that lets you draw your own reaction: a small square tldraw canvas with a locked
 * camera, a pen, and an eraser — nothing else — plus a button that exports what's on it, saves it
 * via `saveDrawing`, and emits the resulting token.
 *
 * Prop-compatible with `EmojiPicker`, so it drops into the same slot; unlike `EmojiPicker` it
 * renders its own editor, so it doesn't need an editor context of its own and can be staged
 * standalone.
 */
export function DrawingReactionPalette({
	emoji,
	selected,
	onSelect,
	saveDrawing,
	renderReaction = renderDrawingReaction,
	size = 'clamp(180px, 25vmin, 320px)',
	exportOptions,
	licenseKey,
	submitLabel = 'React',
}: DrawingReactionPaletteProps) {
	// A thicker brush than the draw tool's default: the drawing is displayed at pill size, where
	// a default-weight stroke thins out to nothing. Scoped to the palette's own editor.
	const handleMount = useCallback((editor: Editor) => {
		editor.setStyleForNextShapes(DefaultSizeStyle, 'l')
	}, [])

	return (
		// The palette is portaled into the host editor's container, so a wheel event that escapes it
		// lands on the host canvas and zooms the document behind the menu. The nested editor's camera
		// is locked, so it has no reason to want the event either — it stops here.
		<div className="tlui-cmt-drawing-palette" onWheel={stopPropagation}>
			{emoji && emoji.length > 0 && (
				<div className="tlui-cmt-drawing-palette__reuse" role="group">
					{emoji.map((token) => {
						const active = selected?.includes(token) ?? false
						return (
							<button
								key={token}
								type="button"
								className={
									active
										? 'tlui-cmt-drawing-palette__reuse-item tlui-cmt-drawing-palette__reuse-item--active'
										: 'tlui-cmt-drawing-palette__reuse-item'
								}
								aria-label={isDrawingReactionToken(token) ? 'Drawn reaction' : token}
								aria-pressed={active}
								onClick={() => onSelect?.(token)}
							>
								{renderReaction(token)}
							</button>
						)
					})}
				</div>
			)}

			<div className="tlui-cmt-drawing-palette__canvas" style={{ width: size, height: size }}>
				<Tldraw
					hideUi
					initialState="draw"
					licenseKey={licenseKey}
					options={DRAWING_EDITOR_OPTIONS}
					overrides={DRAWING_EDITOR_OVERRIDES}
					onMount={handleMount}
				>
					{/* Inside the editor rather than beside it: the toolbar reads the tool and the
					    emptiness straight off `useEditor()`, so there's no editor instance to lift out
					    into React state and nothing that leaves the buttons inert if the lift fails. */}
					<DrawingPaletteToolbar
						exportOptions={exportOptions}
						submitLabel={submitLabel}
						onSelect={onSelect}
						saveDrawing={saveDrawing}
					/>
				</Tldraw>
			</div>
		</div>
	)
}

interface DrawingPaletteToolbarProps {
	exportOptions: DrawingReactionExportOptions | undefined
	submitLabel: string
	onSelect: ((token: string) => void) | undefined
	saveDrawing: ((src: string) => string | Promise<string>) | undefined
}

/** The bar over the bottom of the drawing box. Renders as a child of the palette's own editor. */
function DrawingPaletteToolbar({
	exportOptions,
	submitLabel,
	onSelect,
	saveDrawing,
}: DrawingPaletteToolbarProps) {
	const editor = useEditor()
	const tool = useValue('drawing palette tool', () => editor.getCurrentToolId(), [editor])
	const isEmpty = useValue(
		'drawing palette is empty',
		() => editor.getCurrentPageShapeIds().size === 0,
		[editor]
	)
	const [isExporting, setIsExporting] = useState(false)
	const [error, setError] = useState<string | null>(null)

	const clear = useCallback(() => {
		setError(null)
		editor.deleteShapes([...editor.getCurrentPageShapeIds()])
		editor.setCurrentTool('draw')
	}, [editor])

	const submit = useCallback(async () => {
		setError(null)
		setIsExporting(true)
		try {
			const src = await exportDrawingImage(editor, exportOptions)
			if (src) {
				const token = saveDrawing ? await saveDrawing(src) : src
				onSelect?.(token)
			}
		} catch (e) {
			setError(
				e instanceof DrawingReactionTooLargeError
					? 'That drawing is too detailed — try something simpler.'
					: "Couldn't export that drawing."
			)
		} finally {
			setIsExporting(false)
		}
	}, [editor, exportOptions, onSelect, saveDrawing])

	return (
		<>
			{error && (
				<div className="tlui-cmt-drawing-palette__error" role="alert">
					{error}
				</div>
			)}
			<div className="tlui-cmt-drawing-palette__toolbar">
				<ToolButton
					label="Pen"
					active={tool === 'draw'}
					onClick={() => editor.setCurrentTool('draw')}
				>
					<PenIcon />
				</ToolButton>
				<ToolButton
					label="Eraser"
					active={tool === 'eraser'}
					onClick={() => editor.setCurrentTool('eraser')}
				>
					<EraserIcon />
				</ToolButton>
				<button
					type="button"
					className="tlui-cmt-drawing-palette__text-button"
					onClick={clear}
					disabled={isEmpty}
				>
					Clear
				</button>
				<div className="tlui-cmt-drawing-palette__spacer" />
				<button
					type="button"
					className="tlui-cmt-drawing-palette__submit"
					onClick={submit}
					disabled={isEmpty || isExporting}
				>
					{submitLabel}
				</button>
			</div>
		</>
	)
}

function ToolButton({
	label,
	active,
	onClick,
	children,
}: {
	label: string
	active: boolean
	onClick(): void
	children: ReactNode
}) {
	return (
		<button
			type="button"
			className={
				active
					? 'tlui-cmt-drawing-palette__tool tlui-cmt-drawing-palette__tool--active'
					: 'tlui-cmt-drawing-palette__tool'
			}
			aria-label={label}
			title={label}
			aria-pressed={active}
			onClick={onClick}
		>
			{children}
		</button>
	)
}

function stopPropagation(event: { stopPropagation(): void }) {
	event.stopPropagation()
}

function PenIcon() {
	return (
		<svg
			width="15"
			height="15"
			viewBox="0 0 16 16"
			fill="none"
			stroke="currentColor"
			strokeWidth="1.3"
			strokeLinecap="round"
			strokeLinejoin="round"
			aria-hidden="true"
		>
			<path d="M11.2 2.3a1.6 1.6 0 0 1 2.3 2.3L5.4 12.7l-3 .7.7-3z" />
			<path d="M10.1 3.4 12.4 5.7" />
		</svg>
	)
}

function EraserIcon() {
	return (
		<svg
			width="15"
			height="15"
			viewBox="0 0 16 16"
			fill="none"
			stroke="currentColor"
			strokeWidth="1.3"
			strokeLinecap="round"
			strokeLinejoin="round"
			aria-hidden="true"
		>
			<path d="M8.8 2.9 3 8.7a1.4 1.4 0 0 0 0 2l2 2a1.4 1.4 0 0 0 1 .4h2.4l4.4-4.4a1.4 1.4 0 0 0 0-2l-2-2a1.4 1.4 0 0 0-2 0z" />
			<path d="M5.9 5.8 10.9 10.8M6.4 13.1h6.7" />
		</svg>
	)
}
```

--------

# Comment notifications

Category: Collaboration

Keywords: comments, commenting, notifications, inbox, unread, read receipts, mentions, collaboration

Track unread comments and build a notifications feed.

The commenting layer doesn't decide what's unread or what's worth notifying someone about — it takes both from the host. `isCommentUnread` reports read status, `onCommentsRead` records receipts for the unread comments a thread view displays, and `revealThread` jumps to a thread from anywhere outside the canvas.

That's enough to build a feed: derive it from the comment records with `useComments`, tag each one with why it's there, and check it against your read state. This example uses two reasons — the comment mentions you, or it lands in a thread you're part of.

Use the buttons to post as another user, then click a row to jump to the thread and watch it mark itself read.

## App.tsx

```tsx
import {
	Avatar,
	CanvasComments,
	CommentAuthor,
	commentToolOverrides,
	commentTools,
	filterMentionMembers,
	formatRelativeTime,
	MentionMember,
	putCommentRecords,
	revealThread,
	richTextToPlaintext,
	useComments,
	useCommentThreads,
} from '@tldraw/commenting'
import { getLicenseKey } from '@tldraw/dotcom-shared'
import { useMemo } from 'react'
import {
	atom,
	commentSchemaRecords,
	createComment,
	createCommentThread,
	createShapeId,
	createTLSchema,
	createTLStore,
	Editor,
	TLComment,
	TLCommentId,
	TLCommentThread,
	TLCommentThreadId,
	TLComponents,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	TLRichText,
	toRichText,
	useEditor,
	useValue,
} from 'tldraw'
import '@tldraw/commenting/commenting.css'
import 'tldraw/tldraw.css'
import './comment-notifications.css'

const ME = 'me'

const ADA_AVATAR =
	'data:image/svg+xml,' +
	encodeURIComponent(
		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28"><rect width="28" height="28" fill="#0E9F6E"/><circle cx="14" cy="11" r="5" fill="#fff"/><ellipse cx="14" cy="24" rx="9" ry="7" fill="#fff"/></svg>`
	)

const MEMBERS: MentionMember[] = [
	{ id: ME, name: 'You', color: '#EC5E41', you: true },
	{ id: 'ada', name: 'Ada Lovelace', color: '#0E9F6E', image: ADA_AVATAR },
	{ id: 'grace', name: 'Grace Hopper', color: '#4465E9' },
]

const AUTHORS: Record<string, CommentAuthor> = Object.fromEntries(MEMBERS.map((m) => [m.id, m]))
const resolveAuthor = (id: string): CommentAuthor => AUTHORS[id] ?? { name: id }
const resolveName = (id: string) => AUTHORS[id]?.name

// [1]
const readComments = atom<ReadonlySet<TLCommentId>>('read comments', new Set())

const isCommentUnread = (commentId: TLCommentId) => !readComments.get().has(commentId)

const onCommentsRead = (commentIds: TLCommentId[]) =>
	readComments.update((read) => {
		const unread = commentIds.filter((id) => !read.has(id))
		if (unread.length === 0) return read
		const next = new Set(read)
		for (const id of unread) next.add(id)
		return next
	})

// Your own comment is never news to you, so it's marked read the moment it's posted rather than
// waiting for the thread view to report it.
const onPostComment = (comment: TLComment) => onCommentsRead([comment.id])

// [2]
function mentionedIds(body: TLRichText): string[] {
	const ids: string[] = []
	const visit = (node: any) => {
		if (!node || typeof node !== 'object') return
		if (node.type === 'mention' && typeof node.attrs?.id === 'string') ids.push(node.attrs.id)
		if (Array.isArray(node.content)) node.content.forEach(visit)
	}
	visit(body)
	return ids
}

/**
 * A comment body of the form `<before>@Name<after>`, as the composer would produce it. Empty
 * `before`/`after` segments are dropped — a zero-length text node is invalid rich text.
 */
function bodyMentioning(before: string, memberId: string, after: string): TLRichText {
	return {
		type: 'doc',
		content: [
			{
				type: 'paragraph',
				content: [
					...(before ? [{ type: 'text', text: before }] : []),
					{ type: 'mention', attrs: { id: memberId, label: resolveName(memberId) ?? memberId } },
					...(after ? [{ type: 'text', text: after }] : []),
				],
			},
		],
	}
}

// [3]
type NotificationReason = 'mention' | 'reply'

interface Notification {
	comment: TLComment
	reason: NotificationReason
	unread: boolean
}

const REASON_LABEL: Record<NotificationReason, string> = {
	mention: 'mentioned you',
	reply: 'replied in your thread',
}

const MINUTE = 60 * 1000

function handleMount(editor: Editor) {
	const boxId = createShapeId()
	editor.run(
		() => {
			editor.createShapes([
				{
					id: boxId,
					type: 'geo',
					x: 180,
					y: 140,
					props: { geo: 'rectangle', w: 260, h: 160, richText: toRichText('Hero image') },
				},
			])
		},
		{ history: 'ignore' }
	)

	const pageId = editor.getCurrentPageId()
	const now = Date.now()

	// A thread you started, with a reply from Ada — a `reply` notification.
	const yourThread = createCommentThread({
		pageId,
		anchor: { type: 'point', x: 540, y: 200 },
		createdBy: ME,
		now: now - 90 * MINUTE,
	})
	// A thread Ada started on the shape, mentioning you — a `mention` notification.
	const adaThread = createCommentThread({
		pageId,
		anchor: { type: 'shape', shapeId: boxId, x: 0.5, y: 0.5, isPrecise: true },
		createdBy: 'ada',
		now: now - 20 * MINUTE,
	})

	putCommentRecords(editor, [
		yourThread,
		adaThread,
		createComment({
			threadId: yourThread.id,
			pageId,
			authorId: ME,
			body: toRichText('Should this sit above the fold?'),
			now: now - 90 * MINUTE,
		}),
		createComment({
			threadId: yourThread.id,
			pageId,
			authorId: 'ada',
			body: toRichText('Yes — it reads as an afterthought where it is now.'),
			now: now - 45 * MINUTE,
		}),
		createComment({
			threadId: adaThread.id,
			pageId,
			authorId: 'ada',
			body: bodyMentioning('', ME, ' can you swap in the final crop?'),
			now: now - 20 * MINUTE,
		}),
	])

	// Padded well to the left of the content, so the fitted view leaves the strip under the inbox
	// panel empty and both seeded pins land in the clear.
	editor.zoomToBounds({ x: -160, y: 80, w: 900, h: 400 }, { immediate: true })
}

function NotificationsPanel() {
	const editor = useEditor()
	const comments = useComments(editor)
	const threads = useCommentThreads(editor)
	const read = useValue(readComments)

	// The threads you're a part of: ones you started, plus any you've commented in.
	const yourThreadIds = useMemo(() => {
		const ids = new Set<TLCommentThreadId>(
			threads.filter((thread) => thread.createdBy === ME).map((thread) => thread.id)
		)
		for (const comment of comments) {
			if (comment.authorId === ME) ids.add(comment.threadId)
		}
		return ids
	}, [threads, comments])

	// [4]
	const notifications = useMemo(() => {
		const result: Notification[] = []
		for (const comment of comments) {
			// A notification is always about someone else's comment, never your own.
			if (comment.authorId === ME) continue
			const reason: NotificationReason | null = mentionedIds(comment.body).includes(ME)
				? 'mention'
				: yourThreadIds.has(comment.threadId)
					? 'reply'
					: null
			if (!reason) continue
			result.push({ comment, reason, unread: !read.has(comment.id) })
		}
		return result.sort((a, b) => b.comment.createdAt - a.comment.createdAt)
	}, [comments, yourThreadIds, read])

	const unreadCount = notifications.filter((n) => n.unread).length

	// The newest thread of yours that Ada could reply into.
	const replyTarget = useMemo(
		() =>
			threads
				.filter((thread) => yourThreadIds.has(thread.id))
				.sort((a, b) => b.createdAt - a.createdAt)[0],
		[threads, yourThreadIds]
	)
	const mentionTarget = useMemo(
		() => [...threads].sort((a, b) => b.createdAt - a.createdAt)[0],
		[threads]
	)

	// [5]
	const postAsAda = (body: TLRichText, thread: TLCommentThread | undefined) => {
		if (!thread) return
		putCommentRecords(editor, [
			createComment({ threadId: thread.id, pageId: thread.pageId, authorId: 'ada', body }),
		])
	}

	return (
		<div className="tlui-menu comment-notifications">
			<div className="comment-notifications__header">
				<span className="comment-notifications__title">Inbox</span>
				{unreadCount > 0 && <span className="comment-notifications__badge">{unreadCount}</span>}
				<TldrawUiButton
					type="normal"
					disabled={unreadCount === 0}
					onClick={() => readComments.set(new Set(comments.map((c) => c.id)))}
				>
					<TldrawUiButtonLabel>Mark all read</TldrawUiButtonLabel>
				</TldrawUiButton>
			</div>

			{notifications.length === 0 ? (
				<p className="comment-notifications__empty">
					Nothing here yet. Comments that mention you, or that reply in one of your threads, land in
					this list.
				</p>
			) : (
				<ul className="comment-notifications__list">
					{notifications.map(({ comment, reason, unread }) => (
						<li key={comment.id}>
							<button
								className="comment-notifications__row"
								data-unread={unread}
								// [6]
								onClick={() => revealThread(editor, comment.id)}
							>
								<Avatar author={resolveAuthor(comment.authorId)} />
								<span className="comment-notifications__body">
									<span className="comment-notifications__meta">
										<b>{resolveAuthor(comment.authorId).name}</b> {REASON_LABEL[reason]} ·{' '}
										{formatRelativeTime(new Date(comment.createdAt).toISOString())}
									</span>
									<span className="comment-notifications__preview">
										{richTextToPlaintext(comment.body, resolveName)}
									</span>
								</span>
								{unread && <span className="comment-notifications__dot" />}
							</button>
						</li>
					))}
				</ul>
			)}

			<div className="comment-notifications__actions">
				<TldrawUiButton
					type="normal"
					disabled={!replyTarget}
					onClick={() =>
						postAsAda(
							toRichText('One more thought on this — the spacing feels tight.'),
							replyTarget
						)
					}
				>
					<TldrawUiButtonLabel>Ada replies</TldrawUiButtonLabel>
				</TldrawUiButton>
				<TldrawUiButton
					type="normal"
					disabled={!mentionTarget}
					onClick={() => postAsAda(bodyMentioning('', ME, ' thoughts?'), mentionTarget)}
				>
					<TldrawUiButtonLabel>Ada mentions you</TldrawUiButtonLabel>
				</TldrawUiButton>
			</div>
		</div>
	)
}

const components: TLComponents = {
	InFrontOfTheCanvas: () => (
		<CanvasComments
			currentUserId={ME}
			resolveAuthor={resolveAuthor}
			getMentionSuggestions={(query) => filterMentionMembers(MEMBERS, query)}
			isCommentUnread={isCommentUnread}
			onCommentsRead={onCommentsRead}
			onPostComment={onPostComment}
		/>
	),
}

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

	return (
		<div className="tldraw__editor">
			<Tldraw
				// Commenting is a licensed feature. Every feature is enabled in local development, but a
				// deployed app needs a license key that includes commenting — swap in your own key here.
				licenseKey={getLicenseKey()}
				store={store}
				onMount={handleMount}
				tools={commentTools}
				overrides={[commentToolOverrides]}
				components={components}
			>
				<NotificationsPanel />
			</Tldraw>
		</div>
	)
}

/*
[1]
Read receipts are the host's data, not the SDK's. A comment record says who wrote it and when; who
has *seen* it is one row per (comment, reader), which a real app keeps in its own database so the
count survives a reload and follows you between devices.

Here that store is a local atom, so the whole flow runs in memory. An atom rather than React state
because the two callbacks below are handed to `CanvasComments` once: keeping them stable avoids
re-creating the comments layer every time something is read, and `useValue` gives the panel its
reactive read of the same set.

[2]
An `@`-mention is a `{ type: 'mention', attrs: { id } }` node inside the comment's rich-text body,
where `attrs.id` is the member id the composer's picker chose. Walking the body for those ids is
how "this comment mentions me" is decided — the notification reason with the strongest claim on
someone's attention.

[3]
Why a comment is worth telling someone about is a product decision, so the SDK doesn't make it.
This example uses the two reasons that need no server: the comment mentions you, or it lands in a
thread you're part of. A hosted app usually adds more — activity on a board you own, say — and
resolves them server-side so the feed spans every board rather than the one that's open.

[4]
The feed is derived, not stored: `useComments` and `useCommentThreads` give the comment records
reactively, and each one is tagged with a reason and checked against the read set. Nothing needs to
be written when a comment arrives.

Read comments stay in the list — the unread dot and the header badge are what clear. Filtering the
list down to unread only would make the feed lose its history the moment you read it.

[5]
Comments are ordinary records, so "someone else commented" is just a write. This stands in for the
sync connection a real app would have; opening this example in two tabs against a synced store
would show the same thing arriving on its own.

[6]
`revealThread` is the jump-to-thread entry point for anything outside the canvas — this feed, a
deep link, an email. It's forgiving about timing: `CanvasComments` waits for the records to sync
in, switches pages, unhides pins, and zooms far enough to split the thread out of any cluster
before opening it. It takes a thread id or, as here, the id of any comment in it.

Opening the thread is also what marks it read: the thread view reports every unread comment it
displays through `onCommentsRead`, batched per report, including replies that arrive while it stays
open.
*/
```

## comment-notifications.css

```css
.comment-notifications {
	position: absolute;
	top: 60px;
	left: 8px;
	z-index: 1000;
	display: flex;
	flex-direction: column;
	gap: 4px;
	padding: 8px;
	width: 320px;
	pointer-events: all;
}

.comment-notifications__header {
	display: flex;
	align-items: center;
	gap: 6px;
	padding-left: 4px;
}

.comment-notifications__title {
	font-size: 13px;
	font-weight: 600;
	color: var(--tl-color-text-1);
}

.comment-notifications__badge {
	min-width: 18px;
	padding: 0 5px;
	border-radius: 9px;
	background-color: var(--tl-color-selection-stroke);
	color: #fff;
	font-size: 11px;
	font-weight: 600;
	line-height: 18px;
	text-align: center;
	font-variant-numeric: tabular-nums;
}

.comment-notifications__header .tlui-button {
	margin-left: auto;
}

.comment-notifications__empty {
	margin: 0;
	padding: 4px;
	font-size: 12px;
	line-height: 1.4;
	color: var(--tl-color-text-3);
}

.comment-notifications__list {
	display: flex;
	flex-direction: column;
	gap: 2px;
	margin: 0;
	padding: 0;
	max-height: 260px;
	overflow-y: auto;
	list-style: none;
}

.comment-notifications__row {
	display: flex;
	align-items: flex-start;
	gap: 8px;
	width: 100%;
	padding: 6px;
	border: none;
	border-radius: var(--tl-radius-2);
	background: none;
	color: var(--tl-color-text-1);
	font: inherit;
	text-align: left;
	cursor: pointer;
}

.comment-notifications__row:hover {
	background-color: var(--tl-color-muted-2);
}

.comment-notifications__body {
	display: flex;
	flex-direction: column;
	gap: 1px;
	min-width: 0;
	flex: 1;
}

.comment-notifications__meta {
	font-size: 12px;
	line-height: 1.3;
	color: var(--tl-color-text-3);
}

.comment-notifications__meta b {
	font-weight: 600;
	color: var(--tl-color-text-1);
}

.comment-notifications__preview {
	overflow: hidden;
	font-size: 12px;
	line-height: 1.3;
	color: var(--tl-color-text-3);
	white-space: nowrap;
	text-overflow: ellipsis;
}

/* Unread rows lead with the comment itself; read ones recede to a record of what happened. */
.comment-notifications__row[data-unread='true'] .comment-notifications__preview {
	color: var(--tl-color-text-1);
}

.comment-notifications__row[data-unread='false'] {
	opacity: 0.7;
}

.comment-notifications__dot {
	flex: none;
	width: 8px;
	height: 8px;
	margin-top: 6px;
	border-radius: 50%;
	background-color: var(--tl-color-selection-stroke);
}

.comment-notifications__actions {
	display: flex;
	flex-wrap: wrap;
	gap: 4px;
	border-top: 1px solid var(--tl-color-divider);
	padding-top: 6px;
}
```

--------

# Persist to storage

Category: Data & assets

Keywords: persistence, localstorage, save, load, snapshot, getsnapshot, loadsnapshot, createtlstore, store.listen, throttle

Load and save the document yourself using `getSnapshot`, `loadSnapshot`, and `store.listen`.

The `persistenceKey` prop gives you local persistence for free, but if you want to save to your own backend you need to do the load/save loop yourself. This example does that against `localStorage`: it creates a store with `createTLStore`, loads a saved snapshot into it with `loadSnapshot` before the editor mounts, then uses a throttled `store.listen` callback to serialize the store with `getSnapshot` on every change.

Draw something, reload the page, and it will still be there. To reset, clear the `example-3` key from local storage in your browser's dev tools.

## App.tsx

```tsx
import throttle from 'lodash/throttle'
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 LocalStorageExample() {
	// [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' })

		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 })
			}
		} else {
			setLoadingState({ status: 'ready' })
		}

		// [4]
		const cleanupFn = store.listen(
			throttle(() => {
				const snapshot = getSnapshot(store)
				localStorage.setItem(PERSISTENCE_KEY, JSON.stringify(snapshot))
			}, 500)
		)

		return () => {
			cleanupFn()
		}
	}, [store])

	// [5]
	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>
	)
}

/*
If all you want is local persistence, pass a `persistenceKey` to `Tldraw` and it will
save to IndexedDB for you. This example does the load/save loop by hand against
`localStorage` so you can see the pieces, and swap `localStorage` for your own backend.

[1]
Create the store ourselves rather than letting `Tldraw` do it, so we can load a snapshot
into it before the editor mounts. `useMemo` keeps it stable across renders.

[2]
A discriminated union for the loading state keeps the "error" branch from needing an
`error` field on the other states.

[3]
`useLayoutEffect` runs before the first paint, so if there's a saved snapshot the store
is populated before `Tldraw` renders. `loadSnapshot` replaces the store's contents and
runs any migrations needed for an older snapshot.

[4]
`store.listen` fires on every change. Serializing the whole document each time would be
wasteful, so the listener is throttled. The returned function removes the listener when
the component unmounts.

[5]
Render a spinner while loading, an error if the saved data couldn't be parsed, and the
editor once the store is ready.
*/
```

--------

# Static assets

Category: Data & assets

Keywords: assets, asseturls, custom fonts, custom icons, cdn, static files, self host, configuration

Replace individual fonts and icons, or self-host all of them, with the `assetUrls` prop.

The `Tldraw` component needs fonts, icons, and translations, which it fetches from tldraw's CDN by default. The `assetUrls` prop lets you point any of them at your own files, either to customize the look or to serve everything from your own origin. Entries you don't override keep their defaults.

This example swaps the "draw" font for Comic Mono and replaces the arrow tool's toolbar icon with a custom SVG. Select the draw font from the style panel and type some text, and look at the arrow tool in the toolbar, to see both in effect. To self-host every asset rather than a few, see the [`@tldraw/assets`](https://tldraw.dev/installation#Static-assets) options in the installation docs.

## 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 loads its fonts, icons, and translations from tldraw's
asset CDN. `assetUrls` overrides individual URLs; anything you don't list keeps its
default. Both relative and absolute URLs work.

Here the "draw" font and the arrow tool icon are replaced with files served from this
Vite project's public folder. Check your framework's docs for how it serves static files.

Define this object outside the component (or memoize it with `useMemo`). A fresh object
on every render would make `Tldraw` re-resolve its assets each time.
*/
```

--------

# Custom records

Category: Data & assets

Keywords: record, store, custom, data, migrations, validator, tlglobalrecordpropsmap

Store your own record types in the tldraw store so they persist, sync, and migrate alongside shapes.

Not all app data is a shape, binding, or asset. This example registers a "marker" record type, a pin at a page position with a label and icon, using the `records` option of `createTLStore`. A `CustomRecordInfo` supplies the scope, a validator, migrations (built with `createCustomRecordMigrationIds` and `createCustomRecordMigrationSequence`), and default properties. Augmenting `TLGlobalRecordPropsMap` makes the new type part of `TLRecord`, so store reads and writes are fully typed.

The markers are rendered in the `InFrontOfTheCanvas` slot from a reactive `store.query.records('marker')` query. Press "Add marker" to drop one at the center of the viewport, pan around to see it stay put on the page, and right-click or ctrl-click a marker to remove it.

## App.tsx

```tsx
import { useCallback, useMemo } from 'react'
import {
	BaseRecord,
	CustomRecordInfo,
	RecordId,
	T,
	Tldraw,
	TldrawUiButton,
	TldrawUiButtonLabel,
	Vec,
	createCustomRecordId,
	createCustomRecordMigrationIds,
	createCustomRecordMigrationSequence,
	createTLStore,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './custom-records.css'

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

// [1]
const MARKER_TYPE = 'marker'
interface Marker extends BaseRecord<typeof MARKER_TYPE, RecordId<Marker>> {
	x: number
	y: number
	label: string
	icon: string
}

declare module 'tldraw' {
	interface TLGlobalRecordPropsMap {
		[MARKER_TYPE]: Marker
	}
}

// [2]
const markerVersions = createCustomRecordMigrationIds(MARKER_TYPE, {
	AddIcon: 1,
})

// [3]
const markerRecord: CustomRecordInfo = {
	scope: 'document',
	validator: T.object({
		id: T.string,
		typeName: T.literal(MARKER_TYPE),
		x: T.number,
		y: T.number,
		label: T.string,
		icon: T.string,
	}),
	migrations: createCustomRecordMigrationSequence({
		sequence: [
			{
				id: markerVersions.AddIcon,
				up: (record) => {
					record.icon = '📍'
				},
				down: (record) => {
					delete record.icon
				},
			},
		],
	}),
	createDefaultProperties: () => ({
		x: 0,
		y: 0,
		label: '',
		icon: '📍',
	}),
}

// [4]
function createMarkerId(id?: string) {
	return createCustomRecordId(MARKER_TYPE, id) as Marker['id']
}

const ICONS = ['📍', '⭐', '🏠', '🏢', '🎯', '⚠️']

// [5]
function MarkerOverlay() {
	const editor = useEditor()
	const markersQuery = useMemo(() => editor.store.query.records(MARKER_TYPE), [editor])
	const markers = useValue(
		'markers on screen',
		() =>
			markersQuery.get().map((marker) => ({
				marker,
				screenPoint: editor.pageToViewport(new Vec(marker.x, marker.y)),
			})),
		[editor, markersQuery]
	)

	return (
		<>
			{markers.map(({ marker, screenPoint }) => {
				return (
					<div
						key={marker.id}
						className="custom-records-marker"
						style={{ left: screenPoint.x, top: screenPoint.y }}
						title={marker.label}
						onPointerDown={(e) => {
							e.stopPropagation()
							if (e.button === 2 || e.ctrlKey) {
								editor.store.remove([marker.id])
							}
						}}
					>
						<span className="custom-records-marker__icon">{marker.icon}</span>
						<span className="custom-records-marker__label">{marker.label}</span>
					</div>
				)
			})}
		</>
	)
}

function AddMarkerButton() {
	const editor = useEditor()

	const addMarker = useCallback(() => {
		const label = prompt('Marker label:')
		if (!label) return
		const point = editor.getViewportPageBounds().center
		editor.store.put([
			{
				id: createMarkerId(),
				typeName: MARKER_TYPE,
				x: point.x,
				y: point.y,
				label,
				icon: ICONS[Math.floor(Math.random() * ICONS.length)],
			},
		])
	}, [editor])

	return (
		<div className="tlui-menu" style={{ pointerEvents: 'all' }}>
			<TldrawUiButton type="normal" onClick={addMarker}>
				<TldrawUiButtonLabel>Add marker</TldrawUiButtonLabel>
			</TldrawUiButton>
		</div>
	)
}

const components = {
	InFrontOfTheCanvas: MarkerOverlay,
	TopPanel: AddMarkerButton,
}

// [6]
export default function CustomRecordsExample() {
	const store = useMemo(
		() =>
			createTLStore({
				records: { [MARKER_TYPE]: markerRecord },
			}),
		[]
	)

	return (
		<div className="tldraw__editor">
			<Tldraw store={store} components={components} />
		</div>
	)
}

/*
Custom record types let you keep domain data in the tldraw store that isn't a shape,
binding, or asset, so it's persisted, synced, and migrated alongside everything else.
This example adds a "marker" record: a pin at a page position with a label and icon.

[1]
The record type extends `BaseRecord`, which supplies `id` and `typeName`. Augmenting
`TLGlobalRecordPropsMap` adds it to `TLRecord`, so `store.query.records('marker')`,
`store.put`, and `store.remove` are all typed without casts.

[2]
`createCustomRecordMigrationIds` builds ids in the form `com.tldraw.marker/1`, which is
the sequence id the store expects for custom records.

[3]
The `CustomRecordInfo` passed to the store:
- `scope: 'document'` means persisted and synced; `'session'` would keep records local.
- `validator` checks the whole record, including `id` and `typeName`.
- `migrations` is optional. Each entry mutates the record in place (or returns a new
  one). Here version 1 adds the `icon` field to markers saved before it existed.
- `createDefaultProperties` fills in anything `store.put` doesn't supply.

[4]
Ids for custom records are `typeName:uniqueId`. `createCustomRecordId` returns a
generic record id, so we cast to `Marker['id']` once here.

[5]
`store.query.records(MARKER_TYPE)` returns a computed signal of all marker records.
Reading it and `pageToViewport` inside `useValue` means the overlay re-renders when a
marker is added or removed and when the camera moves, so pins stay glued to their page
position. Right-click (or ctrl-click) a marker to remove it.

[6]
Register the record type when creating the store via the `records` option, then pass
the store to `Tldraw`. The store must be created once, so it's wrapped in `useMemo`.
*/
```

## custom-records.css

```css
.custom-records-marker {
	position: absolute;
	transform: translate(-50%, -100%);
	display: flex;
	flex-direction: column;
	align-items: center;
	pointer-events: all;
	cursor: pointer;
}

.custom-records-marker__icon {
	font-size: 28px;
}

.custom-records-marker__label {
	font-size: 11px;
	background: white;
	border: 1px solid #ccc;
	border-radius: 4px;
	padding: 1px 4px;
	white-space: nowrap;
	max-width: 120px;
	overflow: hidden;
	text-overflow: ellipsis;
}
```

--------

# Export canvas as image

Category: Data & assets

Keywords: export, toimage, download, png, svg, blob, screenshot, canvas export, sharepanel

Render every shape on the page to a PNG with `editor.toImage` and download it.

`editor.toImage(shapeIds, options)` renders a set of shapes to an image `Blob`. This example puts a button in the `SharePanel` slot that passes every shape on the current page, then downloads the resulting PNG using a temporary link with a `download` attribute.

Draw a few shapes and press "Export canvas as image". For the full set of export options (background, padding, scale, dark mode, custom bounds), see the [with settings](https://tldraw.dev/examples/export-canvas-settings) variant.

## App.tsx

```tsx
import { Tldraw, TldrawUiButton, TldrawUiButtonLabel, TLUiComponents, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'

function ExportCanvasButton() {
	const editor = useEditor()
	return (
		<div className="tlui-menu" style={{ pointerEvents: 'all' }}>
			<TldrawUiButton
				type="normal"
				onClick={async () => {
					const shapeIds = editor.getCurrentPageShapeIds()
					if (shapeIds.size === 0) return alert('No shapes on the canvas')
					// [1]
					const { blob } = await editor.toImage([...shapeIds], { format: 'png', background: false })

					// [2]
					const link = document.createElement('a')
					link.href = URL.createObjectURL(blob)
					link.download = 'every-shape-on-the-canvas.png'
					link.click()
					URL.revokeObjectURL(link.href)
				}}
			>
				<TldrawUiButtonLabel>Export canvas as image</TldrawUiButtonLabel>
			</TldrawUiButton>
		</div>
	)
}

const components: TLUiComponents = {
	SharePanel: ExportCanvasButton,
}

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

/*
[1]
`editor.toImage` renders the given shapes to a `Blob`. Passing every shape id on the
page exports the whole canvas; pass a subset (e.g. `editor.getSelectedShapeIds()`) to
export part of it. `format` can be 'png', 'jpeg', 'webp', or 'svg'.

[2]
The simplest way to download a blob in the browser is a temporary link with a
`download` attribute. Revoke the object URL afterwards to free the memory.

See the "Export canvas as image (with settings)" example for the other export options,
and the "Create an image shape" / "Hosted images" examples for handling assets.
*/
```

--------

# Export canvas as image (with settings)

Category: Data & assets

Keywords: toimage, export, download, png, svg, blob, background, padding, scale, darkmode, bounds, box, tlimageexportoptions

Try each `TLImageExportOptions` setting (background, dark mode, padding, scale, bounds) when exporting with `editor.toImage`.

Builds on the [Export canvas as image](https://tldraw.dev/examples/export-canvas-as-image) example with a control panel for the options `editor.toImage` accepts: `background`, `darkMode`, `padding`, `scale`, and a page-space `bounds` box that crops the export instead of fitting it to the shapes. The box starts at the current viewport; set its width or height to 0 to fit all shapes again.

Draw something, adjust the settings, and press "Export canvas as image" to download a PNG.

## 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 ExportCanvasImageSettingsExample() {
	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(() => {
		const v = editor.getViewportPageBounds()
		return { x: Math.round(v.x), y: Math.round(v.y), w: Math.round(v.w), h: Math.round(v.h) }
	})

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

					// [3]
					const { blob } = await editor.toImage([...shapeIds], {
						format: 'png',
						...opts,
						bounds: box.w > 0 && box.h > 0 ? new Box(box.x, box.y, box.w, box.h) : undefined,
					})

					const link = document.createElement('a')
					link.href = URL.createObjectURL(blob)
					link.download = 'every-shape-on-the-canvas.png'
					link.click()
					URL.revokeObjectURL(link.href)
				}}
			>
				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}
			/>
		</>
	)
}

/*
[1]
`TLImageExportOptions` controls the export. The built-in export and copy actions fill
these from user preferences (e.g. `editor.user.getIsDarkMode()`), but when you call
`toImage` yourself you choose. `padding` accepts a number of pixels or 'auto', which
trims to the visual bounds of the content; the default here matches
`editor.options.defaultSvgPadding`.

[2]
`bounds` crops the export to a page-space box instead of fitting the shapes. It starts
as the current viewport so the first export matches what you see.

[3]
A box with zero width or height is treated as "no bounds", so the export fits all
shapes.
*/
```

--------

# Hosted images

Category: Data & assets

Keywords: upload, images, assets, tlassetstore, file upload, asset handling, resolve, fetch, storage, hosting

Upload user images to your own server with a `TLAssetStore` instead of storing them as data URLs.

Without an asset store, images and videos added to the canvas are inlined into the document as data URLs. A `TLAssetStore` passed to the `assets` prop takes over: its `upload` method sends each new file to your server and returns the URL to save, and its optional `resolve` method turns that saved URL into the one actually rendered, which is the place to add auth tokens or pick an optimized size.

The upload endpoint here is a placeholder, so this example won't actually store anything. It shows the code you'd write against your own backend.

## 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>
	)
}
/*
By default, images and videos added to the editor are stored as data URLs inside the
document, which is fine for a demo but bloats the document quickly. A `TLAssetStore`
tells the editor to upload files somewhere and store only a URL.

[1]
A placeholder for your server's upload endpoint. This example doesn't actually have one,
so uploads here will fail; the point is the shape of the code.

[2]
The asset store.

    [a] `upload` is called once when a file is added. It receives the asset record and the
    `File`, and must return the URL (`src`) that will be saved in the asset's props.

    [b] `resolve` is called whenever the editor needs to display the asset. Returning
    `asset.props.src` is the default behavior, so this method could be omitted. Implement
    it to rewrite the URL, for example to add an auth token or pick a resized variant
    based on the `ctx` argument (screen scale, whether it's for export, etc).

[3]
Pass the store to the `assets` prop. From then on, drops, pastes, and the "Upload media"
menu item all go through it.
*/
```

--------

# Custom paste behavior

Category: Data & assets

Keywords: paste, clipboard, external content, handler

Replace the built-in paste handler so a copied frame lands in free space beside the original.

Pasted tldraw content goes through the `'tldraw'` external content handler. This example overrides it with `editor.registerExternalContentHandler('tldraw', ...)` to add one rule: when the clipboard holds a single page-level frame, place the pasted copy to the right of the original (and past any other frames in the way), the way Figma does. Everything else falls through to `defaultHandleExternalTldrawContent`.

Try creating a frame, then pressing `Cmd + C`, `Cmd + V` a few times.

## App.tsx

```tsx
import {
	defaultHandleExternalTldrawContent,
	Editor,
	Tldraw,
	TLFrameShape,
	TLTldrawExternalContent,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

export default function CustomPasteExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					// [1]
					editor.registerExternalContentHandler('tldraw', (content) =>
						handleCustomTldrawPaste(editor, content)
					)
				}}
			/>
		</div>
	)
}

const SPACING_BETWEEN_FRAMES = 50

function handleCustomTldrawPaste(editor: Editor, { content, point }: TLTldrawExternalContent) {
	// [2]
	const onlyCopiedShape =
		content.rootShapeIds.length === 1
			? content.shapes.find((shape) => shape.id === content.rootShapeIds[0])
			: null

	const onlyCopiedFrame =
		onlyCopiedShape?.type === 'frame' ? (onlyCopiedShape as TLFrameShape) : null

	// only use the special behavior if the frame will be a direct child of the page (its
	// parentId isn't a shape in the document)
	const willPasteOnCurrentPage = onlyCopiedFrame
		? !editor.getShape(onlyCopiedFrame.parentId)
		: false

	// [3]
	if (point || !onlyCopiedFrame || !willPasteOnCurrentPage) {
		defaultHandleExternalTldrawContent(editor, { content, point })
		return
	}

	// [4]
	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
	}

	editor.nudgeShapes([newlyPastedFrame.id], {
		x: targetPosition - pastedBounds.minX,
		y: 0,
	})
}

/*
When you copy and paste a frame in Figma, the copy lands in free space to the right of
the original instead of on top of it. This example adds that behavior to tldraw.

[1]
`registerExternalContentHandler` replaces the handler for a content type. `'tldraw'` is
the type used for content copied from tldraw itself, so this intercepts every internal
paste. `defaultHandleExternalTldrawContent` is the built-in handler, which we fall back
to for anything we don't want to special-case.

[2]
Work out whether the clipboard holds exactly one root shape and that shape is a frame.

[3]
If the paste has an explicit `point` (for example, a paste from the context menu, which
lands at the pointer), or it isn't a lone page-level frame, use the default behavior.

[4]
Paste with the default handler first, then walk the frame's siblings from left to right
and slide the new frame past any that overlap it vertically, leaving a gap.
*/
```

--------

# External content sources

Category: Data & assets

Keywords: paste, copy, clipboard, html, registerexternalcontenthandler, text content, custom shape, baseboxshapeutil, htmlcontainer, dangerouslysetinnerhtml

Turn pasted `text/html` into a custom shape by overriding the text external content handler.

Content pasted or dropped into the editor is dispatched to a handler by type: text, files, url, svg-text, embed, or tldraw. This example calls `editor.registerExternalContentHandler('text', ...)` to replace the text handler. When the pasted text has an HTML source among its `sources`, it creates a `dangerous-html` shape that renders the markup with `dangerouslySetInnerHTML`; plain text falls back to `defaultHandleExternalTextContent`.

Try copying a few lines of code from VS Code, or some formatted text from a web page, and pasting them onto the canvas. Rendering arbitrary pasted HTML is unsafe outside of a demo, which is why the shape is named the way it is.

## 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]
type DangerousHtmlShape = TLShape<typeof DANGEROUS_HTML_TYPE>

// [2]
class DangerousHtmlShapeUtil extends BaseBoxShapeUtil<DangerousHtmlShape> {
	static override type = DANGEROUS_HTML_TYPE

	override getDefaultProps() {
		return {
			w: 500,
			h: 300,
			html: '<div>hello</div>',
		}
	}

	override component(shape: DangerousHtmlShape) {
		return (
			<HTMLContainer style={{ overflow: 'auto' }}>
				<div dangerouslySetInnerHTML={{ __html: shape.props.html }}></div>
			</HTMLContainer>
		)
	}

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

const shapeUtils = [DangerousHtmlShapeUtil]

export default function ExternalContentSourcesExample() {
	const handleMount = useCallback((editor: Editor) => {
		// [3]
		editor.registerExternalContentHandler('text', async (content) => {
			// [4]
			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_TYPE,
					x: center.x - 250,
					y: center.y - 150,
					props: {
						html: htmlSource.data,
					},
				})
			} else {
				await defaultHandleExternalTextContent(editor, content)
			}
		})
	}, [])

	return (
		<div className="tldraw__editor">
			<Tldraw onMount={handleMount} shapeUtils={shapeUtils} />
		</div>
	)
}

/*
When content arrives from outside the editor (paste, drop, or `putExternalContent`), it's
classified as text, files, url, svg-text, embed, or tldraw content and routed to the handler
registered for that type. This example replaces the text handler so that pasted `text/html`
becomes a shape that renders the HTML directly.

[1]
The shape type. Its `html` prop holds the raw pasted markup.

[2]
A minimal box shape that renders its `html` with `dangerouslySetInnerHTML`. It's called
"dangerous" for a reason: never do this with HTML you don't trust. See the custom shape
examples for a fuller shape util.

[3]
`registerExternalContentHandler('text', ...)` replaces the built-in text handler for this
editor. The other content types (`files`, `url`, `svg-text`, `embed`, `tldraw`) can be
overridden the same way.

[4]
Pasted text arrives with a `sources` array, one entry per clipboard flavor. Rich text
editors and code editors usually put both `text/plain` and `text/html` on the clipboard.
When there's an HTML source we create our shape at the paste point (or the viewport center
for keyboard paste); otherwise we defer to `defaultHandleExternalTextContent`, which
creates a normal text shape.
*/
```

--------

# Clipboard events

Category: Data & assets

Keywords: clipboard, copy, paste, cut, events, disable

Filter, transform, or block copy, cut, and paste with the clipboard hooks in `TldrawOptions`.

Three options let you intercept clipboard operations. They run for both keyboard shortcuts and menu actions.

- `onClipboardPasteRaw` runs first, before tldraw parses the clipboard. It receives the raw `DataTransfer` (source `native-event`) or `ClipboardItem[]` (source `clipboard-read`). Return `false` to cancel tldraw's default paste handling and deal with the data yourself.
- `onBeforeCopyToClipboard` receives the serialized `TLContent` plus `operation` (`copy` or `cut`) and `source` (`native` or `menu`). Return a modified `TLContent` to change what's written, or `false` to cancel (for cut, the selection is kept).
- `onBeforePasteFromClipboard` receives the parsed `TLExternalContent` about to be applied. Return a modified content object or `false` to cancel. It only fires for clipboard paste, not for file drops or programmatic `putExternalContent` calls.

Use the checkboxes in the top panel to block copy or paste, strip red shapes on copy or paste, take over raw paste, or add a 500ms delay to the hooks. The log below the controls shows each hook as it fires. Try drawing a red and a blue shape, then copying and pasting with different toggles on.

## App.tsx

```tsx
import { useCallback, useSyncExternalStore } from 'react'
import { Tldraw, type TldrawOptions } from 'tldraw'
import 'tldraw/tldraw.css'
import './clipboard-events.css'

// [1]
interface ClipboardLog {
	action: string
	source: string
	prevented: boolean
	detail?: string
}

interface ClipboardEventsState {
	disableCopy: boolean
	disablePaste: boolean
	filterRedOnCopy: boolean
	filterRedOnPaste: boolean
	handleRawPaste: boolean
	useAsyncCallbacks: boolean
	log: ClipboardLog[]
}

const state: ClipboardEventsState = {
	disableCopy: false,
	disablePaste: false,
	filterRedOnCopy: false,
	filterRedOnPaste: false,
	handleRawPaste: false,
	useAsyncCallbacks: false,
	log: [],
}

let stateVersion = 0
const listeners = new Set<() => void>()

function updateState(patch: Partial<ClipboardEventsState>) {
	Object.assign(state, patch)
	stateVersion++
	listeners.forEach((l) => l())
}

function subscribe(listener: () => void) {
	listeners.add(listener)
	return () => listeners.delete(listener)
}

function getSnapshot() {
	return stateVersion
}

function addLog(entry: ClipboardLog) {
	updateState({ log: [entry, ...state.log].slice(0, 3) })
	;(window as any).__tldraw_clipboard_log = [
		...((window as any).__tldraw_clipboard_log ?? []),
		entry,
	]
}

function delay(ms: number) {
	return new Promise<void>((resolve) => setTimeout(resolve, ms))
}

// [2]
const options: Partial<TldrawOptions> = {
	onClipboardPasteRaw(info) {
		if (!state.handleRawPaste) return
		function doThings() {
			if (info.source === 'native-event') {
				const kinds = info.clipboardData
					? [...info.clipboardData.items].map((i) => `${i.kind}:${i.type}`).join(', ')
					: '(no clipboardData)'
				addLog({
					action: 'raw-paste',
					source: 'native-event',
					prevented: false,
					detail: `${kinds}${state.useAsyncCallbacks ? ' (async)' : ''}`,
				})
			} else {
				addLog({
					action: 'raw-paste',
					source: 'clipboard-read',
					prevented: false,
					detail: `${info.clipboardItems.length} clipboard item(s)${state.useAsyncCallbacks ? ' (async)' : ''}`,
				})
			}
		}

		if (state.useAsyncCallbacks) {
			delay(500).then(() => doThings())
		} else {
			doThings()
		}
		return false
	},
	async onBeforeCopyToClipboard({ content, operation, source }) {
		if (state.useAsyncCallbacks) await delay(500)
		if (state.disableCopy) {
			addLog({
				action: operation,
				source,
				prevented: true,
			})
			return false
		}
		addLog({
			action: operation,
			source,
			prevented: false,
		})
		if (!state.filterRedOnCopy) return
		const filtered = content.shapes.filter((s) => !('color' in s.props && s.props.color === 'red'))
		const filteredIds = new Set(filtered.map((s) => s.id))
		const result = {
			...content,
			shapes: filtered,
			rootShapeIds: content.rootShapeIds.filter((id) => filteredIds.has(id)),
		}
		addLog({
			action: 'filter-copy',
			source: 'onBeforeCopyToClipboard',
			prevented: false,
			detail: `kept ${filtered.length}/${content.shapes.length} shapes`,
		})
		return result
	},
	async onBeforePasteFromClipboard({ content, source }) {
		if (state.useAsyncCallbacks) await delay(500)
		if (state.disablePaste) {
			addLog({ action: 'paste', source, prevented: true })
			return false
		}
		addLog({ action: 'paste', source, prevented: false })
		if (!state.filterRedOnPaste) return
		if (content.type !== 'tldraw') return
		const filtered = content.content.shapes.filter(
			(s) => !('color' in s.props && s.props.color === 'red')
		)
		const filteredIds = new Set(filtered.map((s) => s.id))
		addLog({
			action: 'filter-paste',
			source: 'onBeforePasteFromClipboard',
			prevented: false,
			detail: `kept ${filtered.length}/${content.content.shapes.length} shapes`,
		})
		return {
			...content,
			content: {
				...content.content,
				shapes: filtered,
				rootShapeIds: content.content.rootShapeIds.filter((id) => filteredIds.has(id)),
			},
		}
	},
}

// [3]
;(window as any).__tldraw_clipboard_state = state
;(window as any).__tldraw_clipboard_updateState = updateState

function Controls() {
	useSyncExternalStore(subscribe, getSnapshot)

	const toggleCopy = useCallback(() => {
		updateState({ disableCopy: !state.disableCopy })
	}, [])

	const togglePaste = useCallback(() => {
		updateState({ disablePaste: !state.disablePaste })
	}, [])

	const toggleFilterCopy = useCallback(() => {
		updateState({ filterRedOnCopy: !state.filterRedOnCopy })
	}, [])

	const toggleFilterPaste = useCallback(() => {
		updateState({ filterRedOnPaste: !state.filterRedOnPaste })
	}, [])

	const toggleRawPaste = useCallback(() => {
		updateState({ handleRawPaste: !state.handleRawPaste })
	}, [])

	const toggleAsync = useCallback(() => {
		updateState({ useAsyncCallbacks: !state.useAsyncCallbacks })
	}, [])

	return (
		<div className="clipboard-events-panel">
			<div className="clipboard-events-controls">
				<label>
					<input type="checkbox" checked={state.disableCopy} onChange={toggleCopy} />
					Block copy/cut
				</label>
				<label>
					<input type="checkbox" checked={state.disablePaste} onChange={togglePaste} />
					Block paste
				</label>
				<label>
					<input type="checkbox" checked={state.filterRedOnCopy} onChange={toggleFilterCopy} />
					Filter red on copy
				</label>
				<label>
					<input type="checkbox" checked={state.filterRedOnPaste} onChange={toggleFilterPaste} />
					Filter red on paste
				</label>
				<label>
					<input type="checkbox" checked={state.handleRawPaste} onChange={toggleRawPaste} />
					Handle raw paste (take over)
				</label>
				<label>
					<input type="checkbox" checked={state.useAsyncCallbacks} onChange={toggleAsync} />
					Async callbacks (500ms delay)
				</label>
			</div>
			<div className="clipboard-events-log" data-testid="clipboard-log">
				{state.log.length === 0 && <span className="clipboard-events-empty">No events yet</span>}
				{state.log.map((entry, i) => (
					<div key={i} className="clipboard-events-entry" data-testid="clipboard-log-entry">
						<strong>{entry.action}</strong> via <em>{entry.source}</em>
						{entry.prevented ? ' (blocked)' : ''}
						{entry.detail ? ` — ${entry.detail}` : ''}
					</div>
				))}
			</div>
		</div>
	)
}

export default function ClipboardEventsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				options={options}
				onMount={(editor) => {
					;(window as any).editor = editor
				}}
				components={{ TopPanel: Controls }}
				persistenceKey="clipboard-events-example"
			/>
		</div>
	)
}

/*
[1]
The toggles live in a plain module-level object rather than React state. The clipboard
callbacks are defined once in a stable `options` object, so if they closed over React
state they'd see stale values. `useSyncExternalStore` lets the panel re-render when it
changes.

[2]
The `options` object must be stable across renders (changing it recreates the editor),
which is why it's module-level and reads from the shared state.

`onClipboardPasteRaw` runs first, before tldraw parses the clipboard. `source` is
`native-event` (paste event with a DataTransfer) or `clipboard-read` (ClipboardItem[]
from the async clipboard API). Return `false` to cancel tldraw's default handling for
that gesture. This one is synchronous: it must decide immediately whether to take over,
so the "async" toggle only delays the logging here.

`onBeforeCopyToClipboard` runs for both copy and cut; use `operation` to tell them
apart. Return a modified `TLContent` to change what's written, or `false` to cancel
(for cut, the selection is kept).

`onBeforePasteFromClipboard` runs when parsed content is about to be applied. Return a
modified `TLExternalContent` or `false` to cancel.

The two `onBefore*` hooks may return a Promise. The "Async callbacks" toggle adds a
500ms delay so you can check that a slow hook still works, including on Safari where
the clipboard write must stay within the user gesture.

[3]
State and updater are exposed on window for the e2e tests.
*/
```

## clipboard-events.css

```css
.clipboard-events-panel {
	display: flex;
	flex-direction: column;
	gap: 8px;
	padding: 6px;
	border: 1px solid #ccc;
	box-shadow: none;
	pointer-events: all;
	font-size: 12px;
	min-width: 220px;
}

.clipboard-events-controls {
	display: flex;
	gap: 12px;
}

.clipboard-events-controls label {
	display: flex;
	align-items: center;
	gap: 4px;
	cursor: pointer;
	white-space: nowrap;
}

.clipboard-events-log {
	max-height: 120px;
	overflow-y: auto;
	display: flex;
	flex-direction: column;
	gap: 2px;
}

.clipboard-events-empty {
	color: #666;
	font-style: italic;
}

.clipboard-events-entry {
	padding: 2px 4px;
	border-radius: 4px;
	background: #f5f5f5;
}
```

--------

# Custom asset type

Category: Data & assets

Keywords: asset, assetutil, custom, file, upload, drag, drop, pdf, document, non-media

Accept non-media files like PDFs and CSVs by pairing a custom `AssetUtil` with a shape that displays them.

Out of the box, dropping a PDF or text file on the canvas does nothing because no asset type claims those MIME types. This example adds a `file` asset type with a `FileAssetUtil` that declares its supported MIME types and converts a dropped `File` into an asset record. A `FileCardShapeUtil` lists `file` in its `handledAssetTypes` and implements `createShapeForAsset`, so the editor knows to render a card for each uploaded file.

Try dragging a `.pdf`, `.txt`, `.csv`, `.json`, `.zip`, or `.xml` file onto the canvas. The default asset store inlines the file as a data URL, so the card's filename becomes a link you can open.

## App.tsx

```tsx
import {
	AssetUtil,
	BaseBoxShapeUtil,
	HTMLContainer,
	T,
	TLAsset,
	TLAssetId,
	TLBaseAsset,
	TLShape,
	TLShapePartial,
	Tldraw,
	VecModel,
	createShapeId,
	toRichText,
} from 'tldraw'
import 'tldraw/tldraw.css'

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

// [1]
const FILE_ASSET_TYPE = 'file' as const

interface FileAssetProps {
	name: string
	size: number
	mimeType: string
	src: string | null
}

type TLFileAsset = TLBaseAsset<typeof FILE_ASSET_TYPE, FileAssetProps>

declare module 'tldraw' {
	interface TLGlobalAssetPropsMap {
		[FILE_ASSET_TYPE]: FileAssetProps
	}
}

// [2]
class FileAssetUtil extends AssetUtil<TLFileAsset> {
	static override type = FILE_ASSET_TYPE

	static supportedMimeTypes = [
		'application/pdf',
		'text/plain',
		'text/csv',
		'application/json',
		'application/zip',
		'application/xml',
		'text/xml',
	] as const

	static supportedExtensions = ['.pdf', '.txt', '.csv', '.json', '.zip', '.xml'] as const

	// [3]
	static override props = {
		name: T.string,
		size: T.number,
		mimeType: T.string,
		src: T.string.nullable(),
	}

	override getDefaultProps(): TLFileAsset['props'] {
		return {
			name: '',
			size: 0,
			mimeType: '',
			src: null,
		}
	}

	// [4]
	override getSupportedMimeTypes() {
		return [...FileAssetUtil.supportedMimeTypes]
	}

	// [5]
	override async getAssetFromFile(file: File, assetId: TLAssetId): Promise<TLFileAsset> {
		return {
			id: assetId,
			type: FILE_ASSET_TYPE,
			typeName: 'asset',
			props: {
				name: file.name,
				size: file.size,
				mimeType: file.type,
				src: null,
			},
			meta: {},
		}
	}
}

const FILE_CARD_TYPE = 'file-card' as const

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[FILE_CARD_TYPE]: {
			assetId: TLAssetId | null
			w: number
			h: number
		}
	}
}

type FileCardShape = TLShape<typeof FILE_CARD_TYPE>

function formatFileSize(bytes: number): string {
	if (bytes === 0) return '0 B'
	const units = ['B', 'KB', 'MB', 'GB']
	const i = Math.floor(Math.log(bytes) / Math.log(1024))
	const value = bytes / Math.pow(1024, i)
	return `${value % 1 === 0 ? value : value.toFixed(1)} ${units[i]}`
}

// [6]
class FileCardShapeUtil extends BaseBoxShapeUtil<FileCardShape> {
	static override type = FILE_CARD_TYPE
	static override handledAssetTypes = [FILE_ASSET_TYPE] as const

	override getDefaultProps() {
		return {
			assetId: null as TLAssetId | null,
			w: 200,
			h: 64,
		}
	}

	// [7]
	override createShapeForAsset(asset: TLAsset, position: VecModel): TLShapePartial {
		return {
			id: createShapeId(),
			type: FILE_CARD_TYPE,
			x: position.x,
			y: position.y,
			props: {
				assetId: asset.id,
				w: 200,
				h: 64,
			},
		}
	}

	override component(shape: FileCardShape) {
		const asset = shape.props.assetId
			? this.editor.getAsset<TLFileAsset>(shape.props.assetId)
			: null

		const name = asset?.props.name ?? 'Unknown file'
		const size = asset?.props.size ?? 0
		const src = asset?.props.src

		return (
			<HTMLContainer>
				<div
					style={{
						display: 'flex',
						alignItems: 'center',
						gap: 10,
						padding: '10px 14px',
						background: 'var(--color-background)',
						border: '1px solid var(--color-muted-2)',
						borderRadius: 8,
						height: '100%',
						boxSizing: 'border-box',
						fontFamily: 'sans-serif',
						overflow: 'hidden',
					}}
				>
					<div style={{ fontSize: 24, flexShrink: 0 }}>📄</div>
					<div style={{ overflow: 'hidden', flex: 1, minWidth: 0 }}>
						<div
							style={{
								fontSize: 13,
								fontWeight: 500,
								whiteSpace: 'nowrap',
								overflow: 'hidden',
								textOverflow: 'ellipsis',
								color: 'var(--color-text-1)',
							}}
						>
							{/* [8] */}
							{src ? (
								<a
									href={src}
									target="_blank"
									rel="noreferrer"
									style={{ color: 'inherit', textDecoration: 'underline' }}
								>
									{name}
								</a>
							) : (
								name
							)}
						</div>
						<div style={{ fontSize: 11, color: 'var(--color-text-3)', marginTop: 2 }}>
							{formatFileSize(size)}
						</div>
					</div>
				</div>
			</HTMLContainer>
		)
	}

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

// [9]
export default function CustomAssetTypeExample() {
	const instructionText = `Drag a file with these supported extensions ${FileAssetUtil.supportedExtensions.join(', ')} onto the board`

	return (
		<div className="tldraw__editor">
			<Tldraw
				assetUtils={[FileAssetUtil]}
				shapeUtils={[FileCardShapeUtil]}
				persistenceKey="custom-asset-type-example"
				onMount={(editor) => {
					if (editor.getCurrentPageShapes().length === 0) {
						editor.createShapes([
							{
								id: createShapeId(),
								type: 'text',
								x: 100,
								y: 100,
								props: {
									richText: toRichText(instructionText),
								},
							},
						])
					}
				}}
			/>
		</div>
	)
}

/*
By default tldraw handles image, video, and bookmark assets. An `AssetUtil` teaches the
editor about a new asset type, and a `ShapeUtil` with `handledAssetTypes` tells it what
shape to create when one of those assets lands on the canvas.

[1]
The custom asset type. Augmenting `TLGlobalAssetPropsMap` makes `TLAsset` (and
`editor.getAsset`) aware of it, the same way `TLGlobalShapePropsMap` works for shapes.

[2]
`FileAssetUtil` handles MIME-type matching and file-to-asset conversion for the new type.

[3]
Static `props` are the store validators for the asset's props, using the same `T`
validators as shape utils.

[4]
When a file is dropped or pasted, the editor asks each registered `AssetUtil` whether it
supports the file's MIME type. Only files that match reach `getAssetFromFile`.

[5]
`getAssetFromFile` builds the asset record from a dropped file. `src` is left `null`
because the asset store's `upload` fills in the URL after the file is stored.

[6]
`handledAssetTypes` connects the shape to the asset type: when a `file` asset is
created, the editor finds this shape util and calls `createShapeForAsset`.

[7]
Return the shape partial to place on the canvas for a new asset. Returning `null` would
skip creating a shape.

[8]
Once the asset store has uploaded the file and set `src`, the filename becomes a link.

[9]
Register both utils. No custom external content handler is needed: the default file
handler picks the matching `AssetUtil` and uploads through the asset store. Here that is
the default store, which inlines files as data URLs; a real app would pass its own
`TLAssetStore` via the `assets` prop (see the "Hosted images" example).
*/
```

--------

# Meta migrations

Category: Data & assets

Keywords: migrations, meta, schema, createmigrationids, createmigrationsequence, versioning, upgrade, snapshot

Register your own migration sequence to upgrade `meta` data in old snapshots.

Records carry a `meta` field for app-specific data, but tldraw can't migrate what it doesn't know about. This example stores a page background theme in `page.meta`, then defines a migration with `createMigrationIds` and `createMigrationSequence` that maps a retired `'purple'` value to `'blue'`. The sequence is passed to the `migrations` prop; when the bundled snapshot (saved before that migration existed) loads, the migration runs automatically.

Open the page menu: the page that was purple is now blue and renamed "(was purple)". The dropdown in the top panel lets you change the current page's theme.

For migrating the `props` of a custom shape, use the simpler shape-props migration API described in the [persistence docs](https://tldraw.dev/sdk-features/persistence#shape-props-migrations).

## App.tsx

```tsx
import { Tldraw, createMigrationIds, createMigrationSequence } from 'tldraw'
import 'tldraw/tldraw.css'
import { snapshot } from './snapshot'
import { components } from './ui-overrides'

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

// [1]
interface _PageMetaV1 {
	backgroundTheme?: 'red' | 'blue' | 'green' | 'purple'
}

export interface PageMetaV2 {
	backgroundTheme?: 'red' | 'blue' | 'green'
}

// [2]
const sequenceId = 'com.example.my-app'
const versions = createMigrationIds(sequenceId, {
	RemovePurple: 1,
})

// [3]
const migrations = createMigrationSequence({
	sequenceId,
	sequence: [
		{
			id: versions.RemovePurple,
			scope: 'record',
			filter: (record) => record.typeName === 'page',
			up(page: any) {
				if (page.meta.backgroundTheme === 'purple') {
					page.meta.backgroundTheme = 'blue'
					page.name += ' (was purple)'
				}
			},
		},
	],
})

// [4]
const migrationsProp = [migrations]

export default function MetaMigrationsExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw migrations={migrationsProp} snapshot={snapshot} components={components} />
		</div>
	)
}

/*
Every record in the store has a `meta` field for your own data. Because tldraw doesn't
know what's in it, it can't migrate it for you. This example shows how to register your
own migration sequence so old snapshots are upgraded when they load.

If what you want to migrate is the `props` of a custom shape, there's a simpler dedicated
API for that: see https://tldraw.dev/sdk-features/persistence#shape-props-migrations.

[1]
Suppose you store a background color in each page's meta. Version 1 allowed 'purple';
version 2 removes it, and existing purple pages should become blue.

[2]
Pick a sequence id unique to your app, then create an id per version. Version numbers
start at 1 and increment by 1.

[3]
`scope: 'record'` runs the migration once per record, and `filter` limits it to pages.
`scope: 'store'` would instead receive the whole store, for migrations that need to
create or delete records. The `up` function mutates the record in place.

[4]
Pass the sequences to the `migrations` prop (as a stable array). When the `snapshot`
loads, its schema says it was saved before `com.example.my-app/1`, so the migration
runs and the "Purple" page arrives as blue with "(was purple)" in its name. Use the
"bg" dropdown in the top panel to change a page's theme.
*/
```

## 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 { TLComponents, useEditor, useValue } from 'tldraw'
import { PageMetaV2 } from './MetaMigrations'

function usePageBackgroundTheme() {
	const editor = useEditor()
	return useValue(
		'background theme',
		() => (editor.getCurrentPage().meta as PageMetaV2).backgroundTheme,
		[editor]
	)
}

// [1]
function ThemedBackground() {
	const backgroundTheme = usePageBackgroundTheme()
	return <div className="tl-background" style={{ backgroundColor: backgroundTheme }} />
}

function BackgroundThemeSelect() {
	const editor = useEditor()
	const backgroundTheme = usePageBackgroundTheme()

	return (
		<span style={{ pointerEvents: 'all', padding: '5px 15px', margin: 10, fontSize: 18 }}>
			bg: &nbsp;
			<select
				value={backgroundTheme ?? 'none'}
				onChange={(e) => {
					const value = e.currentTarget.value
					editor.updatePage({
						id: editor.getCurrentPageId(),
						meta: value === 'none' ? {} : { backgroundTheme: value },
					})
				}}
			>
				<option value="none">None</option>
				<option value="red">Red</option>
				<option value="blue">Blue</option>
				<option value="green">Green</option>
			</select>
		</span>
	)
}

export const components: TLComponents = {
	Background: ThemedBackground,
	TopPanel: BackgroundThemeSelect,
}

/*
[1]
Rather than reaching into the DOM to recolor the default background, override the
`Background` component slot. `useValue` re-runs when the current page or its meta
changes, so switching pages updates the color too.
*/
```

--------

# D3 geo map

Category: Use cases

Keywords: d3, geo, map, geography, shapes, states, topojson, visualization

Render a D3 geo projection as a custom shape and explode it into one shape per US state.

The `us-map` shape draws every state path from `d3-geo` and `us-atlas` inside a single `SVGContainer`. Double-click it (or press its "Explode states" button) and it is replaced by one `us-state` shape per state, positioned and scaled from the map's page bounds. Each state can then be moved, resized, and selected on its own.

The explode runs inside `editor.run`, so deleting the map and creating the states is a single undo step. Use "Reset map" in the top panel to start over.

## App.tsx

```tsx
import { Editor, TLComponents, Tldraw, TldrawUiButton, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import { MAP_HEIGHT, MAP_WIDTH } from './us-map-data'
import { UsMapShapeUtil } from './UsMapShapeUtil'
import './d3-map.css'
import { UsStateShapeUtil } from './UsStateShapeUtil'

// [1]
const shapeUtils = [UsMapShapeUtil, UsStateShapeUtil]

function createMap(editor: Editor) {
	editor.createShape({
		type: 'us-map',
		x: 0,
		y: 0,
		props: { w: MAP_WIDTH, h: MAP_HEIGHT },
	})
}

function resetMap(editor: Editor) {
	const mapAndStateIds = [...editor.getCurrentPageShapeIds()].filter((id) => {
		const shape = editor.getShape(id)
		return shape?.type === 'us-map' || shape?.type === 'us-state'
	})
	editor.run(() => {
		editor.deleteShapes(mapAndStateIds)
		createMap(editor)
	})
	editor.zoomToFit({ animation: { duration: 200 } })
}

function TopPanel() {
	const editor = useEditor()
	return (
		<div className="d3-map-top-panel tlui-menu">
			<TldrawUiButton type="normal" onClick={() => resetMap(editor)}>
				Reset map
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = {
	TopPanel,
}

export default function D3MapExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				shapeUtils={shapeUtils}
				components={components}
				onMount={(editor) => {
					if (editor.getCurrentPageShapeIds().size === 0) {
						createMap(editor)
					}
					editor.zoomToFit({ animation: { duration: 0 } })
				}}
			/>
		</div>
	)
}

/*
[1]
Two custom shapes: `us-map` renders every state path in one SVG (see UsMapShapeUtil.tsx),
and `us-state` renders a single state. Double-clicking the map, or clicking its "Explode
states" button, replaces the map with one `us-state` shape per state.
*/
```

## UsMapShapeUtil.tsx

```tsx
import {
	Editor,
	Geometry2d,
	RecordProps,
	Rectangle2d,
	SVGContainer,
	ShapeUtil,
	T,
	TLResizeInfo,
	TLShape,
	createShapeId,
	resizeBox,
} from 'tldraw'
import { MAP_HEIGHT, MAP_WIDTH, STATE_COLORS, getUsStatesData } from './us-map-data'

const US_MAP_TYPE = 'us-map' as const

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

export type UsMapShape = TLShape<typeof US_MAP_TYPE>

const statesData = getUsStatesData()

// [1]
export function explodeMap(editor: Editor, shape: UsMapShape) {
	const bounds = editor.getShapePageBounds(shape)
	if (!bounds) return

	const scaleX = bounds.w / MAP_WIDTH
	const scaleY = bounds.h / MAP_HEIGHT

	editor.run(
		() => {
			const newShapes = statesData.map((state, i) => ({
				id: createShapeId(),
				type: 'us-state' as const,
				x: bounds.x + state.bounds.x * scaleX,
				y: bounds.y + state.bounds.y * scaleY,
				props: {
					w: state.bounds.w * scaleX,
					h: state.bounds.h * scaleY,
					name: state.name,
					pathData: state.pathData,
					fill: STATE_COLORS[i % STATE_COLORS.length],
					originalW: state.bounds.w,
					originalH: state.bounds.h,
					pathOffsetX: state.bounds.x,
					pathOffsetY: state.bounds.y,
				},
			}))

			editor.deleteShape(shape.id)
			editor.createShapes(newShapes)
		},
		{ history: 'record-preserveRedoStack' }
	)
}

export class UsMapShapeUtil extends ShapeUtil<UsMapShape> {
	static override type = US_MAP_TYPE
	static override props: RecordProps<UsMapShape> = {
		w: T.number,
		h: T.number,
	}

	getDefaultProps(): UsMapShape['props'] {
		return { w: MAP_WIDTH, h: MAP_HEIGHT }
	}

	override canResize() {
		return true
	}
	override isAspectRatioLocked() {
		return true
	}

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

	override onResize(shape: UsMapShape, info: TLResizeInfo<UsMapShape>) {
		return resizeBox(shape, info)
	}

	override onDoubleClick(shape: UsMapShape) {
		explodeMap(this.editor, shape)
	}

	component(shape: UsMapShape) {
		const scaleX = shape.props.w / MAP_WIDTH
		const scaleY = shape.props.h / MAP_HEIGHT

		return (
			<>
				<SVGContainer>
					<g transform={`scale(${scaleX}, ${scaleY})`}>
						{statesData.map((state, i) => (
							<path
								key={state.id}
								d={state.pathData}
								fill={STATE_COLORS[i % STATE_COLORS.length]}
								stroke="#fff"
								strokeWidth={1 / scaleX}
								strokeLinejoin="round"
							/>
						))}
					</g>
				</SVGContainer>
				{/* [2] */}
				<button
					className="d3-map-explode-button"
					onPointerDown={(e) => e.stopPropagation()}
					onClick={() => explodeMap(this.editor, shape)}
					style={{ pointerEvents: 'all' }}
				>
					Explode states
				</button>
			</>
		)
	}

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

/*
[1]
Exploding deletes the map and creates all the state shapes inside one `editor.run` call,
so the whole operation is a single undo step. The state shapes are positioned from the
map's current page bounds so a resized map explodes at the same scale.

[2]
Stopping pointer-down propagation keeps the select tool from starting a drag on the map
shape when the button is pressed, so the click reaches the button. Shape contents don't
receive pointer events by default, hence `pointerEvents: 'all'`.
*/
```

## UsStateShapeUtil.tsx

```tsx
import {
	Geometry2d,
	RecordProps,
	Rectangle2d,
	SVGContainer,
	ShapeUtil,
	T,
	TLResizeInfo,
	TLShape,
	resizeBox,
} from 'tldraw'

const US_STATE_TYPE = 'us-state' as const

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[US_STATE_TYPE]: {
			w: number
			h: number
			name: string
			pathData: string
			fill: string
			originalW: number
			originalH: number
			pathOffsetX: number
			pathOffsetY: number
		}
	}
}

export type UsStateShape = TLShape<typeof US_STATE_TYPE>

export class UsStateShapeUtil extends ShapeUtil<UsStateShape> {
	static override type = US_STATE_TYPE
	static override props: RecordProps<UsStateShape> = {
		w: T.number,
		h: T.number,
		name: T.string,
		pathData: T.string,
		fill: T.string,
		originalW: T.number,
		originalH: T.number,
		pathOffsetX: T.number,
		pathOffsetY: T.number,
	}

	getDefaultProps(): UsStateShape['props'] {
		return {
			w: 100,
			h: 100,
			name: '',
			pathData: '',
			fill: '#4e79a7',
			originalW: 100,
			originalH: 100,
			pathOffsetX: 0,
			pathOffsetY: 0,
		}
	}

	override canResize() {
		return true
	}
	override isAspectRatioLocked() {
		return true
	}

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

	override onResize(shape: UsStateShape, info: TLResizeInfo<UsStateShape>) {
		return resizeBox(shape, info)
	}

	component(shape: UsStateShape) {
		const { w, h, pathData, fill, originalW, originalH, pathOffsetX, pathOffsetY, name } =
			shape.props
		const scaleX = w / originalW
		const scaleY = h / originalH

		return (
			<>
				<SVGContainer>
					<g transform={`scale(${scaleX}, ${scaleY}) translate(${-pathOffsetX}, ${-pathOffsetY})`}>
						<path
							d={pathData}
							fill={fill}
							stroke="#fff"
							strokeWidth={1 / scaleX}
							strokeLinejoin="round"
						/>
					</g>
				</SVGContainer>
				<div
					className="d3-map-state-label"
					style={{ pointerEvents: 'none', fontSize: `calc(11px * var(--tl-scale))` }}
				>
					{name}
				</div>
			</>
		)
	}

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

## d3-map.css

```css
.d3-map-explode-button {
	position: absolute;
	bottom: calc(8px * var(--tl-scale));
	right: calc(8px * var(--tl-scale));
	padding: calc(6px * var(--tl-scale)) calc(12px * var(--tl-scale));
	font-size: calc(13px * var(--tl-scale));
	background: var(--tl-color-low);
	color: var(--tl-color-text);
	border: 1px solid var(--tl-color-text-3);
	border-radius: calc(var(--tl-radius-4) * var(--tl-scale));
	cursor: pointer;
	white-space: nowrap;
}

.d3-map-explode-button:hover {
	background: var(--tl-color-muted-2);
}

.d3-map-state-label {
	position: absolute;
	bottom: 0;
	left: 0;
	padding: calc(2px * var(--tl-scale)) calc(4px * var(--tl-scale));
	color: var(--tl-color-text);
	background: var(--tl-color-low);
	border-top-right-radius: calc(var(--tl-radius-2) * var(--tl-scale));
	white-space: nowrap;
	overflow: hidden;
	text-overflow: ellipsis;
	max-width: 100%;
}

.d3-map-top-panel {
	display: flex;
	pointer-events: all;
}
```

## us-map-data.ts

```ts
import { geoAlbersUsa, geoPath } from 'd3-geo'
import { feature } from 'topojson-client'
import type { GeometryCollection, Topology } from 'topojson-specification'
import usTopology from 'us-atlas/states-10m.json'

export const MAP_WIDTH = 975
export const MAP_HEIGHT = 610

export const STATE_COLORS = [
	'#4e79a7',
	'#f28e2b',
	'#e15759',
	'#76b7b2',
	'#59a14f',
	'#edc948',
	'#b07aa1',
	'#ff9da7',
	'#9c755f',
	'#bab0ac',
	'#af7aa1',
	'#d4a373',
]

const projection = geoAlbersUsa()
	.scale(1300)
	.translate([MAP_WIDTH / 2, MAP_HEIGHT / 2])
const pathGenerator = geoPath(projection)

// FIPS code to state name
const FIPS_TO_NAME: Record<string, string> = {
	'01': 'Alabama',
	'02': 'Alaska',
	'04': 'Arizona',
	'05': 'Arkansas',
	'06': 'California',
	'08': 'Colorado',
	'09': 'Connecticut',
	'10': 'Delaware',
	'11': 'DC',
	'12': 'Florida',
	'13': 'Georgia',
	'15': 'Hawaii',
	'16': 'Idaho',
	'17': 'Illinois',
	'18': 'Indiana',
	'19': 'Iowa',
	'20': 'Kansas',
	'21': 'Kentucky',
	'22': 'Louisiana',
	'23': 'Maine',
	'24': 'Maryland',
	'25': 'Massachusetts',
	'26': 'Michigan',
	'27': 'Minnesota',
	'28': 'Mississippi',
	'29': 'Missouri',
	'30': 'Montana',
	'31': 'Nebraska',
	'32': 'Nevada',
	'33': 'New Hampshire',
	'34': 'New Jersey',
	'35': 'New Mexico',
	'36': 'New York',
	'37': 'North Carolina',
	'38': 'North Dakota',
	'39': 'Ohio',
	'40': 'Oklahoma',
	'41': 'Oregon',
	'42': 'Pennsylvania',
	'44': 'Rhode Island',
	'45': 'South Carolina',
	'46': 'South Dakota',
	'47': 'Tennessee',
	'48': 'Texas',
	'49': 'Utah',
	'50': 'Vermont',
	'51': 'Virginia',
	'53': 'Washington',
	'54': 'West Virginia',
	'55': 'Wisconsin',
	'56': 'Wyoming',
}

export interface UsStateData {
	id: string
	name: string
	pathData: string
	bounds: { x: number; y: number; w: number; h: number }
}

export function getUsStatesData(): UsStateData[] {
	const topology = usTopology as unknown as Topology<{ states: GeometryCollection }>
	const states = feature(topology, topology.objects.states)
	const result: UsStateData[] = []

	for (const f of states.features) {
		const id = String(f.id)
		const pathData = pathGenerator(f)
		if (!pathData) continue

		const bounds = pathGenerator.bounds(f)
		const [[x0, y0], [x1, y1]] = bounds
		const name = FIPS_TO_NAME[id.padStart(2, '0')] ?? `State ${id}`

		result.push({
			id,
			name,
			pathData,
			bounds: { x: x0, y: y0, w: x1 - x0, h: y1 - y0 },
		})
	}

	return result
}
```

--------

# Slideshow (fixed camera)

Category: Use cases

Keywords: annotation, camera options, constraints, zoom, pan, camera bounds, pan speed, zoom speed, scroll, slides, presentation

A slideshow that locks the camera to the current slide using camera constraints.

Slides are frame shapes laid out in a row. The current slide is tracked in a small reactive `SlidesManager` (an `atom` plus `computed` getters), and whenever it changes the example calls `editor.setCameraOptions` with `bounds` set to that frame and `behavior: 'contain'`, then animates there with `editor.zoomToBounds`. The user can draw on the slide but can't pan or zoom away from it.

Side effects keep the slide frames from being moved, selected, or hovered, and buttons rendered in `OnTheCanvas` let you insert new slides between existing ones.

Compare with the "Slideshow (free camera)" example, which uses a custom slide shape and lets the camera roam.

## App.tsx

```tsx
import { useEffect, useState } from 'react'
import { Editor, TLFrameShape, Tldraw, createShapeId, 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])

	// [1]
	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])

	// [2]
	useEffect(() => {
		if (!editor) return

		const ids = currentSlides.map((slide) => createShapeId(slide.id))

		editor.run(() => {
			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

					// Renumber the frame unless the user has renamed it
					let name = (shape as TLFrameShape).props.name
					if (/Slide \d+/.test(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,
						},
					})
				}
			}
		})

		// [3]
		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

	// [4]
	return (
		<>
			{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,
}

/*
[1]
Whenever the current slide changes, the camera constraints are re-pointed at that slide's
bounds with `contain` behavior and `fit-max` zoom, so the user can't pan or zoom away from
it, then the camera is animated there. `force: true` is needed because the constraints
would otherwise block the move.

[2]
The slide list is app state (see SlidesManager.tsx); each slide is mirrored on the canvas as
a frame shape whose id is derived from the slide id with `createShapeId(slide.id)`. When
slides are inserted, existing frames are shifted and renumbered.

[3]
Two before-change side effects keep the frames in place: any change to a slide frame other
than renaming it is rejected, and slide frames are removed from the selection and hover
state so they can't be picked up by the select tool.

[4]
The buttons for inserting slides are rendered in `OnTheCanvas`, so they are positioned in
page space between the frames. `markEventAsHandled` on pointer down stops the canvas from
treating the press as the start of a drag.
*/
```

## 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)
	}

	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 function 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 slideshow built from a custom slide shape, with a free camera that animates between slides.

A `slide` custom shape is an unfilled dashed rectangle you can draw with the slide tool (`S`), place other shapes on, and move around freely. The slides panel in the `HelperButtons` slot lists slides in page order; clicking one, or pressing the left and right arrow keys, calls `editor.zoomToBounds` to animate the camera to that slide. Double-clicking a slide's border does the same (the interior isn't filled, so double-clicking inside it creates text as usual).

Compare with the "Slideshow (fixed camera)" example, which locks the camera to the current slide instead of letting you pan and zoom.

## App.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TLUiOverrides,
	Tldraw,
	TldrawUiMenuItem,
	computed,
	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'

// [1]
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>
		)
	},
}

// [2]
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 shapeUtils = [SlideShapeUtil]
const tools = [SlideShapeTool]

export default function SlidesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				persistenceKey="slideshow_example"
				shapeUtils={shapeUtils}
				tools={tools}
				components={components}
				overrides={overrides}
				onMount={(editor) => {
					if (getSlides(editor).length === 0) {
						editor.createShapes([
							{ type: 'slide', x: 100, y: 100, props: { w: 720, h: 480 } },
							{ type: 'slide', x: 900, y: 100, props: { w: 720, h: 480 } },
						])
					}
				}}
			/>
		</div>
	)
}

/*
[1]
The slide list lives in the `HelperButtons` slot (top left, under the menu panel). The toolbar
and keyboard shortcuts dialog are replaced with versions that include the slide tool, since
new tools are not added to them automatically.

[2]
Two UI actions bound to the arrow keys move the camera between slides in page order.
`getSlides` is wrapped in a `computed` so the sorted list is only recomputed when shapes
change, not on every keypress.
*/
```

## 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,
		})
	}

	// [1]
	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

		// [2]
		// 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 (
			<>
				{/* [3] */}
				<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>
			</>
		)
	}

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

/*
[1]
Slides can't be rotated: the rotate handle is hidden and `onRotate` returns the initial
shape so rotation via other paths (e.g. the context menu's rotate actions) is a no-op.

[2]
The dashed border is drawn with `getPerfectDashProps` at a length scaled to the zoom level,
so the dashes stay the same size on screen at any zoom, and falls back to a solid line when
zoomed far out.

[3]
The geometry is unfilled, so clicking inside a slide selects the shapes on it rather than
the slide. The label in the corner is the one place a pointer-down selects the slide itself.
*/
```

## 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, camera constraints, grid, split layout, worksheet

A math worksheet with the question on the left and a constrained drawing canvas on the right.

The canvas is a `Tldraw` instance embedded in a page layout rather than filling the window. Camera constraints (`options.camera`) keep the view on a 600x600 coordinate grid, the `tools` UI override strips the toolbar down to select, hand, draw, eraser, line, and text, and `maxPages: 1` hides the page menu. The grid itself is an SVG rendered in the `OnTheCanvas` slot so it moves with the camera.

Try drawing the triangle from the question on the grid, then type answers into the boxes and press "Submit answers". The editor is kept in a ref from `onMount`, which is where a real app would export the drawing (`editor.toImage`) alongside the typed answers.

## App.tsx

```tsx
import { memo, useCallback, useRef, useState } from 'react'
import { Editor, TLComponents, TLUiOverrides, Tldraw, TldrawOptions } from 'tldraw'
import 'tldraw/tldraw.css'
import './education-canvas.css'

const GRID_SIZE = 600

// [1]
const options: Partial<TldrawOptions> = {
	maxPages: 1,
	camera: {
		constraints: {
			initialZoom: 'fit-max',
			baseZoom: 'fit-max',
			bounds: { x: 0, y: 0, w: GRID_SIZE, h: GRID_SIZE },
			behavior: { x: 'contain', y: 'contain' },
			padding: { x: 100, y: 100 },
			origin: { x: 0.5, y: 0.5 },
		},
	},
}

// [2]
const overrides: TLUiOverrides = {
	tools: (_editor, tools) => {
		const allowedTools = ['select', 'hand', 'draw', 'eraser', 'line', 'text']
		for (const key in tools) {
			if (!allowedTools.includes(key)) {
				delete tools[key]
			}
		}
		return tools
	},
}

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

// [3]
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
		// Camera options only set the constraints; a reset applies the initial zoom.
		editor.setCamera(editor.getCamera(), { reset: true })
	}, [])

	const handleSubmit = useCallback(() => {
		const normalizeAnswer = (answer: string) => {
			return answer.toLowerCase().replace(/[^a-z0-9(),.-]/g, '')
		}

		// Accept "8", "8 square units", "8 units²", and so on
		const normalizedB = normalizeAnswer(answers.partB)
		const isPartBCorrect =
			normalizedB.includes('8') &&
			(normalizedB.includes('square') || normalizedB.includes('unit') || normalizedB === '8')

		// Accept "(0,7)", "(0, 7)", "0,7", and so on
		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.')
		}

		// [4]
		const editor = rEditor.current
		if (editor) {
			// e.g. `await editor.toImage([...editor.getCurrentPageShapeIds()])` for part A
		}
	}, [answers])

	return (
		<div className="education-container">
			<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>

			<div className="canvas-panel">
				<div className="canvas-container">
					<Tldraw
						options={options}
						persistenceKey="education-canvas"
						components={components}
						overrides={overrides}
						onMount={handleMount}
					/>
				</div>
			</div>
		</div>
	)
}

/*
[1]
Camera constraints keep the student on the 600x600 grid: `bounds` is the grid, `contain`
stops panning away from it, and `fit-max` zooms so the whole grid fits with 100px padding.
`maxPages: 1` removes the page menu so there is only one canvas to hand in.

[2]
The `tools` override receives every registered tool keyed by id. Deleting the ones we don't
want removes them from the toolbar and keyboard shortcuts, leaving a small set suited to a
worksheet.

[3]
The coordinate grid is a plain SVG rendered in the `OnTheCanvas` slot, so it sits in page
space under the shapes and pans and zooms with the camera.

[4]
The editor ref is only used at submit time, so a ref set in `onMount` is enough. This is
where you would export the drawing and post it along with the typed answers.
*/
```

## 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, image annotation, cameraoptions, constraints, zoom, pan, bounds, panspeed, zoomspeed, zoomsteps, image editor

Annotate an image on a constrained canvas and export the result as a PNG.

The chosen image is placed as a locked image shape. Store side effects keep it locked and at the bottom of the page, and camera constraints (`editor.setCameraOptions` with `contain` behavior and a `fit-min-100` base zoom) stop you from panning or zooming away from it. An `InFrontOfTheCanvas` overlay dims everything outside the image so it's clear what will be exported.

Press "Done" to export with `editor.toImage`, cropped to the image bounds, then copy or download the result.

Try picking a very long, thin image to see how the camera constraints behave.

## 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 when a new image is chosen
						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 { useMemo, useState } from 'react'
import {
	AssetRecordType,
	Editor,
	SVGContainer,
	TLComponents,
	TLShapeId,
	Tldraw,
	createShapeId,
	track,
	useEditor,
} from 'tldraw'
import { AnnotatorImage } from './types'

export function ImageAnnotationEditor({
	image,
	onDone,
}: {
	image: AnnotatorImage
	onDone(result: Blob): void
}) {
	// [1]
	const [imageShapeId] = useState(() => createShapeId())

	const components = useMemo<TLComponents>(
		() => ({
			PageMenu: null,
			InFrontOfTheCanvas: () => <ImageBoundsOverlay imageShapeId={imageShapeId} />,
			SharePanel: () => <DoneButton imageShapeId={imageShapeId} onClick={onDone} />,
		}),
		[imageShapeId, onDone]
	)

	function onMount(editor: Editor) {
		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,
				},
			},
		])
		editor.createShape({
			id: imageShapeId,
			type: 'image',
			x: 0,
			y: 0,
			isLocked: true,
			props: {
				w: image.width,
				h: image.height,
				assetId,
			},
		})

		// [2]
		function makeSureShapeIsAtBottom() {
			const shape = editor.getShape(imageShapeId)
			if (!shape) return

			const pageId = editor.getCurrentPageId()
			if (shape.parentId !== pageId) {
				editor.moveShapesToPage([shape], pageId)
			}

			const siblings = editor.getSortedChildIdsForParent(pageId)
			if (siblings[0] !== imageShapeId) {
				editor.sendToBack([shape])
			}
		}

		makeSureShapeIsAtBottom()

		const removeOnCreate = editor.sideEffects.registerAfterCreateHandler(
			'shape',
			makeSureShapeIsAtBottom
		)
		const removeOnChange = editor.sideEffects.registerAfterChangeHandler(
			'shape',
			makeSureShapeIsAtBottom
		)

		// [3]
		const removeKeepLocked = editor.sideEffects.registerBeforeChangeHandler(
			'shape',
			(prev, next) => {
				if (next.id !== imageShapeId) return next
				if (next.isLocked) return next
				return { ...prev, isLocked: true }
			}
		)

		// [4]
		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 })

		// The image setup shouldn't be undoable
		editor.clearHistory()

		return () => {
			removeOnCreate()
			removeOnChange()
			removeKeepLocked()
		}
	}

	return <Tldraw onMount={onMount} components={components} />
}

// [5]
const ImageBoundsOverlay = track(function ImageBoundsOverlay({
	imageShapeId,
}: {
	imageShapeId: TLShapeId
}) {
	const editor = useEditor()
	const imagePageBounds = editor.getShapePageBounds(imageShapeId)
	if (!imagePageBounds) return null

	const viewport = editor.getViewportScreenBounds()
	const topLeft = editor.pageToViewport(imagePageBounds)
	const bottomRight = editor.pageToViewport({ x: imagePageBounds.maxX, y: imagePageBounds.maxY })

	const path = [
		// trace around the viewport
		`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 () => {
				// [6]
				const { blob } = await editor.toImage([...editor.getCurrentPageShapeIds()], {
					format: 'png',
					background: true,
					bounds: editor.getShapePageBounds(imageShapeId)!,
					padding: 0,
					scale: 1,
				})

				onClick(blob)
			}}
		>
			Done
		</button>
	)
}

/*
[1]
The image shape's id is decided up front so the overlay and done button can be given it
before the editor exists. The parent remounts this component (via `key`) when a new image is
chosen, so the id is stable for the life of one annotation session.

[2]
Annotations must draw on top of the image, so after any shape is created or changed we make
sure the image is still the first child of the page (and still on the page at all).

[3]
A before-change side effect rejects any update that would unlock the image, so it can't be
moved, deleted, or edited.

[4]
Camera constraints keep the image in view: `contain` stops you panning away from it and
`fit-min-100` stops you zooming out past the point where it fills the viewport. Try a very
long, thin image to see the behavior.

[5]
Only the image bounds are exported, so an even-odd SVG path in screen space dims everything
outside the image. `track` re-renders it as the camera moves.

[6]
`editor.toImage` with `bounds` set to the image's page bounds crops the export to exactly the
image, including any annotations that overlap it.
*/
```

## 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: pdf, annotation, camera options, constraints, zoom, pan, camera bounds, pan speed, zoom speed, scroll, document viewer

Annotate a PDF on the canvas and export the result back to a PDF.

Each PDF page is rendered with `pdfjs-dist` and placed on the canvas as a locked image shape. Side effects keep those page shapes locked and below every other shape. Camera constraints (`editor.setCameraOptions`) confine the viewport to the document, with `contain` behavior so you can scroll through pages but not away from them.

The `OnTheCanvas` slot draws a translucent overlay around the pages, and the export button uses `editor.toImage` with per-page `bounds` to render the annotations for each page and stamp them onto the original PDF with `pdf-lib`.

Try it: open your own PDF or use the example, draw on it, then press "Export PDF".

## 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
		}

		// [1]
		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()
	}

	const url = URL.createObjectURL(
		new Blob([(await pdf.save()) as BlobPart], { type: 'application/pdf' })
	)
	tickProgress()
	const a = document.createElement('a')
	a.href = url
	a.download = name
	a.click()
	URL.revokeObjectURL(url)
}

/*
[1]
`editor.toImage` with `bounds` set to the page rectangle exports only that region, so the PNG
lines up with the PDF page. Only the annotations that overlap the page are passed in, and
the page image itself is excluded because it is already in the PDF.
*/
```

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

export function PdfEditor({ pdf }: { pdf: Pdf }) {
	// [1]
	const components = useMemo<TLComponents>(
		() => ({
			PageMenu: null,
			OnTheCanvas: () => <PageOverlayScreen pdf={pdf} />,
			SharePanel: () => <ExportPdfButton pdf={pdf} />,
		}),
		[pdf]
	)

	return (
		<Tldraw
			onMount={(editor) => {
				// [2]
				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)

				// [3]
				editor.sideEffects.registerBeforeChangeHandler('shape', (prev, next) => {
					if (!shapeIdSet.has(next.id)) return next
					if (next.isLocked) return next
					return { ...prev, isLocked: true }
				})

				// [4]
				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)

				// [5]
				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

				const stopReacting = react('update camera', () => {
					const isMobileNow = editor.getViewportScreenBounds().width < 840
					if (isMobileNow === isMobile) return
					isMobile = isMobileNow
					updateCameraBounds(isMobile)
				})

				updateCameraBounds(isMobile)

				return stopReacting
			}}
			components={components}
		/>
	)
}

// [6]
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)`,
					}}
				/>
			))}
		</>
	)
})

/*
[1]
The page menu is hidden because everything lives on one page. `OnTheCanvas` draws the dimmed
area around the PDF pages and `SharePanel` is repurposed for the export button.

[2]
Each PDF page is rendered to a PNG in PdfPicker.tsx and placed on the canvas as a locked
image shape backed by an image asset.

[3]
A before-change side effect rejects any update that would unlock a page image, so users
can't accidentally move or delete a page.

[4]
Annotations must draw above the pages, so after any shape is created or changed we check
that the page images still hold the lowest indexes and re-index them if not.

[5]
Camera constraints keep the viewport on the pages: `contain` prevents scrolling past the
document, `fit-x-100` fits the width on load. The horizontal padding shrinks on narrow
screens; the `react` callback re-applies the constraints when the viewport crosses that
threshold. Returning its disposer from `onMount` stops it when the editor unmounts.

[6]
The overlay is an SVG in page space with an even-odd path: the viewport rectangle minus each
visible page rectangle, filled with a translucent background color. Only pages that collide
with the viewport are drawn.
*/
```

## 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 .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, clip, clippath, overlay, selection bounds, getselectionrotatedscreenbounds, usequickreactor, css, viewport

Dim the whole canvas except the selected shapes, using a CSS clip-path overlay.

A translucent white `<div>` in the `InFrontOfTheCanvas` slot covers the canvas. A `useQuickReactor` reads `editor.getSelectionRotatedScreenBounds()` and `editor.getSelectionRotation()` and sets the overlay's `clip-path` to a polygon that winds around the selection, so only the selection shows through. With nothing selected the clip is cleared and the whole canvas is dimmed.

Try selecting, dragging, rotating, and zooming: the window follows the selection.

## App.tsx

```tsx
import { useRef } from 'react'
import { Editor, TLComponents, Tldraw, createShapeId, useEditor, useQuickReactor } from 'tldraw'
import 'tldraw/tldraw.css'
import './mask-window.css'

function MaskWindow() {
	const editor = useEditor()
	const ref = useRef<HTMLDivElement>(null)

	// [1]
	useQuickReactor(
		'clip',
		() => {
			const elm = ref.current
			if (!elm) return

			const rotation = editor.getSelectionRotation()
			const box = editor.getSelectionRotatedScreenBounds()

			if (!box) {
				elm.style.clipPath = ''
				return
			}

			// [2]
			const vsb = editor.getViewportScreenBounds()
			const { corners } = box.clone().translate(vsb.point.clone().neg()).expandBy(20)
			const [tl, tr, br, bl] = corners.map((p) => p.rotWith(box.point, rotation))

			// [3]
			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]
	)

	return <div ref={ref} className="mask-fg" />
}

const components: TLComponents = {
	InFrontOfTheCanvas: MaskWindow,
}

// Seed an empty canvas with some shapes and select one so the mask has something to show
function seedCanvas(editor: Editor) {
	if (editor.getCurrentPageShapeIds().size > 0) return

	const vpb = editor.getViewportPageBounds()
	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()
	editor.createShape({
		id,
		type: 'geo',
		x: vpb.center.x - 100,
		y: vpb.center.y - 100,
		props: { w: 200, h: 200 },
	})
	editor.select(id)
}

export default function MaskWindowExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="mask" components={components} onMount={seedCanvas} />
		</div>
	)
}

/*
[1]
`useQuickReactor` re-runs synchronously whenever the selection or camera changes, and writes
straight to the element's style, so the mask never lags a frame behind the selection.

[2]
`getSelectionRotatedScreenBounds` is in screen space relative to the page, so it is offset by
the viewport's screen position to get coordinates relative to the overlay element. The
corners are then rotated to match the selection's rotation.

[3]
CSS `clip-path` has no "everything except this" mode, so the polygon traces the outer edge of
the overlay, dips in to wind around the selection rectangle, and comes back out. The wound
region ends up outside the polygon and is therefore transparent.
*/
```

## mask-window.css

```css
.mask-fg {
	position: absolute;
	top: 0px;
	left: 0px;
	width: 100%;
	height: 100%;
	pointer-events: none;
	background-color: rgba(255, 255, 255, 0.9);
}
```

--------

# Fog of war

Category: Use cases

Keywords: canvas, overlay, infrontofthecanvas, html canvas, usereactor, getcurrentpageshapes, getshapepagebounds, getshapegeometry, collision detection

Cover the canvas in fog that clears wherever shapes are drawn, using an HTML canvas kept in sync with the editor.

An HTML `<canvas>` rendered in the `InFrontOfTheCanvas` slot paints a dark overlay over the whole viewport. A `useReactor` callback re-runs whenever shapes or the camera change: it marks any grid cell that overlaps a shape's page bounds as revealed, then redraws the overlay with the camera transform applied and clears the revealed cells.

Try drawing anywhere: the fog lifts around your strokes and stays lifted as you pan and zoom.

## App.tsx

```tsx
import { useEffect, useRef } from 'react'
import { Box, TLComponents, Tldraw, useEditor, useReactor } from 'tldraw'
import 'tldraw/tldraw.css'

const CELL_SIZE = 32
const COUNT = 100
// The canvas is oversized by this much on every side so the blur doesn't fade at the edges
const BLEED = 100

// [1]
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 editor = useEditor()

	useEffect(() => {
		const cvs = rCanvas.current!
		const rect = cvs.getBoundingClientRect()
		cvs.width = rect.width
		cvs.height = rect.height
	}, [editor])

	// [2]
	useReactor(
		'update fog',
		() => {
			for (const shape of editor.getCurrentPageShapes()) {
				const bounds = editor.getShapePageBounds(shape)
				if (!bounds) continue
				for (let i = 0; i < boxes.length; i++) {
					for (let j = 0; j < boxes[i].length; j++) {
						if (bounds.collides(boxes[i][j])) {
							cells[i][j] = true
						}
					}
				}
			}

			// [3]
			const cvs = rCanvas.current!
			const ctx = cvs.getContext('2d')!
			const camera = editor.getCamera()

			cvs.style.filter = `blur(${camera.z * 15}px)`

			ctx.resetTransform()
			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(BLEED, BLEED)
			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: -BLEED,
				left: -BLEED,
				width: `calc(100% + ${BLEED * 2}px)`,
				height: `calc(100% + ${BLEED * 2}px)`,
				pointerEvents: 'none',
			}}
		/>
	)
}

const components: TLComponents = {
	InFrontOfTheCanvas: Fog,
}

export default function FogOfWarExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="fog-of-war-example" components={components} />
		</div>
	)
}

/*
[1]
The fog is a fixed grid of cells in page space centered on the origin. Once a cell has been
revealed it stays revealed, so the grid lives at module level rather than in React state and
survives re-renders (but not a page reload).

[2]
`useReactor` runs the callback whenever any signal it read changes: shapes, their bounds,
and the camera. Any cell that overlaps a shape's page bounds is marked as revealed.

[3]
The HTML canvas sits in the `InFrontOfTheCanvas` slot in screen space, so we apply the
tldraw camera transform (scale by zoom, then translate) before clearing the revealed cells.
The blur radius is scaled with the zoom so the fog edge looks the same at every zoom level.
*/
```

--------

# Mark exams

Category: Use cases

Keywords: education, pdf, annotation, marking, scoring, grading, toolbar, ui overrides, widget

Mark up an exam PDF with per-question score shapes and see the total tallied live.

This builds on the [pdf-editor](https://examples.tldraw.com/pdf-editor) example (a copy of it lives in the `pdf-editor` folder here) and adds:

- An `exam-mark` custom shape: a small numeric input whose value is stored in the shape's `score` prop.
- A `mark` tool that places an exam mark where you click, plus a select-tool override so double-clicking the canvas does the same.
- A `SharePanel` widget that sums the scores of every `exam-mark` on the page with `useValue`, so it updates as marks are added, edited, or removed.
- UI overrides that add the tool to the toolbar and the keyboard shortcuts dialog (shortcut `M`).

Try it: open the example exam, click on a question to drop a mark, type a score, and watch the total change.

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

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

/*
This example is built on top of the pdf-editor example; a copy of those files lives in the
`pdf-editor` folder here. On top of that it adds:

- `add-mark-util.tsx`: the `exam-mark` shape, a numeric score input.
- `add-mark-tool.tsx`: a tool that places an exam mark where you click.
- `ExamScoreLabel.tsx`: a widget that sums every exam mark on the page.
- `ui-overrides.tsx`: adds the tool to the toolbar and keyboard shortcuts dialog.
*/
```

## ExamScoreLabel.tsx

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

export function ExamScoreLabel() {
	const editor = useEditor()

	// [1]
	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]
`useValue` re-runs this computation whenever a shape it read changes, so the total tracks
every exam mark that is added, edited, or deleted with no manual subscription.
*/
```

## add-mark-tool.tsx

```tsx
import { StateNode } from 'tldraw'
import { EXAM_MARK_HEIGHT, EXAM_MARK_WIDTH } from './add-mark-util'

// See the custom-tool example for a fuller explanation of `StateNode`.
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(): 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 getIndicatorPath() {
		const path = new Path2D()
		path.rect(0, 0, EXAM_MARK_WIDTH, EXAM_MARK_HEIGHT)
		return path
	}

	getGeometry() {
		return new Rectangle2d({
			width: EXAM_MARK_WIDTH,
			height: EXAM_MARK_HEIGHT,
			isFilled: true,
		})
	}

	override hideSelectionBoundsBg() {
		return true
	}
	override hideSelectionBoundsFg() {
		return true
	}

	override canResize(): boolean {
		return false
	}
}

/*
See the custom-config example for the basics of a shape util. The notes below cover only
what is specific to this shape.

[1]
Making the shape editable means double-clicking it enters editing mode, which we read back
via `editor.getEditingShapeId()` and use to enable and focus the input.

[2]
The component is a plain `HTMLContainer` wrapping a number input.

 - [a] The input only receives pointer events while the shape is being edited, so a
   single click still selects and drags the shape.

 - [b] Local state holds the raw text of the input (which may be empty or "-" mid-edit);
   only valid numbers are written back to the shape's `score` prop.

 - [c] Newly created marks start in editing mode so the input is ready to type into.

 - [d] Focus and select the input whenever editing starts, whether from creation or a
   double-click.

 - [e] `editor.updateShape` writes the score into the store, which is what makes the total
   in `ExamScoreLabel` update.
*/
```

## ui-overrides.tsx

```tsx
import {
	DefaultKeyboardShortcutsDialog,
	DefaultKeyboardShortcutsDialogContent,
	DefaultToolbar,
	DefaultToolbarContent,
	TLComponents,
	TldrawUiMenuItem,
	TLUiOverrides,
	useIsToolSelected,
	useTools,
} from 'tldraw'

// [1]
export const uiOverrides: TLUiOverrides = {
	tools(editor, tools) {
		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>
		)
	},
}

/*
[1]
The `tools` override registers the tool item in the UI: its icon, label, keyboard shortcut,
and what selecting it does. Registering it here is what makes `useTools()` return it below.

[2]
The toolbar and keyboard shortcuts dialog don't pick up new tools automatically, so we
replace both with versions that render our item ahead of the default content.
*/
```

## 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(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()
	}

	const url = URL.createObjectURL(
		new Blob([(await pdf.save()) as BlobPart], { 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,
	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,
			OnTheCanvas: () => <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) => {
				// [1]
				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)

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

				const stopReacting = react('update camera', () => {
					const isMobileNow = editor.getViewportScreenBounds().width < 840
					if (isMobileNow === isMobile) return
					isMobile = isMobileNow
					updateCameraBounds(isMobile)
				})

				updateCameraBounds(isMobile)

				return stopReacting
			}}
			components={pdfEditorComponents}
			tools={customTools}
			initialState="mark"
			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`
	}

	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)`,
					}}
				/>
			))}
		</>
	)
})

/*
[1]
Double-clicking empty canvas normally creates a text shape. Overriding the select tool's
`select.idle` handler makes it place an exam mark instead. See the
custom-double-click-behavior example for details on this technique. The rest of this file
is the pdf-editor example, with footnotes explained there.
*/
```

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

		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(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 .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 .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);
}
```

--------

# Many shapes

Category: Use cases

Keywords: performance, stress test, many shapes, LOD, level of detail, culling

Populate the canvas with hundreds of shapes to see tldraw's performance optimizations in action.

This example creates a large number of shapes to demonstrate how tldraw handles dense canvases. Try zooming out to see level-of-detail transitions: sticky note shadows disappear, draw-style strokes simplify to solid paths, and pattern fills flatten to solid colors.

Use "Zoom to fit" in the zoom menu (bottom left) to see all shapes at once and observe how culling, debounced zoom, and LOD work together.

## App.tsx

```tsx
import {
	Editor,
	TLComponents,
	TLCreateShapePartial,
	Tldraw,
	TldrawUiButton,
	createShapeId,
	useEditor,
} from 'tldraw'
import 'tldraw/tldraw.css'

const GEO_TYPES = [
	'rectangle',
	'ellipse',
	'triangle',
	'diamond',
	'pentagon',
	'hexagon',
	'octagon',
	'star',
	'cloud',
	'heart',
] as const

const COLORS = [
	'black',
	'grey',
	'light-violet',
	'violet',
	'blue',
	'light-blue',
	'yellow',
	'orange',
	'green',
	'light-green',
	'light-red',
	'red',
] as const

const FILLS = ['none', 'semi', 'solid', 'pattern'] as const
const DASHES = ['draw', 'solid', 'dashed', 'dotted'] as const
const SIZES = ['s', 'm', 'l'] as const

function pick<T>(arr: readonly T[]): T {
	return arr[Math.floor(Math.random() * arr.length)]
}

// [1]
function generateShapes(editor: Editor, count: number) {
	const cols = Math.ceil(Math.sqrt(count * 1.5))
	const cellW = 200
	const cellH = 200
	const padding = 20

	const shapes: TLCreateShapePartial[] = []
	for (let i = 0; i < count; i++) {
		const col = i % cols
		const row = Math.floor(i / cols)
		const x = col * cellW + padding
		const y = row * cellH + padding
		const w = cellW - padding * 2
		const h = cellH - padding * 2

		if (i % 7 === 0) {
			shapes.push({
				id: createShapeId(),
				type: 'note' as const,
				x: x + Math.random() * 20,
				y: y + Math.random() * 20,
				props: {
					color: pick(COLORS),
					size: pick(SIZES),
				},
			})
		} else {
			shapes.push({
				id: createShapeId(),
				type: 'geo' as const,
				x: x + Math.random() * 20,
				y: y + Math.random() * 20,
				props: {
					geo: pick(GEO_TYPES),
					w: w * (0.6 + Math.random() * 0.4),
					h: h * (0.6 + Math.random() * 0.4),
					color: pick(COLORS),
					fill: pick(FILLS),
					dash: pick(DASHES),
					size: pick(SIZES),
				},
			})
		}
	}

	// [2]
	editor.createShapes(shapes)
}

function Controls() {
	const editor = useEditor()

	const handleGenerate = (count: number) => {
		generateShapes(editor, count)
		editor.zoomToFit({ animation: { duration: 300 } })
	}

	const handleClear = () => {
		editor.deleteShapes([...editor.getCurrentPageShapeIds()])
	}

	return (
		<div style={{ display: 'flex', gap: 4, padding: 8, flexWrap: 'wrap' }}>
			<TldrawUiButton type="normal" onClick={() => handleGenerate(200)}>
				Add 200 shapes
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={() => handleGenerate(500)}>
				Add 500 shapes
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={() => handleGenerate(1000)}>
				Add 1000 shapes
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={handleClear}>
				Clear all
			</TldrawUiButton>
		</div>
	)
}

const components: TLComponents = { TopPanel: Controls }

export default function ManyShapesExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				onMount={(editor) => {
					generateShapes(editor, 500)
					editor.zoomToFit({ animation: { duration: 0 } })
				}}
				components={components}
			/>
		</div>
	)
}

/*
[1]
Shapes are laid out in a grid with slight random offsets. Every 7th shape is a sticky note,
whose shadow is dropped at low zoom; the rest are geo shapes with random fills, dashes, and
sizes so that "draw" strokes and "pattern" fills get exercised too, since both simplify when
zoomed out.

[2]
One `createShapes` call with the whole array is a single store transaction, so observers get
one batched update instead of one per shape. Wrapping many separate editor calls in
`editor.run` achieves the same thing.
*/
```

--------

# Soft clipping region

Category: Use cases

Keywords: soft clip, dim, mask, geo, meta, overlay, infrontofthecanvas, getshapegeometry, pagetoscreen, usequickreactor, fill-rule, evenodd

A geo shape that dims everything outside it.

Any regular geo shape (rectangle, ellipse, triangle, star, ...) can act as a soft clipping region. The behaviour is opted into per shape through `shape.meta.softClip`, so no custom shape util is needed.

An `InFrontOfTheCanvas` SVG overlay reactively reads every shape with that meta flag, transforms its vertices to screen space, and renders a single `<path>` using `fill-rule="evenodd"`. The viewport rectangle plus each region's outline form a "donut" shape — the outside fills with a translucent colour and the inside stays untouched.

Select any geo shape and use the toggle to turn its soft-clip behaviour on or off. Use the slider to adjust how visible the outside content is (0% is fully dimmed, 100% removes the dim entirely).

## App.tsx

```tsx
import { useRef, useState } from 'react'
import {
	Editor,
	TLComponents,
	TLGeoShape,
	TLShape,
	Tldraw,
	createShapeId,
	useEditor,
	useQuickReactor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './soft-clip.css'

const SOFT_CLIP_META_KEY = 'softClip'

function isSoftClipShape(shape: TLShape) {
	return shape.type === 'geo' && shape.meta?.[SOFT_CLIP_META_KEY] === true
}

function SoftClipOverlay({ opacity }: { opacity: number }) {
	const editor = useEditor()
	const pathRef = useRef<SVGPathElement>(null)

	// [1]
	useQuickReactor(
		'soft clip overlay',
		() => {
			const path = pathRef.current
			if (!path) return

			const vsb = editor.getViewportScreenBounds()
			const clipShapes = editor.getCurrentPageShapes().filter(isSoftClipShape)

			if (clipShapes.length === 0) {
				path.setAttribute('d', '')
				return
			}

			// [2]
			let d = `M0,0 L${vsb.w},0 L${vsb.w},${vsb.h} L0,${vsb.h} Z`

			for (const shape of clipShapes) {
				const geo = editor.getShapeGeometry(shape)
				const pageTransform = editor.getShapePageTransform(shape)
				if (!pageTransform || geo.vertices.length === 0) continue

				const pagePts = pageTransform.applyToPoints(geo.vertices)
				const screenPts = pagePts.map((p) => editor.pageToScreen(p))

				d += ` M${(screenPts[0].x - vsb.x).toFixed(2)},${(screenPts[0].y - vsb.y).toFixed(2)}`
				for (let i = 1; i < screenPts.length; i++) {
					d += ` L${(screenPts[i].x - vsb.x).toFixed(2)},${(screenPts[i].y - vsb.y).toFixed(2)}`
				}
				d += ' Z'
			}

			path.setAttribute('d', d)
		},
		[editor]
	)

	return (
		<svg className="soft-clip-overlay">
			<path ref={pathRef} fillRule="evenodd" fillOpacity={1 - opacity} />
		</svg>
	)
}

function SoftClipControls({
	opacity,
	onOpacityChange,
}: {
	opacity: number
	onOpacityChange(value: number): void
}) {
	const editor = useEditor()
	const selectedGeoShapes = useValue(
		'selected geo shapes',
		() => editor.getSelectedShapes().filter((s): s is TLGeoShape => s.type === 'geo'),
		[editor]
	)

	const allMarked =
		selectedGeoShapes.length > 0 &&
		selectedGeoShapes.every((s) => s.meta?.[SOFT_CLIP_META_KEY] === true)

	return (
		<div className="soft-clip-controls">
			<label className="soft-clip-slider">
				<span>Opacity</span>
				<input
					type="range"
					min={0}
					max={100}
					value={Math.round(opacity * 100)}
					onChange={(e) => onOpacityChange(Number(e.target.value) / 100)}
				/>
				<span className="soft-clip-slider-value">{Math.round(opacity * 100)}%</span>
			</label>
			{selectedGeoShapes.length > 0 && (
				<button
					onClick={() => {
						editor.updateShapes(
							selectedGeoShapes.map((s) => ({
								id: s.id,
								type: s.type,
								meta: { ...s.meta, [SOFT_CLIP_META_KEY]: !allMarked },
							}))
						)
					}}
				>
					{allMarked ? 'Disable soft clip' : 'Enable soft clip'}
				</button>
			)}
		</div>
	)
}

function SoftClipUI() {
	const [opacity, setOpacity] = useState(0.3)
	return (
		<>
			<SoftClipOverlay opacity={opacity} />
			<SoftClipControls opacity={opacity} onOpacityChange={setOpacity} />
		</>
	)
}

function setupDemoShapes(editor: Editor) {
	if (editor.getCurrentPageShapeIds().size > 0) return

	const { center } = editor.getViewportPageBounds()

	editor.createShapes([
		{
			type: 'geo',
			x: center.x - 280,
			y: center.y - 200,
			props: { geo: 'rectangle', w: 160, h: 110, color: 'blue', fill: 'semi' },
		},
		{
			type: 'geo',
			x: center.x + 80,
			y: center.y - 220,
			props: { geo: 'ellipse', w: 130, h: 130, color: 'yellow', fill: 'semi' },
		},
		{
			type: 'geo',
			x: center.x - 240,
			y: center.y + 30,
			props: { geo: 'triangle', w: 150, h: 140, color: 'green', fill: 'semi' },
		},
		{
			type: 'geo',
			x: center.x + 60,
			y: center.y + 40,
			props: { geo: 'star', w: 150, h: 140, color: 'violet', fill: 'semi' },
		},
	])

	// [3]
	const clipId = createShapeId()
	editor.createShape({
		id: clipId,
		type: 'geo',
		x: center.x - 180,
		y: center.y - 180,
		props: { geo: 'ellipse', w: 360, h: 360, color: 'black', fill: 'none' },
		meta: { [SOFT_CLIP_META_KEY]: true },
	})
	editor.select(clipId)
}

const components: TLComponents = {
	InFrontOfTheCanvas: SoftClipUI,
}

export default function SoftClipExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="soft-clip" components={components} onMount={setupDemoShapes} />
		</div>
	)
}

/*
[1]
`useQuickReactor` re-runs synchronously whenever any of the signals it reads change (shapes,
their geometry, the camera), and writes the path data straight to the DOM so the overlay
never lags the canvas.

[2]
The first subpath is the whole viewport; each clip shape's vertices, transformed to screen
space, add another subpath. With `fill-rule="evenodd"` the inner subpaths are holes, so the
outside is dimmed and the inside is left alone.

[3]
Soft clipping is opted into per shape via `shape.meta.softClip`. Meta is free-form data
stored on the record, so no custom shape util or schema change is needed and it persists
with the document.
*/
```

## soft-clip.css

```css
.soft-clip-overlay {
	position: absolute;
	inset: 0;
	width: 100%;
	height: 100%;
	pointer-events: none;
}

.soft-clip-overlay path {
	fill: rgb(248, 249, 250);
}

.soft-clip-controls {
	position: absolute;
	bottom: 60px;
	left: 50%;
	transform: translateX(-50%);
	pointer-events: all;
	z-index: 300;
	display: flex;
	flex-direction: column;
	align-items: stretch;
	gap: 8px;
	padding: 10px 14px;
	background: var(--tl-color-panel);
	border: 1px solid var(--tl-color-divider);
	border-radius: 10px;
	box-shadow: var(--tl-shadow-2);
	color: var(--tl-color-text);
	font-size: 13px;
	min-width: 240px;
}

.soft-clip-slider {
	display: grid;
	grid-template-columns: auto 1fr auto;
	align-items: center;
	gap: 10px;
}

.soft-clip-slider input[type='range'] {
	width: 100%;
	accent-color: var(--tl-color-selected);
}

.soft-clip-slider-value {
	font-variant-numeric: tabular-nums;
	color: var(--tl-color-text-1);
	min-width: 38px;
	text-align: right;
}

.soft-clip-controls button {
	background: var(--tl-color-low);
	color: var(--tl-color-text);
	border: 1px solid var(--tl-color-divider);
	border-radius: 8px;
	padding: 8px 14px;
	font: inherit;
	font-size: 13px;
	cursor: pointer;
}

.soft-clip-controls button:hover {
	background: var(--tl-color-hint);
}
```

--------

# Tower defense

Category: Use cases

Keywords: overlay, overlayutil, canvas, animation, game, hit testing, raf, tick

A small tower defense game whose enemies, projectiles, and effects are drawn with `OverlayUtil` classes on the overlay canvas.

Pick a tower from the toolbar (or press 1, 2, or 3) and click the canvas to place it. Each tower is a locked geo shape (triangle, rectangle, or ellipse) with its own range, fire rate, damage, and projectile. Enemies follow a fixed path; click an enemy to deal damage by hand, and hover a tower to see its range and an upgrade button.

Everything that moves is an `OverlayUtil` subclass registered through the `overlayUtils` prop: the path, enemies, projectiles, explosions, tower ranges, the placement preview, and the upgrade button. Game state lives in `atom`s that `getOverlays()` reads, so when the game loop updates them every overlay redraws reactively. Overlays that respond to input implement `getGeometry()` for hit testing, `getCursor()` for the hover cursor, and `onPointerDown()` for clicks; the editor routes pointer events to them before the canvas.

The game loop runs on the editor's `tick` event, which fires once per frame with the elapsed milliseconds. Tower placement itself goes through an overlay too: the preview follows the pointer and its `onPointerDown` creates the geo shape.

## App.tsx

```tsx
import { useCallback, useEffect } from 'react'
import {
	Box,
	Editor,
	TLAnyOverlayUtilConstructor,
	TLUiComponents,
	Tldraw,
	defaultOverlayUtils,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import { resetSpawnTimer, runGameTick } from './game-loop'
import {
	enemies$,
	gameOver$,
	gold$,
	lives$,
	placingTower$,
	projectiles$,
	resetGameState,
	score$,
} from './game-state'
import { EnemyOverlayUtil } from './overlays/EnemyOverlayUtil'
import { ExplosionOverlayUtil } from './overlays/ExplosionOverlayUtil'
import { PathOverlayUtil } from './overlays/PathOverlayUtil'
import { PlacementPreviewOverlayUtil } from './overlays/PlacementPreviewOverlayUtil'
import { ProjectileOverlayUtil } from './overlays/ProjectileOverlayUtil'
import { TowerRangeOverlayUtil } from './overlays/TowerRangeOverlayUtil'
import { UpgradeButtonOverlayUtil } from './overlays/UpgradeButtonOverlayUtil'
import { TOWER_GEOS, TOWER_STATS_BY_GEO, TowerGeo } from './tower-config'
import './tower-defense.css'

const overlayUtils: TLAnyOverlayUtilConstructor[] = [
	...defaultOverlayUtils,
	PathOverlayUtil,
	TowerRangeOverlayUtil,
	PlacementPreviewOverlayUtil,
	EnemyOverlayUtil,
	ProjectileOverlayUtil,
	ExplosionOverlayUtil,
	UpgradeButtonOverlayUtil,
]

function pickTower(geo: TowerGeo) {
	// Only arm a tower the player can afford, so the preview only shows when a click would place one
	if (gold$.get() < TOWER_STATS_BY_GEO[geo].cost) return
	placingTower$.set(geo)
}

function pickSelect(editor: Editor) {
	placingTower$.set(null)
	editor.setCurrentTool('select')
}

function restartGame(editor: Editor) {
	resetGameState()
	resetSpawnTimer()
	placingTower$.set(null)
	// Towers are locked shapes, so deleting them needs `ignoreShapeLock`
	const allShapeIds = [...editor.getCurrentPageShapeIds()]
	editor.run(() => editor.deleteShapes(allShapeIds), { ignoreShapeLock: true })
}

function GameRunner() {
	const editor = useEditor()

	useEffect(() => {
		const onTick = (elapsedMs: number) => {
			// After a background tab resumes, `tick` reports one large elapsed value that would
			// otherwise teleport every enemy down the path
			const dt = Math.min(60, elapsedMs)
			runGameTick(editor, dt)
		}
		editor.on('tick', onTick)

		const onKeyDown = (e: KeyboardEvent) => {
			if (e.metaKey || e.ctrlKey || e.altKey) return
			const target = e.target as HTMLElement | null
			if (target?.matches('input, textarea, [contenteditable="true"]')) return
			if (e.key === '1') pickTower('triangle')
			else if (e.key === '2') pickTower('rectangle')
			else if (e.key === '3') pickTower('ellipse')
			else if (e.key === 'Escape') pickSelect(editor)
			else if (e.key === ' ') {
				e.preventDefault()
				restartGame(editor)
			}
		}
		window.addEventListener('keydown', onKeyDown)

		return () => {
			editor.off('tick', onTick)
			window.removeEventListener('keydown', onKeyDown)
			placingTower$.set(null)
		}
	}, [editor])

	return null
}

function GameToolbar() {
	const editor = useEditor()
	const placingGeo = useValue('placingGeo', () => placingTower$.get(), [])
	const gold = useValue('gold', () => gold$.get(), [])

	const onPickSelect = useCallback(() => pickSelect(editor), [editor])

	return (
		<div className="td-toolbar">
			<button
				className={'td-toolbar__btn' + (placingGeo === null ? ' is-active' : '')}
				onClick={onPickSelect}
				title="Select (Esc)"
			>
				<SelectGlyph />
				<span className="td-toolbar__label">Select</span>
				<span className="td-toolbar__cost">
					<kbd>esc</kbd>
				</span>
			</button>
			{TOWER_GEOS.map((geo, i) => {
				const stats = TOWER_STATS_BY_GEO[geo]
				const isActive = placingGeo === geo
				const canAfford = gold >= stats.cost
				const cls =
					'td-toolbar__btn' + (isActive ? ' is-active' : '') + (canAfford ? '' : ' is-disabled')
				return (
					<button
						key={geo}
						className={cls}
						onClick={() => canAfford && pickTower(geo)}
						disabled={!canAfford}
						title={`${stats.label} (${geo}) — ${stats.cost} gold — press ${i + 1}`}
					>
						<TowerGlyph geo={geo} />
						<span className="td-toolbar__label">{stats.label}</span>
						<span className="td-toolbar__cost">
							{stats.cost}g · <kbd>{i + 1}</kbd>
						</span>
					</button>
				)
			})}
		</div>
	)
}

function SelectGlyph() {
	return (
		<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
			<path
				d="M4 3 L4 15 L7.5 12 L9.7 17 L11.5 16.2 L9.3 11.2 L14 11 Z"
				fill="currentColor"
				stroke="currentColor"
				strokeWidth="1"
				strokeLinejoin="round"
			/>
		</svg>
	)
}

function TowerGlyph({ geo }: { geo: TowerGeo }) {
	const stroke = 'currentColor'
	if (geo === 'triangle') {
		return (
			<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
				<polygon points="10,2 18,18 2,18" fill="none" stroke={stroke} strokeWidth="2" />
			</svg>
		)
	}
	if (geo === 'rectangle') {
		return (
			<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
				<rect x="2" y="4" width="16" height="12" fill="none" stroke={stroke} strokeWidth="2" />
			</svg>
		)
	}
	return (
		<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
			<ellipse cx="10" cy="10" rx="8" ry="6" fill="none" stroke={stroke} strokeWidth="2" />
		</svg>
	)
}

function HUD() {
	const editor = useEditor()
	const score = useValue('score', () => score$.get(), [])
	const gold = useValue('gold', () => gold$.get(), [])
	const lives = useValue('lives', () => lives$.get(), [])
	const enemyCount = useValue('enemies', () => enemies$.get().length, [])
	const projectileCount = useValue('projectiles', () => projectiles$.get().length, [])
	const gameOver = useValue('gameOver', () => gameOver$.get(), [])

	const onRestart = useCallback(() => restartGame(editor), [editor])

	return (
		<div className="td-hud">
			<div className="td-hud__row">
				<span>
					Gold <strong>{gold}</strong>
				</span>
				<span>
					Score <strong>{score}</strong>
				</span>
				<span>
					Lives <strong>{lives}</strong>
				</span>
				<span>
					Enemies <strong>{enemyCount}</strong>
				</span>
				<span>
					Shots <strong>{projectileCount}</strong>
				</span>
				<button className="td-hud__btn" onClick={onRestart}>
					Restart
				</button>
			</div>
			<div className="td-hud__hint">
				Pick a tower from the toolbar (or press <kbd>1</kbd>/<kbd>2</kbd>/<kbd>3</kbd>), then click
				the canvas to place it. Each tower costs gold; kill enemies to earn more. Magic blasts deal
				area damage. Click an enemy to chip damage for free. Press <kbd>space</kbd> to restart.
			</div>
			{gameOver && <div className="td-hud__gameover">Game over — press Restart</div>}
		</div>
	)
}

const components: Required<TLUiComponents> = {
	TopPanel: HUD,
	Toolbar: GameToolbar,
	ContextMenu: null,
	ActionsMenu: null,
	HelpMenu: null,
	ZoomMenu: null,
	MainMenu: null,
	Minimap: null,
	StylePanel: null,
	PageMenu: null,
	NavigationPanel: null,
	KeyboardShortcutsDialog: null,
	QuickActions: null,
	HelperButtons: null,
	DebugPanel: null,
	DebugMenu: null,
	SharePanel: null,
	MenuPanel: null,
	CursorChatBubble: null,
	RichTextToolbar: null,
	ImageToolbar: null,
	VideoToolbar: null,
	Dialogs: null,
	Toasts: null,
	A11y: null,
	FollowingIndicator: null,
	PeopleMenu: null,
	PeopleMenuAvatar: null,
	PeopleMenuItem: null,
	PeopleMenuFacePile: null,
	UserPresenceEditor: null,
}

function onEditorMount(editor: Editor) {
	resetGameState()
	resetSpawnTimer()
	editor.zoomToBounds(new Box(-300, 0, 1700, 700), { immediate: true })
}

// Rapid clicks on enemies would otherwise create text shapes on double-click
const tldrawOptions = { createTextOnCanvasDoubleClick: false }

export default function TowerDefenseExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw
				overlayUtils={overlayUtils}
				components={components}
				options={tldrawOptions}
				onMount={onEditorMount}
			>
				<GameRunner />
			</Tldraw>
		</div>
	)
}
```

## enemy-config.ts

```ts
// Enemy archetypes. Each carries its own multipliers and visual identity so
// later waves can mix tougher/faster targets and the overlay layer has more
// to render than uniform circles.

export type EnemyType = 'grunt' | 'runner' | 'brute'

export interface EnemyConfig {
	label: string
	hpMultiplier: number
	speedMultiplier: number
	radius: number
	bountyMultiplier: number
	bodyColor: string
	ringColor: string
}

export const ENEMY_CONFIG: Record<EnemyType, EnemyConfig> = {
	grunt: {
		label: 'Grunt',
		hpMultiplier: 1,
		speedMultiplier: 1,
		radius: 18,
		bountyMultiplier: 1,
		bodyColor: '#c84',
		ringColor: '#000',
	},
	runner: {
		label: 'Runner',
		hpMultiplier: 0.55,
		speedMultiplier: 1.9,
		radius: 13,
		bountyMultiplier: 1.4,
		bodyColor: '#3aa',
		ringColor: '#055',
	},
	brute: {
		label: 'Brute',
		hpMultiplier: 3.2,
		speedMultiplier: 0.62,
		radius: 26,
		bountyMultiplier: 2.6,
		bodyColor: '#735',
		ringColor: '#220',
	},
}

// Weighted spawn picker: the longer the game runs, the more often runners and
// brutes appear. Returns an enemy type.
export function pickEnemyType(elapsedMs: number): EnemyType {
	const t = Math.min(1, elapsedMs / 60_000)
	const wGrunt = Math.max(0.2, 1 - t)
	const wRunner = 0.3 + 0.4 * t
	const wBrute = 0.05 + 0.5 * t
	const total = wGrunt + wRunner + wBrute
	const r = Math.random() * total
	if (r < wGrunt) return 'grunt'
	if (r < wGrunt + wRunner) return 'runner'
	return 'brute'
}
```

## game-loop.ts

```ts
import { Editor, TLGeoShape } from 'tldraw'
import { ENEMY_CONFIG, pickEnemyType } from './enemy-config'
import {
	Enemy,
	Explosion,
	Projectile,
	elapsedMs$,
	enemies$,
	explosions$,
	gainBounty,
	gameOver$,
	lives$,
	nextEnemyId,
	nextExplosionId,
	nextProjectileId,
	projectiles$,
	towerCooldowns,
} from './game-state'
import { PATH_LENGTH, getPositionAtDistance } from './path'
import { playFireSound } from './sounds'
import { getScaledStats, getTowerLevel, getTowerStats } from './tower-config'

const SPAWN_BASE_INTERVAL_MS = 1400
const SPAWN_RAMP_RATE = 0.00004 // shaves spawn interval over time
const SPAWN_INTERVAL_FLOOR_MS = 350
const ENEMY_BASE_HP = 50
const ENEMY_HP_RAMP = 0.025 // per second of game time
const ENEMY_BASE_SPEED = 65 // page units / sec
const ENEMY_BASE_BOUNTY = 5
const PROJECTILE_MAX_AGE_MS = 4000
const MAGIC_AOE_RADIUS = 60
// Magic projectiles slow enemies they hit for this long, scaling speed by
// MAGIC_SLOW_FACTOR until the timer expires.
const MAGIC_SLOW_DURATION_MS = 1500
const MAGIC_SLOW_FACTOR = 0.4

let lastSpawnAt = 0

export function resetSpawnTimer() {
	lastSpawnAt = 0
}

export function runGameTick(editor: Editor, dtMs: number) {
	if (gameOver$.get()) return
	const now = elapsedMs$.get() + dtMs
	elapsedMs$.set(now)
	const dt = dtMs / 1000

	maybeSpawn(now)
	moveEnemies(dt, now)
	fireTowers(editor, now)
	moveProjectiles(dt, dtMs)
	resolveHits()
	tickExplosions(dtMs)
	checkGameOver()
}

const EXPLOSION_DURATION_MS = 320

function spawnExplosion(x: number, y: number, radius: number) {
	const exp: Explosion = {
		id: nextExplosionId(),
		x,
		y,
		radius,
		ageMs: 0,
		maxAgeMs: EXPLOSION_DURATION_MS,
	}
	explosions$.update((list) => [...list, exp])
}

function tickExplosions(dtMs: number) {
	const list = explosions$.get()
	if (list.length === 0) return
	const next: Explosion[] = []
	for (const e of list) {
		const ageMs = e.ageMs + dtMs
		if (ageMs >= e.maxAgeMs) continue
		next.push({ ...e, ageMs })
	}
	explosions$.set(next)
}

function maybeSpawn(now: number) {
	const interval = Math.max(
		SPAWN_INTERVAL_FLOOR_MS,
		SPAWN_BASE_INTERVAL_MS - now * SPAWN_RAMP_RATE * SPAWN_BASE_INTERVAL_MS
	)
	if (now - lastSpawnAt < interval) return
	lastSpawnAt = now
	const type = pickEnemyType(now)
	const cfg = ENEMY_CONFIG[type]
	const hpScale = 1 + (now / 1000) * ENEMY_HP_RAMP
	const maxHp = Math.round(ENEMY_BASE_HP * hpScale * cfg.hpMultiplier)
	const bounty = Math.round((ENEMY_BASE_BOUNTY + maxHp / 10) * cfg.bountyMultiplier)
	const enemy: Enemy = {
		id: nextEnemyId(),
		type,
		distance: 0,
		hp: maxHp,
		maxHp,
		speed: (ENEMY_BASE_SPEED + Math.random() * 25) * cfg.speedMultiplier,
		radius: cfg.radius,
		bounty,
		slowedUntilMs: 0,
	}
	enemies$.update((list) => [...list, enemy])
}

function moveEnemies(dt: number, now: number) {
	const enemies = enemies$.get()
	if (enemies.length === 0) return
	const next: Enemy[] = []
	let leaks = 0
	for (const e of enemies) {
		const isSlowed = e.slowedUntilMs > now
		const speed = isSlowed ? e.speed * MAGIC_SLOW_FACTOR : e.speed
		const distance = e.distance + speed * dt
		if (distance >= PATH_LENGTH) {
			leaks++
			continue
		}
		next.push({ ...e, distance })
	}
	if (leaks > 0) lives$.update((l) => Math.max(0, l - leaks))
	enemies$.set(next)
}

function fireTowers(editor: Editor, now: number) {
	const enemies = enemies$.get()
	if (enemies.length === 0) return
	const shapes = editor.getCurrentPageShapes()
	for (const shape of shapes) {
		if (shape.type !== 'geo') continue
		const baseStats = getTowerStats((shape as TLGeoShape).props.geo)
		if (!baseStats) continue
		const stats = getScaledStats(baseStats, getTowerLevel(shape))
		const cooldown = towerCooldowns.get(shape.id)
		if (cooldown && now - cooldown.lastFiredAt < stats.fireRateMs) continue
		const bounds = editor.getShapePageBounds(shape.id)
		if (!bounds) continue
		const cx = bounds.center.x
		const cy = bounds.center.y
		// Pick the enemy closest to the end of the path within range.
		let target: Enemy | null = null
		let targetPos = { x: 0, y: 0 }
		let bestProgress = -1
		for (const enemy of enemies) {
			const pos = getPositionAtDistance(enemy.distance)
			const dx = pos.x - cx
			const dy = pos.y - cy
			if (dx * dx + dy * dy > stats.range * stats.range) continue
			if (enemy.distance > bestProgress) {
				bestProgress = enemy.distance
				target = enemy
				targetPos = pos
			}
		}
		if (!target) continue
		const dx = targetPos.x - cx
		const dy = targetPos.y - cy
		const dist = Math.hypot(dx, dy) || 1
		const projectile: Projectile = {
			id: nextProjectileId(),
			x: cx,
			y: cy,
			vx: (dx / dist) * stats.projectileSpeed,
			vy: (dy / dist) * stats.projectileSpeed,
			damage: stats.damage,
			kind: stats.projectileKind,
			targetEnemyId: target.id,
			ageMs: 0,
		}
		projectiles$.update((list) => [...list, projectile])
		towerCooldowns.set(shape.id, { lastFiredAt: now })
		playFireSound(stats.projectileKind)
	}
}

function moveProjectiles(dt: number, dtMs: number) {
	const list = projectiles$.get()
	if (list.length === 0) return
	const next: Projectile[] = []
	for (const p of list) {
		const ageMs = p.ageMs + dtMs
		if (ageMs > PROJECTILE_MAX_AGE_MS) continue
		next.push({ ...p, x: p.x + p.vx * dt, y: p.y + p.vy * dt, ageMs })
	}
	projectiles$.set(next)
}

function resolveHits() {
	const projectiles = projectiles$.get()
	if (projectiles.length === 0) return
	const enemies = enemies$.get()
	if (enemies.length === 0) {
		// Projectiles whose targets vanished can keep flying until expiry.
		return
	}
	const now = elapsedMs$.get()
	const enemyById = new Map<number, Enemy>()
	for (const e of enemies) enemyById.set(e.id, e)

	const survivingProjectiles: Projectile[] = []
	const damageByEnemyId = new Map<number, number>()
	const slowedEnemyIds = new Set<number>()
	for (const p of projectiles) {
		// Use current position of the original target if still alive; otherwise
		// look for any nearby enemy to make impacts feel responsive.
		const target = enemyById.get(p.targetEnemyId)
		let hit: Enemy | null = null
		if (target) {
			const pos = getPositionAtDistance(target.distance)
			if (Math.hypot(p.x - pos.x, p.y - pos.y) <= target.radius) hit = target
		}
		if (!hit) {
			for (const e of enemies) {
				const pos = getPositionAtDistance(e.distance)
				if (Math.hypot(p.x - pos.x, p.y - pos.y) <= e.radius) {
					hit = e
					break
				}
			}
		}
		if (hit) {
			if (p.kind === 'orb') {
				// Magic projectiles explode on impact: damage and slow every
				// enemy in the AOE, plus a transient ring overlay.
				spawnExplosion(p.x, p.y, MAGIC_AOE_RADIUS)
				for (const e of enemies) {
					const pos = getPositionAtDistance(e.distance)
					if (Math.hypot(p.x - pos.x, p.y - pos.y) <= MAGIC_AOE_RADIUS + e.radius) {
						damageByEnemyId.set(e.id, (damageByEnemyId.get(e.id) ?? 0) + p.damage)
						slowedEnemyIds.add(e.id)
					}
				}
			} else {
				damageByEnemyId.set(hit.id, (damageByEnemyId.get(hit.id) ?? 0) + p.damage)
			}
		} else {
			survivingProjectiles.push(p)
		}
	}
	if (survivingProjectiles.length !== projectiles.length) {
		projectiles$.set(survivingProjectiles)
	}
	if (damageByEnemyId.size === 0 && slowedEnemyIds.size === 0) return

	let bountyGained = 0
	const slowExpiry = now + MAGIC_SLOW_DURATION_MS
	const nextEnemies: Enemy[] = []
	for (const e of enemies) {
		const dmg = damageByEnemyId.get(e.id) ?? 0
		const slowed = slowedEnemyIds.has(e.id)
		if (dmg === 0 && !slowed) {
			nextEnemies.push(e)
			continue
		}
		const hp = e.hp - dmg
		if (hp <= 0) {
			bountyGained += e.bounty
			continue
		}
		nextEnemies.push({
			...e,
			hp,
			// Slows refresh — multiple magic hits keep the effect alive rather
			// than stacking duration.
			slowedUntilMs: slowed ? Math.max(e.slowedUntilMs, slowExpiry) : e.slowedUntilMs,
		})
	}
	enemies$.set(nextEnemies)
	if (bountyGained > 0) gainBounty(bountyGained)
}

function checkGameOver() {
	if (lives$.get() <= 0) gameOver$.set(true)
}
```

## game-state.ts

```ts
import { atom } from 'tldraw'
import { EnemyType } from './enemy-config'
import { ProjectileKind, TowerGeo } from './tower-config'

export interface Enemy {
	id: number
	type: EnemyType
	distance: number
	hp: number
	maxHp: number
	speed: number
	radius: number
	bounty: number
	// Absolute elapsedMs at which any active slow ends. 0 = not slowed.
	slowedUntilMs: number
}

export interface Projectile {
	id: number
	x: number
	y: number
	vx: number
	vy: number
	damage: number
	kind: ProjectileKind
	targetEnemyId: number
	ageMs: number
}

export interface TowerCooldown {
	lastFiredAt: number
}

export interface Explosion {
	id: number
	x: number
	y: number
	radius: number
	ageMs: number
	maxAgeMs: number
}

export const STARTING_GOLD = 100
export const STARTING_LIVES = 20

export const enemies$ = atom<Enemy[]>('enemies', [])
export const projectiles$ = atom<Projectile[]>('projectiles', [])
export const explosions$ = atom<Explosion[]>('explosions', [])
// Currently armed tower placement; non-null while the player has a tower
// "in hand" from the toolbar / keyboard.
export const placingTower$ = atom<TowerGeo | null>('placingTower', null)
export const score$ = atom('score', 0)
export const gold$ = atom('gold', STARTING_GOLD)
export const lives$ = atom('lives', STARTING_LIVES)
export const gameOver$ = atom('gameOver', false)
export const elapsedMs$ = atom('elapsedMs', 0)

// Tower cooldowns are keyed by shape id. Not an atom — only the game loop reads
// and writes them, and they don't need to drive overlay reactivity.
export const towerCooldowns = new Map<string, TowerCooldown>()

let _nextEnemyId = 1
export function nextEnemyId() {
	return _nextEnemyId++
}
let _nextProjId = 1
export function nextProjectileId() {
	return _nextProjId++
}
let _nextExplosionId = 1
export function nextExplosionId() {
	return _nextExplosionId++
}

export function resetGameState() {
	enemies$.set([])
	projectiles$.set([])
	explosions$.set([])
	score$.set(0)
	gold$.set(STARTING_GOLD)
	lives$.set(STARTING_LIVES)
	gameOver$.set(false)
	elapsedMs$.set(0)
	towerCooldowns.clear()
	_nextEnemyId = 1
	_nextProjId = 1
	_nextExplosionId = 1
}

export function gainBounty(amount: number) {
	score$.update((s) => s + amount)
	gold$.update((g) => g + amount)
}

export function applyDamage(enemyId: number, amount: number) {
	const enemies = enemies$.get()
	const next: Enemy[] = []
	let killed: Enemy | null = null
	for (const e of enemies) {
		if (e.id !== enemyId) {
			next.push(e)
			continue
		}
		const hp = e.hp - amount
		if (hp <= 0) {
			killed = e
		} else {
			next.push({ ...e, hp })
		}
	}
	if (killed) gainBounty(killed.bounty)
	enemies$.set(next)
}
```

## path.ts

```ts
// Hardcoded enemy path. Page-space waypoints; enemies move along it from start
// to end. Kept simple so the OverlayUtil mechanics, not the routing, are the
// point of the example.

export interface Waypoint {
	x: number
	y: number
}

export const PATH: Waypoint[] = [
	{ x: -200, y: 200 },
	{ x: 200, y: 200 },
	{ x: 200, y: 500 },
	{ x: 600, y: 500 },
	{ x: 600, y: 100 },
	{ x: 1000, y: 100 },
	{ x: 1000, y: 600 },
	{ x: 1400, y: 600 },
]

const SEGMENT_LENGTHS: number[] = []
let TOTAL_LENGTH = 0
for (let i = 1; i < PATH.length; i++) {
	const dx = PATH[i].x - PATH[i - 1].x
	const dy = PATH[i].y - PATH[i - 1].y
	const len = Math.hypot(dx, dy)
	SEGMENT_LENGTHS.push(len)
	TOTAL_LENGTH += len
}

export const PATH_LENGTH = TOTAL_LENGTH

export interface PointOnPath {
	x: number
	y: number
	angle: number
}

export function getPositionAtDistance(distance: number): PointOnPath {
	if (distance <= 0) {
		const a = PATH[0]
		const b = PATH[1]
		return { x: a.x, y: a.y, angle: Math.atan2(b.y - a.y, b.x - a.x) }
	}
	let remaining = distance
	for (let i = 0; i < SEGMENT_LENGTHS.length; i++) {
		const segLen = SEGMENT_LENGTHS[i]
		if (remaining <= segLen) {
			const a = PATH[i]
			const b = PATH[i + 1]
			const t = remaining / segLen
			return {
				x: a.x + (b.x - a.x) * t,
				y: a.y + (b.y - a.y) * t,
				angle: Math.atan2(b.y - a.y, b.x - a.x),
			}
		}
		remaining -= segLen
	}
	const last = PATH[PATH.length - 1]
	const prev = PATH[PATH.length - 2]
	return { x: last.x, y: last.y, angle: Math.atan2(last.y - prev.y, last.x - prev.x) }
}
```

## sounds.ts

```ts
import { ProjectileKind } from './tower-config'

// We synthesize fire sounds with Web Audio API rather than loading assets so
// the example stays self-contained. The AudioContext is created lazily on the
// first call to side-step browser autoplay restrictions — by then the user has
// already clicked something to place a tower.

let ctx: AudioContext | null = null
let lastPlayedAt = 0
const MIN_INTERVAL_MS = 25 // hard cap to stop a wall of overlapping shots

function getCtx(): AudioContext | null {
	if (ctx) return ctx
	try {
		const Ctor =
			window.AudioContext ??
			(window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext
		if (!Ctor) return null
		ctx = new Ctor()
		return ctx
	} catch {
		return null
	}
}

interface ToneSpec {
	type: OscillatorType
	startFreq: number
	endFreq: number
	durationMs: number
	gain: number
}

const TONES: Record<ProjectileKind, ToneSpec> = {
	arrow: { type: 'sawtooth', startFreq: 760, endFreq: 480, durationMs: 90, gain: 0.07 },
	rock: { type: 'square', startFreq: 160, endFreq: 70, durationMs: 180, gain: 0.1 },
	orb: { type: 'sine', startFreq: 880, endFreq: 320, durationMs: 220, gain: 0.09 },
}

export function playUpgradeSound() {
	const c = getCtx()
	if (!c) return
	if (c.state === 'suspended') c.resume().catch(() => {})

	// Two quick ascending sine notes — a small "level up" chime.
	const t0 = c.currentTime
	const notes = [
		{ freq: 660, start: 0, durMs: 120 },
		{ freq: 990, start: 90, durMs: 180 },
	]
	for (const n of notes) {
		const osc = c.createOscillator()
		osc.type = 'sine'
		const gain = c.createGain()
		const startAt = t0 + n.start / 1000
		const stopAt = startAt + n.durMs / 1000
		osc.frequency.setValueAtTime(n.freq, startAt)
		gain.gain.setValueAtTime(0.001, startAt)
		gain.gain.exponentialRampToValueAtTime(0.12, startAt + 0.01)
		gain.gain.exponentialRampToValueAtTime(0.0001, stopAt)
		osc.connect(gain).connect(c.destination)
		osc.start(startAt)
		osc.stop(stopAt + 0.02)
	}
}

export function playFireSound(kind: ProjectileKind) {
	const c = getCtx()
	if (!c) return
	if (c.state === 'suspended') c.resume().catch(() => {})

	const now = performance.now()
	if (now - lastPlayedAt < MIN_INTERVAL_MS) return
	lastPlayedAt = now

	const spec = TONES[kind]
	const t0 = c.currentTime
	const t1 = t0 + spec.durationMs / 1000

	const osc = c.createOscillator()
	osc.type = spec.type
	osc.frequency.setValueAtTime(spec.startFreq, t0)
	osc.frequency.exponentialRampToValueAtTime(Math.max(20, spec.endFreq), t1)

	const gain = c.createGain()
	gain.gain.setValueAtTime(spec.gain, t0)
	gain.gain.exponentialRampToValueAtTime(0.0001, t1)

	osc.connect(gain).connect(c.destination)
	osc.start(t0)
	osc.stop(t1 + 0.02)
}
```

## tower-config.ts

```ts
// Maps geo shape variants to tower stats. Only these three geo types act as
// towers; other geo shapes the user draws are ignored by the game loop so the
// editor stays usable.

import { TLShape } from 'tldraw'

export type ProjectileKind = 'arrow' | 'rock' | 'orb'

export const MAX_TOWER_LEVEL = 4

export type TowerGeo = 'triangle' | 'rectangle' | 'ellipse'
export const TOWER_GEOS: TowerGeo[] = ['triangle', 'rectangle', 'ellipse']
export const TOWER_PLACEMENT_SIZE = 60

export interface TowerStats {
	label: string
	range: number
	fireRateMs: number
	damage: number
	projectileSpeed: number
	projectileKind: ProjectileKind
	cost: number
}

// Cost is roughly proportional to overall strength (range × damage / fireRate).
// Starting gold (see game-state) is calibrated to afford one Archer immediately
// and earn the others through kills.
export const TOWER_STATS_BY_GEO: Record<string, TowerStats> = {
	triangle: {
		label: 'Archer',
		range: 220,
		fireRateMs: 350,
		damage: 8,
		projectileSpeed: 700,
		projectileKind: 'arrow',
		cost: 50,
	},
	rectangle: {
		label: 'Cannon',
		range: 160,
		fireRateMs: 1100,
		damage: 30,
		projectileSpeed: 380,
		projectileKind: 'rock',
		cost: 120,
	},
	ellipse: {
		label: 'Magic',
		range: 190,
		fireRateMs: 600,
		damage: 14,
		projectileSpeed: 520,
		projectileKind: 'orb',
		cost: 80,
	},
}

export function getTowerStats(geo: string | undefined): TowerStats | null {
	if (!geo) return null
	return TOWER_STATS_BY_GEO[geo] ?? null
}

export function getTowerLevel(shape: TLShape): number {
	const lvl = shape.meta?.towerLevel
	return typeof lvl === 'number' && lvl >= 1 ? Math.min(MAX_TOWER_LEVEL, lvl) : 1
}

// Each upgrade adds 60% of base cost per level: L1→2 = 60%, L2→3 = 120%, L3→4 = 180%.
export function getUpgradeCost(baseCost: number, currentLevel: number): number {
	if (currentLevel >= MAX_TOWER_LEVEL) return 0
	return Math.ceil(baseCost * 0.6 * currentLevel)
}

// Visual cue for tower level — also makes the level readable at a glance.
export function levelColor(level: number): 'blue' | 'violet' | 'red' | 'orange' {
	if (level >= 4) return 'red'
	if (level === 3) return 'violet'
	if (level === 2) return 'blue'
	return 'orange'
}

// Damage and range grow with level; fire rate shortens. Level 1 returns base.
export function getScaledStats(stats: TowerStats, level: number): TowerStats {
	const k = Math.max(0, level - 1)
	if (k === 0) return stats
	return {
		...stats,
		damage: Math.round(stats.damage * Math.pow(1.4, k)),
		range: Math.round(stats.range * Math.pow(1.06, k)),
		fireRateMs: Math.round(stats.fireRateMs * Math.pow(0.9, k)),
	}
}
```

## tower-defense.css

```css
.td-hud {
	display: flex;
	flex-direction: column;
	gap: 4px;
	padding: 8px 12px;
	background: var(--color-panel);
	border-radius: 8px;
	box-shadow: var(--shadow-2);
	font-size: 12px;
	color: var(--color-text);
	max-width: 720px;
	pointer-events: auto;
}

.td-hud__row {
	display: flex;
	gap: 16px;
	align-items: center;
	flex-wrap: wrap;
}

.td-hud__row strong {
	font-variant-numeric: tabular-nums;
	font-weight: 600;
}

.td-hud__btn {
	margin-left: auto;
	padding: 4px 10px;
	border: 1px solid var(--color-divider);
	border-radius: 6px;
	background: var(--color-low);
	color: var(--color-text);
	cursor: pointer;
	font: inherit;
}

.td-hud__btn:hover {
	background: var(--color-hint);
}

.td-hud__hint {
	color: var(--color-text-1);
	font-size: 11px;
	opacity: 0.85;
}

.td-hud__hint code,
.td-hud__hint kbd {
	display: inline-block;
	padding: 0 4px;
	border-radius: 3px;
	background: var(--color-low);
	font: inherit;
	font-size: 10px;
}

.td-hud__gameover {
	color: #d33;
	font-weight: 600;
}

.td-toolbar {
	display: flex;
	gap: 6px;
	padding: 6px;
	background: var(--color-panel);
	border-radius: 10px;
	box-shadow: var(--shadow-2);
	pointer-events: auto;
}

.td-toolbar__btn {
	display: flex;
	flex-direction: column;
	align-items: center;
	gap: 2px;
	min-width: 56px;
	padding: 6px 8px;
	border: 1px solid transparent;
	border-radius: 8px;
	background: transparent;
	color: var(--color-text);
	cursor: pointer;
	font-size: 11px;
	font: inherit;
}

.td-toolbar__btn:hover {
	background: var(--color-hint);
}

.td-toolbar__btn.is-active {
	border-color: var(--color-selected);
	background: var(--color-selected-contrast);
	color: var(--color-selected);
}

.td-toolbar__btn.is-disabled,
.td-toolbar__btn:disabled {
	opacity: 0.4;
	cursor: not-allowed;
}

.td-toolbar__btn.is-disabled:hover,
.td-toolbar__btn:disabled:hover {
	background: transparent;
}

.td-toolbar__label {
	font-size: 10px;
	letter-spacing: 0.02em;
}

.td-toolbar__cost {
	font-size: 10px;
	color: var(--color-text-1);
	font-variant-numeric: tabular-nums;
}

.td-toolbar__cost kbd {
	display: inline-block;
	padding: 0 4px;
	min-width: 14px;
	text-align: center;
	border: 1px solid var(--color-divider);
	border-radius: 3px;
	background: var(--color-low);
	font: inherit;
	font-size: 9px;
}
```

## EnemyOverlayUtil.ts

```ts
import { Circle2d, Geometry2d, OverlayUtil, TLCursorType, TLOverlay } from 'tldraw'
import { ENEMY_CONFIG, EnemyType } from '../enemy-config'
import { applyDamage, elapsedMs$, enemies$ } from '../game-state'
import { getPositionAtDistance } from '../path'

interface TLEnemyOverlay extends TLOverlay {
	props: {
		enemyId: number
		type: EnemyType
		x: number
		y: number
		hp: number
		maxHp: number
		radius: number
		slowed: boolean
	}
}

const CLICK_DAMAGE = 5

export class EnemyOverlayUtil extends OverlayUtil<TLEnemyOverlay> {
	static override type = 'td-enemy'
	override options = { zIndex: 200 }

	override isActive(): boolean {
		return enemies$.get().length > 0
	}

	override getOverlays(): TLEnemyOverlay[] {
		const now = elapsedMs$.get()
		return enemies$.get().map((e) => {
			const pos = getPositionAtDistance(e.distance)
			return {
				id: `td-enemy:${e.id}`,
				type: 'td-enemy',
				props: {
					enemyId: e.id,
					type: e.type,
					x: pos.x,
					y: pos.y,
					hp: e.hp,
					maxHp: e.maxHp,
					radius: e.radius,
					slowed: e.slowedUntilMs > now,
				},
			}
		})
	}

	override getGeometry(overlay: TLEnemyOverlay): Geometry2d {
		const { x, y, radius } = overlay.props
		// Circle2d's x/y is the bounding-box top-left, so center = (x+radius, y+radius).
		return new Circle2d({ x: x - radius, y: y - radius, radius, isFilled: true })
	}

	override getCursor(): TLCursorType {
		return 'cross'
	}

	override onPointerDown(overlay: TLEnemyOverlay): boolean {
		applyDamage(overlay.props.enemyId, CLICK_DAMAGE)
		// Returning truthy keeps the editor from starting a brush/select drag on
		// what is effectively a game click.
		return true
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLEnemyOverlay[]): void {
		const zoom = this.editor.getZoomLevel()
		const isDark = this.editor.getColorMode() === 'dark'
		const hoveredId = this.editor.overlays.getHoveredOverlayId()
		for (const overlay of overlays) {
			const { x, y, hp, maxHp, radius, type, slowed } = overlay.props
			const cfg = ENEMY_CONFIG[type]
			const t = Math.max(0, Math.min(1, hp / maxHp))

			ctx.save()
			ctx.beginPath()
			ctx.arc(x, y, radius, 0, Math.PI * 2)
			ctx.fillStyle = cfg.bodyColor
			ctx.fill()
			ctx.lineWidth = 2 / zoom
			ctx.strokeStyle = cfg.ringColor
			ctx.stroke()
			// Inner ring shrinks/dims with HP so wounded enemies read at a glance.
			ctx.beginPath()
			ctx.arc(x, y, radius * 0.55, 0, Math.PI * 2)
			ctx.fillStyle = `rgba(0, 0, 0, ${0.15 + 0.45 * (1 - t)})`
			ctx.fill()

			// Frosty halo when slowed by Magic.
			if (slowed) {
				ctx.beginPath()
				ctx.arc(x, y, radius + 4 / zoom, 0, Math.PI * 2)
				ctx.fillStyle = 'rgba(140, 200, 255, 0.35)'
				ctx.fill()
				ctx.lineWidth = 1.5 / zoom
				ctx.strokeStyle = 'rgba(180, 220, 255, 0.9)'
				ctx.setLineDash([4 / zoom, 3 / zoom])
				ctx.stroke()
				ctx.setLineDash([])
			}

			// HP bar above the enemy.
			const barW = radius * 2
			const barH = 5 / zoom
			const barX = x - radius
			const barY = y - radius - barH - 4 / zoom
			ctx.fillStyle = isDark ? 'rgba(60,60,80,0.85)' : 'rgba(220,220,230,0.9)'
			ctx.fillRect(barX, barY, barW, barH)
			ctx.fillStyle = '#3bce5a'
			ctx.fillRect(barX, barY, barW * t, barH)
			ctx.lineWidth = 1 / zoom
			ctx.strokeStyle = isDark ? '#000' : '#444'
			ctx.strokeRect(barX, barY, barW, barH)

			// HP readout above the bar when this enemy is hovered.
			if (overlay.id === hoveredId) {
				const text = `${cfg.label} · ${Math.max(0, Math.ceil(hp))} / ${maxHp}`
				const fontPx = 12 / zoom
				ctx.font = `600 ${fontPx}px sans-serif`
				ctx.textAlign = 'center'
				ctx.textBaseline = 'bottom'
				const textY = barY - 4 / zoom
				const metrics = ctx.measureText(text)
				const padX = 6 / zoom
				const padY = 3 / zoom
				const boxW = metrics.width + padX * 2
				const boxH = fontPx + padY * 2
				const boxX = x - boxW / 2
				const boxY = textY - boxH + padY
				ctx.fillStyle = isDark ? 'rgba(20,20,28,0.92)' : 'rgba(255,255,255,0.95)'
				ctx.fillRect(boxX, boxY, boxW, boxH)
				ctx.lineWidth = 1 / zoom
				ctx.strokeStyle = isDark ? '#fff' : '#000'
				ctx.strokeRect(boxX, boxY, boxW, boxH)
				ctx.fillStyle = isDark ? '#fff' : '#000'
				ctx.fillText(text, x, textY)
			}

			ctx.restore()
		}
	}
}
```

## ExplosionOverlayUtil.ts

```ts
import { OverlayUtil, TLOverlay } from 'tldraw'
import { explosions$ } from '../game-state'

interface TLExplosionOverlay extends TLOverlay {
	props: {
		x: number
		y: number
		radius: number
		t: number // 0 = just spawned, 1 = about to expire
	}
}

export class ExplosionOverlayUtil extends OverlayUtil<TLExplosionOverlay> {
	static override type = 'td-explosion'
	override options = { zIndex: 230 }

	override isActive(): boolean {
		return explosions$.get().length > 0
	}

	override getOverlays(): TLExplosionOverlay[] {
		return explosions$.get().map((e) => ({
			id: `td-explosion:${e.id}`,
			type: 'td-explosion',
			props: {
				x: e.x,
				y: e.y,
				radius: e.radius,
				t: Math.min(1, e.ageMs / e.maxAgeMs),
			},
		}))
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLExplosionOverlay[]): void {
		const zoom = this.editor.getZoomLevel()
		ctx.save()
		for (const overlay of overlays) {
			const { x, y, radius, t } = overlay.props
			// Expanding ring + fading filled core.
			const ringR = radius * (0.4 + 0.6 * t)
			const alpha = 1 - t

			ctx.globalAlpha = alpha * 0.45
			const grd = ctx.createRadialGradient(x, y, 1, x, y, radius)
			grd.addColorStop(0, 'rgba(180, 220, 255, 1)')
			grd.addColorStop(0.6, 'rgba(120, 160, 240, 0.5)')
			grd.addColorStop(1, 'rgba(80, 120, 220, 0)')
			ctx.fillStyle = grd
			ctx.beginPath()
			ctx.arc(x, y, radius, 0, Math.PI * 2)
			ctx.fill()

			ctx.globalAlpha = alpha
			ctx.lineWidth = 3 / zoom
			ctx.strokeStyle = 'rgba(180, 220, 255, 1)'
			ctx.beginPath()
			ctx.arc(x, y, ringR, 0, Math.PI * 2)
			ctx.stroke()
		}
		ctx.restore()
	}
}
```

## PathOverlayUtil.ts

```ts
import { OverlayUtil, TLOverlay } from 'tldraw'
import { PATH } from '../path'

interface TLPathOverlay extends TLOverlay {
	props: Record<string, never>
}

export class PathOverlayUtil extends OverlayUtil<TLPathOverlay> {
	static override type = 'td-path'
	override options = { zIndex: 50 }

	override isActive(): boolean {
		return true
	}

	override getOverlays(): TLPathOverlay[] {
		return [{ id: 'td-path:main', type: 'td-path', props: {} }]
	}

	override render(ctx: CanvasRenderingContext2D): void {
		const zoom = this.editor.getZoomLevel()
		const isDark = this.editor.getColorMode() === 'dark'

		ctx.save()
		ctx.lineCap = 'round'
		ctx.lineJoin = 'round'

		// Wide soft track
		ctx.lineWidth = 38
		ctx.strokeStyle = isDark ? 'rgba(80, 80, 110, 0.45)' : 'rgba(160, 170, 200, 0.45)'
		ctx.beginPath()
		ctx.moveTo(PATH[0].x, PATH[0].y)
		for (let i = 1; i < PATH.length; i++) ctx.lineTo(PATH[i].x, PATH[i].y)
		ctx.stroke()

		// Center dashed line
		ctx.lineWidth = 2 / zoom
		ctx.setLineDash([10 / zoom, 10 / zoom])
		ctx.strokeStyle = isDark ? 'rgba(220, 220, 240, 0.7)' : 'rgba(60, 60, 80, 0.7)'
		ctx.beginPath()
		ctx.moveTo(PATH[0].x, PATH[0].y)
		for (let i = 1; i < PATH.length; i++) ctx.lineTo(PATH[i].x, PATH[i].y)
		ctx.stroke()

		ctx.restore()
	}
}
```

## PlacementPreviewOverlayUtil.ts

```ts
import { Circle2d, Geometry2d, OverlayUtil, TLCursorType, TLOverlay, createShapeId } from 'tldraw'
import { gold$, placingTower$ } from '../game-state'
import { TOWER_PLACEMENT_SIZE, TOWER_STATS_BY_GEO, TowerGeo, getTowerStats } from '../tower-config'

interface TLPlacementPreviewOverlay extends TLOverlay {
	props: {
		geo: TowerGeo
		x: number
		y: number
		range: number
	}
}

export class PlacementPreviewOverlayUtil extends OverlayUtil<TLPlacementPreviewOverlay> {
	static override type = 'td-placement-preview'
	override options = { zIndex: 150 }

	override isActive(): boolean {
		const placing = placingTower$.get()
		if (!placing) return false
		const stats = TOWER_STATS_BY_GEO[placing]
		return gold$.get() >= stats.cost
	}

	override getOverlays(): TLPlacementPreviewOverlay[] {
		const geo = placingTower$.get()
		if (!geo) return []
		const stats = getTowerStats(geo)
		if (!stats) return []
		const { x, y } = this.editor.inputs.getCurrentPagePoint()
		return [
			{
				id: 'td-placement-preview:main',
				type: 'td-placement-preview',
				props: { geo, x, y, range: stats.range },
			},
		]
	}

	// The preview tracks the cursor, so a click at the cursor always lands inside
	// this circle — that's how we route placement through the overlay system
	// instead of bolting on a capture-phase canvas listener.
	override getGeometry(overlay: TLPlacementPreviewOverlay): Geometry2d {
		const { x, y } = overlay.props
		const r = TOWER_PLACEMENT_SIZE / 2
		return new Circle2d({ x: x - r, y: y - r, radius: r, isFilled: true })
	}

	override getCursor(): TLCursorType {
		return 'cross'
	}

	override onPointerDown(overlay: TLPlacementPreviewOverlay): boolean {
		const { geo, x, y } = overlay.props
		const stats = TOWER_STATS_BY_GEO[geo]
		if (gold$.get() < stats.cost) return true
		this.editor.createShape({
			id: createShapeId(),
			type: 'geo',
			x: x - TOWER_PLACEMENT_SIZE / 2,
			y: y - TOWER_PLACEMENT_SIZE / 2,
			isLocked: true,
			props: { geo, w: TOWER_PLACEMENT_SIZE, h: TOWER_PLACEMENT_SIZE },
		})
		gold$.update((g) => g - stats.cost)
		placingTower$.set(null)
		return true
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLPlacementPreviewOverlay[]): void {
		const overlay = overlays[0]
		if (!overlay) return
		const { geo, x, y, range } = overlay.props
		const zoom = this.editor.getZoomLevel()
		const colors = this.editor.getCurrentTheme().colors[this.editor.getColorMode()]

		ctx.save()

		// Range ring + soft fill.
		ctx.lineWidth = 2 / zoom
		ctx.setLineDash([8 / zoom, 6 / zoom])
		ctx.strokeStyle = colors.selectionStroke
		ctx.fillStyle = colors.selectionFill
		ctx.globalAlpha = 0.35
		ctx.beginPath()
		ctx.arc(x, y, range, 0, Math.PI * 2)
		ctx.fill()
		ctx.globalAlpha = 1
		ctx.stroke()
		ctx.setLineDash([])

		// Ghost shape silhouette at the would-be placement.
		const half = TOWER_PLACEMENT_SIZE / 2
		ctx.globalAlpha = 0.55
		ctx.lineWidth = 2 / zoom
		ctx.strokeStyle = colors.selectionStroke
		ctx.fillStyle = colors.selectionFill

		ctx.beginPath()
		if (geo === 'rectangle') {
			ctx.rect(x - half, y - half, TOWER_PLACEMENT_SIZE, TOWER_PLACEMENT_SIZE)
		} else if (geo === 'ellipse') {
			ctx.ellipse(x, y, half, half, 0, 0, Math.PI * 2)
		} else {
			// Triangle — match how the geo shape renders: top-center, bottom-left, bottom-right.
			ctx.moveTo(x, y - half)
			ctx.lineTo(x + half, y + half)
			ctx.lineTo(x - half, y + half)
			ctx.closePath()
		}
		ctx.fill()
		ctx.stroke()

		ctx.restore()
	}
}
```

## ProjectileOverlayUtil.ts

```ts
import { OverlayUtil, TLOverlay } from 'tldraw'
import { projectiles$ } from '../game-state'
import { ProjectileKind } from '../tower-config'

interface TLProjectileOverlay extends TLOverlay {
	props: {
		x: number
		y: number
		angle: number
		kind: ProjectileKind
	}
}

export class ProjectileOverlayUtil extends OverlayUtil<TLProjectileOverlay> {
	static override type = 'td-projectile'
	override options = { zIndex: 250 }

	override isActive(): boolean {
		return projectiles$.get().length > 0
	}

	override getOverlays(): TLProjectileOverlay[] {
		return projectiles$.get().map((p) => ({
			id: `td-projectile:${p.id}`,
			type: 'td-projectile',
			props: {
				x: p.x,
				y: p.y,
				angle: Math.atan2(p.vy, p.vx),
				kind: p.kind,
			},
		}))
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLProjectileOverlay[]): void {
		const zoom = this.editor.getZoomLevel()
		const isDark = this.editor.getColorMode() === 'dark'
		for (const overlay of overlays) {
			const { x, y, angle, kind } = overlay.props
			ctx.save()
			ctx.translate(x, y)
			ctx.rotate(angle)
			switch (kind) {
				case 'arrow':
					ctx.lineWidth = 2 / zoom
					ctx.strokeStyle = isDark ? '#ddd' : '#222'
					ctx.beginPath()
					ctx.moveTo(-10, 0)
					ctx.lineTo(8, 0)
					ctx.stroke()
					ctx.beginPath()
					ctx.moveTo(8, 0)
					ctx.lineTo(2, -3)
					ctx.lineTo(2, 3)
					ctx.closePath()
					ctx.fillStyle = isDark ? '#ddd' : '#222'
					ctx.fill()
					break
				case 'rock':
					ctx.beginPath()
					ctx.arc(0, 0, 6, 0, Math.PI * 2)
					ctx.fillStyle = '#806040'
					ctx.fill()
					ctx.lineWidth = 1.5 / zoom
					ctx.strokeStyle = '#3a2a1a'
					ctx.stroke()
					break
				case 'orb': {
					const grd = ctx.createRadialGradient(0, 0, 1, 0, 0, 8)
					grd.addColorStop(0, 'rgba(180, 220, 255, 1)')
					grd.addColorStop(1, 'rgba(80, 120, 220, 0.1)')
					ctx.fillStyle = grd
					ctx.beginPath()
					ctx.arc(0, 0, 8, 0, Math.PI * 2)
					ctx.fill()
					break
				}
			}
			ctx.restore()
		}
	}
}
```

## TowerRangeOverlayUtil.ts

```ts
import { computed, OverlayUtil, TLGeoShape, TLOverlay } from 'tldraw'
import { getScaledStats, getTowerLevel, getTowerStats } from '../tower-config'

interface TLTowerRangeOverlay extends TLOverlay {
	props: {
		shapeId: string
		cx: number
		cy: number
		range: number
	}
}

export class TowerRangeOverlayUtil extends OverlayUtil<TLTowerRangeOverlay> {
	static override type = 'td-tower-range'
	override options = { zIndex: 100 }

	// Not `editor.getHoveredShape()`: unfilled geo shapes are hollow to hit-testing, so hovering
	// their interior wouldn't count. Checking bounds directly also lets the range show for
	// locked shapes. Memoised so isActive() and getOverlays() share one walk per tick.
	private _hoveredTowers = computed('td-tower-range:hovered', (): TLTowerRangeOverlay[] => {
		const point = this.editor.inputs.getCurrentPagePoint()
		const result: TLTowerRangeOverlay[] = []
		for (const shape of this.editor.getCurrentPageShapes()) {
			if (shape.type !== 'geo') continue
			const baseStats = getTowerStats((shape as TLGeoShape).props.geo)
			if (!baseStats) continue
			const stats = getScaledStats(baseStats, getTowerLevel(shape))
			const bounds = this.editor.getShapePageBounds(shape.id)
			if (!bounds) continue
			// Placed towers are locked and only show range on hover; an unlocked tower shape
			// (e.g. one being drawn by hand) always shows it
			const isPlacing = !shape.isLocked
			if (!isPlacing && !bounds.containsPoint(point)) continue
			result.push({
				id: `td-tower-range:${shape.id}`,
				type: 'td-tower-range',
				props: {
					shapeId: shape.id,
					cx: bounds.center.x,
					cy: bounds.center.y,
					range: stats.range,
				},
			})
		}
		return result
	})

	override isActive(): boolean {
		return this._hoveredTowers.get().length > 0
	}

	override getOverlays(): TLTowerRangeOverlay[] {
		return this._hoveredTowers.get()
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLTowerRangeOverlay[]): void {
		const zoom = this.editor.getZoomLevel()
		const colors = this.editor.getCurrentTheme().colors[this.editor.getColorMode()]

		ctx.save()
		ctx.lineWidth = 2 / zoom
		ctx.setLineDash([8 / zoom, 6 / zoom])
		ctx.strokeStyle = colors.selectionStroke
		ctx.fillStyle = colors.selectionFill
		for (const overlay of overlays) {
			const { cx, cy, range } = overlay.props
			ctx.globalAlpha = 0.4
			ctx.beginPath()
			ctx.arc(cx, cy, range, 0, Math.PI * 2)
			ctx.fill()
			ctx.globalAlpha = 1
			ctx.stroke()
		}
		ctx.restore()
	}
}
```

## UpgradeButtonOverlayUtil.ts

```ts
import {
	Box,
	Circle2d,
	Geometry2d,
	OverlayUtil,
	TLCursorType,
	TLGeoShape,
	TLOverlay,
	TLShapeId,
	computed,
} from 'tldraw'
import { gold$ } from '../game-state'
import { playUpgradeSound } from '../sounds'
import {
	MAX_TOWER_LEVEL,
	getTowerLevel,
	getTowerStats,
	getUpgradeCost,
	levelColor,
} from '../tower-config'

interface TLUpgradeBtnOverlay extends TLOverlay {
	props: {
		shapeId: TLShapeId
		x: number
		y: number
		radius: number
		level: number
		upgradeCost: number
		canAfford: boolean
	}
}

const BTN_RADIUS = 14

interface UpgradeCandidate {
	shapeId: TLShapeId
	cx: number
	cy: number
	bounds: Box
	level: number
	upgradeCost: number
}

export class UpgradeButtonOverlayUtil extends OverlayUtil<TLUpgradeBtnOverlay> {
	static override type = 'td-upgrade-btn'
	override options = { zIndex: 260 }

	// Walk the page shapes once per shape/bounds change. Filtering by pointer
	// happens in getOverlays(), so a mousemove storm only re-runs the cheap
	// pointer filter — not the full shape scan and bounds resolution.
	private _candidates = computed('td-upgrade-btn:candidates', (): UpgradeCandidate[] => {
		const result: UpgradeCandidate[] = []
		for (const shape of this.editor.getCurrentPageShapes()) {
			if (shape.type !== 'geo' || !shape.isLocked) continue
			const stats = getTowerStats((shape as TLGeoShape).props.geo)
			if (!stats) continue
			const level = getTowerLevel(shape)
			if (level >= MAX_TOWER_LEVEL) continue
			const bounds = this.editor.getShapePageBounds(shape.id)
			if (!bounds) continue
			result.push({
				shapeId: shape.id,
				cx: bounds.center.x,
				cy: bounds.center.y,
				bounds,
				level,
				upgradeCost: getUpgradeCost(stats.cost, level),
			})
		}
		return result
	})

	override isActive(): boolean {
		return this._candidates.get().length > 0
	}

	override getOverlays(): TLUpgradeBtnOverlay[] {
		const candidates = this._candidates.get()
		if (candidates.length === 0) return []
		const gold = gold$.get()
		const point = this.editor.inputs.getCurrentPagePoint()
		const result: TLUpgradeBtnOverlay[] = []
		for (const c of candidates) {
			// Show only while the pointer is over the tower or the button itself —
			// the button stays accessible after the cursor moves up onto it.
			const overShape = c.bounds.containsPoint(point)
			const dx = point.x - c.cx
			const dy = point.y - c.cy
			const overButton = dx * dx + dy * dy <= BTN_RADIUS * BTN_RADIUS
			if (!overShape && !overButton) continue
			result.push({
				id: `td-upgrade-btn:${c.shapeId}`,
				type: 'td-upgrade-btn',
				props: {
					shapeId: c.shapeId,
					x: c.cx,
					y: c.cy,
					radius: BTN_RADIUS,
					level: c.level,
					upgradeCost: c.upgradeCost,
					canAfford: gold >= c.upgradeCost,
				},
			})
		}
		return result
	}

	override getGeometry(overlay: TLUpgradeBtnOverlay): Geometry2d {
		const { x, y, radius } = overlay.props
		return new Circle2d({ x: x - radius, y: y - radius, radius, isFilled: true })
	}

	override getCursor(): TLCursorType {
		return 'pointer'
	}

	override onPointerDown(overlay: TLUpgradeBtnOverlay): boolean {
		const { shapeId, upgradeCost, level, canAfford } = overlay.props
		if (!canAfford) return true
		const shape = this.editor.getShape(shapeId)
		if (!shape) return true
		const nextLevel = level + 1
		gold$.update((g) => g - upgradeCost)
		// updateShape silently skips locked shapes unless run with ignoreShapeLock;
		// without this the meta + props don't persist on placed (locked) towers.
		this.editor.run(
			() => {
				this.editor.updateShape({
					id: shapeId,
					type: 'geo',
					meta: { ...shape.meta, towerLevel: nextLevel },
					props: { fill: 'solid', color: levelColor(nextLevel) },
				})
			},
			{ ignoreShapeLock: true }
		)
		playUpgradeSound()
		return true
	}

	override render(ctx: CanvasRenderingContext2D, overlays: TLUpgradeBtnOverlay[]): void {
		const zoom = this.editor.getZoomLevel()
		const isDark = this.editor.getColorMode() === 'dark'
		for (const overlay of overlays) {
			const { x, y, radius, level, upgradeCost, canAfford } = overlay.props
			ctx.save()
			ctx.beginPath()
			ctx.arc(x, y, radius, 0, Math.PI * 2)
			ctx.fillStyle = canAfford ? '#3aa56a' : isDark ? '#444' : '#aaa'
			ctx.fill()
			ctx.lineWidth = 2 / zoom
			ctx.strokeStyle = isDark ? '#000' : '#222'
			ctx.stroke()

			// Plus sign.
			ctx.lineWidth = 3 / zoom
			ctx.lineCap = 'round'
			ctx.strokeStyle = '#fff'
			const arm = radius * 0.5
			ctx.beginPath()
			ctx.moveTo(x - arm, y)
			ctx.lineTo(x + arm, y)
			ctx.moveTo(x, y - arm)
			ctx.lineTo(x, y + arm)
			ctx.stroke()

			// Cost + level chip below the button.
			const fontPx = 11 / zoom
			ctx.font = `600 ${fontPx}px sans-serif`
			ctx.textAlign = 'center'
			ctx.textBaseline = 'top'
			const text = `L${level}→${level + 1} · ${upgradeCost}g`
			const metrics = ctx.measureText(text)
			const padX = 5 / zoom
			const padY = 2 / zoom
			const boxW = metrics.width + padX * 2
			const boxH = fontPx + padY * 2
			const boxX = x - boxW / 2
			const boxY = y + radius + 3 / zoom
			ctx.fillStyle = isDark ? 'rgba(20,20,28,0.92)' : 'rgba(255,255,255,0.95)'
			ctx.fillRect(boxX, boxY, boxW, boxH)
			ctx.lineWidth = 1 / zoom
			ctx.strokeStyle = isDark ? '#fff' : '#000'
			ctx.strokeRect(boxX, boxY, boxW, boxH)
			ctx.fillStyle = canAfford ? (isDark ? '#fff' : '#000') : isDark ? '#888' : '#888'
			ctx.fillText(text, x, boxY + padY)

			ctx.restore()
		}
	}
}
```

--------

# Customize Mermaid diagrams

Category: Use cases

Keywords: mermaid, diagram, custom, pipeline, workflow

Import a Mermaid flowchart as custom shapes and run it as an animated CI/CD pipeline.

`createMermaidDiagram` from `@tldraw/mermaid` accepts a `blueprintRender.mapNodeToRenderSpec` callback that decides which shape each parsed node becomes. This example maps every flowchart vertex to a custom `flowchart-util` shape and stores the Mermaid node id in the shape's props.

After the import, the pipeline graph is rebuilt from the arrows and arrow bindings on the canvas (`extractFlowchartPipelineFromEditor`), not from the Mermaid text. The graph must be a DAG. Steps are scheduled with AND-join semantics: a node runs once all of its predecessors have passed, and the "Step n" badges are Kahn layers, so nodes in the same layer share a number.

Try it: paste a `flowchart` or `graph` diagram, click "Apply workflow", then "Run pipeline". Steps fail at random; click "Retry" on a failed shape to resume from there. Only flowchart and graph diagrams are accepted, and pipeline status lives in a shared atom in memory, not in the store.

## App.tsx

```tsx
import { useCallback, useState } from 'react'
import { TLComponents, Tldraw, TldrawUiButton, useEditor, useValue } from 'tldraw'
import 'tldraw/tldraw.css'
import { FlowchartShapeUtil } from './customMermaidShapeUtil'
import './custom-shape-mermaid.css'
import { getFlowchartSourceError } from './flowchartSourceGuard'
import { mapNodeToRenderSpec } from './mermaidPipelineBlueprint'
import { type StepStatus, pipelineStateAtom, runFullPipeline } from './mermaidPipelineState'
import { applyPipelineStepIndices, extractFlowchartPipelineFromEditor } from './pipelineFromEditor'

const components: TLComponents = {
	TopPanel: TopPanel,
}

const customShapes = [FlowchartShapeUtil]

const DEFAULT_MERMAID = `flowchart LR
  s1[Checkout] --> s2[Build]
  s2 --> s3[Unit tests]
  s2 --> s4[Integration tests]
  s3 --> s5[Deploy]
  s4 --> s5`

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

function TopPanel() {
	const editor = useEditor()
	const [mermaidText, setMermaidText] = useState(DEFAULT_MERMAID)
	const [isApplying, setIsApplying] = useState(false)
	const pipeline = useValue(pipelineStateAtom)

	const canRun =
		!pipeline.parseError && pipeline.nodeIds.length > 0 && !pipeline.isRunning && !isApplying

	const applyWorkflow = useCallback(async () => {
		if (isApplying) return
		setIsApplying(true)

		try {
			const sourceError = getFlowchartSourceError(mermaidText)
			if (sourceError) {
				pipelineStateAtom.set({
					nodeIds: [],
					edges: [],
					statusByNodeId: {},
					parseError: sourceError,
					isRunning: false,
				})
				return
			}

			// [1]
			const { createMermaidDiagram } = await import('@tldraw/mermaid')

			editor.deleteShapes([...editor.getCurrentPageShapeIds()])

			try {
				// [2]
				await createMermaidDiagram(editor, mermaidText, {
					blueprintRender: {
						position: { x: 200, y: 400 },
						centerOnPosition: false,
						mapNodeToRenderSpec,
					},
				})
			} catch {
				pipelineStateAtom.set({
					nodeIds: [],
					edges: [],
					statusByNodeId: {},
					parseError: `An error occurred; please make sure your diagram is valid.`,
					isRunning: false,
				})
				return
			}

			// [3]
			const parsed = extractFlowchartPipelineFromEditor(editor)
			if (!parsed.ok) {
				pipelineStateAtom.set({
					nodeIds: [],
					edges: [],
					statusByNodeId: {},
					parseError: parsed.error,
					isRunning: false,
				})
			} else {
				pipelineStateAtom.set({
					nodeIds: parsed.nodeIds,
					edges: parsed.edges,
					statusByNodeId: Object.fromEntries(
						parsed.nodeIds.map((id) => [id, 'pending' as const])
					) as Record<string, StepStatus>,
					parseError: null,
					isRunning: false,
				})
				applyPipelineStepIndices(editor, parsed.stepIndexByNodeId)
			}

			editor.selectNone()
		} catch {
			pipelineStateAtom.update((s) => ({
				...s,
				parseError: `An error occurred; please make sure your diagram is valid.`,
			}))
		} finally {
			setIsApplying(false)
		}
	}, [editor, isApplying, mermaidText])

	const runPipeline = useCallback(() => {
		void runFullPipeline()
	}, [])

	return (
		<div className="custom-shape-mermaid">
			<div>
				Paste a Mermaid <strong>flowchart</strong> or <strong>graph</strong> (branching is ok; merge
				nodes run after <strong>all</strong> incoming steps pass). Apply runs Mermaid import, then
				builds the DAG from <strong>arrows on the canvas</strong>. Run simulates steps; failures can
				be retried on the shape. Step badges are Kahn layers, not a global sequence. Status is only
				in memory for this demo.
			</div>
			<textarea
				value={mermaidText}
				onChange={(e) => setMermaidText(e.target.value)}
				rows={7}
				spellCheck={false}
				className="custom-shape-mermaid__textarea"
			/>
			{pipeline.parseError && (
				<div className="custom-shape-mermaid__error">{pipeline.parseError}</div>
			)}
			<div className="custom-shape-mermaid__controls">
				<TldrawUiButton type="normal" onClick={applyWorkflow} disabled={isApplying}>
					{isApplying ? 'Applying…' : 'Apply workflow'}
				</TldrawUiButton>
				<TldrawUiButton type="low" onClick={runPipeline} disabled={!canRun}>
					Run pipeline
				</TldrawUiButton>
			</div>
			{pipeline.isRunning && (
				<div className="custom-shape-mermaid__notice">Running simulated steps…</div>
			)}
		</div>
	)
}

/*
[1]
`@tldraw/mermaid` pulls in the (large) mermaid library, so it is imported lazily the first
time the user applies a workflow rather than on page load.

[2]
`blueprintRender.mapNodeToRenderSpec` lets you decide which shape each parsed Mermaid node
becomes. Our mapper (see mermaidPipelineBlueprint.ts) turns every flowchart vertex into a
`flowchart-util` shape and stores the Mermaid node id in its props so we can find it later.

[3]
The pipeline graph is not read from the Mermaid text. Instead it is rebuilt from the arrows
and arrow bindings that the import created on the canvas (see pipelineFromEditor.ts), so if
you reconnect arrows by hand and apply again the pipeline follows the drawing.
*/
```

## custom-shape-mermaid.css

```css
.custom-shape-mermaid {
	position: fixed;
	top: 0;
	left: 50%;
	transform: translateX(-50%);
	z-index: 1000;
	padding: 10px 12px;
	background: #f1f3f4;
	border-radius: 0 0 8px 8px;
	display: flex;
	flex-direction: column;
	gap: 8px;
	max-width: 440px;
	box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
	font-size: 12px;
	color: #444;
	line-height: 1.4;
}

.custom-shape-mermaid__textarea {
	width: 100%;
	font-family: ui-monospace, monospace;
	padding: 8px;
	border-radius: 4px;
	border: 1px solid #ccc;
	resize: vertical;
	box-sizing: border-box;
	pointer-events: auto;
}

.custom-shape-mermaid__error {
	color: #842029;
	background: #f8d7da;
	padding: 8px;
	border-radius: 4px;
}

.custom-shape-mermaid__controls {
	display: flex;
	flex-wrap: wrap;
	gap: 8px;
}

.custom-shape-mermaid__notice {
	font-size: 12px;
	color: #666;
}
```

## customMermaidShapeUtil.css

```css
/* Custom flowchart node rendered by FlowchartShapeUtil (canvas HTML overlay). */

.flowchart-util-shape {
	position: relative;
	/* `.tl-html-container` uses pointer-events: none; override so Retry and label interact. */
	pointer-events: all;
	border-radius: 6px;
	display: flex;
	flex-direction: column;
	justify-content: center;
	align-items: center;
	gap: 6px;
	overflow: hidden;
}

.flowchart-util-shape--pending {
	background-color: #e8eaed;
	border: 1px solid rgba(0, 0, 0, 0.12);
}

.flowchart-util-shape--running {
	background-color: #fff3cd;
	border: 2px solid #856404;
}

.flowchart-util-shape--passed {
	background-color: #d1e7dd;
	border: 1px solid rgba(0, 0, 0, 0.12);
}

.flowchart-util-shape--failed {
	background-color: #f8d7da;
	border: 2px solid #842029;
}

.flowchart-util-shape__step-badge {
	position: absolute;
	top: 4px;
	right: 4px;
	z-index: 2;
	font-size: 10px;
	font-weight: 600;
	line-height: 1;
	padding: 2px 6px;
	border-radius: 4px;
	background: rgba(0, 0, 0, 0.06);
	color: #333;
	pointer-events: none;
}

.flowchart-util-shape__label {
	position: relative;
	flex: 1;
	align-self: stretch;
	min-height: 0;
	width: 100%;
}

.flowchart-util-shape__retry {
	margin-bottom: 6px;
	cursor: pointer;
}
```

## customMermaidShapeUtil.tsx

```tsx
import {
	BaseBoxShapeUtil,
	HTMLContainer,
	RecordProps,
	RichTextLabel,
	T,
	TLDefaultSizeStyle,
	TLRichText,
	TLShape,
	getColorValue,
	richTextValidator,
	toRichText,
	useEditor,
	useValue,
} from 'tldraw'
import './customMermaidShapeUtil.css'
import { type StepStatus, pipelineStateAtom, retryPipelineFromNode } from './mermaidPipelineState'

// Same multipliers the default note and geo shapes use for their labels.
const LABEL_FONT_SIZES: Record<TLDefaultSizeStyle, number> = {
	s: 1.125,
	m: 1.375,
	l: 1.625,
	xl: 2,
}

export const CUSTOM_SHAPE_TYPE = 'flowchart-util'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[CUSTOM_SHAPE_TYPE]: {
			w: number
			h: number
			fill: string
			color: string
			dash: string
			size: string
			font: string
			richText: TLRichText
			align: string
			verticalAlign: string
			mermaidNodeId: string
			/** 1-based Kahn layer after import; set in `applyPipelineStepIndices` from the canvas DAG. */
			pipelineStepIndex: number
		}
	}
}
export type ICustomShape = TLShape<typeof CUSTOM_SHAPE_TYPE>

export class FlowchartShapeUtil extends BaseBoxShapeUtil<ICustomShape> {
	static override type = CUSTOM_SHAPE_TYPE
	static override props: RecordProps<ICustomShape> = {
		w: T.number,
		h: T.number,
		fill: T.string,
		color: T.string,
		dash: T.string,
		size: T.string,
		font: T.string,
		richText: richTextValidator,
		align: T.string,
		verticalAlign: T.string,
		mermaidNodeId: T.string,
		pipelineStepIndex: T.number,
	}

	override getDefaultProps() {
		return {
			w: 100,
			h: 100,
			fill: 'none',
			color: 'black',
			dash: 'draw',
			size: 'm',
			font: 'draw',
			richText: toRichText(''),
			align: 'middle',
			verticalAlign: 'middle',
			mermaidNodeId: '',
			pipelineStepIndex: 0,
		}
	}

	override canEdit() {
		return false
	}

	override component(shape: ICustomShape) {
		return <CustomShapeComponent shape={shape} />
	}

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

function CustomShapeComponent({ shape }: { shape: ICustomShape }) {
	const { id, type, props } = shape
	const editor = useEditor()
	const theme = useValue('theme', () => editor.getCurrentTheme(), [editor])
	const colors = theme.colors[editor.getColorMode()]
	const pipeline = useValue(pipelineStateAtom)
	const status: StepStatus = props.mermaidNodeId
		? (pipeline.statusByNodeId[props.mermaidNodeId] ?? 'pending')
		: 'pending'

	const isOnlySelected = useValue(
		'flowchartUtilOnlySelected',
		() => shape.id === editor.getOnlySelectedShapeId(),
		[editor, shape.id]
	)

	return (
		<HTMLContainer
			className={`flowchart-util-shape flowchart-util-shape--${status}`}
			style={{ width: shape.props.w, height: shape.props.h }}
		>
			{props.pipelineStepIndex > 0 && (
				<div className="flowchart-util-shape__step-badge">Step {props.pipelineStepIndex}</div>
			)}
			<div className="flowchart-util-shape__label">
				<RichTextLabel
					shapeId={id}
					type={type}
					fontFamily={`var(--tl-font-${props.font})`}
					fontSize={
						(LABEL_FONT_SIZES[props.size as TLDefaultSizeStyle] ?? LABEL_FONT_SIZES.m) *
						theme.fontSize
					}
					lineHeight={theme.lineHeight}
					padding={12}
					textAlign={props.align === 'middle' ? 'center' : (props.align as any)}
					verticalAlign={props.verticalAlign as any}
					richText={props.richText}
					isSelected={isOnlySelected}
					labelColor={getColorValue(colors, props.color as any, 'solid')}
					wrap
					showTextOutline={false}
				/>
			</div>
			{status === 'failed' && (
				<button
					type="button"
					className="flowchart-util-shape__retry"
					// So the select tool does not treat the press as a canvas/shape drag before `click` fires.
					onPointerDown={editor.markEventAsHandled}
					onClick={() => void retryPipelineFromNode(props.mermaidNodeId)}
				>
					Retry
				</button>
			)}
		</HTMLContainer>
	)
}
```

## flowchartSourceGuard.ts

```ts
/**
 * This example only runs Mermaid `flowchart` / `graph` diagrams.
 * Returns a user-facing error string, or null if the first real line looks valid.
 */
export function getFlowchartSourceError(source: string): string | null {
	const lines = source.split(/\r?\n/)
	for (const line of lines) {
		const t = line.trim()
		if (t === '') continue
		if (t.startsWith('%%')) continue
		if (/^(flowchart|graph)\b/i.test(t)) {
			return null
		}
		return 'Use a flowchart or graph diagram only (first line should start with flowchart or graph).'
	}
	return 'Diagram source is empty.'
}
```

## mermaidPipelineBlueprint.ts

```ts
import type { MermaidNodeRenderMapper } from '@tldraw/mermaid'
import { CUSTOM_SHAPE_TYPE } from './customMermaidShapeUtil'

/** Pass to `createMermaidDiagram` → `blueprintRender.mapNodeToRenderSpec`: custom `flowchart-util` + `mermaidNodeId` (layer badges applied after import via `applyPipelineStepIndices`). */
export const mapNodeToRenderSpec: MermaidNodeRenderMapper = function mapNodeToRenderSpec(input) {
	if (input.diagramKind !== 'flowchart') return undefined

	return {
		variant: 'shape',
		type: CUSTOM_SHAPE_TYPE,
		props: {
			fill: 'solid',
			color: 'grey',
			mermaidNodeId: input.nodeId,
		},
	}
}
```

## mermaidPipelineState.ts

```ts
import { atom } from 'tldraw'
import { predecessorsFromEdges } from './pipelineGraph'

export type StepStatus = 'pending' | 'running' | 'passed' | 'failed'

export interface PipelineState {
	nodeIds: string[]
	edges: [string, string][]
	statusByNodeId: Record<string, StepStatus>
	parseError: string | null
	isRunning: boolean
}

/**
 * One shared atom for the whole page: every `flowchart-util` instance subscribes with `useValue`,
 * which is why this cannot live inside `useAtom` per component (each mount would get its own atom).
 */
export const pipelineStateAtom = atom<PipelineState>('mermaidPipelineExample', {
	nodeIds: [],
	edges: [],
	statusByNodeId: {},
	parseError: null,
	isRunning: false,
})

/** Probability each simulated step ends in `failed` (0–1). */
const FAIL_PROBABILITY = 0.2

const STEP_DELAY_MS_MIN = 800
const STEP_DELAY_MS_EXTRA = 400

function delay(ms: number) {
	return new Promise<void>((resolve) => setTimeout(resolve, ms))
}

/** Runs one simulated step. Returns false if the step failed (pipeline should stop or wait for Retry). */
async function simulateStep(nodeId: string): Promise<boolean> {
	pipelineStateAtom.update((s) => ({
		...s,
		statusByNodeId: { ...s.statusByNodeId, [nodeId]: 'running' },
	}))
	await delay(STEP_DELAY_MS_MIN + Math.random() * STEP_DELAY_MS_EXTRA)
	const failed = Math.random() < FAIL_PROBABILITY
	pipelineStateAtom.update((s) => ({
		...s,
		statusByNodeId: { ...s.statusByNodeId, [nodeId]: failed ? 'failed' : 'passed' },
	}))
	return !failed
}

function getReadyNodeIds(
	nodeIds: string[],
	edges: [string, string][],
	statusByNodeId: Record<string, StepStatus>
): string[] {
	const preds = predecessorsFromEdges(edges)
	return nodeIds.filter((id) => {
		if (statusByNodeId[id] !== 'pending') return false
		const ps = preds.get(id) ?? []
		return ps.every((p) => statusByNodeId[p] === 'passed')
	})
}

/**
 * Runs pending steps in AND-join order until all pass, fail, or execution is blocked by a failure.
 */
async function drainPipelineSteps() {
	while (true) {
		const s = pipelineStateAtom.get()
		const { nodeIds, edges, statusByNodeId } = s

		const pending = nodeIds.filter((id) => statusByNodeId[id] === 'pending')
		if (pending.length === 0) {
			break
		}

		const ready = getReadyNodeIds(nodeIds, edges, statusByNodeId)
		if (ready.length === 0) {
			break
		}

		ready.sort()
		for (const id of ready) {
			const ok = await simulateStep(id)
			if (!ok) {
				return
			}
		}
	}
}

/** Resets every step to pending, then runs until a failure or completion. */
export async function runFullPipeline() {
	const s = pipelineStateAtom.get()
	if (s.isRunning || s.nodeIds.length === 0 || s.parseError) return

	pipelineStateAtom.update((prev) => ({
		...prev,
		isRunning: true,
		statusByNodeId: Object.fromEntries(
			prev.nodeIds.map((id) => [id, 'pending' as const])
		) as Record<string, StepStatus>,
	}))

	await drainPipelineSteps()
	pipelineStateAtom.update((p) => ({ ...p, isRunning: false }))
}

/** Re-runs a failed step, then continues scheduling from current graph state. */
export async function retryPipelineFromNode(nodeId: string) {
	const s = pipelineStateAtom.get()
	if (s.isRunning || s.statusByNodeId[nodeId] !== 'failed') return
	if (!s.nodeIds.includes(nodeId)) return

	pipelineStateAtom.update((p) => ({ ...p, isRunning: true }))

	const ok = await simulateStep(nodeId)
	if (!ok) {
		pipelineStateAtom.update((p) => ({ ...p, isRunning: false }))
		return
	}

	await drainPipelineSteps()
	pipelineStateAtom.update((p) => ({ ...p, isRunning: false }))
}
```

## pipelineFromEditor.ts

```ts
import type { Editor, TLArrowBinding } from 'tldraw'
import { CUSTOM_SHAPE_TYPE, type ICustomShape } from './customMermaidShapeUtil'
import { flowchartPipelineFromEdges, type ParseFlowchartPipelineResult } from './pipelineGraph'

/**
 * Derives a DAG from imported Mermaid shapes: `flowchart-util` nodes (`mermaidNodeId`)
 * and `arrow` shapes with arrow bindings.
 */
export function extractFlowchartPipelineFromEditor(editor: Editor): ParseFlowchartPipelineResult {
	const shapes = editor.getCurrentPageShapes()
	const mermaidByShapeId = new Map<string, string>()
	for (const s of shapes) {
		if (s.type !== CUSTOM_SHAPE_TYPE) continue
		const props = (s as ICustomShape).props
		const mid = props.mermaidNodeId
		if (mid) mermaidByShapeId.set(s.id, mid)
	}

	const pairs: [string, string][] = []
	const seen = new Set<string>()

	for (const s of shapes) {
		if (s.type !== 'arrow') continue
		const bindings = editor.getBindingsInvolvingShape(s.id, 'arrow') as TLArrowBinding[]
		let startTarget: string | undefined
		let endTarget: string | undefined
		for (const b of bindings) {
			if (b.fromId !== s.id) continue
			const target = b.toId
			if (b.props.terminal === 'start') startTarget = target
			else if (b.props.terminal === 'end') endTarget = target
		}
		if (!startTarget || !endTarget) continue
		const a = mermaidByShapeId.get(startTarget)
		const b = mermaidByShapeId.get(endTarget)
		if (!a || !b) continue
		const key = `${a}->${b}`
		if (seen.has(key)) continue
		seen.add(key)
		pairs.push([a, b])
	}

	return flowchartPipelineFromEdges(pairs)
}

/** Sets `pipelineStepIndex` (Kahn layer, 1-based) on each `flowchart-util` shape; others get 0. */
export function applyPipelineStepIndices(
	editor: Editor,
	stepIndexByNodeId: Record<string, number>
) {
	const byMermaidId = new Map<string, ICustomShape>()
	for (const s of editor.getCurrentPageShapes()) {
		if (s.type !== CUSTOM_SHAPE_TYPE) continue
		const shape = s as ICustomShape
		const id = shape.props.mermaidNodeId
		if (id) byMermaidId.set(id, shape)
	}

	editor.run(() => {
		for (const [mermaidId, shape] of byMermaidId) {
			const step = stepIndexByNodeId[mermaidId] ?? 0
			editor.updateShape({
				id: shape.id,
				type: CUSTOM_SHAPE_TYPE,
				props: { ...shape.props, pipelineStepIndex: step },
			})
		}
	})
}
```

## pipelineGraph.ts

```ts
export type ParseFlowchartPipelineResult =
	| {
			ok: true
			nodeIds: string[]
			edges: [string, string][]
			stepIndexByNodeId: Record<string, number>
	  }
	| { ok: false; error: string }

const ERR_NO_STEPS =
	'No pipeline edges found between steps. Add arrows between nodes, e.g. a --> b --> c.'
const ERR_CYCLE = 'The flowchart has a cycle. This demo only supports directed acyclic graphs.'

/** Build predecessor lists: node id -> list of parents (from directed edges). */
export function predecessorsFromEdges(edges: [string, string][]): Map<string, string[]> {
	const m = new Map<string, string[]>()
	for (const [a, b] of edges) {
		let ps = m.get(b)
		if (!ps) {
			ps = []
			m.set(b, ps)
		}
		ps.push(a)
	}
	return m
}

/**
 * Validate edges form a DAG; assign a 1-based Kahn "layer" per node (same wave = same badge number).
 */
function dagLayersFromEdges(
	edges: [string, string][],
	nodes: Set<string>
): { ok: true; stepIndexByNodeId: Record<string, number> } | { ok: false; error: string } {
	const nodeList = [...nodes]
	const outgoing = new Map<string, string[]>()
	const indeg = new Map<string, number>()
	for (const n of nodeList) {
		outgoing.set(n, [])
		indeg.set(n, 0)
	}
	for (const [u, v] of edges) {
		outgoing.get(u)!.push(v)
		indeg.set(v, (indeg.get(v) ?? 0) + 1)
	}

	const indegWork = new Map(indeg)
	const stepIndexByNodeId: Record<string, number> = {}
	let layer = 0
	let remaining = nodeList.length

	while (remaining > 0) {
		const sources = nodeList.filter((n) => (indegWork.get(n) ?? 0) === 0)
		if (sources.length === 0) {
			return { ok: false, error: ERR_CYCLE }
		}
		layer++
		sources.sort()
		for (const u of sources) {
			stepIndexByNodeId[u] = layer
			indegWork.set(u, -1)
			remaining--
			for (const v of outgoing.get(u) ?? []) {
				const d = indegWork.get(v) ?? 0
				if (d >= 0) indegWork.set(v, d - 1)
			}
		}
	}

	return { ok: true, stepIndexByNodeId }
}

export function flowchartPipelineFromEdges(
	pairs: [string, string][]
): ParseFlowchartPipelineResult {
	if (pairs.length === 0) {
		return { ok: false, error: ERR_NO_STEPS }
	}

	const nodes = new Set<string>()
	for (const [a, b] of pairs) {
		nodes.add(a)
		nodes.add(b)
	}

	const layered = dagLayersFromEdges(pairs, nodes)
	if (!layered.ok) {
		return layered
	}

	const nodeIds = [...nodes].sort()
	return {
		ok: true,
		nodeIds,
		edges: pairs,
		stepIndexByNodeId: layered.stepIndexByNodeId,
	}
}
```

--------

# Gravity sim (xkcd 2347)

Category: Use cases

Keywords: physics, gravity, animation, fun, xkcd, rapier

Rebuild the xkcd "Dependency" comic as geo shapes and drop it into a Rapier 2D physics simulation.

Each block in the comic is a geo shape with a matching Rapier rigid body. On every editor `tick` the world steps and awake bodies write their position and rotation back to their shapes with `editor.updateShapes`. Selected blocks become kinematic and follow the shape instead, so you can drag them; deleting a block removes its body and wakes the rest.

Try pulling out the red block near the bottom and watch everything collapse, just like in the [original comic](https://xkcd.com/2347/).

## App.tsx

```tsx
import RAPIER from '@dimforge/rapier2d-compat'
import { useEffect, useRef } from 'react'
import { createShapeId, Tldraw, TLShapeId, toRichText, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'

// Block positions from the xkcd "Dependency" comic (#2347), as [x, y, w, h] quads with y=0 at
// the bottom of the tower. Source: https://editor.p5js.org/isohedral/sketches/vJa5RiZWs
const RAW_DATA = [
	0.5, 0.5, 217.113, 16.4414, 14.168, 16.9414, 181.059, 19.4141, 28.4297, 36.3555, 55.668, 10.6953,
	158.977, 36.3555, 7.921, 25.7539, 36.5547, 47.0508, 42.9844, 15.0586, 31.9961, 62.1094, 144.4099,
	8.7148, 23.2891, 70.8242, 159.1059, 48.2578, 15.918, 119.082, 83.4336, 106.715, 20.1875, 225.797,
	71.4023, 13.973, 102.844, 119.082, 85.371, 32.207, 102.844, 151.289, 89.254, 33.762, 24.9766,
	239.77, 14.6132, 19.457, 47.6055, 239.77, 11.7851, 13.562, 64.5781, 239.77, 27.0117, 20.636,
	66.4609, 260.406, 21.2149, 41.016, 69.2891, 301.422, 6.3672, 15.558, 79.4258, 301.422, 6.6015,
	25.457, 64.5781, 316.98, 12.4922, 4.95, 75.6563, 326.879, 13.4375, 9.43, 75.3047, 336.309, 6.3086,
	9.07, 84.3086, 336.309, 5.9609, 8.554, 52.375, 253.332, 5.2578, 15.426, 21.1602, 259.227, 27.3515,
	7.675, 20.1875, 266.902, 5.6094, 7.883, 28.5781, 266.902, 5.7188, 14.012, 38.7773, 266.902,
	4.6368, 10.2, 22.9922, 280.914, 17.332, 5.149, 27.1875, 286.063, 5.0938, 27.351, 27.1875, 313.414,
	4.4688, 10.82, 34.8359, 286.063, 9.3516, 10.355, 35.5313, 296.418, 7.8828, 7.879, 105.641,
	185.051, 13.078, 11.426, 104.254, 196.477, 4.359, 6.101, 109.813, 196.477, 4.96, 19.429, 106.434,
	215.906, 10.968, 6.231, 109.813, 222.137, 3.601, 6.617, 181.543, 185.051, 12.844, 19.719, 183.684,
	204.77, 5.754, 14.253, 179.27, 219.023, 15.117, 8.622, 180.207, 227.645, 4.547, 7.89, 189.438,
	227.645, 4.414, 6.421, 123.215, 185.051, 20.336, 52.625, 137.531, 237.676, 9.938, 11.238, 127.766,
	237.676, 8.16, 24.215, 152.379, 185.051, 23.414, 68.812, 156.125, 253.863, 14.383, 14.383,
	159.605, 268.246, 9.497, 10.367, 121.609, 261.891, 19.133, 16.722, 116.395, 278.613, 59.398,
	10.703, 166.961, 289.316, 12.309, 21.004, 170.508, 310.32, 5.285, 12.844, 113.414, 289.316,
	11.941, 10.5, 118.668, 299.816, 5.352, 13.715, 115.59, 313.531, 10.433, 6.555, 131.176, 289.316,
	30.703, 38.129, 130.305, 327.445, 14.582, 9.899, 150.641, 327.445, 14.984, 9.899, 137.598,
	337.344, 22.742, 9.765, 138.867, 347.109, 4.684, 14.18, 147.469, 347.109, 3.976, 10.301, 153.852,
	347.109, 4.949, 10.301,
]

const CANVAS_H = 434
const SCALE = 3

// The "critical dependency" block near the base of the tower
const DEPENDENCY_BLOCK_INDEX = 3

const COLORS = [
	'light-blue',
	'light-green',
	'yellow',
	'orange',
	'light-red',
	'light-violet',
	'blue',
	'green',
	'red',
	'violet',
] as const

interface Block {
	x: number
	y: number
	w: number
	h: number
}

function processBlocks(): Block[] {
	const blocks: Block[] = []
	const scaled = RAW_DATA.map((v) => v * 1.07)
	for (let i = 0; i < scaled.length; i += 4) {
		const x = (scaled[i] + 20) * SCALE
		const y = (CANVAS_H - scaled[i + 1] - scaled[i + 3] - 20) * SCALE
		const w = scaled[i + 2] * SCALE
		const h = scaled[i + 3] * SCALE
		blocks.push({ x, y, w, h })
	}
	return blocks
}

function XkcdDependency() {
	const editor = useEditor()
	const worldRef = useRef<RAPIER.World | null>(null)
	const bodiesRef = useRef<{ id: TLShapeId; body: RAPIER.RigidBody; w: number; h: number }[]>([])

	useEffect(() => {
		let cancelled = false
		let onTick: (() => void) | null = null
		let removeListener: (() => void) | null = null

		const blocks = processBlocks()
		const depBlock = blocks[DEPENDENCY_BLOCK_INDEX]

		const shapes = blocks.map((block, i) => {
			const id = createShapeId(`xkcd-${i}`)
			return {
				id,
				type: 'geo' as const,
				x: block.x,
				y: block.y,
				props: {
					w: block.w,
					h: block.h,
					fill: 'solid' as const,
					color: i === DEPENDENCY_BLOCK_INDEX ? ('red' as const) : COLORS[i % COLORS.length],
					geo: 'rectangle' as const,
					size: 's' as const,
				},
			}
		})

		const titleId = createShapeId('xkcd-title')
		const minX = Math.min(...blocks.map((b) => b.x))
		const maxX = Math.max(...blocks.map((b) => b.x + b.w))
		const minY = Math.min(...blocks.map((b) => b.y))

		const annotationId = createShapeId('xkcd-annotation')
		const arrowId = createShapeId('xkcd-arrow')
		const depId = createShapeId(`xkcd-${DEPENDENCY_BLOCK_INDEX}`)
		const creditId = createShapeId('xkcd-credit')
		const groundY = blocks.reduce((max, b) => Math.max(max, b.y + b.h), 0) + 10

		editor.createShapes([
			...shapes,
			{
				id: titleId,
				type: 'text',
				x: minX + (maxX - minX) / 2 - 200,
				y: minY - 80,
				props: {
					richText: toRichText('All modern digital infrastructure'),
					size: 'l',
					color: 'black',
				},
			},
			{
				id: annotationId,
				type: 'text',
				x: depBlock.x + 220,
				y: depBlock.y + depBlock.h - 300,
				props: {
					richText: toRichText(
						'A project some\nrandom person\nin Nebraska has\nbeen thanklessly\nmaintaining\nsince 2003'
					),
					size: 's',
					color: 'black',
				},
			},
			{
				id: arrowId,
				type: 'arrow',
				x: depBlock.x - 30,
				y: depBlock.y + depBlock.h + 50,
				props: {
					start: { x: 0, y: 0 },
					end: { x: 30, y: -50 },
					color: 'black',
					size: 's',
					kind: 'arc',
					bend: -70,
					elbowMidPoint: 0.5,
					arrowheadStart: 'none',
					arrowheadEnd: 'arrow',
				},
			},
			{
				id: creditId,
				type: 'text',
				x: minX,
				y: groundY + 30,
				props: {
					richText: {
						type: 'doc',
						content: [
							{
								type: 'paragraph',
								content: [
									{ type: 'text', text: 'With apologies to ' },
									{
										type: 'text',
										text: 'xkcd.com/2347',
										marks: [{ type: 'link', attrs: { href: 'https://xkcd.com/2347' } }],
									},
								],
							},
							{
								type: 'paragraph',
								content: [
									{ type: 'text', text: 'Inspired by ' },
									{
										type: 'text',
										text: 'editor.p5js.org/isohedral',
										marks: [
											{
												type: 'link',
												attrs: {
													href: 'https://editor.p5js.org/isohedral/full/vJa5RiZWs',
												},
											},
										],
									},
								],
							},
						],
					},
					size: 's',
					color: 'grey',
				},
			},
		])

		editor.createBindings([
			{
				fromId: arrowId,
				toId: depId,
				type: 'arrow',
				props: {
					terminal: 'end',
					normalizedAnchor: { x: 0.5, y: 0.5 },
					isPrecise: false,
					isExact: false,
				},
			},
			{
				fromId: arrowId,
				toId: annotationId,
				type: 'arrow',
				props: {
					terminal: 'start',
					normalizedAnchor: { x: 0.5, y: 0.5 },
					isPrecise: true,
					isExact: false,
				},
			},
		])

		editor.zoomToFit({ animation: { duration: 300 } })

		// [1]
		RAPIER.init().then(() => {
			if (cancelled) return

			const world = new RAPIER.World({ x: 0, y: 200 })
			worldRef.current = world

			const groundBody = world.createRigidBody(
				RAPIER.RigidBodyDesc.fixed().setTranslation((minX + maxX) / 2, groundY + 50)
			)
			world.createCollider(RAPIER.ColliderDesc.cuboid(((maxX - minX) * 3) / 2, 50), groundBody)

			const blockIdSet = new Set<string>()
			const bodies: typeof bodiesRef.current = []
			for (let i = 0; i < blocks.length; i++) {
				const block = blocks[i]
				const id = createShapeId(`xkcd-${i}`)
				blockIdSet.add(id)
				const body = world.createRigidBody(
					RAPIER.RigidBodyDesc.dynamic()
						.setTranslation(block.x + block.w / 2, block.y + block.h / 2)
						.setCanSleep(true)
				)
				world.createCollider(
					RAPIER.ColliderDesc.cuboid(block.w / 2, block.h / 2)
						.setRestitution(0.05)
						.setFriction(0.1),
					body
				)
				bodies.push({ id, body, w: block.w, h: block.h })
			}
			bodiesRef.current = bodies

			// [2]
			for (let i = 0; i < 120; i++) world.step()
			const settled: { id: TLShapeId; type: 'geo'; x: number; y: number; rotation: number }[] = []
			for (const { id, body, w, h } of bodies) {
				const pos = body.translation()
				settled.push({
					id,
					type: 'geo',
					x: pos.x - w / 2,
					y: pos.y - h / 2,
					rotation: body.rotation(),
				})
				body.sleep()
			}
			editor.updateShapes(settled)

			let updatingFromPhysics = false
			const kinematicIds = new Set<string>()

			// [3]
			removeListener = editor.store.listen(
				({ changes }) => {
					if (updatingFromPhysics) return

					for (const key of Object.keys(changes.removed)) {
						if (!blockIdSet.has(key)) continue
						blockIdSet.delete(key)
						kinematicIds.delete(key)
						const idx = bodiesRef.current.findIndex((b) => b.id === key)
						if (idx !== -1) {
							world.removeRigidBody(bodiesRef.current[idx].body)
							bodiesRef.current.splice(idx, 1)
						}
						for (const { body } of bodiesRef.current) body.wakeUp()
					}
				},
				{ source: 'user', scope: 'document' }
			)

			// [4]
			onTick = () => {
				if (!worldRef.current) return

				const selectedIds = new Set(editor.getSelectedShapeIds() as string[])

				// Release bodies that are no longer selected back to dynamic
				for (const id of kinematicIds) {
					if (selectedIds.has(id)) continue
					kinematicIds.delete(id)
					const entry = bodiesRef.current.find((b) => b.id === id)
					if (!entry) continue
					entry.body.setBodyType(RAPIER.RigidBodyType.Dynamic, true)
					entry.body.setLinvel({ x: 0, y: 0 }, true)
					entry.body.setAngvel(0, true)
					for (const { body } of bodiesRef.current) body.wakeUp()
				}

				// Switch selected bodies to kinematic so they follow the user's drag
				for (const entry of bodiesRef.current) {
					if (!selectedIds.has(entry.id as string)) continue
					if (!kinematicIds.has(entry.id as string)) {
						entry.body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true)
						kinematicIds.add(entry.id as string)
					}
					const shape = editor.getShape(entry.id)
					if (!shape) continue
					entry.body.setNextKinematicTranslation({
						x: shape.x + entry.w / 2,
						y: shape.y + entry.h / 2,
					})
					entry.body.setNextKinematicRotation(shape.rotation)
				}

				world.step()

				// Sync non-selected, non-sleeping bodies back to tldraw shapes
				const updates: {
					id: TLShapeId
					type: 'geo'
					x: number
					y: number
					rotation: number
				}[] = []
				for (const { id, body, w, h } of bodiesRef.current) {
					if (kinematicIds.has(id as string)) continue
					if (body.isSleeping()) continue
					const pos = body.translation()
					const bx = pos.x - w / 2
					const by = pos.y - h / 2
					if (!isFinite(bx) || !isFinite(by)) continue
					updates.push({ id, type: 'geo', x: bx, y: by, rotation: body.rotation() })
				}

				if (updates.length > 0) {
					updatingFromPhysics = true
					editor.updateShapes(updates)
					updatingFromPhysics = false
				}
			}

			editor.on('tick', onTick)
		})

		return () => {
			cancelled = true
			if (onTick) editor.off('tick', onTick)
			if (removeListener) removeListener()
			if (worldRef.current) {
				worldRef.current.free()
				worldRef.current = null
			}
			const shapeIds: TLShapeId[] = blocks.map((_, i) => createShapeId(`xkcd-${i}`))
			shapeIds.push(titleId, annotationId, arrowId, creditId)
			editor.deleteShapes(shapeIds)
		}
	}, [editor])

	return null
}

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

/*
[1]
Rapier is a WASM module and must be initialised asynchronously. The shapes are created first
so the comic appears immediately; physics attaches once the module is ready.

[2]
The traced block positions overlap slightly, so the world is stepped a number of times before
the first frame to let them settle, then every body is put to sleep so the tower is still
until something disturbs it.

[3]
When the user deletes a block, its rigid body is removed too and everything is woken so the
tower re-settles. `source: 'user'` filters out the position updates we write ourselves.

[4]
Every editor `tick`, selected blocks are switched to kinematic bodies that follow the shape's
position (so dragging moves the physics body, not the other way round), the world is stepped,
and every awake, unselected body writes its position and rotation back to its shape with
`editor.updateShapes`.
*/
```

--------

# Hundreds of Mermaid diagrams

Category: Use cases

Keywords: mermaid, diagram

Convert over a hundred Mermaid flowcharts, state diagrams, mind maps, and sequence diagrams into native tldraw shapes.

`createMermaidDiagram` from `@tldraw/mermaid` parses Mermaid source and creates ordinary tldraw shapes (geo shapes, arrows with bindings, text) at a given position. This example runs it over a large set of diagram definitions from `mermaids.ts` and lays the results out in rows by diagram type.

Next to each native version it also places Mermaid's own SVG rendering as an image shape, scaled to the same height, so you can compare the two side by side.

Click the button in the top panel and wait: the panel hides while generating and comes back with the final count. Both libraries are imported lazily on first click.

## App.tsx

```tsx
import { useCallback } from 'react'
import {
	Editor,
	TLComponents,
	TLShapeId,
	Tldraw,
	TldrawUiButton,
	createShapeId,
	useAtom,
	useEditor,
	useValue,
} from 'tldraw'
import 'tldraw/tldraw.css'
import './hundred-mermaids.css'
import mermaidDefinitions from './mermaids'

const GAP = 100
const PAIR_GAP = 40

// [1]
const MERMAID_CONFIG = {
	flowchart: { useMaxWidth: false },
	state: { useMaxWidth: false },
	mindmap: { useMaxWidth: false },
	sequence: { useMaxWidth: false },
}

const components: TLComponents = {
	TopPanel: TopPanel,
}

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

function getNewShapeIds(editor: Editor, shapesBefore: Set<TLShapeId>): TLShapeId[] {
	return [...editor.getCurrentPageShapeIds()].filter((id) => !shapesBefore.has(id))
}

function measureSelection(editor: Editor) {
	const bounds = editor.getSelectionPageBounds()
	return bounds ? { w: bounds.width, h: bounds.height } : { w: 0, h: 0 }
}

function parseSvgSize(svgText: string): { w: number; h: number } {
	const svg = new DOMParser().parseFromString(svgText, 'image/svg+xml').querySelector('svg')
	if (!svg) return { w: 100, h: 100 }
	let w = parseFloat(svg.getAttribute('width') || '0')
	let h = parseFloat(svg.getAttribute('height') || '0')
	if (!(w && h)) {
		const vb = svg.getAttribute('viewBox')?.split(/\s+/).map(Number)
		if (vb && vb.length === 4) {
			w = vb[2]
			h = vb[3]
		}
	}
	return { w: w || 100, h: h || 100 }
}

function TopPanel() {
	const editor = useEditor()
	const isGeneratingAtom = useAtom<boolean>('isGenerating', false)
	const isGenerating = useValue(isGeneratingAtom)
	const countAtom = useAtom<number>('mermaidCount', 0)
	const count = useValue(countAtom)

	const handleClick = useCallback(async () => {
		if (isGeneratingAtom.get()) {
			return
		}
		countAtom.set(0)
		isGeneratingAtom.set(true)

		// [2]
		const [{ createMermaidDiagram }, { default: mermaid }] = await Promise.all([
			import('@tldraw/mermaid'),
			import('mermaid'),
		])

		const offscreen = document.createElement('div')
		offscreen.style.cssText = 'position:absolute;left:-9999px;top:-9999px;overflow:hidden'
		document.body.appendChild(offscreen)

		editor.deleteShapes([...editor.getCurrentPageShapeIds()])

		let currentX = 0
		let currentY = 0

		try {
			for (const group of mermaidDefinitions) {
				currentX = 0
				let maxRowHeight = 0

				for (const def of group) {
					const shapesBefore = new Set(editor.getCurrentPageShapeIds())
					let nativeSize = { w: 0, h: 0 }

					// [3]
					try {
						await createMermaidDiagram(editor, def, {
							mermaidConfig: MERMAID_CONFIG,
							blueprintRender: {
								position: { x: currentX, y: currentY },
								centerOnPosition: false,
							},
						})

						const nativeIds = getNewShapeIds(editor, shapesBefore)
						if (nativeIds.length) {
							editor.setSelectedShapes(nativeIds)
						}
						nativeSize = measureSelection(editor)
						currentX += nativeSize.w + PAIR_GAP
					} catch (e) {
						console.warn('[mermaid] blueprint failed:', e, '\n---\n' + def)
					}

					// [4]
					try {
						const { svg } = await mermaid.render(
							`mmd-svg-${Date.now()}-${Math.random().toString(36).slice(2)}`,
							def,
							offscreen
						)

						const { w: svgW, h: svgH } = parseSvgSize(svg)
						const scale = nativeSize.h > 0 && svgH > 0 ? nativeSize.h / svgH : 1
						const scaledW = svgW * scale
						const scaledH = svgH * scale

						const asset = await editor.getAssetForExternalContent({
							type: 'file',
							file: new File([svg], 'diagram.svg', { type: 'image/svg+xml' }),
						})
						if (asset) {
							if (!editor.getAsset(asset.id)) {
								editor.createAssets([asset])
							}
							editor.createShape({
								id: createShapeId(),
								type: 'image',
								x: currentX,
								y: currentY,
								props: { assetId: asset.id, w: scaledW, h: scaledH },
							})
						}

						currentX += scaledW + GAP
						maxRowHeight = Math.max(maxRowHeight, nativeSize.h, scaledH)
					} catch (e) {
						console.warn('[mermaid] svg render failed:', e, '\n---\n' + def)
						currentX += GAP - PAIR_GAP
						maxRowHeight = Math.max(maxRowHeight, nativeSize.h)
					}

					countAtom.set(countAtom.get() + 1)
				}

				currentY += maxRowHeight + GAP
			}
		} finally {
			offscreen.remove()
			isGeneratingAtom.set(false)
		}

		editor.selectNone()
	}, [editor, isGeneratingAtom, countAtom])

	return (
		<div className="hundred-mermaids-panel" style={{ opacity: isGenerating ? 0 : 1 }}>
			<TldrawUiButton type="low" onClick={handleClick}>
				Click to see a thousand mermaids
				{count > 0 && <>({count} actually…)</>}
			</TldrawUiButton>
		</div>
	)
}

/*
[1]
Mermaid's `useMaxWidth` makes rendered SVGs stretch to their container. We turn it off so
the SVG we render for comparison has an intrinsic size we can read back. `createMermaidDiagram`
merges `mermaidConfig` over its own defaults and calls `mermaid.initialize` for us.

[2]
Both `@tldraw/mermaid` and mermaid itself are large, so they are loaded on first click rather
than on page load.

[3]
`createMermaidDiagram` parses the Mermaid source and creates native tldraw shapes (geo shapes,
arrows, text) at the given position. We diff the page's shape ids before and after to find what
it created so we can measure it and lay out the next diagram.

[4]
For comparison, the same source is also rendered by Mermaid to an SVG, which is turned into an
image asset and placed next to the native version at the same height.
*/
```

## hundred-mermaids.css

```css
.hundred-mermaids-panel {
	position: fixed;
	top: 0;
	left: 50%;
	transform: translateX(-50%);
	padding: 8px;
	background: #eee;
	border-radius: 0 0 8px 8px;
	display: flex;
	gap: 8px;
	z-index: 1000;
}
```

## mermaids.ts

```ts
export default [
	[
		`flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]`,
		`flowchart TD
    A[Start] --> B[End]`,
		`flowchart LR
    A[Open app] --> B[Sign in]
    B --> C[Dashboard]`,
		`flowchart TB
    A[Receive request] --> B[Validate]
    B --> C[Process]
    C --> D[Respond]`,
		`flowchart TD
    A[Submit form] --> B{Is valid?}
    B -- Yes --> C[Save]
    B -- No --> D[Show errors]`,
		`flowchart TD
    A[Start] --> B{User type?}
    B -- Admin --> C[Admin panel]
    B -- Member --> D[Member home]
    B -- Guest --> E[Landing page]
    C --> F[Common logout]
    D --> F
    E --> F`,
		`flowchart TD
    A([Start]) --> B[Task]
    B --> C{Decision}
    C -- Yes --> D[[Subprocess]]
    C -- No --> E[(Database)]
    D --> F([End])
    E --> F`,
		`flowchart LR
    A[Client] -->|POST /login| B[API]
    B -->|Check credentials| C[(Users DB)]
    C -->|User record| B
    B -->|JWT token| A`,
		`flowchart TD
    A[Draft] -. Review .-> B[Editor]
    B ==> C[Published]
    A --> D[Archived]`,
		`flowchart LR
    A[Idea] --> B[Spec] --> C[Build] --> D[Test] --> E[Release]`,
		`flowchart TD
    subgraph Frontend
        A[UI]
        B[State manager]
    end

    subgraph Backend
        C[API]
        D[(DB)]
    end

    A --> B
    B --> C
    C --> D`,
		`flowchart TD
    subgraph Client
        direction LR
        A[Page] --> B[Form] --> C[Submit button]
    end

    subgraph Server
        direction TB
        D[Controller] --> E[Service] --> F[(DB)]
    end

    C --> D`,
		`flowchart TD
    X[User action] --> A

    subgraph Auth
        A[Enter credentials] --> B{Valid?}
        B -- Yes --> C[Issue session]
        B -- No --> D[Reject]
    end

    C --> Y[Go to app]
    D --> Z[Retry]`,
		`flowchart TD
    A([Start]) --> B[Collect order]
    B --> C{In stock?}
    C -- Yes --> D[Pack item]
    C -- No --> E[Backorder]
    E --> F[Notify customer]
    D --> G[Ship]
    F --> H([End])
    G --> H`,
		`flowchart TD
    A[Request] --> B[Validation]
    B --> C[Success]
    B --> D[Failure]

    style B fill:#fff4cc,stroke:#cc9900,stroke-width:2px
    style C fill:#e8f5e9,stroke:#2e7d32
    style D fill:#ffebee,stroke:#c62828`,
		`flowchart LR
    A[Start]:::good --> B[Process]:::normal --> C{OK?}:::warn
    C -- Yes --> D[Done]:::good
    C -- No --> E[Retry]:::bad

    classDef good fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef normal fill:#e3f2fd,stroke:#1565c0,stroke-width:1px;
    classDef warn fill:#fff8e1,stroke:#ef6c00,stroke-width:2px;
    classDef bad fill:#ffebee,stroke:#c62828,stroke-width:2px;`,
		`flowchart TD
    A[API Gateway] --> B[Auth Service]
    A --> C[Orders Service]
    A --> D[Inventory Service]
    B --> E[(Users DB)]
    C --> F[(Orders DB)]
    D --> G[(Stock DB)]

    classDef svc fill:#e3f2fd,stroke:#1565c0;
    classDef db fill:#f3e5f5,stroke:#6a1b9a;
    class A,B,C,D svc;
    class E,F,G db;`,
		`flowchart TD
    A[Client] --> B[API]
    A --> C[Cache]
    B --> D[(Primary DB)]
    C --> D

    linkStyle 0 stroke:#1565c0,stroke-width:2px;
    linkStyle 1 stroke:#ef6c00,stroke-dasharray: 5 5;
    linkStyle 2 stroke:#2e7d32,stroke-width:2px;
    linkStyle 3 stroke:#6a1b9a,stroke-dasharray: 2 2;`,
		`%%{init: {'flowchart': {'curve': 'basis'}}}%%
flowchart LR
    A[Input] --> B{Transform?}
    B -- Yes --> C[Mapper]
    B -- No --> D[Pass through]
    C --> E[Output]
    D --> E`,
		`flowchart TD
    A[Checkout] --> B[Payment] --> C[Confirmation]`,
		`flowchart LR
    A[Producer] --> B[Queue]
    B --> C[Worker]
    C --> D[Result]

    classDef pulse stroke-width:3px,stroke:#d32f2f,animate:true,animation:fast;
    class B pulse;`,
		`flowchart TD
    A[Start] --> B{Route?}
    B -- Short --> C[Quick task]
    B -- Long --> D[Step 1]
    D --> E[Step 2]
    E --> F[Step 3]
    F --> G[Step 4]
    G --> H[Finish]
    C --> H`,
		`flowchart LR
    A[Input] --> B[Parse]
    A --> C[Validate]
    A --> D[Normalize]
    B --> E[Assemble]
    C --> E
    D --> E
    E --> F[Output]`,
		`flowchart TD
    A[User opens checkout] --> B[System validates whether the currently selected shipping address is complete and deliverable]
    B --> C{Was the validation successful?}
    C -- Yes --> D[Continue to payment]
    C -- No --> E[Show address correction prompt]`,
		`flowchart TD
    A[Request] --> B{Authenticated?}
    B -- No --> C[Reject]
    B -- Yes --> D{Authorized?}
    D -- No --> E[Forbidden]
    D -- Yes --> F{Cached?}
    F -- Yes --> G[Return cached result]
    F -- No --> H[Query service]
    H --> I[Return fresh result]
    G --> J[Done]
    I --> J
    C --> J
    E --> J`,
		`flowchart LR
    A[Draft] --> B[Review]
    B --> C{Approved?}
    C -- Yes --> D[Publish]
    C -- No --> E[Revise]
    E --> B`,
		`flowchart TD
    subgraph Client
        A[Page]
        B[Form]
    end

    subgraph Server
        C[Gateway]
        D[Auth service]
        E[Profile service]
        F[(User DB)]
    end

    A --> B
    B --> C
    C --> D
    C --> E
    D --> F
    E --> F`,
		`flowchart TD
    X[Start] --> A

    subgraph Pipeline
        direction LR
        A[Ingest] --> B[Transform] --> C[Store]
    end

    C --> D[Notify]
    D --> E[End]`,
		`flowchart TD
    A[Upload file] --> B{File type accepted by the current processing pipeline?}
    B -- Yes, continue with normal processing --> C[Process file]
    B -- No, reject and explain supported formats --> D[Show unsupported format message]
    C --> E[Done]
    D --> E`,
		`flowchart LR
    A[Web app] --> D[API]
    B[Mobile app] --> D
    C[Admin app] --> D
    D --> E[Auth]
    D --> F[Orders]
    D --> G[Inventory]
    E --> H[(Users DB)]
    F --> I[(Orders DB)]
    G --> I`,
		`flowchart TD
    A[Event received] --> B{Needs enrichment?}
    B -- No --> C[Dispatch immediately]
    B -- Yes --> D[Load metadata]
    D --> E[Merge payload]
    E --> F[Run policy checks]
    F --> G[Dispatch]
    C --> H[Complete]
    G --> H`,
		`flowchart LR
    A[Start] --> B{Decision}
    B -- Path 1 --> C[Short]
    B -- Path 2 --> D[Much longer intermediate processing step]
    D --> E[Another step]
    E --> F[End]
    C --> F`,
		`flowchart LR
    A[Start] -->|Begin initial system bootstrap process| B[Initialize services]
    B -->|Wait for all dependency containers to finish starting successfully| C[Dependency ready]
    C -->|Notify orchestration layer that system state is now healthy| D[Operational]`,
		`flowchart LR
    A[Request] -->|"GET /users?id=42"| B[API]
    B -->|"SELECT * FROM users WHERE id=42;"| C[(Database)]
    C -->|"200 OK + JSON payload"| B
    B -->|"HTTP response (compressed)"| A`,
		`flowchart TD
    A[Submit form] --> B{Validation}
    B -- OK --> C[Continue]
    B -- "Invalid because the provided address fails multiple delivery verification rules" --> D[Show detailed validation errors]
    C --> E[Finish]
    D --> E`,
		`flowchart TD

    subgraph Client
        A[Browser] --> B[Form submit]
    end

    subgraph Gateway
        C[Edge proxy]
    end

    subgraph Backend
        D[Controller]
        E[Service]
        F[(DB)]
    end

    B -->|"POST /api/submit"| C
    C -->|"forward request"| D
    D -->|"invoke business logic"| E
    E -->|"write transaction"| F`,
		`flowchart TD

    subgraph System
        subgraph Frontend
            A[Page] --> B[Submit]
        end

        subgraph Backend
            C[API]
            D[Worker]
        end
    end

    B -->|"JSON payload"| C
    C -->|"enqueue job"| D`,
		`flowchart LR
    A[Event] -->|"This event triggers a complex downstream processing pipeline"| B[Processor]
    B -->|"Output results that may contain multiple transformation stages"| C[Consumer]`,
		`flowchart LR
    A[Client] -->|"request"| B[Gateway]
    A -->|"healthcheck ping"| C[Monitor]

    B -->|"authenticate session token"| D[Auth]
    B -->|"fetch order history from service"| E[Orders]

    D -->|"validate user"| F[(User DB)]
    E -->|"load order data"| G[(Orders DB)]`,
		`flowchart LR

    subgraph UserLayer
        A[User]
    end

    subgraph AppLayer
        B[UI]
        C[Controller]
    end

    subgraph DataLayer
        D[Service]
        E[(DB)]
    end

    A -->|"click action"| B
    B -->|"dispatch event"| C
    C -->|"invoke business logic"| D
    D -->|"query persistent storage"| E
    E -->|"return dataset"| D
    D -->|"response payload"| C`,
	],
	[
		`stateDiagram-v2
    [*] --> Idle
    Idle --> Active`,
		`stateDiagram-v2
    [*] --> Idle
    Idle --> Active: start
    Active --> Idle: stop`,
		`stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit
    Review --> Published: approve
    Published --> [*]`,
		`stateDiagram-v2
    [*] --> Editing
    Editing --> Editing: type
    Editing --> Saved: save
    Saved --> [*]`,
		`stateDiagram-v2
    [*] --> LoggedOut
    LoggedOut --> LoggedIn: login
    SessionExpired --> LoggedIn: reauthenticate
    LoggedIn --> SessionExpired: timeout`,
		`stateDiagram-v2
    [*] --> Validate
    Validate --> Accepted: valid
    Validate --> Rejected: invalid
    Accepted --> [*]
    Rejected --> [*]`,
		`stateDiagram-v2
    [*] --> Idle
    state Idle: Waiting for input
    state Processing: Running background work
    Idle --> Processing: submit
    Processing --> Idle: done`,
		`stateDiagram-v2
    direction LR
    [*] --> New
    New --> Assigned: assign
    Assigned --> Resolved: resolve
    Resolved --> Closed: close`,
		`stateDiagram-v2
    [*] --> Authentication

    state Authentication {
        [*] --> EnterCredentials
        EnterCredentials --> Verifying: submit
        Verifying --> Success: valid
        Verifying --> Failure: invalid
    }

    Authentication --> Dashboard: success`,
		`stateDiagram-v2
    [*] --> Checkout

    state Checkout {
        [*] --> Cart
        Cart --> Address: continue
        Address --> Payment: next
        Payment --> Complete: pay
    }

    Checkout --> Confirmation: order complete
    Confirmation --> [*]`,
		`stateDiagram-v2
    [*] --> Order

    state Order {
        [*] --> Pending
        Pending --> Packed: pack
        Packed --> Shipped: ship
        Shipped --> Delivered: deliver
    }

    Order --> Archived: archive`,
		`stateDiagram-v2
    [*] --> Processing

    state Processing {
        [*] --> Fork
        state Fork <<fork>>

        Fork --> FraudCheck
        Fork --> InventoryCheck

        FraudCheck --> Join
        InventoryCheck --> Join

        state Join <<join>>
        Join --> Ready
    }

    Ready --> [*]`,
		`stateDiagram-v2
    [*] --> Submitted
    Submitted --> ReviewDecision

    state ReviewDecision <<choice>>

    ReviewDecision --> Approved: score >= 80
    ReviewDecision --> NeedsInfo: score < 80
    Approved --> [*]
    NeedsInfo --> [*]`,
		`stateDiagram-v2
    [*] --> StartValidation

    StartValidation --> MergeChecks
    ManualValidation --> MergeChecks

    state MergeChecks <<junction>>

    MergeChecks --> Accepted: all checks pass
    MergeChecks --> Rejected: any check fails`,
		`stateDiagram-v2
    [*] --> Session

    state Session {
        state entry1 <<entryPoint>>
        state exit1 <<exitPoint>>

        [*] --> entry1
        entry1 --> Active
        Active --> exit1: logout
    }

    Session --> LoggedOut`,
		`stateDiagram-v2
    [*] --> TicketOpen
    TicketOpen --> Investigating: assign
    Investigating --> WaitingForCustomer: need info
    WaitingForCustomer --> Investigating: reply received
    Investigating --> Resolved: fix applied
    Resolved --> Closed: confirm

    note right of WaitingForCustomer
        SLA clock may pause here
    end note`,
		`stateDiagram-v2
    [*] --> Player

    state Player {
        [*] --> Stopped
        Stopped --> Playing: play
        Playing --> Paused: pause
        Paused --> Playing: resume
        Playing --> Stopped: stop

        state H <<history>>
    }

    Player --> Suspended: app backgrounded
    Suspended --> H: app foregrounded`,
		`stateDiagram-v2
    [*] --> Editor

    state Editor {
        [*] --> Viewing

        state Mode {
            [*] --> Select
            Select --> Draw: pen tool
            Draw --> Erase: eraser
            Erase --> Select: pointer
        }

        Viewing --> Mode: edit
        Mode --> Viewing: preview

        state H <<history>>
    }

    Editor --> Suspended: sleep
    Suspended --> H: wake`,
		`stateDiagram-v2
    [*] --> Running
    Running --> Saving: exit requested
    Saving --> [*]: save complete
    Running --> FatalError: crash

    state FatalError <<terminate>>`,
		`stateDiagram-v2
    direction LR

    [*] --> Draft
    Draft --> Submitted: submit

    state Review {
        [*] --> ManagerReview
        ManagerReview --> LegalReview: manager approves
        ManagerReview --> Rejected: manager rejects
        LegalReview --> Approved: legal approves
        LegalReview --> Rejected: legal rejects
    }

    Submitted --> Review
    Review --> Published: approved
    Review --> Draft: rejected for edits
    Published --> [*]`,
		`stateDiagram-v2
    [*] --> OrderPlaced
    OrderPlaced --> Validation

    state Validation {
        [*] --> F
        state F <<fork>>

        F --> PaymentCheck
        F --> StockCheck
        F --> AddressCheck

        PaymentCheck --> J
        StockCheck --> J
        AddressCheck --> J

        state J <<join>>
        J --> Decision
    }

    state Decision <<choice>>

    Decision --> Approved: all valid
    Decision --> Rejected: any invalid

    Approved --> Fulfillment
    Rejected --> Cancelled
    Fulfillment --> Shipped
    Shipped --> Delivered
    Delivered --> [*]
    Cancelled --> [*]`,
		`stateDiagram-v2
    [*] --> Editing
    Editing --> Editing: type character
    Editing --> Saved: save
    Saved --> [*]`,
		`stateDiagram-v2
    [*] --> Waiting
    Waiting --> Processing: user clicks the big primary call-to-action button after hesitating for several seconds
    Processing --> Completed: background work finishes successfully
    Completed --> [*]`,
		`stateDiagram-v2
    state "Idle but still listening for websocket reconnection attempts in the background" as Idle
    state "Processing a surprisingly complicated synchronization routine" as Processing

    [*] --> Idle
    Idle --> Processing: reconnect
    Processing --> Idle: synced`,
		`%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#eef7ff",
    "primaryBorderColor": "#336699",
    "lineColor": "#222",
    "fontSize": "16px"
  }
}}%%
stateDiagram-v2
    direction LR

    [*] --> Draft
    Draft --> Review: submit
    Review --> Review: request more changes
    Review --> Published: approve
    Published --> [*]`,
		`stateDiagram-v2
    [*] --> Validate
    Validate --> Decision

    state Decision <<choice>>

    Decision --> Accept: everything looks fine
    Decision --> Validate: hmm... maybe run the exact same validation pipeline one more time just to be absolutely certain
    Accept --> [*]`,
		`stateDiagram-v2
	state "Drafting\\nwith autosave\\nand validation" as Drafting

    [*] --> Drafting
    Drafting --> Drafting: type
    Drafting --> [*]: close`,
	],
	[
		`sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!`,
		`sequenceDiagram
    Alice->>Bob: Hello Bob`,
		`sequenceDiagram
    User->>App: Open app
    App->>API: Fetch profile
    API-->>App: Profile data
    App-->>User: Render profile`,
		`sequenceDiagram
    participant U as User
    participant A as App
    participant S as Server

    U->>A: Click login
    A->>S: POST /login
    S-->>A: 200 OK
    A-->>U: Show dashboard`,
		`sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Request data
    activate Server
    Server-->>Client: Response data
    deactivate Server`,
		`sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: Get order
    activate API
    API->>DB: Query order
    activate DB
    DB-->>API: Order row
    deactivate DB
    API-->>Client: Order JSON
    deactivate API`,
		`sequenceDiagram
    participant Worker

    Worker->>Worker: Retry counter++
    Worker->>Worker: Recompute backoff`,
		`sequenceDiagram
    participant User
    participant App

    User->>App: Open settings
    Note right of App: Settings are cached locally
    App-->>User: Show settings page`,
		`sequenceDiagram
    actor User
    participant App

    User->>App: Open settings
    App-->>User: Show preferences`,
		`sequenceDiagram
    participant Worker

    Worker->>Worker: Recalculate cache
    Worker-->>Worker: Cache updated`,
		`sequenceDiagram
    participant User
    participant App

    User->>App: Sign in
    alt Credentials valid
        App-->>User: Redirect to dashboard
    else Credentials invalid
        App-->>User: Show error message
    end`,
		`sequenceDiagram
    participant Shopper
    participant Checkout

    Shopper->>Checkout: Place order
    opt Promo code provided
        Checkout->>Checkout: Apply discount
    end
    Checkout-->>Shopper: Order confirmation`,
		`sequenceDiagram
    participant App
    participant Auth
    participant Profile
    participant Billing

    App->>Auth: Validate token
    par Load profile
        App->>Profile: Get profile
        Profile-->>App: Profile data
    and Load billing
        App->>Billing: Get subscription
        Billing-->>App: Billing data
    end
    Auth-->>App: Token valid`,
		`sequenceDiagram
    participant Client
    participant Inventory
    participant Payment

    Client->>Inventory: Reserve item
    critical Atomic checkout
        Inventory->>Payment: Charge card
        Payment-->>Inventory: Payment success
    option Payment failed
        Inventory-->>Client: Reservation released
    end
    Inventory-->>Client: Order completed`,
		`sequenceDiagram
    participant User
    participant API

    User->>API: Request export
    break Rate limit exceeded
        API-->>User: 429 Too Many Requests
    end
    API-->>User: Export ready`,
		`sequenceDiagram
    participant Browser
    participant App
    participant DB

    rect rgb(235, 245, 255)
        Browser->>App: Submit search
        App->>DB: Query records
        DB-->>App: Results
        App-->>Browser: Render results
    end`,
		`sequenceDiagram
    autonumber
    participant User
    participant API
    participant DB

    User->>API: Create item
    API->>DB: Insert row
    DB-->>API: Inserted
    API-->>User: 201 Created`,
		`sequenceDiagram
    participant Client
    participant TempSession

    Client->>TempSession: Start temporary session
    TempSession-->>Client: Session active
    Client->>TempSession: Close session
    destroy TempSession`,
		`sequenceDiagram
    participant User
    participant App

    User->>App: Start report generation
    create participant JobRunner
    App->>JobRunner: Spawn background job
    JobRunner-->>App: Job started
    App-->>User: Report is processing`,
		`sequenceDiagram
    participant MobileApp
    participant Gateway
    participant AuthService
    participant OrdersService

    MobileApp->>Gateway: GET /orders
    activate Gateway
    Gateway->>AuthService: Validate JWT
    activate AuthService
    AuthService-->>Gateway: User claims
    deactivate AuthService

    Note right of Gateway: Forward request with user context

    Gateway->>OrdersService: Fetch orders
    activate OrdersService
    OrdersService-->>Gateway: Order list
    deactivate OrdersService

    Gateway-->>MobileApp: 200 OK + JSON
    deactivate Gateway`,
		`sequenceDiagram
    participant Client
    participant API
    participant Queue
    participant Worker

    Client->>API: Submit video for processing
    API->>Queue: Enqueue job
    API-->>Client: 202 Accepted

    loop Retry until worker available
        Worker->>Queue: Pull next job
        alt Job available
            Queue-->>Worker: Video job
        else No job yet
            Queue-->>Worker: Empty
        end
    end

    Note over Worker: Video processing may take several minutes`,
		`sequenceDiagram
    autonumber
    actor User
    participant Frontend
    participant AuthAPI
    participant AuditLog
    participant Email

    User->>Frontend: Submit username/password
    Frontend->>AuthAPI: POST /login

    alt Login successful
        par Record audit log
            AuthAPI->>AuditLog: Write login success event
        and Optional alert
            opt New device detected
                AuthAPI->>Email: Send new device alert
            end
        end
        AuthAPI-->>Frontend: Access token
        Frontend-->>User: Redirect to app
    else Login failed
        AuthAPI->>AuditLog: Write failed login event
        AuthAPI-->>Frontend: 401 Unauthorized
        Frontend-->>User: Show login error
    end`,
		`sequenceDiagram
    participant Customer
    participant Storefront
    participant Inventory
    participant Payment
    participant Shipping

    Customer->>Storefront: Checkout cart

    rect rgb(245, 255, 245)
        Note over Storefront,Shipping: Order orchestration begins

        Storefront->>Inventory: Reserve items
        Inventory-->>Storefront: Reserved

        critical Finalize payment and shipment
            Storefront->>Payment: Authorize payment
            Payment-->>Storefront: Authorized
            Storefront->>Shipping: Create shipment
            Shipping-->>Storefront: Shipment created
        option Shipment creation failed
            Storefront->>Payment: Void authorization
            Payment-->>Storefront: Authorization voided
        end
    end

    alt All steps succeeded
        Storefront-->>Customer: Order confirmed
    else Failure occurred
        Storefront-->>Customer: Checkout failed
    end`,
		`sequenceDiagram
    autonumber
    actor Customer
    participant WebApp
    participant API
    participant Auth
    participant Catalog
    participant Inventory
    participant Payment
    participant Notification
    participant Analytics

    Customer->>WebApp: Click "Buy now"
    WebApp->>API: POST /purchase
    activate API

    API->>Auth: Validate session
    activate Auth
    Auth-->>API: Session valid
    deactivate Auth

    par Fetch product data
        API->>Catalog: Get product details
        activate Catalog
        Catalog-->>API: Product details
        deactivate Catalog
    and Check stock
        API->>Inventory: Check availability
        activate Inventory
        Inventory-->>API: In stock
        deactivate Inventory
    end

    alt Product available
        opt Customer included coupon
            API->>API: Apply discount rules
        end

        critical Commit purchase
            API->>Payment: Capture payment
            activate Payment
            Payment-->>API: Payment confirmed
            deactivate Payment

            API->>Inventory: Deduct stock
            activate Inventory
            Inventory-->>API: Stock updated
            deactivate Inventory
        option Payment failed
            Note right of API: Stop flow before inventory mutation
        end

        alt Purchase committed
            par Notify customer
                API->>Notification: Send receipt
                activate Notification
                Notification-->>API: Receipt queued
                deactivate Notification
            and Track analytics
                API->>Analytics: Record purchase event
                activate Analytics
                Analytics-->>API: Event stored
                deactivate Analytics
            end
            API-->>WebApp: 200 Purchase complete
            WebApp-->>Customer: Show confirmation page
        else Commit failed
            API-->>WebApp: 409 Purchase failed
            WebApp-->>Customer: Show retry message
        end
    else Out of stock
        API-->>WebApp: 409 Out of stock
        WebApp-->>Customer: Show unavailable message
    end

    deactivate API`,
		`sequenceDiagram
    participant Cache

    Cache->>Cache: Recompute eviction policy
    Cache-->>Cache: Policy updated`,
		`sequenceDiagram
    participant Browser
    participant API

    Browser->>API: Send a request containing a deliberately over-explained label to see how Mermaid wraps or stretches the message text in the renderer
    API-->>Browser: Return a response with an equally verbose description for layout testing`,
		`sequenceDiagram
    participant U as Extremely Verbose End User
    participant S as Somewhat Overengineered Backend Service

    U->>S: Submit form
    Note right of S: This note is intentionally long<br/>and split over multiple lines<br/>to test spacing and wrapping.
    S-->>U: Accepted`,
		`sequenceDiagram
    participant Client
    participant Gateway
    participant Worker

    Client->>Gateway: Submit job

    rect rgb(235, 245, 255)
        Gateway->>Worker: Start processing
        Worker->>Worker: Retry parsing malformed input
        Worker-->>Gateway: Done
    end

    Gateway-->>Client: Result ready`,
		`sequenceDiagram
    participant JobRunner

    JobRunner->>JobRunner: poll
    JobRunner->>JobRunner: poll again
    JobRunner->>JobRunner: perform an unusually long internal bookkeeping step with a very wide label
    JobRunner-->>JobRunner: ok`,
		`%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#f4f4ff",
    "primaryBorderColor": "#7a7aff",
    "lineColor": "#444",
    "secondaryColor": "#fff4e6",
    "tertiaryColor": "#eef9f1"
  }
}}%%
sequenceDiagram
    actor User
    participant App
    participant DB

    User->>App: Save settings
    activate App
    App->>DB: Write preferences
    activate DB
    DB-->>App: Stored
    deactivate DB
    App-->>User: Success
    deactivate App`,
		`sequenceDiagram
    participant A
    participant B

    A->>B: ok
    B->>A: This label is intentionally much, much, much longer than the previous one so you can see how the diagram stretches unevenly`,
		`sequenceDiagram
    participant Worker

    activate Worker
    Worker->>Worker: parse chunk 1
    Worker->>Worker: parse chunk 2
    Worker->>Worker: parse chunk 3 with a suspiciously long status label for layout testing
    deactivate Worker`,
	],
	[
		`mindmap
    Root
        A
            B
            C`,
		`mindmap
    root[Square]
        A
        B`,
		`mindmap
    root(Rounded square)
        A
        B`,
		`mindmap
    root((Circle))
        A
        B`,
		`mindmap
    root)Cloud(
        A
        B`,
		`mindmap
    root{{Hexagon}}
        A
        B`,
		`mindmap
    Root
        A
            B
          C`,
		`mindmap
    Root
        A
        B
            C
            D
        E
            F`,
		`mindmap
    Project
        Planning
            Requirements
            Timeline
        Development
            Frontend
            Backend
            Database
        Testing
            Unit tests
            Integration`,
		`mindmap
    Web Development
        Frontend
            HTML
            CSS
            JavaScript
                React
                Vue
                Angular
        Backend
            Node.js
            Python
            Go
        DevOps
            Docker
            CI/CD
            Monitoring`,
		`mindmap
    Company
        Engineering
            Platform
            Product
            Infrastructure
        Design
            UX
            Visual
        Marketing
            Content
            Analytics`,
		`mindmap
    root((Central Idea))
        Branch A
            Leaf 1
            Leaf 2
            Leaf 3
        Branch B
            Leaf 4
            Leaf 5
        Branch C
            Leaf 6`,
		`mindmap
    root[Decision]
        (Option A)
            Pro 1
            Pro 2
        (Option B)
            Pro 3
            Con 1
        (Option C)
            Pro 4`,
		`mindmap
    Release Plan
        v1.0
            Core features
            Bug fixes
            Documentation
        v1.1
            Performance
            New API
        v2.0
            Breaking changes
            Migration guide
            New architecture`,
		`mindmap
    Onboarding
        Day 1
            Setup
            Intro meeting
            Codebase tour
        Week 1
            First PR
            Code review
            Team lunch
        Month 1
            Own a feature
            Present to team`,
		`mindmap
    root((tldraw))
        Editor
            Shapes
            Tools
            Bindings
        Store
            Records
            Signals
        UI
            Components
            Styles
        Sync
            Multiplayer
            Persistence`,
		`mindmap
    Debugging
        Check logs
            Server logs
            Client console
        Reproduce
            Steps
            Environment
        Fix
            Root cause
            Regression test
        Deploy
            Staging
            Production`,
		`mindmap
    root[Quarterly Goals]
        Reliability
            Uptime target
            Alerting
            Incident response
        Growth
            New users
            Retention
            Activation
        Platform
            API v2
            SDK improvements
            Documentation`,
		`mindmap
    Meal Planning
        Monday
            Breakfast
            Lunch
            Dinner
        Tuesday
            Breakfast
            Lunch
            Dinner
        Wednesday
            Breakfast
            Lunch
            Dinner`,
		`mindmap
    root((AI))
        Machine Learning
            Supervised
                Classification
                Regression
            Unsupervised
                Clustering
                Dimensionality Reduction
        Deep Learning
            CNNs
            RNNs
            Transformers
        Applications
            NLP
            Computer Vision
            Robotics`,
		`mindmap
  root((System Architecture))
    Layer 1
      Layer 2
        Layer 3
          Layer 4
            Layer 5
              Layer 6
                Layer 7
                  Layer 8
                    Layer 9
                      Layer 10`,
		`mindmap
  root((Wide Node))
    A1
    A2
    A3
    A4
    A5
    A6
    A7
    A8
    A9
    A10
    A11
    A12
    A13`,
		`mindmap
  root((Product))
    Design
      UX
        Research
        Personas
      UI
    Engineering
      Backend
        APIs
        DB
      Frontend
        Components
        State
    Marketing
      SEO
      Ads
      Social`,
		`mindmap
  root((Documentation))
    "This is a very long node label intended to test text wrapping and overflow behavior"
      "Another extremely verbose and descriptive child node that could break layouts"
        "Even deeper explanation with excessive verbosity and complexity"`,
		`mindmap
  root((Company))
    CEO
      Strategy
    CTO
      Engineering
        Platform
          Infra
            Kubernetes
    Intern`,
		`mindmap
  root((Duplicates))
    Node
      Node
        Node
    Node
      Node`,
		`mindmap
  root((Numbers))
    1
      1.1
        1.1.1
    2
      2.1
      2.2
    3`,
		`mindmap
  root((AI System))
    Data
      Collection
      Cleaning
      Labeling
    Model
      Training
      Evaluation
      Deployment
    Ethics
      Bias
      Privacy
      Transparency`,
		`mindmap
  root((Hybrid))
    A
      A1
        A1a
        A1b
      A2
    B
      B1
      B2
      B3
        B3a
          B3a1
    C`,
		`mindmap
  root((Uneven))
    Short
    Medium
      Mid1
      Mid2
    VeryLong
      L1
        L2
          L3
            L4
              L5`,
		`mindmap
  root((Knowledge))
    Science
      Physics
      Chemistry
      Biology
    Arts
      Music
      Painting
      Dance
    Technology
      Software
      Hardware
      AI`,
		`mindmap
  root((Decision))
    Start
      Yes
        Continue
          Optimize
      No
        Stop
        Retry`,
		`mindmap
  root((Edge))
    ""
    " "
    "   "
    Filled`,
	],
]
```

--------

# Pasting Mermaid code as shapes

Category: Use cases

Keywords: mermaid, diagram, paste, external content

Paste Mermaid source onto the canvas and get native tldraw shapes.

A custom `text` external content handler (`editor.registerExternalContentHandler`) checks whether pasted text looks like a Mermaid diagram. If it does, `createMermaidDiagram` from `@tldraw/mermaid` turns it into geo shapes, arrows, and text; otherwise the default text handler runs.

Flowcharts, state diagrams, sequence diagrams, and mind maps become native shapes. Other diagram types are rendered by Mermaid to SVG and pasted as an image, with a toast to say so.

Try copying this and pasting it onto the canvas:

```
graph TD
    A[Start] --> B{Is it correct?}
    B -- Yes --> C[Display diagram]
    B -- No --> D[Edit code]
    D --> B
    C --> E[End]
```

## App.tsx

```tsx
import { useEffect } from 'react'
import { Tldraw, defaultHandleExternalTextContent, useEditor, useToasts } from 'tldraw'
import 'tldraw/tldraw.css'

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

function MermaidPasteHandler() {
	const editor = useEditor()
	const { addToast } = useToasts()

	useEffect(() => {
		// [1]
		editor.registerExternalContentHandler('text', async (content) => {
			// [2]
			const plainTextSource = content.sources?.find(
				(s) => s.type === 'text' && s.subtype === 'text'
			)
			const plainText = plainTextSource?.data ?? content.text
			const textToTest = simpleMermaidStringTest(plainText) ? plainText : content.text

			if (!simpleMermaidStringTest(textToTest)) {
				await defaultHandleExternalTextContent(editor, content)
				return
			}
			const mermaidText = stripMarkdownMermaidFence(textToTest)
			const { createMermaidDiagram } = await import('@tldraw/mermaid')
			const shapesBefore = new Set(editor.getCurrentPageShapeIds())

			const selectNewShapes = () => {
				const newShapeIds = [...editor.getCurrentPageShapeIds()].filter(
					(id) => !shapesBefore.has(id)
				)
				if (newShapeIds.length) {
					editor.setSelectedShapes(newShapeIds)
				}
			}

			try {
				// [3]
				const onUnsupportedDiagram = async (svgString: string) => {
					await editor.putExternalContent({
						type: 'svg-text',
						text: svgString,
						point: content.point,
						sources: content.sources,
					})
					addToast({
						id: 'unsupported-mermaid-diagram',
						title: 'Unsupported mermaid diagram',
						description: 'This diagram is not supported yet',
						severity: 'warning',
					})
				}

				await createMermaidDiagram(editor, mermaidText, { onUnsupportedDiagram })
				selectNewShapes()
			} catch (e) {
				console.error(e)
				await defaultHandleExternalTextContent(editor, content)
			}
		})
	}, [editor, addToast])

	return null
}

/**
 * Lightweight mermaid detection replicating mermaid's own detectType preprocessing
 * (from mermaid v11.12.2 src/diagram-api/detectType.ts and src/diagram-api/regexes.ts).
 *
 * https://github.com/mermaid-js/mermaid/blob/277c4967f97405e9bb172c0a2f67f462a672b162/packages/mermaid/src/diagram-api/detectType.ts
 * https://github.com/mermaid-js/mermaid/blob/277c4967f97405e9bb172c0a2f67f462a672b162/packages/mermaid/src/diagram-api/regexes.ts
 *
 * Strips YAML frontmatter, %%{...}%% directives, and %% comments, then tests for
 * a known diagram keyword at the start of the cleaned text. It has no mermaid
 * import so the heavy library is only loaded once a diagram is actually detected.
 */
const FRONTMATTER_REGEX = /^-{3}\s*[\n\r]([\s\S]*?)[\n\r]-{3}\s*[\n\r]+/
const DIAGRAM_KEYWORD_REGEX =
	/^\s*(flowchart|graph|sequenceDiagram|classDiagram|stateDiagram|erDiagram|journey|gantt|pie|gitGraph|mindmap|timeline|sankey|xychart|block|quadrantChart|requirement|C4Context|C4Container|C4Component|C4Dynamic|C4Deployment|packet|kanban|architecture|treemap|radar|info)/

/**
 * Leading ```mermaid (or longer run) fence, closed by the first line that ends
 * the same run length (CommonMark-style: inner shorter ``` lines do not close a
 * longer fence). Trailing markdown after the block is allowed so multi-block
 * pastes do not pull in later fences. Group 1 = fence run, group 2 = diagram body.
 */
const MARKDOWN_MERMAID_FENCE_REGEX =
	/^\s*(```+)\s*mermaid\s*\r?\n([\s\S]*?)\r?\n\s*\1\s*(?:[\s\S]*)$/

/**
 * Strip mermaid boilerplate (frontmatter, directives, comments) so only the
 * diagram body remains. The two global regexes are created as fresh literals
 * each call to avoid the stateful-lastIndex footgun of module-level /g regexes.
 */
function stripMermaidBoilerplate(text: string): string {
	return text
		.replace(FRONTMATTER_REGEX, '')
		.replace(/%{2}{\s*(?:(\w+)\s*:|(\w+))\s*(?:(\w+)|((?:(?!}%{2}).|\r?\n)*))?\s*(?:}%{2})?/gi, '')
		.replace(/\s*%%.*\n/gm, '\n')
}

function stripMarkdownMermaidFence(text: string): string {
	const match = text.match(MARKDOWN_MERMAID_FENCE_REGEX)
	return match ? match[2] : text
}

function simpleMermaidStringTest(text: string): boolean {
	return DIAGRAM_KEYWORD_REGEX.test(stripMermaidBoilerplate(stripMarkdownMermaidFence(text)))
}

/*
[1]
`registerExternalContentHandler('text', ...)` replaces the default handler for pasted text.
Anything that doesn't look like Mermaid is passed on to `defaultHandleExternalTextContent`
so ordinary text still pastes as a text shape.

[2]
When HTML is pasted, the derived `content.text` has its line breaks stripped, which makes
Mermaid unparseable. The clipboard usually carries a plain-text source alongside the HTML,
so we prefer that when it looks like a diagram.

[3]
`createMermaidDiagram` creates native shapes for flowcharts, state diagrams, sequence
diagrams, and mind maps. For other diagram types it calls `onUnsupportedDiagram` with
Mermaid's SVG, which we drop onto the canvas as an image via `putExternalContent`.
*/
```

--------

# Snowstorm

Category: Use cases

Keywords: overlay, visual effects, animation, css, children, layering, infrontofthecanvas

Animate a snowstorm over the canvas that reacts to camera movement and the pointer.

The `SnowStorm` component is passed as a child of `Tldraw`, so it renders inside the editor container above the canvas. It listens to the editor's `tick` event and moves a set of absolutely positioned DOM snowflakes each frame, adding wind from camera movement (`editor.getCamera()`) and pushing flakes near a fast pointer (`editor.inputs.getPointerVelocity()`). It does nothing when the OS "reduce motion" preference is on (`usePrefersReducedMotion`).

Try panning the canvas quickly, or waving the pointer through the snow.

## App.tsx

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

export default function SnowStormExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw persistenceKey="snowstorm-example">
				{/* Children of Tldraw render inside the editor container, above the canvas */}
				<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

	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()
	}

	render(screenPoint: Vec, pointerVelocity: Vec, time: number) {
		if (!this.active) return

		// slow sinusoidal gusts
		this.baseWindX = Math.sin(time / GUST_ROTATION_DURATION) * MAX_GUST_SPEED

		const pointerLen = pointerVelocity.len2()

		for (const flake of this.flakes) {
			const dist2 = Vec.Dist2(screenPoint, new Vec(flake.x, flake.y))

			// a fast-moving pointer pushes nearby flakes; flakes it leaves behind slow back down
			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 {
				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
						}
					}
				}
			}

			flake.x += flake.vx + this.windX + this.baseWindX + flake.pvx
			flake.y += flake.vy + this.windY + flake.pvy

			// wrap around the screen
			if (flake.x < 0) {
				flake.x += this.width
				flake.pvx = 0
			} else if (flake.x > this.width) {
				flake.x -= this.width
				flake.pvx = 0
			}

			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
	}

	// Bound once so the same reference can be removed in stop()
	private handleResize = this.resize.bind(this)

	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.handleResize)
	}

	stop() {
		this.active = false
		for (const flake of this.flakes) {
			this.container.removeChild(flake.element)
		}
		this.flakes = []
	}

	dispose() {
		this.stop()
		window.removeEventListener('resize', this.handleResize)
	}
}

export function SnowStorm() {
	const editor = useEditor()
	const rElm = useRef<HTMLDivElement>(null)
	// [1]
	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()

		// [2]
		function updateOnTick() {
			const time = Date.now() - start

			const newCamera = editor.getCamera()

			// [3]
			if (newCamera.z === camera.z) {
				const dx = (newCamera.x - camera.x) * camera.z
				const dy = (newCamera.y - camera.y) * camera.z

				velocity.addXY(
					Math.min(dx / MAX_PIXELS_SCROLL_EFFECT, MAX_SCROLL_SPEED),
					Math.min(dy / MAX_PIXELS_SCROLL_EFFECT, MAX_SCROLL_SPEED)
				)
				velocity.mul(SNOWFLAKE_VELOCITY_DECAY)
				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" />
}

/*
[1]
Respect the OS "reduce motion" setting: no snow at all when it is on.

[2]
The editor emits a `tick` event every animation frame with the editor's own timing, so
hooking into it keeps the effect in step with the canvas and stops with it. Positions are
written straight to the DOM rather than through React state.

[3]
Panning the camera adds "wind" so the snow appears to blow past as you scroll. This is skipped
while zooming since the camera position changes then without any real scrolling.
`editor.inputs.getPointerVelocity()` also nudges flakes near a fast-moving pointer.
*/
```

## 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, store.listen, RecordsDiff, squashRecordDiffs, reverseRecordsDiff, applyDiff, document changes

Record every document change as a diff and scrub back and forth through the history with a slider.

`editor.store.listen` (scoped to `document` changes from the `user` source) captures a `RecordsDiff` for every edit. Dragging the slider collects the diffs between the current and target positions, squashes them with `squashRecordDiffs`, reverses them with `reverseRecordsDiff` when going backwards, and applies the result with `store.applyDiff` inside `store.mergeRemoteChanges` so the listener does not record the time travel itself.

Try drawing a few shapes, then drag the slider back. Make a change while scrubbed back and the later entries are discarded, starting a new branch from that point.

## App.tsx

```tsx
import { useCallback, useEffect, useState } from 'react'
import {
	RecordsDiff,
	reverseRecordsDiff,
	squashRecordDiffs,
	Tldraw,
	TldrawUiSlider,
	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>
	)
}

function TimelineScrubber() {
	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]
			const newEntries = [...prev.entries.slice(0, prev.currentIndex), newEntry]
			return {
				entries: newEntries,
				currentIndex: newEntries.length,
			}
		})
	}, [])

	// [3]
	useEffect(() => {
		return editor.store.listen(
			({ changes }) => {
				recordChange(changes)
			},
			{ scope: 'document', source: 'user' }
		)
	}, [editor, recordChange])

	// [4]
	const navigateToIndex = useCallback(
		(targetIndex: number) => {
			if (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 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={navigateToIndex}
			/>
		</div>
	)
}

/*
[1]
Each store change becomes one timeline entry holding its `RecordsDiff`. Index 0 is the empty
canvas, index n is the state after the nth change.

[2]
If the user edits while scrubbed back (`currentIndex < entries.length`), the entries after
the current point are discarded and the new change starts a fresh branch from there.

[3]
`store.listen` with `scope: 'document'` ignores presence and session records (camera,
selection), and `source: 'user'` ignores changes we apply ourselves during navigation, so
time travel doesn't record itself.

[4]
Moving from one index to another collects the diffs in between, squashes them into one with
`squashRecordDiffs`, reverses it with `reverseRecordsDiff` when going backwards, and applies
it inside `store.mergeRemoteChanges` so it arrives with `source: 'remote'` and is neither
recorded by our listener nor pushed onto the undo stack.
*/
```

## 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(--tl-color-panel);
	border-bottom: 1px solid var(--tl-color-muted-1);
	font-size: 12px;
	color: var(--tl-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);
}
```