@tldraw/core

This package contains the Renderer and core utilities used by tldraw.

You can use this package to render React components in a canvas user interface.

? 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/core --peer
# or
npm i @tldraw/core

Usage

Import the Renderer React component and pass it the required props. See the CodeSandbox example.

import * as React from "react"
import { Renderer, TLShape, TLShapeUtil, Vec } from '@tldraw/core'
import { BoxShape, BoxUtil } from "./shapes/box"

const shapeUtils = { box: new BoxUtil() }

function App() {
  const [page, setPage] = React.useState({
    id: "page"
    shapes: {
      "box1": {
        id: 'box1',
        type: 'box',
        parentId: 'page',
        childIndex: 0,
        point: [0, 0],
        size: [100, 100],
        rotation: 0,
      }
    },
    bindings: {}
  })

  const [pageState, setPageState] = React.useState({
    id: "page",
    selectedIds: [],
    camera: {
      point: [0,0],
      zoom: 1
    }
  })

  return (<Renderer
    page={page}
    pageState={pageState}
    shapeUtils={myShapes}
  />)
}

Documentation

Renderer

To avoid unnecessary renders, be sure to pass “stable” values as props to the Renderer. Either define these values outside of the parent component, or place them in React state, or memoize them with React.useMemo.

In addition to these required props, the Renderer accents many optional props.

The theme object accepts valid CSS colors for the following properties:

The Renderer also accepts many (optional) event callbacks.

The @tldraw/core library provides types for most of the event handlers:

TLPage

An object describing the current page. It contains:

TLPageState

An object describing the current page. It contains:

TLShape

An object that describes a shape on the page. The shapes in your document should extend this interface with other properties. See Shape Type.

TLHandle

An object that describes a relationship between two shapes on the page.

When a shape with handles is the only selected shape, the Renderer will display its handles. You can respond to interactions with these handles using the `on

TLBinding

An object that describes a relationship between two shapes on the page.

TLSnapLine

A snapline is an array of points (formatted as [x, y]) that represent a “snapping” line.

TLShapeUtil

The TLShapeUtil is an abstract class that you can extend to create utilities for your custom shapes. See the Creating Shapes guide to learn more.

TLUser

A TLUser is the presence information for a multiplayer user. The user’s pointer location and selections will be shown on the canvas. If the TLUser‘s id matches the Renderer‘s userId prop, then the user’s cursor and selections will not be shown.

Utils

A general purpose utility class. See source for more.

Guide: Creating Shapes

The Renderer component has no built-in shapes. It’s up to you to define every shape that you want to see on the canvas. While these shapes are highly reusable between projects, you’ll need to define them using the API described below.

For several example shapes, see the folder /example/src/shapes/.

Shape Type

Your first task is to define an interface for the shape that extends TLShape. It must have a type property.

// BoxShape.ts
import type { TLShape } from '@tldraw/core'

export interface BoxShape extends TLShape {
  type: 'box'
  size: number[]
}

Component

Next, use TLShapeUtil.Indicator to create a second component for your shape’s Component. The Renderer will use this component to display the shape on the canvas.

// BoxComponent.ts

import * as React from 'react'
import { shapeComponent, SVGContainer } from '@tldraw/core'
import type { BoxShape } from './BoxShape'

export const BoxComponent = TLShapeUtil.Component<BoxShape, SVGSVGElement>(
  ({ shape, events, meta }, ref) => {
    const color = meta.isDarkMode ? 'white' : 'black'

    return (
      <SVGContainer ref={ref} {...events}>
        <rect
          width={shape.size[0]}
          height={shape.size[1]}
          stroke={color}
          strokeWidth={2}
          strokeLinejoin="round"
          fill="none"
          pointerEvents="all"
        />
      </SVGContainer>
    )
  }
)

Your component can return HTML elements or SVG elements. If your shape is returning only SVG elements, wrap it in an SVGContainer. If your shape returns HTML elements, wrap it in an HTMLContainer. Not that you must set pointerEvents manually on the shapes you wish to receive pointer events.

The component will receive the following props:

Indicator

Next, use TLShapeUtil.Indicator to create a second component for your shape’s Indicator. This component is shown when the shape is hovered or selected. Your Indicator must return SVG elements only.

// BoxIndicator.ts

export const BoxIndicator = TLShapeUtil.Indicator<BoxShape>(({ shape }) => {
  return (
    <rect
      fill="none"
      stroke="dodgerblue"
      strokeWidth={1}
      width={shape.size[0]}
      height={shape.size[1]}
    />
  )
})

The indicator component will receive the following props:

ShapeUtil

Next, create a “shape util” for your shape. This is a class that extends TLShapeUtil. The Renderer will use an instance of this class to answer questions about the shape: what it should look like, where it is on screen, whether it can rotate, etc.

// BoxUtil.ts

import { Utils, TLBounds, TLShapeUtil } from '@tldraw/core'
import { BoxComponent } from './BoxComponent'
import { BoxIndicator } from './BoxIndicator'
import type { BoxShape } from './BoxShape'

export class BoxUtil extends TLShapeUtil<BoxShape, SVGSVGElement> {
  Component = BoxComponent

  Indicator = BoxIndicator

  getBounds = (shape: BoxShape): TLBounds => {
    const [width, height] = shape.size

    const bounds = {
      minX: 0,
      maxX: width,
      minY: 0,
      maxY: height,
      width,
      height,
    }

    return Utils.translateBounds(bounds, shape.point)
  }
}

Set the Component field to your component and the Indicator field to your indicator component. Then define the getBounds method. This method will receive a shape and should return a TLBounds object.

You may also set the following fields:

ShapeUtils Object

Finally, create a mapping of your project’s shape utils and the type properties of their corresponding shapes. Pass this object to the Renderer‘s shapeUtils prop.

// App.tsx

const shapeUtils = {
  box: new BoxUtil(),
  circle: new CircleUtil(),
  text: new TextUtil(),
}

export function App() {
  // ...

  return <Renderer page={page} pageState={pageState} {...etc} shapeUtils={shapeUtils} />
}

Local Development

• Run yarn to install dependencies.

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

• Open localhost:5000 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 or this CodeSandbox example.

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 perfect-freehand in a commercial product, please consider becoming a sponsor.

Author

• @steveruizok

GitHub

View Github