No history yet

Tldraw Core Integration

Setting Up Your Canvas

First, you need to add the tldraw library to your React project. It’s a single package that contains everything you need to get a full-featured canvas up and running.

npm install tldraw

With the package installed, the next step is to import the core component and its required stylesheet into your application. The CSS handles the default UI, icons, and themes.

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

Rendering the Component

The <Tldraw /> component is the heart of the library. Placing it in your JSX is all it takes to render a complete infinite canvas with a default set of tools. It's designed to be simple to integrate. For a fullscreen experience, a common pattern is to wrap it in a container div with fixed positioning.

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

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

When this component mounts, it sets up a that draws shapes, handles user input, and manages camera panning and zooming. This engine operates independently of the React DOM tree for rendering shapes, which allows it to handle thousands of objects smoothly. The UI elements, like the toolbar and menus, are still React components, giving you the best of both worlds: performance for drawing and flexibility for the interface.

Accessing the Editor API

To programmatically control the canvas—like creating shapes, changing tools, or moving the camera—you need access to the editor instance. The recommended way to get this is through the onMount callback prop. This function is called once when the editor is ready, passing the editor instance as its only argument.

The onMount callback is the primary entry point for any custom logic that needs to interact directly with the tldraw canvas state.

The instance you receive is an object. This object is the main API for all interactions. You can use it to create, update, and delete shapes, manage selections, and listen for events on the canvas. It's designed to be your central point of control.

Here’s how you can use onMount to create a shape as soon as the canvas loads. We'll add a simple rectangle with some text inside.

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

export default function App() {
  const handleMount = (editor) => {
    // Create a new shape id
    const id = createShapeId('my-rectangle')

    // Create the shape
    editor.createShapes([
      {
        id,
        type: 'geo',
        x: 120,
        y: 120,
        props: {
          geo: 'rectangle',
          w: 150,
          h: 60,
          text: 'Hello from the API!',
          align: 'middle',
          color: 'light-violet',
        },
      },
    ])
  }

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

In this example, the handleMount function receives the editor object and immediately calls editor.createShapes(). We provide an array containing a single shape object, defining its ID, type, position, and properties. The createShapeId utility is a simple helper to generate a unique, formatted ID for the new shape. With this foundation, you can start building more complex interactions and custom tools.

Time to check your understanding of the initial setup.

Quiz Questions 1/4

What are the two essential items you need to import to get a basic <Tldraw /> canvas working in your React component?

Quiz Questions 2/4

True or False: For performance reasons, shapes drawn on the tldraw canvas are rendered independently of the main React DOM tree.