---

name: tldraw description: tldraw infinite canvas SDK for React. Use when: (1) Creating whiteboard/canvas applications, (2) Building diagramming tools, (3) Programmatically creating and managing shapes, (4) Setting up real-time collaboration, (5) Exporting canvas as SVG/PNG/JSON, (6) Customizing tools, shapes, or UI.

tldraw SDK

Infinite canvas platform for building whiteboard, diagramming, and collaborative tools in React.

Website: https://tldraw.com
Docs: https://tldraw.dev
GitHub: https://github.com/tldraw/tldraw
NPM: npm install tldraw @tldraw/sync

Quick Start

Basic Canvas

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

export default function App() {
  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <Tldraw />
    </div>
  )
}

This gives you a full working canvas with drawing, shapes, text, images, undo/redo, copy/paste.

Local Persistence

<Tldraw persistenceKey="my-app" />

Saves to browser localStorage. Also syncs between tabs with same key.

Programmatic Control

Access the Editor

import { Editor, Tldraw } from 'tldraw'

function App() {
  const handleMount = (editor: Editor) => {
    // Create a shape
    editor.createShape({
      type: 'text',
      x: 100,
      y: 100,
      props: {
        text: 'Hello World'
      }
    })

    // Select and zoom to it
    editor.selectAll()
    editor.zoomToSelection({ animation: { duration: 1000 } })
  }

  return <Tldraw onMount={handleMount} />
}

Create Shapes

// Text
editor.createShape({
  type: 'text',
  x: 0, y: 0,
  props: { text: 'Hello' }
})

// Rectangle
editor.createShape({
  type: 'geo',
  x: 0, y: 0,
  props: { w: 100, h: 100, geo: 'rectangle' }
})

// Arrow
editor.createShape({
  type: 'arrow',
  x: 0, y: 0,
  props: {
    start: { x: 0, y: 0, type: 'point' },
    end: { x: 100, y: 100, type: 'point' }
  }
})

// Image
editor.createShape({
  type: 'image',
  x: 0, y: 0,
  assetId: 'asset-id'
})

Batch Operations

// Batch multiple changes into one transaction
editor.run(() => {
  editor.createShapes([shape1, shape2, shape3])
  editor.sendToBack(shape1)
  editor.selectNone()
})

// Ignore undo/redo history
editor.run(
  () => editor.createShapes(myShapes),
  { history: 'ignore' }
)

Query Shapes

// Get all shapes on current page
const shapes = editor.getCurrentPageShapes()

// Get selected shapes
const selected = editor.getSelectedShapes()

// Find shape by ID
const shape = editor.getShape(shapeId)

// Get sorted shapes (z-order)
const sorted = editor.getCurrentPageShapesSorted()

Modify Shapes

// Update properties
editor.updateShapes([
  { id: shapeId, type: 'text', props: { text: 'Updated' } }
])

// Delete
editor.deleteShapes([shapeId])

// Move to back/front
editor.sendToBack([shapeId])
editor.bringToFront([shapeId])

// Rotate
editor.rotateShapesBy([shapeId], 45)

// Duplicate
editor.duplicateShapes([shapeId])

Selection

// Select shapes
editor.selectShapes([shapeId1, shapeId2])

// Select all
editor.selectAll()

// Deselect
editor.selectNone()

// Get selected
editor.getSelectedShapeIds()

// Zoom to selection
editor.zoomToSelection()

Camera Control

// Zoom
editor.zoomIn()
editor.zoomOut()
editor.zoomToFit()

// Pan
editor.pan({ x: 100, y: 100 })

// Set viewport
editor.setCamera({
  x: 100,
  y: 100,
  z: 1.5
})

// Zoom to selection with animation
editor.zoomToSelection({
  animation: { duration: 500 }
})

Real-Time Collaboration

Using @tldraw/sync

import { Tldraw } from 'tldraw'
import { useSyncDemo } from '@tldraw/sync'
import 'tldraw/tldraw.css'

export default function App() {
  const store = useSyncDemo({ roomId: 'my-room' })

  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <Tldraw store={store} />
    </div>
  )
}

Features:

• Live cursors with names
• Viewport following
• Cursor chat
• Presence awareness

Open in multiple windows/devices to test.

Export Canvas

SVG Export

const svgString = await editor.getSvgString(shapeIds)
console.log(svgString)

PNG Export

const blob = await editor.getPNGBuffer(shapeIds)
// blob is a Blob of PNG image data

JSON Export (Document Format)

// Get all records (shapes, pages, etc.)
const records = editor.store.allRecords()

// Serialize
const json = JSON.stringify(records)

// Save/send/etc.

Snapshot

// Get current state for debugging/analysis
const json = editor.store.serialize('json')

Events & Reactivity

Listen to Changes

// Track reactive values
import { track } from 'tldraw'

const SelectedCount = track(() => {
  const editor = useEditor()
  return <div>{editor.getSelectedShapeIds().length}</div>
})

Subscribe to Events

const unsub = editor.on('change', () => {
  console.log('Document changed')
  const shapes = editor.getCurrentPageShapes()
})

// Cleanup
unsub()

Store Changes

// React to specific shape updates
editor.on('record', (update) => {
  console.log('Record changed:', update)
})

Tools & Shapes

Available Tools

• select — Selection tool
• draw — Freehand drawing
• eraser — Erase shapes
• text — Add text
• rectangle — Rectangle shape
• diamond — Diamond shape
• ellipse — Ellipse shape
• arrow — Arrow connector
• line — Line shape

Change Current Tool

editor.setCurrentTool('draw')
editor.setCurrentTool('text')

Shape Types

• text — Text box
• geo — Rectangle, diamond, ellipse, cloud, etc.
• arrow — Connectors
• line — Lines
• frame — Artboard/container
• image — Images
• video — Video embeds
• bookmark — Web links (appears as card)

Configuration

Readonly Mode

<Tldraw readOnly />

Disables all editing. Users can view and interact with canvas but can't modify.

Dark Mode

<Tldraw persistenceKey="app" darkMode />

Custom UI

import {
  TldrawEditor,
  UI,
  DefaultToolbar,
  DefaultUiAssetResolver,
} from 'tldraw'

<TldrawEditor {...args}>
  <UI />
  <DefaultToolbar />
</TldrawEditor>

Can replace UI components with custom versions.

Disable Features

editor.updateInstanceState({
  isGridMode: false,  // Hide grid
  showBindings: false, // Hide connection dots
})

Common Patterns

Programmatically Build Diagram

const shapes = []

// Add boxes
for (let i = 0; i < 3; i++) {
  shapes.push({
    type: 'geo',
    x: i * 150,
    y: 0,
    props: {
      w: 100,
      h: 100,
      geo: 'rectangle',
      text: `Item ${i}`
    }
  })
}

// Add connecting arrows
for (let i = 0; i < shapes.length - 1; i++) {
  shapes.push({
    type: 'arrow',
    x: i * 150 + 100,
    y: 50,
    props: {
      start: { type: 'point', x: 0, y: 0 },
      end: { type: 'point', x: 50, y: 0 }
    }
  })
}

editor.run(() => {
  editor.createShapes(shapes)
})

Save/Load Canvas

// Save to backend
async function saveCanvas() {
  const records = editor.store.allRecords()
  await fetch('/api/save', {
    method: 'POST',
    body: JSON.stringify(records)
  })
}

// Load from backend
async function loadCanvas(docId) {
  const response = await fetch(`/api/load/${docId}`)
  const records = await response.json()
  editor.store.deserialize(records, 'json')
}

API Reference

Key Editor Methods:

• createShape(shape) / createShapes(shapes[])
• updateShape(partial) / updateShapes(partial[])
• deleteShape(id) / deleteShapes(id[])
• selectShapes(id[]) / selectAll() / selectNone()
• getSelectedShapeIds() / getSelectedShapes()
• getShape(id) / getCurrentPageShapes()
• sendToBack() / bringToFront() / moveShapesBy()
• rotateShapesBy() / duplicateShapes()
• zoomIn() / zoomOut() / zoomToFit() / zoomToSelection()
• pan(point) / setCamera(viewport)
• setCurrentTool(name) / getCurrentTool()
• undo() / redo()
• getPNGBuffer() / getSvgString()

Resources

• Examples: https://tldraw.dev/examples
• Starter Kits: https://tldraw.dev/starter-kits
• API Reference: https://tldraw.dev/reference
• Discord: https://discord.tldraw.com