v4.0.0

This major release introduces new starter kits, a CLI tool, WCAG 2.2 Level AA accessibility compliance, and significant API enhancements for building custom canvas applications.

What's new

npm create tldraw (#6753)

A new CLI tool for quickly scaffolding tldraw projects. Run npm create tldraw to initialize projects using templates and starter kits.

Starter kits

Five new MIT-licensed starter kits demonstrate different applications of tldraw's canvas:

agent - Cursor-style chatbot interface where conversations occur on the canvas with AI assistance
workflow - Node-and-wire visual programming interface for automation workflows and state machines
branching-chat - Multi-path conversation explorer for managing conversation branches
chat - Canvas-based image annotation with integrated chatbot
multiplayer - Collaborative whiteboard foundation built on tldraw sync

Licensing (#6707)

Production deployments now require a license key. Development and localhost environments remain exempt. Available licenses include:

Free 100-day trial license
Commercial license for commercial projects
Hobby license for non-commercial use

Accessibility (#6695)

Achieves WCAG 2.2 Level AA compliance with an accessibility mode, improved keyboard shortcuts, comprehensive aria-labels, and scrollable menus.

Create shapes by dragging directly from the toolbar, eliminating the click-then-draw workflow.

Custom shape clipping (#6649)

Shapes can now clip their children, enabling complex visual hierarchies and container-style shapes.

The toolbar supports vertical orientation for alternative layout configurations.

Rich text arrows (#6594)

Arrow labels support rich text formatting including bold, italic, and text styling.

API changes

💥 CSS variables now start with --tl- prefix. Update custom CSS: --color-background → --tl-color-background, --space-4 → --tl-space-4. (#6712)
💥 Geometry2D.isLabel replaced with excludeFromShapeBounds flag. (#6668)
💥 open-url event now uses destinationUrl instead of url. (#6641)
💥 Arrow shapes now use richText instead of text property. Data migrates automatically, but direct access to arrow.props.text must update to arrow.props.richText. (#6594)
💥 @tldraw/ai module removed. Use the agent starter kit instead.
💥 Event propagation behavior changed. Use editor.markEventAsHandled() for custom event handling. (#6592)
💥 Style panel redesigned with legacy picker components removed. (#6573)
💥 Toolbar CSS class names updated for consistency. (#6551)
Add custom messages in TLSocketRoom via sendCustomMessage() and onCustomMessageReceived. (#6614) (contributed by @mootari)
Add Editor.getShapesAtPoint() with flexible margin options for precise hit testing. (#6724)
Add editor.toImageDataUrl() for generating image data URLs directly from shapes. (#6658)
Add ShapeUtil.isExportBoundsContainer and canCull methods for controlling export behavior and rendering optimization. (#6649)
Add EditorAtom for managing UI state outside React components. (#6687)
Add enhanced handle drag callbacks with timing events for custom drag interactions. (#6702)