Options

The tldraw editor accepts two kinds of configuration: editor options for core behavior (timing, limits, performance) and component props for features like persistence and custom shapes. Editor options are immutable after initialization; component props configure how the editor sets up.

Editor options

The options prop accepts a Partial<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 sensible defaults.

import { Tldraw, TldrawOptions } from 'tldraw'

const options: Partial<TldrawOptions> = {
	maxPages: 3,
	maxShapesPerPage: 1000,
}

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

The TldrawOptions type defines all available options. Since you typically only need to customize a few values, pass Partial<TldrawOptions> to override specific options while accepting defaults for the rest.

Reading options at runtime

After the editor initializes, access options through editor.options:

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

Control maximum quantities to prevent performance issues or enforce business rules:

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:

Drag detection

Control when pointer movement becomes a drag operation:

Values are squared to avoid computing square roots during hit testing. The larger touch thresholds prevent accidental drags on mobile devices.

Handle and hit testing

Configure selection handles and click target areas:

Edge scrolling

Configure auto-scroll behavior when dragging near viewport edges:

See Edge scrolling for details on how these options affect behavior.

Camera

Control camera movement and viewport behavior:

Snapping

Collaboration

Configure timing for collaborator presence:

Export

Configure image and SVG export behavior:

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:

const options: Partial<TldrawOptions> = {
	exportProvider: ({ children }) => <ThemeProvider theme={myTheme}>{children}</ThemeProvider>,
}

Grid

Configure the alignment grid:

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. At lower zoom levels, larger grid steps are used; at higher zoom levels, finer grid steps appear.

Performance

Options that affect rendering performance:

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

The actionShortcutsLocation option controls where keyboard shortcuts appear:

• 'menu' - Show shortcuts in menu items only
• 'toolbar' - Show shortcuts in toolbar tooltips only
• 'swap' - Show in menus when toolbar is collapsed, toolbar when expanded

Asset handling

Default values

The defaultTldrawOptions export provides all default values:

import { defaultTldrawOptions } from 'tldraw'

console.log(defaultTldrawOptions.maxPages) // 40

Use this to check defaults or spread into your own options:

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

The hideUi prop is useful when building custom interfaces around the canvas:

function CustomEditor() {
	return (
		<Tldraw hideUi>
			<MyCustomToolbar />
		</Tldraw>
	)
}

External content handling

These props control how the editor handles dropped or pasted files:

function App() {
	return (
		<Tldraw
			maxImageDimension={2000}
			maxAssetSize={5 * 1024 * 1024} // 5 MB
			acceptedImageMimeTypes={['image/png', 'image/jpeg']}
		/>
	)
}

Embeds

The embeds prop customizes which embed types the editor recognizes:

import { Tldraw, TLEmbedDefinition } from 'tldraw'

const customEmbeds: TLEmbedDefinition[] = [
	{
		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 embeds={customEmbeds} />
}

Editor setup

These props configure how the editor initializes:

The getShapeVisibility callback lets you conditionally hide shapes based on their properties:

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

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 - Override default options like max pages and animation speed.
• Disable pages - Set maxPages to 1 to create a single-page editor.