tldraw (the SDK)

Active contributors: Steve Ruiz, Mitja Bezenšek, Mime Čuvalo, David Sheldrick

Purpose

tldraw (the npm package, named without scope) is the full SDK. It re-exports @tldraw/editor and adds default shapes, default tools, default bindings, the UI layer (toolbar, style panel, menus, dialogs, share panel), CSS, and integration glue (clipboard, embeds, exports, file formats, external content handlers).

If you import { Tldraw } from 'tldraw', you get a working whiteboard with one component.

Directory layout

packages/tldraw/
├── api-report.api.md
├── package.json
└── src/
    ├── index.ts                 # public exports (~600 lines)
    ├── lib/
    │   ├── Tldraw.tsx           # <Tldraw /> component (12 KB)
    │   ├── TldrawImage.tsx      # <TldrawImage /> static export
    │   ├── defaultShapeUtils.ts
    │   ├── defaultShapeTools.ts
    │   ├── defaultTools.ts
    │   ├── defaultBindingUtils.ts
    │   ├── defaultExternalContentHandlers.ts (24 KB)
    │   ├── defaultEmbedDefinitions.ts (22 KB)
    │   ├── defaultSideEffects.ts
    │   ├── defaultOverlayUtils.ts
    │   ├── shapes/              # one folder per shape kind
    │   ├── tools/               # SelectTool, HandTool, EraserTool, LaserTool, ZoomTool, selection-logic
    │   ├── bindings/            # default binding utils
    │   ├── overlays/            # snap lines, hovered handles, etc.
    │   ├── ui/
    │   │   ├── TldrawUi.tsx
    │   │   ├── components/      # toolbar, menus, dialogs, panels
    │   │   ├── context/
    │   │   ├── hooks/
    │   │   └── overrides.ts     # the UI override system
    │   ├── utils/               # clipboard, export, embeds, .tldr file format, excalidraw import
    │   ├── styles.tsx           # default StyleProp definitions (color, size, dash, fill, font)
    │   ├── ui.css               # 47 KB of UI styles
    │   └── assets/
    └── test/                    # integration tests against the full SDK

Key abstractions

Type	File	Purpose
<Tldraw />	packages/tldraw/src/lib/Tldraw.tsx	Top-level React component. Wraps <TldrawEditor /> with the default UI, shapes, tools, and external-content handlers.
<TldrawImage />	packages/tldraw/src/lib/TldrawImage.tsx	Renders a static snapshot of a tldraw store.
defaultShapeUtils	packages/tldraw/src/lib/defaultShapeUtils.ts	Array of all default shape utils.
defaultTools / defaultShapeTools	packages/tldraw/src/lib/defaultTools.ts, defaultShapeTools.ts	The default tool set.
defaultBindingUtils	packages/tldraw/src/lib/defaultBindingUtils.ts	Default binding utilities.
defaultExternalContentHandlers	packages/tldraw/src/lib/defaultExternalContentHandlers.ts	Drop/paste handling for files, URLs, text, embeds.
defaultEmbedDefinitions	packages/tldraw/src/lib/defaultEmbedDefinitions.ts	Built-in embed providers (YouTube, Figma, GitHub, CodePen, etc.).
<TldrawUi />	packages/tldraw/src/lib/ui/TldrawUi.tsx	Top-level UI shell.
UI overrides	packages/tldraw/src/lib/ui/overrides.ts	The mechanism for customizing/extending menus, toolbar, actions.

Default shapes

Each shape lives in its own folder under packages/tldraw/src/lib/shapes/:

Shape	Folder	Notes
Arrow	arrow/	Curved/straight, with bindings to other shapes.
Bookmark	bookmark/	URL preview cards.
Draw	draw/	Freehand pressure-sensitive strokes.
Embed	embed/	Iframe embeds (YouTube, Figma, GitHub, …).
Frame	frame/	Container shape with title and clipping.
Geo	geo/	Rectangles, ellipses, triangles, diamonds, polygons.
Highlight	highlight/	Highlighter pen strokes.
Image	image/	Image with optional crop.
Line	line/	Multi-point lines.
Note	note/	Sticky notes.
Text	text/	Standalone text labels.
Video	video/	Video player shape.
Group (geometry-only)	../shared/	Group shape geometry/util shared across shapes.

shared/ holds reusable rendering helpers: dashed strokes, label rendering, common SVG components.

Default tools

Tool	Folder	Purpose
SelectTool	packages/tldraw/src/lib/tools/SelectTool/	The biggest tool. Manages selection, translation, resizing, rotation, cropping, brushing, and edit mode. Has many child states.
HandTool	tools/HandTool/	Pan the camera.
EraserTool	tools/EraserTool/	Erase shapes.
LaserTool	tools/LaserTool/	Temporary laser pointer.
ZoomTool	tools/ZoomTool/	Zoom in/out.
Shape tools	(defaultShapeTools.ts)	Draw, Arrow, Note, Text, Highlight, Frame, Geo, Line — these are tools wired to a specific shape kind.

The shared selection logic (snapping during translate, cropping math, hit-testing during brush) lives in packages/tldraw/src/lib/tools/selection-logic/.

UI layer

packages/tldraw/src/lib/ui/components/ hosts the React components for every menu and panel:

• Toolbar/ — the bottom toolbar with tool buttons.
• StylePanel/ — color/size/font controls.
• PageMenu/, MainMenu/, ContextMenu/, ZoomMenu/, HelpMenu/, ActionsMenu/, DebugMenu/, KeyboardShortcutsDialog/.
• SharePanel/ — multiplayer share UI.
• Minimap/.
• NavigationPanel/, OfflineIndicator/, QuickActions/, HelperButtons/, TopPanel/.
• menu-items.tsx — 20 KB of menu wiring; the canonical place to look for "where is this menu item defined?".

The override system (overrides.ts) lets app code add or replace menu items, toolbar buttons, and actions without forking. The dotcom client uses this heavily — see apps/dotcom/client/src/components/.

How it works

graph LR
    App["<Tldraw />"] -->|wraps| Editor["<TldrawEditor />"]
    App -->|wraps| UI["<TldrawUi />"]
    App -->|injects| ShapeUtils[default shape utils]
    App -->|injects| Tools[default tools]
    App -->|injects| Bindings[default binding utils]
    App -->|injects| ExtContent[default external-content handlers]
    Editor -->|context| UI
    Editor -->|context| ShapeUtils
    Editor -->|context| Tools

The component is opinionated by default but every part is replaceable through props or the UI override system.

Integration points

• Imports. @tldraw/editor (everything), @tiptap/* for rich text in shapes, classnames. Test deps include @testing-library/react.
• Importers. apps/dotcom/client, apps/examples, apps/vscode/editor, every template under templates/.
• CSS. tldraw.css plus per-component CSS modules. The CSS is required: import 'tldraw/tldraw.css'.

Entry points for modification

• Adding a default shape. Create a folder under packages/tldraw/src/lib/shapes/<kind>/, add <Kind>ShapeUtil.tsx, register it in defaultShapeUtils.ts, and add a tool in defaultShapeTools.ts if relevant.
• Adding a UI item. Edit packages/tldraw/src/lib/ui/components/menu-items.tsx, then surface it in the right menu component.
• Adding an embed. Add to defaultEmbedDefinitions.ts. Each embed is a record of provider host pattern, dimensions, sandbox flags, and a transform from URL to embed URL.
• Customizing externally. Use the props on <Tldraw /> (shapeUtils, tools, bindings, overrides) instead of forking.

Related

• Editor
• Shapes and tools
• UI system
• File formats and export