Alchemical Canvas Building with tldraw
tldraw Core Architecture
Your Digital Cauldron
At the heart of any tldraw application is the Tldraw component. Think of it as the cauldron where all the magic happens. It's not just a blank drawing surface; it's a complete, self-contained system that bundles the user interface, the canvas itself, and the state management engine that tracks every shape, color, and position.
When you want to create an infinite canvas, you simply render this React component. It's the primary entry point for everything else we'll discuss.
import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'
export default function App() {
return (
<div style={{ position: 'fixed', inset: 0 }}>
<Tldraw />
</div>
)
}
This simple snippet gives you a full-featured digital whiteboarding experience. But the real power comes from customizing it. The Tldraw component accepts a variety of props that let you pass in initial data, override default behaviors, and listen for changes on the canvas.
The Brain of the Canvas
While the Tldraw component is the body, the is the brain. It's the central 'god object' that holds all the methods and state for a given tldraw instance. You don't interact with shapes or the camera directly; you ask the Editor to do it for you. This separation of concerns is key to the library's stability and power.
Want to create a shape? editor.createShape(). Need to move the user's view? editor.setCamera(). Want to select everything? editor.selectAll(). The Editor is your command center for all programmatic interactions with the canvas.
You can get access to the Editor instance using a hook or a component prop, allowing your custom UI to control the canvas.
Where Everything Lives
One of tldraw's most powerful features is its a design pattern that prioritizes storing and managing data on the user's device. This makes the application feel incredibly fast and responsive, because it doesn't need to wait for a server to respond. It also works offline seamlessly.
By default, the tldraw Store persists all canvas data—shapes, assets, and camera position—directly in the browser's a built-in, client-side database. When you reload the page, your drawing is still there, just as you left it. This persistence happens automatically without any configuration.
Finding Your Way Around
The tldraw canvas is infinite. You can pan and zoom forever. This creates a challenge: how do you keep track of where things are? The answer is the canvas coordinate system, which is separate from the pixel coordinates of your screen.
Imagine the canvas as a vast, unchanging map. A shape's position at (x: 100, y: 200) is its absolute 'world' coordinate on that map. Your screen, on the other hand, is just a small window looking at a portion of that map. When you pan or zoom, you're not moving the shapes on the map; you're moving your window (the camera).
The Editor API provides helper functions to convert between these two coordinate systems. This is crucial when handling user input, like mouse clicks, because you need to know where the user clicked on the infinite map, not just on their screen.
Understanding these core architectural pieces—the Tldraw component, the Editor API, the local-first Store, and the coordinate system—is the foundation for building anything custom with tldraw. You now have a mental model of how the different parts work together.
What is the primary role of the Tldraw component in a tldraw application?
If you want to programmatically create a new shape on the tldraw canvas, which part of the library would you use?