# Documentation ## Introduction This file contains the documentation for the `` component as well as the data model that the component accepts. ## `tldraw` The `Tldraw` React component is the [tldraw](https://tldraw.com) editor exported as a standalone component. You can control the editor through props, or through the `TldrawApp`'s imperative API. **All props are optional.** | Prop | Type | Description | | ----------------- | ------------ | --------------------------------------------------------------------------------------------------------- | | `id` | `string` | An id under which to persist the component's state. | | `document` | `TDDocument` | An initial [`TDDocument`](#TDDocument) object. | | `currentPageId` | `string` | A current page id, referencing the `TDDocument` object provided via the `document` prop. | | `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. | | `showSponsorLink` | `boolean` | Whether to show a sponsor link. | | `onMount` | `Function` | Called when the editor first mounts, receiving the current `TldrawApp`. | | `onPatch` | `Function` | Called when the state is updated via a patch. | | `onCommand` | `Function` | Called when the state is updated via a command. | | `onPersist` | `Function` | Called when the state is persisted after an action. | | `onChange` | `Function` | Called when the `TldrawApp` updates for any reason. | | `onUserChange` | `Function` | Called when the user's "presence" information changes. | | `onUndo` | `Function` | Called when the `TldrawApp` updates after an undo. | | `onRedo` | `Function` | Called when the `TldrawApp` updates after a redo. | | `onSignIn` | `Function` | Called when the user selects Sign In from the menu. | | `onSignOut` | `Function` | Called when the user selects Sign Out from the menu. | | `onNewProject` | `Function` | Called when the user when the user creates a new project through the menu or through a keyboard shortcut. | | `onSaveProject` | `Function` | Called when the user saves a project through the menu or through a keyboard shortcut. | | `onSaveProjectAs` | `Function` | Called when the user saves a project as a new project through the menu or through a keyboard shortcut. | | `onOpenProject` | `Function` | Called when the user opens new project through the menu or through a keyboard shortcut. | > **Note**: For help with the file-related callbacks, see `useFileSystem`. ## `useFileSystem` You can use the `useFileSystem` hook to get prepared callbacks for `onNewProject`, `onOpenProject`, `onSaveProject`, and `onSaveProjectAs`. These callbacks allow a user to save files via the [FileSystem](https://developer.mozilla.org/en-US/docs/Web/API/FileSystem) API. ```ts import { Tldraw, useFileSystem } from '@tldraw/tldraw' function App() { const fileSystemEvents = useFileSystem() return } ``` ## `TDDocument` You can initialize or control the `` component via its `document` property. A `TDDocument` is an object with three properties: - `id` - A unique ID for this document - `pages` - A table of `TDPage` objects - `pageStates` - A table of `TLPageState` objects - `version` - The document's version, used internally for migrations. ```ts import { TDDocument, TldrawApp } from '@tldraw/tldraw' const myDocument: TDDocument = { id: 'doc', version: TldrawApp.version, pages: { page1: { id: 'page1', shapes: {}, bindings: {}, }, }, pageStates: { page1: { id: 'page1', selectedIds: [], currentParentId: 'page1', camera: { point: [0, 0], zoom: 1, }, }, }, assets: {}, } function App() { return } ``` **Tip:** The pages and pageStates in tldraw are objects containing `TLPage` and `TLPageState` objects from the [@tldraw/core](/packages/core) library. **Tip:** The `assets` in tldraw is a table of `TDAssets` (images and videos). **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` | `TDHandle{}` | (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, 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 `DrawShape`s. | 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. | ## `TldrawApp` API You can change the `tldraw` component's state through an imperative API called `TldrawApp`. To access this API, use the `onMount` callback, or any of the component's callback props, like `onPersist`. ```tsx import { Tldraw, TldrawApp } from '@tldraw/tldraw' function App() { const handleMount = React.useCallback((app: TldrawApp) => { app.selectAll() }, []) return } ``` Here are some useful methods: - `loadDocument` - `select` - `selectAll` - `selectNone` - `delete` - `deleteAll` - `deletePage` - `changePage` - `cut` - `copy` - `paste` - `copyJson` - `copySvg` - `undo` - `redo` - `zoomIn` - `zoomOut` - `zoomToContent` - `zoomToSelection` - `zoomToFit` - `zoomTo` - `resetZoom` - `setCamera` - `resetCamera` - `align` - `distribute` - `stretch` - `nudge` - `duplicate` - `flipHorizontal` - `flipVertical` - `rotate` - `style` - `group` - `ungroup` - `createShapes` - `updateShapes` - `updateDocument` - `updateUsers` - `removeUser` - `setSetting` - `selectTool` - `cancel` Check the source or the TypeScript types for more on these and other methods.