--- title: "Whiteboard types" description: "TypeScript types of the Tiptap Whiteboard extension." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/types" --- # Whiteboard types TypeScript types of the Tiptap Whiteboard extension. Import these TypeScript types for the camera, shapes, tools, styles, doc frames, board files and images from `@tiptap-pro/extension-whiteboard`. `Editor` comes from `@tiptap/core` and `UndoRedoOptions` from `@tiptap/extensions`. `ProseMirrorNode` is `Node` from `@tiptap/pm/model`. ## `Camera` Where the board shows in the stage. ### Properties - `x` (`number`): In screen pixels. - `y` (`number`): In screen pixels. - `zoom` (`number`): The zoom, where 1 is 100%. ## `UpdateCamera` Type: `(update: (camera: Camera) => Camera) => void`. Changes the camera through an update function, like a React state setter. ## `Point`, `Rect` and `Size` ### `Point` A point, with `x` to the right and `y` down. - `x` (`number`) - `y` (`number`) ### `Rect` A rectangle, from its top left corner. - `x` (`number`) - `y` (`number`) - `width` (`number`) - `height` (`number`) ### `Size` A width and a height. - `width` (`number`) - `height` (`number`) ## `Insets` Room to keep free at each edge of the stage, in screen pixels. Options that take insets also take one number for every edge. ### Properties - `top` (`number`) - `right` (`number`) - `bottom` (`number`) - `left` (`number`) ## `ShapeAttributes` The attributes of shapes. Positions and sizes are in board units. ### Properties - `id` (`string | null`): Unique on the board. - `x` (`number`) - `y` (`number`) - `width` (`number`) - `height` (`number`) - `zIndex` (`string | null`): A fractional index: shapes with a higher one are in front. - `frameId` (`string | null`): The [frame](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/guides/frames.md) that the shape is in, or `null`. The board keeps it as shapes move in and out. - `color` (`string`): The name of a board color, like `yellow`. - `kind?` (`GeoKind`): The kind of a geometric shape, a name from `geoKinds`. Arrows have no box, but ends, see [`ArrowEndAttributes`](#arrowendattributes), the styles `arrowheads`, `arrowheadKind`, `arrowKind` and `dash`, and a `fontSize` and a `font` for their label. Doc frames have no `color`, but a `docId`. Frames have no `color` and no `frameId`, but a `name`. Images have no `color`, but a `src`, the URL of their image, and an `alt`, its text for screen readers. Shapes with text also have the styles `fontSize`, `textAlign` and `font`, see [`ShapeStyles`](#shapestyles). Pen lines also have `points` and `strokeWidth`. ## `ShapeGeometry` Type: `Pick`. The box of a shape, in board units. ## `ArrowEndAttributes` Where the ends of an arrow are. An end with the id of a shape on the board follows that shape. Otherwise it is free and sits at its point. ### Properties - `fromId` (`string | null`) - `toId` (`string | null`) - `fromX` (`number`) - `fromY` (`number`) - `toX` (`number`) - `toY` (`number`) - `fromAnchorX`, `fromAnchorY`, `toAnchorX` and `toAnchorY` (`number`): Where a connected end aims in the box of its shape, from 0 at the left or top to 1 at the right or bottom. The line stops at the shape's outline. A curved or elbow line goes through the side nearest to it, unless it lies in the middle half of the box on both axes. Default: `0.5`, the middle. ## `ShapeUpdate` A change to the attributes of one shape. An update can change any of a shape's attributes, except the id. ### Properties - `id` (`string`) - `attributes` (`ShapeUpdateAttributes`) ### `ShapeUpdateAttributes` Type: `Partial & ArrowEndAttributes & ShapeStyles & { points: string; strokeWidth: number; docId: string }> & { [attribute: string]: unknown; id?: never }`. `points` and `strokeWidth` are those of a pen line, and `docId` is the document of a doc frame. [Custom shapes](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/guides/custom-shapes.md) can have attributes of their own, like the data of a chart. ## `Tool`, `ShapeTool` and `ToolKeys` ### `Tool` Type: `'select' | 'hand' | 'eraser' | ShapeTool`. What a press on the board does: select shapes, pan the board, erase shapes, or add a shape. ### `ShapeTool` Type: `'note' | 'text' | 'doc' | 'rectangle' | 'ellipse' | 'diamond' | 'pen' | 'arrow' | 'frame'`. A `ShapeTool` adds a shape of its kind. ### `ToolKeys` Type: `Readonly>>`. The key that chooses each tool. `null` leaves a tool without a key. See [`toolKeys`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#toolkeys). ## `GeoKind` and `ShapeColor` ### `GeoKind` Type: `(typeof geoKinds)[number]`, which is `'rectangle' | 'ellipse' | 'diamond' | 'triangle'`. A kind of geometric shape, from `geoKinds`. ### `ShapeColor` Type: `(typeof shapeColors)[number] | (string & {})`. The name of a board color: one from `shapeColors`, like `'black'` or `'red'`, or one of your own. See [Colors](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/styling.md#colors). ## `ShapeStyles` Type: `{ [Name in ShapeStyleName]: ShapeStyleValue }`. The styles of shapes come from `shapeStyles`. `ShapeStyles` has a value for each style. ### `ShapeStyleName` Type: `keyof typeof shapeStyles`, which is `'color' | 'fontSize' | 'textAlign' | 'font' | 'arrowheads' | 'arrowheadKind' | 'arrowKind' | 'dash'`. The name of a style, like `color` or `fontSize`. ### `ShapeStyleValue` Type: `(typeof shapeStyles)[Name][number] | (string & {})` for `color`, `fontSize` and `font`, and `(typeof shapeStyles)[Name][number]` for the other styles, where `Name extends ShapeStyleName`. The name of a value of a style, like `blue` for `color`. Colors, font sizes and fonts also take names of your own, because only your CSS gives them a look. ## `ShapeElementAttributes` Type: `(node: ProseMirrorNode) => Record`. Returns extra attributes for the element of a shape, from the shape's node. Values become strings, and `null` or `undefined` leaves an attribute out. ## `WhiteboardKitOptions` The options of `WhiteboardKit`. See [Extensions](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/extensions.md#whiteboardkit). ### Properties - `undoRedo` (`Partial | false`) - `shapeElementAttributes` (`ShapeElementAttributes | null`) - `docs` (`BoardDocs | null`) - `images` (`BoardImages | null`) - `colors` (`readonly ShapeColor[]`) - `toolKeys` (`ToolKeys | false`) `BoardOptions`, the options of `Board`, has `shapeElementAttributes`, `docs` and `images`. `BoardStorage` is what the board keeps in `editor.storage.board`, see [Extensions](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/extensions.md#storage-boardstorage). The kit passes `colors` and `toolKeys` on to its extensions. `BoardTextColorOptions`, the options of `BoardTextColor`, has `colors`. `BoardHighlightOptions`, the options of `BoardHighlight`, has `colors` and the `HighlightOptions` of Tiptap's Highlight. `ShapeSelectionOptions`, the options of `ShapeSelection`, has `toolKeys`. ## `BoardDocs` Where the documents of doc frames live, like local storage or Tiptap Cloud. The app provides it, so the board stays free of any storage. See [Doc frames](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/guides/doc-frames.md). ### Properties - `createEditor` (`(options: CreateDocEditorOptions) => Editor`): Creates the editor of a document inside `element`, the frame's content element, `[data-shape-content]`. The board destroys it with its frame. - `start?` (`(docId: string) => void`): Starts the document of every frame that a change in this editor brings onto the board: a new frame, a copy after `copy`, and frames that `setContent` or an undo with `UndoRedo` bring back. Runs before the frame shows, so keep a document that the frame already has. Frames that come through Yjs, from other editors or from its undo, don't start a document here. - `copy` (`(options: CopyDocOptions) => void`): Copies a document for the copy of its frame. Runs before the copy shows, and before `start`. - `load?` (`(options: LoadDocOptions) => void`): Fills a new document with the content of a frame from a board file, for `importBoard`. Runs before the frame shows, and before `start`. Without it, imported frames start empty. ### `CreateDocEditorOptions` - `element` (`HTMLElement`) - `docId` (`string`) ### `CopyDocOptions` - `fromDocId` (`string`) - `toDocId` (`string`) ### `LoadDocOptions` - `docId` (`string`): The id of the new document, which the imported frame shows. - `content` (`JSONContent`): The JSON of the document, from the board file. ## `BoardImages` Where the files of image shapes go, like a file storage of your app. The app provides it, so the board stays free of any storage. Images show from the URLs that `upload` returns. See [Images](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/guides/images.md). ### Properties - `upload` (`(options: UploadImageOptions) => Promise`): Uploads an image file and returns the URL that its image shape shows it from. - `accept?` (`readonly string[]`): The image types that users can add. Default: `['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/avif', 'image/svg+xml']`. - `maxSize?` (`number`): The size of the largest file that users can add, in bytes. Default: `10 * 1024 * 1024`, 10 MB. - `onError?` (`(options: ImageErrorOptions) => void`): Tells the app about a file that the board left out, like to show a message. ### `UploadImageOptions` - `file` (`File`): The image file that a user pasted, dropped or picked. - `signal` (`AbortSignal`): Aborts when the board's editor is destroyed before the upload ends. ### `ImageErrorOptions` - `file` (`File`): The file that the board left out. - `reason` (`'type' | 'size' | 'upload'`): `type` when `accept` doesn't list the file's type or the browser can't show the file, `size` when the file is larger than `maxSize`, and `upload` when `upload` threw or returned a URL that can't show. - `error?` (`unknown`): What `upload` threw, or the URL that it returned when the URL can't show. ## `BoardFile` A board saved as JSON by `exportBoard`, with the documents that its doc frames show. `importBoard` opens it again. See [Export and import](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/guides/export-and-import.md). ### Properties - `type` (`'tiptap-whiteboard'`): Marks the JSON as a board file. - `version` (`number`): The version of the file format. `importBoard` opens versions up to the one that `exportBoard` writes. - `content` (`JSONContent`): The board's document, like `editor.getJSON()` returns it. - `docs` (`Record`): The documents that the doc frames show, by document id. ## `BoardFileError` A class that extends `Error`. `importBoard` throws it when the JSON is none of the files that it opens, or has a newer file format of the whiteboard or of tldraw. ### Properties - `code` (`BoardFileErrorCode`): Why the file can't be opened. ### `BoardFileErrorCode` Type: `'not-a-board-file' | 'version-too-new'`. `not-a-board-file` is for JSON that is none of the files that `importBoard` opens, and `version-too-new` for a newer format of the whiteboard or of tldraw. ## `ImportBoardResult` What `importBoard` added, and what it left out. ### Properties - `ids` (`string[]`): The ids of the added shapes. - `skipped` (`SkippedShape[]`): The shapes of the file that the editor can't show, like ones of a type that it doesn't have, or with attributes of the wrong type. For a file of Excalidraw or tldraw, also what the board has no shape for, like frames, and the shapes of other pages. Each says why, and what it held and where it would be when the file says. ### `SkippedShape` - `id` (`string | null`): The shape's id in the file, or `null` when it has none. - `type` (`string`): The shape's node type in the file, or its type in the app that saved the file, like `frame`. - `reason` (`SkippedReason`): Why it was left out. - `detail` (`string`, optional): What it held, to name it by: a frame's name, a link, a page's name or text. - `box` ([`Rect`](#point-rect-and-size), optional): Where it would be on the board, when the file says. The width and height are 0 when the file gives only its spot. In `insert` mode, it moves with the copies. ### `SkippedReason` Type: `'unsupported' | 'other-page' | 'missing-image' | 'unreadable'`. The board has no shape like it, like a frame, or the editor lacks its node type. It is on a page after the first of a tldraw file. The file lacks the image that it shows. Its data is broken. ## `BoardSvg` An SVG image of shapes on the board, as `exportBoardSvg` returns it. ### Properties - `svg` (`string`): The markup of the SVG. - `width` (`number`): The width of the image, in board units. - `height` (`number`): The height of the image, in board units. ## `RemoteSelection` The shapes that one other user selects, and their color as `#RRGGBB`. A selection with another color, like `red` or `#abc`, doesn't show. ### Properties - `color` (`string`) - `ids` (`readonly string[]`) ## `RemoteCursor` Where another user points on the board, and what they drag. ### Properties - `owner` (`unknown`): Whose cursor it is, like the client id of another user. - `point` (`Point`): Where the user points, in board units. - `time?` (`number`): When the user's browser shared the point, by its own clock, in ms. The cursor moves at the pace that the points were shared. Without it, it takes the time that a point arrives. - `name` (`string`): The name next to the cursor. - `color` (`string`): The user's color as `#RRGGBB`, in the cursor's `--remote-cursor`. Another color doesn't show. - `drag?` (`{ ids: readonly string[]; delta: Point } | null`): The shapes that the user drags, and how far they moved them since the drag began, in board units, when the user pointed at `point`. ## `RemoteCursors` The cursors of other users on a board. `createRemoteCursors` returns it. ### Properties - `update` (`(cursors: readonly RemoteCursor[]) => void`) - `destroy` (`() => void`) ## `RemoteMoves` Shows the drags of other users, until they drop their shapes. `createRemoteMoves` returns it. ### Properties - `show` (`(options: ShowRemoteMoveOptions) => void`) - `end` (`(owner: unknown) => void`) ### `ShowRemoteMoveOptions` - `owner` (`unknown`): Whose drag it is, like the client id of another user. - `ids` (`readonly string[]`) - `delta` (`Point`): How far the drag has moved the shapes since it began, in board units. ## `FreehandShape` Type: `ShapeGeometry & { points: string }`. The box and the points of a pen line, as `freehandFromPoints` returns them. ## `StackPlace` Type: `'front' | 'back'`. Where `restackShapes` puts shapes: in front of all others, or behind them. ## Options types The options of each function and command have a type of their own: | Type | Options of | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `StageOptions` | [`attachStage`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#attachstage) | | `ZoomAtStageCenterOptions` | [`zoomAtStageCenter`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#zoomatstagecenter) | | `StepZoomOptions` | [`stepZoom`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#stepzoom) | | `ZoomToFitShapesOptions` | [`zoomToFitShapes`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#zoomtofitshapes) | | `ScrollShapesIntoViewOptions` | [`scrollShapesIntoView`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#scrollshapesintoview) | | `FitCameraToRectOptions` | [`fitCameraToRect`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#fitcameratorect) | | `VisibleBoardRectOptions` | [`visibleBoardRect`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#visibleboardrect) | | `ClientToBoardOptions` | [`clientToBoard`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#clienttoboard) | | `TextShapeContentOptions` | [`textShapeContent`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#textshapecontent) | | `StickyNoteContentOptions` | [`stickyNoteContent`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#stickynotecontent) | | `FreehandFromPointsOptions` | [`freehandFromPoints`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#freehandfrompoints) | | `FindShapesOptions` | [`findShapes`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#findshapes) | | `InsertShapesInFrontOptions` | [`insertShapesInFront`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#insertshapesinfront) | | `RemoveShapesOptions` | [`removeShapes`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#removeshapes) | | `RestackShapesOptions` | [`restackShapes`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#restackshapes) | | `ShapeNodeViewOptions` | [`shapeNodeView`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#shapenodeview) | | `DataAttributeOptions` | [`dataAttribute`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#dataattribute) | | `AddImageFilesOptions` | [`addImageFiles`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#addimagefiles) | | `ExportBoardOptions` | [`exportBoard`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#exportboard) | | `ImportBoardOptions` | [`importBoard`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#importboard) | | `ExportBoardSvgOptions` | [`exportBoardSvg`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#exportboardsvg) | | `ExportBoardImageOptions` | [`exportBoardImage`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/utilities.md#exportboardimage) | | `InsertShapeOptions` | [`insertShape`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/commands.md#insertshape) | | `InsertStickyNoteOptions` | [`insertStickyNote`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/commands.md#insertstickynote) | | `MoveShapesOptions` | [`moveShapes`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/commands.md#moveshapes) | | `DuplicateShapesOptions` | [`duplicateShapes`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/commands.md#duplicateshapes) | | `FrameShapesOptions` | [`frameShapes`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/commands.md#frameshapes) | | `EditShapeTextOptions` | [`editShapeText`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/commands.md#editshapetext) | | `SetShapeStyleOptions` | [`setShapeStyle`](https://tiptap-docs.lin52025i.qzz.io/editor/whiteboard/api-reference/commands.md#setshapestyle) |