write-example

by tldraw

Writing examples for the tldraw SDK examples app. Use when creating new examples, adding SDK demonstrations, or writing example code in apps/examples. npx skills add https://github.com/tldraw/tldraw --skill write-example Download ZIPGitHub48.5k

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 (
 
 
 

 )
}

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 (
 
 editor.zoomIn()}>
 Zoom in
 
 editor.zoomOut()}>
 Zoom out
 
 

 )
}

export default function MyExampleExample() {
 return (
 
 
 

 )
}

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 (
 
 {/* [2] */}
 
 

 )
}

/*
[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