Releases

How tldraw is versioned

Unlike many JavaScript packages distributed on NPM, the tldraw SDK does not follow semantic versioning in its release versions. Here's what we do instead:

Major version bumps are very rare and we reserve them for special changes that signify a paradigm shift of some kind.
Minor version bumps are released on a regular cadence - approximately monthly. They may contain breaking changes. We aim to make breaking changes as minimally disruptive as possible, but tldraw is actively evolving as we add new features. We recommend updating tldraw at a similar pace to our release cadence, and be sure to check the release notes.
Patch version bumps are for bugfixes and hotfixes that can't wait for the next cadence release.

Current release: v3.8.0

This update brings a host of improvements across performance, user interface, and developer experience—all while squashing a number of bugs. Read on for a quick summary of the highlights.

What's New

Shape & Asset Enhancements

ShapeUtil.configure for shape options (#5399). Introduces a new utility for passing options to shape utils. (This change also moves note shape resize mode and max draw shape points to their respective configuration objects.)
Note Shape Resize Option. The note shape can be configured to resize by scale. (#5273)
Asset uploads updated (#5218). The upload API now returns an object with both the asset src and optional metadata—allowing for richer asset records.
New "select geo tool" shortcut (#5341). Quickly select your most recent geometric tool with the g shortcut.
Drag URLs onto the canvas (#5411). Drag a URL or link onto the canvas to create a bookmark shape.

Developer Experience & API Improvements

Exports DX Pass (#5114). We’ve refined export functionality:
- The copy/export as JSON option has been removed.
- Export APIs (like Editor.getSvgElement and Editor.getSvgString) now handle shape selections more gracefully.
- Export contexts now expose scale and pixelRatio options and offer a resolveAssetUrl helper.
- A new Editor.toImage method simplifies creating images from your canvas.
i18n Enhancements (#5208). Expanded our localization support to cover the top 40 languages.
React 19 (#5293). tldraw now supports React 19.
Easier external content customisation (#5298, #5402). You can re-use our default handlers, and now customise pasted tldraw & excalidraw content.
Customize input event handling (#5319). Listen to the before-event event to run custom code before tldraw handles input events.
Custom cropping (#5137). There’s a new onCrop method that ShapeUtils can implement to opt-into & customize cropping.

Breaking Changes

Shape Options Configuration. With the introduction of ShapeUtil.configure, if you pass in a shape util that shares a type with a default, it now replaces the default instead of crashing. In addition, the previous options.maxDrawShapePoints is now set via:
- DrawShapeUtil.configure({ maxPoints })
- HighlightShapeUtil.configure({ maxPoints }) (#5399, #5349)
Asset Upload API Changes. In @tldraw/tlschema, TLAssetStore.upload now returns an object with { src, meta? } rather than just the source string. Similarly, Editor.uploadAsset has been updated to reflect this change. (#5218)
Export Functionality. The option to copy/export as JSON has been removed since it was not fully supported. Additionally, hooks like useImageOrVideoAssetUrl now require a width parameter, and export methods have been updated to export all shapes when no IDs are provided. (#5114)

Bug Fixes

UI & Interaction Bugs
- Resolved dialog and edit menu glitches (#5274).
- Addressed problems with mousewheel events not working on scrollable elements (#5356).
Asset & Export Fixes
- Ensured images in exports use the uncropped width (#5300).
- Corrected paste behavior for text/plain via keyboard shortcuts (#5303).

Performance & Reliability

Improved performance for headings (#5413). Improved frame performance by relocating computations to their point of use.

Authors

A huge thank you to everyone who contributed to this release: