Quick start

Get a working infinite canvas in your React app

Quick start

Get tldraw running in your React app in just a few steps. This guide walks you through creating a basic infinite canvas with the full tldraw UI and default tools.

Basic setup

The simplest way to use tldraw is to import the <Tldraw /> component and render it with a fixed container:

1. Import tldraw

   Import the Tldraw component and CSS stylesheet:

   import { Tldraw } from 'tldraw'
   import 'tldraw/tldraw.css'
   
2. Render the component

   Add the <Tldraw /> component to your app:

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

   Start your development server and visit your app:

   npm run dev
   

   You should see a fully functional infinite canvas with drawing tools, shapes, and UI controls.

The container must have explicit dimensions. Using position: fixed with inset: 0 ensures the canvas fills the viewport.

Complete example

Here’s a complete working example:

App.tsx

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

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

This gives you:

• Full infinite canvas with pan and zoom
• Drawing tools (pencil, highlighter, eraser)
• Shape tools (rectangles, ellipses, arrows, text, sticky notes)
• Selection and manipulation tools
• Complete UI with toolbars, menus, and panels
• Undo/redo functionality
• Keyboard shortcuts
• Multi-touch and pen support

Accessing the editor instance

To interact with the canvas programmatically, access the Editor instance using the onMount callback:

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

export default function App() {
  function handleMount(editor: Editor) {
    // Access the editor instance
    console.log('Canvas mounted with', editor.getCurrentPageShapes().length, 'shapes')

    // Create a shape programmatically
    editor.createShape({
      type: 'geo',
      x: 100,
      y: 100,
      props: {
        w: 200,
        h: 150,
        geo: 'rectangle',
        text: 'Hello tldraw!',
      },
    })
  }

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

Storing the editor reference

To access the editor instance outside the component, store it in a ref or state:

import { Tldraw, Editor } from 'tldraw'
import 'tldraw/tldraw.css'
import { useRef } from 'react'

export default function App() {
  const editorRef = useRef<Editor | null>(null)

  function handleMount(editor: Editor) {
    editorRef.current = editor
  }

  function handleCreateShape() {
    if (!editorRef.current) return

    editorRef.current.createShape({
      type: 'text',
      x: 250,
      y: 250,
      props: {
        text: 'Created from a button!',
      },
    })
  }

  return (
    <>
      <button 
        onClick={handleCreateShape}
        style={{ position: 'fixed', top: 10, left: 10, zIndex: 1000 }}
      >
        Add Text Shape
      </button>
      <div style={{ position: 'fixed', inset: 0 }}>
        <Tldraw onMount={handleMount} />
      </div>
    </>
  )
}

Persisting canvas data

By default, tldraw stores canvas data in memory and the browser’s IndexedDB. To implement custom persistence:

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

export default function App() {
  function handleMount(editor: Editor) {
    // Load saved data
    const savedData = localStorage.getItem('my-tldraw-data')
    if (savedData) {
      editor.store.loadSnapshot(JSON.parse(savedData))
    }

    // Save data on every change
    editor.store.listen(
      () => {
        const snapshot = editor.store.getSnapshot()
        localStorage.setItem('my-tldraw-data', JSON.stringify(snapshot))
      },
      { scope: 'document', source: 'user' }
    )
  }

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

The example above saves on every change, which can be expensive. For production apps, consider debouncing or using the built-in persistence features.

Common container patterns

Fixed viewport

// Fills the entire browser window
<div style={{ position: 'fixed', inset: 0 }}>
  <Tldraw />
</div>

Default features

The <Tldraw /> component includes:

Tools

• Select - Select and manipulate shapes
• Hand - Pan around the canvas
• Draw - Freehand drawing with pressure sensitivity
• Eraser - Remove drawn segments
• Arrow - Connect shapes with arrows
• Text - Add rich text
• Note - Create sticky notes
• Geo shapes - Rectangles, ellipses, diamonds, hexagons, stars, and more
• Line - Straight lines
• Frame - Group shapes in frames
• Highlight - Transparent highlighter
• Laser - Temporary pointer (disappears after drawing)

UI components

• Toolbar - Quick access to shape and drawing tools
• Style panel - Customize colors, sizes, and other properties
• Main menu - File operations and preferences
• Context menu - Right-click options
• Zoom menu - Zoom controls
• Page menu - Multi-page support
• Helper buttons - Undo, redo, and other quick actions

Built-in features

• Pan and zoom (mouse wheel, trackpad, touch)
• Multi-selection with shift-click or drag
• Precision snapping to shapes and guides
• Arrow binding to shapes
• Edge scrolling when dragging near viewport edges
• Undo/redo with keyboard shortcuts
• Copy/paste with formatting
• Image and video embedding
• Export to PNG, SVG, and JSON

Next steps

Now that you have a working canvas, explore how to customize and extend tldraw:

Custom shapes

Create custom shape types

Custom tools

Build custom interaction tools

Editor API

Control the canvas programmatically

UI customization

Customize the user interface

Starter templates

For framework-specific setup with best practices, use the tldraw CLI:

npx create-tldraw@latest

This provides templates for:

• Multiplayer - Real-time collaboration with @tldraw/sync
• Agent - AI agents that interact with the canvas
• Workflow - Node-based visual programming
• Chat - AI chat with canvas integration
• Vite - Minimal Vite + React setup
• Next.js - Next.js App Router setup
• Vue - Vue.js integration

Need help? Join the tldraw Discord to ask questions and get support from the community.