How tldraw is versioned

We do not follow SemVer.

  • 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.



2.2.1 (#3958)

  • Docs improvements (#3930, #3931, #3935, #3956)
  • Make ArrowBindingUtil public (#3913)
  • Add editor.getSnapshot() and editor.loadSnapshot (#3912)
  • CSS tweaks on bookmark elements (#3955)

🐛 Bug Fix

Authors: 3



Bindings allow you to create relationships between shapes. Our default arrow shapes are a great example of this: each end of the arrow can bind to the shape it's pointing to. When that shape moves, so does the arrow. Before this change, it wasn't possible to build things like arrows on top of the tldraw sdk - arrows were hard-coded into the library. Now, with bindings, you can create arrows, constraint systems, visual programming environments, and much more.

Check out the bindings guide for more information. (#3326, #3780, #3797, #3800, #3871)

Camera constraints

You can now limit the camera in tldraw to a certain fixed area of the canvas. This is useful for creating experiences that don't quite fit the "infinite canvas" paradigm: document annotators, image editor, slideshow creators, etc.

See the camera constraints guide for more information. (#3282, #3747, #3814, #3828, #3844, #3863)

Configurable options prop

You can now override many options which were previously hard-coded constants. Pass an options prop into the tldraw component to change the maximum number of pages, grid steps, or other previously hard-coded values.

See TldrawOptions for details. (#3799, #3900)

Breaking changes

  • The canBind flag now accepts an options object instead of just the shape in question. If you're relying on its arguments, check out TLShapeUtilCanBindOpts for its replacement.
  • editor.sideEffects.registerBatchCompleteHandler has been replaced with editor.sideEffects.registerOperationCompleteHandler (#3748)
  • editor.getArrowInfo(shape) has been replaced with getArrowInfo(editor, shape)
  • editor.getArrowsBoundTo(shape) has been removed. Instead, use editor.getBindingsToShape(shape, 'arrow') and follow the fromId of each binding to the corresponding arrow shape
  • These types have moved from @tldraw/editor to tldraw:
    • TLArcInfo
    • TLArrowInfo
    • TLArrowPoint
  • The start and end properties on TLArrowShape no longer have type: point | binding. Instead, they're always a point, which may be out of date if a binding exists. To check for & retrieve arrow bindings, use getArrowBindings(editor, shape) instead.
  • getArrowTerminalsInArrowSpace must be passed a TLArrowBindings as a third argument: getArrowTerminalsInArrowSpace(editor, shape, getArrowBindings(editor, shape))
  • The following types have been renamed:
    • ShapeProps -> RecordProps
    • ShapePropsType -> RecordPropsType
    • TLShapePropsMigrations -> TLPropsMigrations
    • SchemaShapeInfo -> SchemaPropsInfo
1. History Options

Previously, some (not all!) commands accepted a history options object with squashing, ephemeral, and preserveRedoStack flags. Squashing enabled/disabled a memory optimisation (storing individual commands vs squashing them together). Ephemeral stopped a command from affecting the undo/redo stack at all. Preserve redo stack stopped commands from wiping the redo stack. These flags were never available consistently - some commands had them and others didn't.

In this version, most of these flags have been removed. squashing is gone entirely (everything squashes & does so much faster than before). There were a couple of commands that had a special default - for example, updateInstanceState used to default to being ephemeral. Those maintain the defaults, but the options look a little different now - {ephemeral: true} is now {history: 'ignore'} and {preserveRedoStack: true} is now {history: 'record-preserveRedoStack'}.

If you were previously using these options in places where they've now been removed, you can use wrap them with editor.history.ignore(fn) or editor.history.batch(fn, {history: 'record-preserveRedoStack'}). For example,

editor.nudgeShapes(..., { ephemeral: true })

can now be written as

editor.history.ignore(() => {
2. Automatic recording

Previously, only commands (e.g. editor.updateShapes and things that use it) were added to the undo/redo stack. Everything else (e.g. wasn't. Now, everything that touches the store is recorded in the undo/redo stack (unless it's part of mergeRemoteChanges). You can use editor.history.ignore(fn) as above if you want to make other changes to the store that aren't recorded - this is short for editor.history.batch(fn, {history: 'ignore'})

When upgrading to this version of tldraw, you shouldn't need to change anything unless you're using store.put, store.remove, or store.applyDiff outside of store.mergeRemoteChanges. If you are, you can preserve the functionality of those not being recorded by wrapping them either in mergeRemoteChanges (if they're multiplayer-related) or history.ignore as appropriate.

3. Side effects

Before this diff, any changes in side-effects weren't captured by the undo-redo stack. This was actually the motivation for this change in the first place! But it's a pretty big change, and if you're using side effects we recommend you double-check how they interact with undo/redo before/after this change. To get the old behaviour back, wrap your side effects in editor.history.ignore.

4. Mark options

Previously, editor.mark(id) accepted two additional boolean parameters: onUndo and onRedo. If these were set to false, then when undoing or redoing we'd skip over that mark and keep going until we found one with those values set to true. We've removed those options - if you're using them, let us know and we'll figure out an alternative!


  • Nicer rendering for bookmarks without preview images. (#3856)
  • Improve undo/redo UX around image cropping. (#3891)
  • Disable toolbar items that don't work when not in select mode. (#3819)
  • ❤️ We've added a heart shape to the geo shape set. (#3787)
  • Detect coarse pointers (ie touch) more reliably. (#3572, #3656, #3795)
  • Reduce padding when zooming to fit. (#3798)
  • Increase the default limit of shapes per page from 2000 to 4000 (#3716)
  • Unify list of accepted image types and expand to include webp, webm, apng, & avif. (#3730)
  • Prunes unused assets when loading a .tldr file. (#3689)
  • Improve handling of mouse-type devices that support pressure, e.g. wacom tablets. They now use the same freehand options as true pen-type inputs. (#3639)
  • Separate the text align property for text shapes and labels. Text shapes are now left-aligned by default. (#3627)
  • Add desmos graph embed type. (#3608)
  • Tweak default gap value to be consistent with sticky note gaps. (#3606)

API changes

  • Add editor.blur method. (#3875)
  • Better defaults for createTLStore. (#3886)
  • Add getSnapshot and loadSnapshot for easier loading/saving of tldraw documents. Read more here. (#3811)
  • Add select option to Editor.groupShapes and Editor.ungroupShapes. (#3690)
  • InFrontOfTheCanvas now has access to the editor's UI context (#3782)
  • useEditor and other context-based hooks will now throw an error when used out-of-context, instead of returning a fake value. (#3750)
  • Expose migrations, validators, and versions from tlschema. Previously, we weren't exporting migrations & validators for our default shapes. This meant that it wasn't possible to make your own tlschema with both our default shapes and some of your own (e.g. for custom multiplayer). This fixes that by exposing all the migrations, validators, and versions from tlschema, plus defaultShapeSchemas which can be passed directly to createTLSchema.(#3613)

Bug fixes

  • Fix 'insert media' undo removing other changes. (#3910)
  • Fix referrer being sent for bookmarks and images. (#3881)
  • Prevent stale shape data sometimes being used in render. (#3882)
  • Fix an issue with pen pressure. (#3877)
  • Fixed a bug where the minimum distance for a drag was wrong when zoomed in or out. (#3873)
  • Make sure timers/animation frames are disposed along with the editor. (#3852)
  • Fix some inconsistencies with text label rendering. (#3830)
  • Fixed cropped images not exporting properly. (#3837)
  • Fix bug with spacebar & middle mousenbutton panning. (#3791, #3792)
  • Make sure any in-progress interactions are cancelled when switching page/ (#3771
  • Fixes a bug that caused the cursor & shapes to wiggle around when following someone else's viewport. (#3695)
  • Fix some long-stanging cross-browser issues with focus management. (#3718)
  • Fix bug preventing imports in Astro. (#3742)
  • Fixes an issue with copy pasting shapes as svg and png not correctly working for patterned shapes. (#3708)
  • Fix RTL text layout for SVG exports. (#3680)
  • Fixes a rare crash effecting text shapes on mobile. (#3672)
  • Fix textbox direction when it contains both RTL and LTR languages /(#3188)
  • Fix an links in embeds that open the embedded site (e.g. YouTube). (#3609)
  • Fix pasting not working from Edit menu. (#3623)
  • Fixed a bug with resizing text shapes from the left and right while holding alt. (#3632)
  • Fix a bug where locked shapes could still be hovered. (#3575)
  • Fix clicking on the minimap sometimes not changing the viewport. (#3617)
  • Fix an issue with the minimap bugging out after you change the window's height. (#3621)


  • Update French, Hungarian, & Korean translations.
  • Add Bahasa Indonesia translation. (#3649)

Authors: 14


Release Notes

textfields: fix up flakiness in text selection and for unfilled geo shapes fix edit->edit (#3577) (#3643)

  • Text labels: fix up regression to selection when clicking into a text shape. (was causing flaky selections)
  • Text labels: fix edit→edit not working as expected when unfilled geo shapes are on 'top' of other shapes.

🐛 Bug Fix

  • @tldraw/editor, tldraw
    • textfields: fix up flakiness in text selection (#3578)
    • textfields: for unfilled geo shapes fix edit->edit (#3577) #3643 (@mimecuvalo)

Authors: 1


Expose migrations, validators, and versions from tlschema (#3613)

Previously, we weren't exporting migrations & validators for our default shapes. This meant that it wasn't possible to make your own tlschema with both our default shapes and some of your own (e.g. for custom multiplayer). This fixes that by exposing all the migrations, validators, and versions from tlschema, plus defaultShapeSchemas which can be passed directly to createTLSchema

📚 SDK Changes

  • @tldraw/tlschema
    • Expose migrations, validators, and versions from tlschema #3613 (@SomeHats)

Authors: 1


Revert "[signia] Smart dirty checking of active computeds (#3516)" (#3611)

This performance optimisation introduced a regression where sometimes computed caches wouldn't get invalidated at the correct time, leading to stale data causing crashes. We're reverting the change for now.

🐛 Bug Fix

  • @tldraw/state
    • Revert "[signia] Smart dirty checking of active computeds (#3516)" #3611 (@SomeHats)

🏠 Internal

Authors: 1


fix migration exports (#3594)

We were missing an export createShapePropsMigrationIds, part of the new migrations API introduced in v2.1.0. This release fixes that, and also adds exports for a few extra APIs that we were using in our examples, but weren't exporting properly: defaultEditorAssetUrls, PORTRAIT_BREAKPOINT, useDefaultColorTheme, & getPerfectDashProps

🐛 Bug Fix

⚠️ Pushed to v2.1.x

Authors: 1


New stickies & performance improvements

This tldraw release has loads of performance improvements, plus completely redesigned sticky notes. Check out our release notes for for more details on those.

Breaking changes

New migrations (#3220)
  • The Migrations type is now called LegacyMigrations.

  • The serialized schema format (e.g. returned by StoreSchema.serialize() and Store.getSnapshot()) has changed. You don't need to do anything about it unless you were reading data directly from the schema for some reason. In which case it'd be best to avoid that in the future! We have no plans to change the schema format again (this time was traumatic enough) but you never know.

  • compareRecordVersions and the RecordVersion type have both disappeared. There is no replacement. These were public by mistake anyway, so hopefully nobody had been using it.

  • compareSchemas is gone. Comparing the schemas directly is no longer really possible since we introduced some fuzziness. The best thing to do now to check compatibility is to call schema.getMigraitonsSince(prevSchema) and it will return an error if the schemas are not compatible, an empty array if there are no migrations to apply since the prev schema, and a nonempty array otherwise.

    Generally speaking, the best way to check schema compatibility now is to call store.schema.getMigrationsSince(persistedSchema). This will throw an error if there is no upgrade path from the persistedSchema to the current version.

  • defineMigrations has been deprecated and will be removed in a future release. For upgrade instructions see updating legacy shape migrations

  • migrate has been removed. Nobody should have been using this but if you were you'll need to find an alternative. For migrating tldraw data, you should stick to using schema.migrateStoreSnapshot and, if you are building a nuanced sync engine that supports some amount of backwards compatibility, also feel free to use schema.migratePersistedRecord.

  • the Migration type has changed. If you need the old one for some reason it has been renamed to LegacyMigration. It will be removed in a future release.

  • the Migrations type has been renamed to LegacyMigrations and will be removed in a future release.

  • the SerializedSchema type has been augmented. If you need the old version specifically you can use SerializedSchemaV1

Input buffering (#3223)

Events are now buffered and sent to state nodes every tick, instead of immediately. This unlocks some big performance improvements, but could introduce some subtle issues with any custom tools you might have. Make sure you test any custom tools thoroughly!

React-powered SVG exports (#3117)
  1. If any of your shapes implement toSvg for exports, you'll need to replace your implementation with a new version that returns JSX instead of manually constructing SVG DOM nodes.
  2. editor.getSvg is deprecated. It still works, but will be going away in a future release. Instead, use editor.getSvgElement or editor.getSvgString.
Component-based toolbar customisation API (#3067)

If you're using the toolbar callback to override the items in the toolbar at the bottom of the default tldraw UI, you need to switch to using the new Toolbar component override.

See the custom toolbar example for more details.


  • All-new sticky notes! (#3249)
  • Improve color contrast. (#3486)
  • Add long press event. (#3275)
  • Add white. It's a secret! (#3321)
  • Add severity colors and icons to toasts. (#2988)
  • Better handling of broken images / videos. (#2990)

API changes

  • Expose Editor.getStyleForNextShape - previously marked as internal. (#3039)
  • Expose usePreloadAssets. (#3545)
  • getRenderingShapes no longer returns isCulled. Instead, use getCulledShapes.

Bug fixes

  • Prevent copy error sound in safari. (#3536)
  • Fix arrow label positioning overlapping the shape the arrow is bound to. (#3512)
  • Fix cursor chat button appearing when not in select tool. (#3485)
  • Fix alt-duplicating shapes sometimes not working. (#3488)
  • Fix camera sliding after pinch. (#3462)
  • Hide edit link context menu option for locked shapes. (#3457)
  • Fix text shapes overflowing their bounds when resized (#3327)
  • Allow fully hiding the debug panel. (#3261)
  • Fix missing title attributes on toolbar items. (#3244)
  • Fix incorrectly rotated handles on rotated cropping images. (#3093)
  • Fix videos not being sized correctly. (#3047)
  • Fix autocomplete, autocapitalize, and autocorrect tags on text inputs. (#3038)
  • Fix cursor chat bubble position. (#3042)
  • Prevent localStorage crash in React Native webviews. (#3043)
  • Fix a rare crash with video shapes. (#3037)

Performance improvements

  • Improve performance of draw shapes. (#3464)
  • Improve icon preloading. (#3507)
  • Use WebGL to draw the minimap. (#3510)
  • Faster reactivity bookkeeping. (#3471, #3487)
  • Faster selection / erasing (#3454)
  • Improve performance of text shapes on iOS / Safari. (#3429)
  • Throttle updates to the hovered shape ID. (#3419)
  • Block browser hit tests while moving camera. (#3418)
  • Faster minimum distance checks. (#3401)
  • Don't trigger pointer move on zoom. (#3305)
  • Reduce rendered dom nodes for geo shape and arrows. (#3283)
  • Don't double squash undo/redo history entries. (#3182)
  • Batch tick events. (#3181)
  • Faster shape rendering. (#3176)
  • Faster selection rotated page bounds / page bounds. (#3178)
  • Prevent unnecessary handles renders. (#3172)
  • Faster rendering. (#2977)


  • Update Romanian translations. (#3269)
  • Update Hungarian translations. (#3049)



🐛 Bug Fix

⚠️ Pushed to v2.0.x

Authors: 2


🐛 Bug Fix

  • @tldraw/editor
    • [patch 2.0.1] Cherry-pick 'Avoid randomness at init time...' #3076 (@ds300)

⚠️ Pushed to v2.0.x

  • fetch main during patch publish (@ds300)
  • cherry-pick tooling changes too i guess (@ds300)

Authors: 1


⚠️ Pushed to main

📝 Documentation

Authors: 1

Edit this page