write-example

SKILL.md

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