Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@tldraw/state

tldraw193.2kMIT3.12.1TypeScript support: included

A tiny little drawing app (state).

tldraw, drawing, app, development, whiteboard, canvas, infinite

readme

tldraw

Welcome to the public monorepo for tldraw. tldraw is a library for creating infinite canvas experiences in React. It's the software behind the digital whiteboard tldraw.com.

Click here to learn about our license and pricing.

Installation

npm i tldraw

Usage

import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
    return (
        <div style={{ position: 'fixed', inset: 0 }}>
            <Tldraw />
        </div>
    )
}

Learn more at tldraw.dev.

Local development

The local development server will run our examples app. The basic example will show any changes you've made to the codebase.

To run the local development server, first clone this repo.

Enable corepack to make sure you have the right version of yarn:

npm i -g corepack

Install dependencies:

yarn

Start the local development server:

yarn dev

Open the example project at localhost:5420.

License

The tldraw SDK is provided under the tldraw license.

You can use the tldraw SDK in commercial or non-commercial projects so long as you preserve the "Made with tldraw" watermark on the canvas. To remove the watermark, you can purchase a business license. Visit tldraw.dev to learn more.

Trademarks

Copyright (c) 2024-present tldraw Inc. The tldraw name and logo are trademarks of tldraw. Please see our trademark guidelines for info on acceptable usage.

Distributions

You can find tldraw on npm here.

Contribution

Please see our contributing guide. Found a bug? Please submit an issue.

Community

Have questions, comments or feedback? Join our discord. For the latest news and release notes, visit tldraw.dev.

Contributors

Star History

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=tldraw/tldraw&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=tldraw/tldraw&type=Date" /> Star History Chart </picture>

Contact

Find us on Twitter/X at @tldraw. You can contact us by email at hello@tldraw.com.

changelog

v3.12.0 (Tue Apr 15 2025)

Release Notes

