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](https://tldraw.dev/examples) and deployed to [examples.tldraw.com](https://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:

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

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

export default function MyExampl