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

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:

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:

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 drag detection. 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:

The camera and deepLinks options replace the deprecated cameraOptions and deepLinks props on the component. See Camera for the camera options.

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. Zoomed out, the grid uses larger steps; zoomed in, finer ones.

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

Clipboard hooks

These callbacks let you intercept and customize clipboard operations:

See Clipboard for more details on clipboard operations.

Drop 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

Customize which embed types the editor recognizes using EmbedShapeUtil.configure():

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 for the full embed definition API.

Editor setup

These props configure how the editor initializes:

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:

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