write-example

Writing tldraw examples

The examples project (apps/examples) contains minimal demonstrations of how to use the tldraw SDK. Examples are embedded on the docs site and deployed to examples.tldraw.com.

Standards for examples in apps/examples/src/examples.

Example structure

Each example lives in its own folder:

apps/examples/src/examples/
└── my-example/
    ├── README.md          # Required metadata
    ├── MyExampleExample.tsx  # Main example file
    └── my-example.css     # Optional styles

Folder name

• Lowercase kebab-case: custom-canvas, button-demo, magical-wand
• Used as the URL path for the example

README.md

Required frontmatter format:

---
title: Example title
component: ./ExampleFile.tsx
category: category-id
priority: 1
keywords: [keyword1, keyword2]
---

One-line summary of what this example demonstrates.

---

Detailed explanation of the example. Include code snippets here if they help explain concepts not obvious from the example code itself.

Frontmatter fields

Field	Description
title	Sentence case, corresponds to folder name
component	Relative path to example file
category	One of the valid category IDs (see below)
priority	Display order within category (lower = higher)
keywords	Search terms (avoid obvious terms like "tldraw")

Valid categories

getting-started, configuration, editor-api, ui, layout, events, shapes/tools, collaboration, data/assets, use-cases

Example file

Naming

• PascalCase ending with "Example": CustomCanvasExample.tsx, ButtonExample.tsx
• Name should correspond to the folder name and title

Structure

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

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

Requirements:

• Must have a default export React component
• Use tldraw__editor class for full-page examples
• Import tldraw/tldraw.css for styles

Layout

• Full page: wrap in <div className="tldraw__editor">
• Inset: see existing examples for page layout patterns

Styles

• Put CSS in a separate file named after the example: my-example.css
• Import alongside tldraw CSS: import './my-example.css'
• Avoid extensive inline styles via the style prop

Control panels

For examples that need buttons or controls, use the TopPanel component slot with TldrawUiButton:

import { Tldraw, TldrawUiButton, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './my-example.css'

function MyControls() {
	const editor = useEditor()
	return (
		<div className="tlui-menu my-controls">
			<TldrawUiButton type="normal" onClick={() => editor.zoomIn()}>
				Zoom in
			</TldrawUiButton>
			<TldrawUiButton type="normal" onClick={() => editor.zoomOut()}>
				Zoom out
			</TldrawUiButton>
		</div>
	)
}

export default function MyExampleExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw components={{ TopPanel: MyControls }} />
		</div>
	)
}

CSS for control panels:

.my-controls {
	display: flex;
	flex-wrap: wrap;
	margin: 8px;
}

Comments

Use footnote format with numbered references:

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

// [1]
const components: TLComponents = {
	PageMenu: null,
}

export default function CustomComponentsExample() {
	return (
		<div className="tldraw__editor">
			{/* [2] */}
			<Tldraw components={components} />
		</div>
	)
}

/*
[1]
Define component overrides outside the React component so they're static.
If defined inside, use useMemo to prevent recreation on every render.

[2]
Pass component overrides via the components prop.
*/

Example types

Tight examples

• Narrow focus on a specific SDK feature
• Minimal styling
• Meant to be read, not used
• Remove any extraneous code

Use-case examples

• Show a recognizable user experience
• Prioritize clarity and completeness
• Category: use-cases

Additional files

• Split complex code into separate files if it distracts from the example's purpose
• Example: complex input component in Input.tsx
• Keep the main example file focused on demonstrating the concept

Important

• Follow React and TypeScript best practices
• Never use title case for titles - use sentence case
• Keep examples minimal and focused