No description
Find a file
Steve Ruiz b726796d88 v0.1.5
2021-11-07 14:44:20 +00:00
.github Updates to new core. (#210) 2021-10-28 17:50:58 +01:00
.husky [mega-chore] renaming (#223) 2021-11-06 11:16:30 +00:00
.vscode big refactor 2021-09-13 16:38:42 +01:00
electron v0.1.5 2021-11-07 14:44:20 +00:00
example v0.1.5 2021-11-07 14:44:20 +00:00
packages/tldraw v0.1.5 2021-11-07 14:44:20 +00:00
vscode v0.1.5 2021-11-07 14:44:20 +00:00
www v0.1.5 2021-11-07 14:44:20 +00:00
.eslintignore Create VS Code Extension (#4) 2021-11-06 16:49:53 +00:00
.eslintrc.js Fix build errors 2021-08-11 22:11:23 +01:00
.gitignore [improvement] Migrations (#217) 2021-11-04 15:48:39 +00:00
.npmignore Replace 2021-08-10 17:12:55 +01:00
card-repo.png [improvement] repo shuffle (#214) 2021-11-02 11:46:25 +00:00
CHANGELOG.md Fix shortcut in menu 2021-11-06 08:07:43 +00:00
lerna.json v0.1.5 2021-11-07 14:44:20 +00:00
LICENSE.md [improvement] UI (#215) 2021-11-03 16:46:33 +00:00
package.json Electron App (#224) 2021-11-07 13:45:48 +00:00
README.md Change listening port from 5000 to 5420 (#225) 2021-11-07 14:29:24 +00:00
setupTests.ts Adjusts small example, makes inputs unique to each instance 2021-09-08 17:18:43 +01:00
tsconfig.base.json [fix] rotate center (#213) 2021-10-30 10:04:33 +01:00
tsconfig.json Remove libraries 2021-11-01 15:26:44 +00:00
yarn.lock Change listening port from 5000 to 5420 (#225) 2021-11-07 14:29:24 +00:00

@tldraw/tldraw

This package contains the tldraw editor as a React component named <TLDraw>. You can use this package to embed the editor in any React application.

🎨 Want to build your own tldraw-ish app instead? Try @tldraw/core.

💕 Love this library? Consider becoming a sponsor.

Installation

Use your package manager of choice to install @tldraw/core and its peer dependencies.

yarn add @tldraw/tldraw
# or
npm i @tldraw/tldraw

Usage

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

import { TLDraw } from '@tldraw/tldraw'

function App() {
  return <TLDraw />
}

You can control the TLDraw component through props:

import { TLDraw, TLDrawDocument } from '@tldraw/tldraw'

function App() {
  const myDocument: TLDrawDocument = {}

  return <TLDraw document={document} />
}

Or imperatively through the TLDrawState instance:

import { TLDraw, TLDrawState } from '@tldraw/tldraw'

function App() {
  const handleMount = React.useCallback((tlstate: TLDrawState) => {
    const myDocument: TLDrawDocument = {}

    tlstate.loadDocument(myDocument).selectAll()
  }, [])

  return <TLDraw onMount={handleMount} />
}

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. All props are optional.

Prop Type Description
id string An id under which to persist the component's state.
document TLDrawDocument An initial TLDrawDocument object.
currentPageId string A current page id, referencing the TLDrawDocument object provided via the document prop.
onMount Function A callback function that will be called when the editor first mounts, receiving the current TLDrawState.
onChange Function A callback function that will be called whenever the TLDrawState updates. The update will include the current TLDrawState and the reason for the change.
onUserChange Function A callback function that will be fired when the user's "presence" information changes.
autofocus boolean Whether the editor should immediately receive focus. Defaults to true.
showMenu boolean Whether to show the menu.
showPages boolean Whether to show the pages menu.
showStyles boolean Whether to show the styles menu.
showTools boolean Whether to show the tools.
showUI boolean Whether to show any UI other than the canvas.

TLDrawDocument

A TLDrawDocument is an object with three properties:

  • id - A unique ID for this document
  • pages - A table of TLDrawPage objects
  • pageStates - A table of TLPageState objects
  • version - The document's version, used internally for migrations.
import { TLDrawDocument, TLDrawState } from '@tldraw/tldraw'

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

Tip: TLDraw is built @tldraw/core. The pages and pagestates in TLDraw are just objects containing TLPage and TLPageState objects from the core library. For more about these types, check out the @tldraw/core documentation.

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.

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 TLDrawHandle{} (optional) A table of TLHandle objects.
isLocked boolean (optional) True if the shape is locked.
isHidden boolean (optional) True if the shape is hidden.
isEditing boolean (optional) True if the shape is currently editing.
isGenerated boolean (optional) True if the shape is generated.
isAspectRatioLocked boolean (optional) 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.

DrawShape

A hand-drawn line.

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

A rectangular shape.

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

EllipseShape

An elliptical shape.

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

ArrowShape

An arrow that can connect shapes.

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

TextShape

A line of text.

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

StickyShape

A sticky note.

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

Bindings

A binding is a connection from one shape and to another shape. At the moment, only arrows may be bound "from". Most shapes may be bound "to", except other ArrowShape and DrawShapes.

Property Type Description
id string The binding's own unique ID.
fromId string The id of the ArrowShape that the binding is bound to.
toId string The id of the other shape that the binding is bound to.
handleId start or end The connected arrow handle.
distance number The distance from the bound point.
point number[] A normalized point representing the bound point.

Local Development

  • Run yarn to install dependencies.

  • Run yarn start to start the development server for the package and for the example.

  • Open localhost:5420 to view the example project.

  • Run yarn test to execute unit tests via Jest.

  • Run yarn docs to build the docs via ts-doc.

Example

See the example folder.

Community

Support

Need help? Please open an issue for support.

Discussion

Want to connect with other devs? Visit the Discord channel.

License

This project is licensed under MIT. If you're using the library in a commercial product, please consider becoming a sponsor.

Author