Tldraw/packages/tldraw/README.md

@tldraw/tldraw

This library is not yet released and these docs are partially out of date!

This package contains the tldraw editor as a standalone React component.

Installation

npm i @tldraw/tldraw

or

yarn add @tldraw/tldraw

Usage

Import the TLDraw React component and use it in your app.

import { TLDraw } from '@tldraw/tldraw'

function App() {
  return <TLDraw />
}

Documentation

TLDraw

The TLDraw React component is the tldraw editor exported as a standalone component. You can control the editor through props, or through the TLDrawState's imperative API.

Prop	Type	Description
id	string	(optional) An id under which to persist the component's state.
document	TLDrawDocument	(optional) An initial TLDrawDocument object.
currentPageId	string	(optional) A current page id, referencing the TLDrawDocument object provided via the document prop.
onMount	(TLDrawState) => void	(optional) A callback function that will be called when the editor first mounts, receiving the current TLDrawState.
onChange	(TLDrawState, string) => void	(optional) A callback function that will be called whenever the TLDrawState updates. The update will include the current TLDrawState and the reason for the change.

TLDrawDocument

A TLDrawDocument is an object with three properties:

• id - A unique ID for this document
• pages - A table of TLPage objects
• pageStates - A table of TLPageState objects

const tldocument: TLDrawDocument = {
  id: 'doc',
  pages: {
    page1: {
      id: 'page1',
      shapes: {},
      bindings: {},
    },
  },
  pageStates: {
    page1: {
      id: 'page1',
      selectedIds: [],
      currentParentId: 'page1',
      camera: {
        point: [0, 0],
        zoom: 1,
      },
    },
  },
}

Important: In the pages object, each TLPage object must be keyed under its id property. Likewise, each TLPageState object must be keyed under its id. In addition, each TLPageState object must have an id that matches its corresponding page.

In the example above, the page above with the id page1is at tldocument.pages["page1"]. Its corresponding page state has the same id (page1) and is at tldocument.pageStates["page1"].

Shapes

Your TLPage objects may include shapes: objects that fit one of the TLDrawShape interfaces listed below. All TLDrawShapes extends a common interface:

Property	Type	Description
id	string	A unique ID for the shape.
name	string	The shape's name.
type	string	The shape's type.
parentId	string	The ID of the shape's parent (a shape or its page).
childIndex	number	The shape's order within its parent's children, indexed from 1.
point	number[]	The [x, y] position of the shape.
rotation	number[]	(optional) The shape's rotation in radians.
children	string[]	(optional) The shape's child shape ids.
handles	TLHandle{}	(optional) A table of TLHandle objects.
isLocked	boolean	True if the shape is locked.
isHidden	boolean	True if the shape is hidden.
isEditing	boolean	True if the shape is currently editing.
isGenerated	boolean	True if the shape is generated.
isAspectRatioLocked	boolean	True if the shape's aspect ratio is locked.

Important: In order for re-ordering to work correctly, a shape's childIndex values must start from 1, not 0. The page or parent shape's "bottom-most" child should have a childIndex of 1.

The ShapeStyle object is a common style API for all shapes.

Property	Type	Description
size	SizeStyle	The size of the shape's stroke.
dash	DashStyle	The style of the shape's stroke.
color	ColorStyle	The shape's color.
isFilled	boolean	(optional) True if the shape is filled.

Draw

Property	Type	Description
points	number[][]	An array of points as [x, y, pressure].

Rectangle

Property	Type	Description
size	number[]	The [width, height] of the rectangle.

Ellipse

Property	Type	Description
radius	number[]	The [x, y] radius of the ellipse.

Arrow

Property	Type	Description
handles	object	An object with three TLHandle properties: start, end, and bend.

Text

Property	Type	Description
text	string	The shape's text content.

Development

Running unit tests

Run nx test tldraw to execute the unit tests via Jest.