Announcing tldraw SDK 5.0

May 7, 2026Steve Ruiz

Hey, this is Steve Ruiz from tldraw. This week we launched the fifth major version of the tldraw SDK, our library for building infinite canvas apps with React. If you’re new to tldraw, you're finding us at a good time! Get started with npm create tldraw@latest or through one of our starter kits.

This new releases is all about features. These are deep and many but cluster most around customization, performance, and extension. I've joked that we shipped our backlog: many our community's most common requests, like adding or customizing our default styles and shapes, are finally here in the SDK.

Here are the highlights:

Themes, display values, and custom styles

You can customize the visual properties of our default shapes through a new display values system. This system lets you choose individual colors, stroke weights, line spacing, and other rendering details that had previously required fragile patches and hacks to our default shapes. This new system is much more robust and will work on the canvas and in image outputs, too.

Custom themes

A new theme system lets you add, remove, and change colors, sizes, and other defaults that apply across all of our default shapes, and that feed into the display values system.

Both the new theme system and the display values systems are reactive: you can change them at any time.

Custom geo shapes

We’ve also introduced an API for custom geo shapes. You can use this to add, remove, or modify the shapes used alongside our default geometries, such as rectangles and ellipses.

Overlays

A major change in this version applies to indicators, handles, and other overlays. Previously, these were rendered using React as individual SVGs. In the new version, these ephemeral overlays are now rendered more efficiently into a single HTML canvas.

To achieve this, the SDK now includes a new Overlays Utils system that you can use to add, modify, and replace overlays that paint into the canvas. Like our Shape Utils system, each of our default overlay utils pull display values from the theme and can be customized through an options API.

A new spatial indexing system helps the editor better identify off-screen shapes, and we have also optimized many of the hottest code paths in our math and geometry systems.

Mermaid & driver modules

We're shipping two new modules in the SDK: a package to convert Mermaid.js into tldraw shapes, and a Driver package you can use to simulate user behavior in the editor. The Driver package extracts many of the shortcuts and helpers that were previously part of our test harness—tools that are increasingly relevant for MCP and AI features.

Attribution

The SDK now includes an attribution system that you can use to connect editor shapes and activities with your application’s users. This is a foundational system that will power future work in permissions, commenting, and document history.

…and much more

Custom records
Custom assets
Better support for Electron and webviews
Improved RTL support
Improved padding on exported images
WebSocket hibernation in tldraw sync
Pass-through events on transparent areas of images

Migrating to 5.0... with agents!

To help developers migration to the new version, we’ve put together an agent skill that pulls relevant release notes and migration guides in order to perform the upgrade for you. To use the skill, run your agent harness of choice (e.g. Claude Code or Codex) at the directory containing your tldraw project, and ask it to:

Please visit https://github.com/tldraw/tldraw/blob/main/skills/tldraw-migrate/README.md and follow the instructions there to migrate tldraw to the latest version.

As always when working with AI tools, do read carefully before committing any code. In our experience, the models have been pretty good at migrating older projects up to 5.0.

Enjoy

Whether you're migrating up or coming in fresh, I hope you're able to build great things with the new tldraw SDK 5.0. If you have questions for the team, looking for inspiration, or want to connect with other developers working with the SDK, drop by the discord or follow us on Twitter/X.