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

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