Add & fix missing state docs (#5696)

  • Docs: Added more docs to the @tldraw/state and @tldraw/state-react API reference,

🐛 Bug Fix

Authors: 2


v3.11.0 (Thu Mar 20 2025)

Release Notes

[Friendly Spellcheck]: Fix comments of types.ts file in @tldraw/state (#5683)

  • Fixed typos found in the Signal interface's comments

🐛 Bug Fix

  • [Friendly Spellcheck]: Fix comments of types.ts file in @tldraw/state #5683 (@Jastor11)
  • Fix API links for state packages #5606 (@TodePond)

Authors: 2


v3.10.0 (Tue Mar 11 2025)

Release Notes

[feature] add rich text and contextual toolbar (#4895)

  • Rich text using ProseMirror as a first-class supported option in the Editor.

🐛 Bug Fix

🎉 New Features

Authors: 6


v3.9.0 (Mon Mar 03 2025)

🐛 Bug Fix

Authors: 4


v3.8.0 (Wed Feb 12 2025)

Release Notes

support react 19 (#5293)

  • tldraw now supports react 19

💄 Product Improvements

Authors: 3


v3.4.0 (Thu Oct 24 2024)

Release Notes

npm: upgrade eslint v8 → v9 (#4757)

  • Upgrade eslint v8 → v9

🐛 Bug Fix

💄 Product Improvements

Authors: 6


v3.3.0 (Wed Oct 09 2024)

Release Notes

[state] fix error 'cannot change atoms during reaction cycle' bug (#4645)

  • Fixed a bug that was manifesting as Error('cannot change atoms during reaction cycle')

Add eslint rule to check that tsdoc params match with function params (#4615)

  • Add lint rules to check for discrepancies between tsdoc params and function params and fix all the discovered issues.

🐛 Bug Fixes

  • [state] fix error 'cannot change atoms during reaction cycle' bug #4645 (@ds300)

💄 Product Improvements

Authors: 2


v3.1.0 (Wed Sep 25 2024)

🐛 Bug Fix

Authors: 4


v3.0.0 (Fri Sep 13 2024)

Release Notes

Detect multiple installed versions of tldraw packages (#4398)

  • We detect when there are multiple versions of tldraw installed and let you know, as this can cause bugs in your application

Move from function properties to methods (#4288)

  • Adds eslint rules for enforcing the use of methods instead of function properties and fixes / disables all the resulting errors.

🐛 Bug Fix

💄 Product Improvements

🛠️ API Changes

Authors: 4


v2.4.0 (Mon Jul 22 2024)

Release Notes

Split @tldraw/state into @tldraw/state and @tldraw/state-react (#4170)

  • Fixed a bug with…

[sdk] make EffectScheduler and useStateTracking public (#4155)

  • Made EffectScheduler and useStateTracking public

💄 Product Improvements

  • [3/5] Automatically enable multiplayer UI when using demo sync #4119 (@SomeHats)

🛠️ API Changes

  • Split @tldraw/state into @tldraw/state and @tldraw/state-react #4170 (@ds300)
  • [sdk] make EffectScheduler and useStateTracking public #4155 (@ds300)

Authors: 2


v2.3.0 (Tue Jun 25 2024)

Release Notes

assets: make option to transform urls dynamically / LOD (#3827)

  • Assets: make option to transform urls dynamically to provide different sized images on demand.

📚 SDK Changes

Authors: 1


v2.2.0 (Tue Jun 11 2024)

Release Notes

editor: register timeouts/intervals/rafs for disposal (#3852)

  • Editor: add registry of timeouts/intervals/rafs

[signia] perf thing again (#3645)

  • Add a brief release note for your PR here.

📚 SDK Changes

📖 Documentation changes

  • make sure everything marked @public gets documented #3892 (@SomeHats)

🏠 Internal

Authors: 4


v2.1.0 (Tue Apr 23 2024)

Release Notes

[perf] faster signia capture (again) (#3487)

  • Add a brief release note for your PR here.

[perf] faster signia capture (#3471)

  • Slight performance improvement to reactivity bookkeeping.

New migrations again (#3220)

BREAKING CHANGES

  • 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 https://tldraw.dev/docs/persistence#Updating-legacy-shape-migrations-defineMigrations

  • 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

[perf] Reinstate render throttling (#3160)

  • Add a brief release note for your PR here.

Performance improvements (#2977)

  • Improves the performance of rendering.

Fix typo in useValue comment (#3088)

  • Fix typo in useValue comment.

💥 Breaking Change

📚 SDK Changes

📖 Documentation changes

🏠 Internal

🐛 Bug Fixes

Authors: 4


v2.0.0-beta.5 (Thu Feb 29 2024)

🔩 Dependency Updates

Authors: 1


v2.0.0-beta.4 (Wed Feb 21 2024)

Release Notes

Improve signia error handling (#2835)

  • Add a brief release note for your PR here.

🐛 Bug Fix

🏠 Internal

Authors: 2


v2.0.0-beta.3 (Tue Feb 13 2024)

Release Notes

dev: add test-dev command for easier testing of packages (#2627)

  • Adds easier testing command for individual packages.

🚀 Enhancement

  • [dx] use Biome instead of Prettier, part 2 #2731 (@si14)

🏠 Internal

🔩 Dependency Updates

  • Bump Yarn to 4.0.2 and add version constraints #2481 (@si14)

Authors: 4


v2.0.0-beta.1 (Wed Dec 20 2023)

Release Notes

Remove deprecated getters (#2333)

  • (Breaking) Removed deprecated getters.

Use a global singleton for tlstate (#2322)

  • Make a global singleton for tlstate.

💥 Breaking Change

🐛 Bug Fix

Authors: 2


v2.0.0-alpha.19 (Tue Dec 12 2023)

💥 Breaking Change

🐛 Bug Fix

📝 Documentation

Authors: 2


v2.0.0-alpha.18 (Fri Nov 10 2023)

Release Notes

Remove (optional) from jsdocs (#2109)

  • dev: Removed duplicate/inconsistent (optional)s from docs

🏠 Internal

  • Revert "bump prerelease from alpha to beta" #2192 (@ds300)
  • bump prerelease from alpha to beta #2148 (@ds300)

📝 Documentation

Authors: 2


v2.0.0-alpha.16 (Wed Oct 11 2023)

🏠 Internal

Authors: 1


v2.0.0-alpha.15 (Fri Oct 06 2023)

Release Notes

Editor commands API / effects (#1778)

  • tbd

tldraw zero - package shuffle (#1710)

  • [@tldraw/editor] lots, wip
  • [@tldraw/ui] gone, merged to tldraw/tldraw
  • [@tldraw/polyfills] gone, merged to tldraw/editor
  • [@tldraw/primitives] gone, merged to tldraw/editor / tldraw/tldraw
  • [@tldraw/indices] gone, merged to tldraw/editor
  • [@tldraw/file-format] gone, merged to tldraw/tldraw

💥 Breaking Change

🚀 Enhancement

Authors: 2


v2.0.0-alpha.14 (Tue Jul 04 2023)

🐛 Bug Fix

Authors: 1


v2.0.0-alpha.13 (Wed Jun 28 2023)

🔩 Dependency Updates

Authors: 2


v2.0.0-alpha.12 (Mon Apr 03 2023)

🐛 Bug Fix

Authors: 5


@tldraw/tlstore

2.0.0-alpha.11

Patch Changes

2.0.0-alpha.10

Patch Changes

2.0.0-alpha.9

Patch Changes

2.0.0-alpha.8

Patch Changes

  • 23dd81cfe: Make signia a peer dependency

2.0.0-alpha.7

Patch Changes

2.0.0-alpha.6

Patch Changes

2.0.0-alpha.5

Patch Changes

2.0.0-alpha.4

Patch Changes

2.0.0-alpha.3

Patch Changes

2.0.0-alpha.2

Patch Changes

0.1.0-alpha.11

Patch Changes

0.1.0-alpha.10

Patch Changes

0.1.0-alpha.9

Patch Changes

0.1.0-alpha.8

Patch Changes

0.1.0-alpha.7

Patch Changes

0.0.2-alpha.1

Patch Changes

0.0.2-alpha.0

Patch Changes