--- title: "Whiteboard types" description: "TypeScript types of the Tiptap Whiteboard extension." canonical_url: "https://tiptap.dev/docs/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. - `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), and also the style `arrowheads`. Doc frames have no `color`, but a `docId`. 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`) ## `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.dev/docs/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'`. 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.dev/docs/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.dev/docs/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'`. 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.dev/docs/editor/whiteboard/api-reference/extensions.md#whiteboardkit). ### Properties - `undoRedo` (`Partial | false`) - `shapeElementAttributes` (`ShapeElementAttributes | null`) - `docs` (`BoardDocs | null`) - `colors` (`readonly ShapeColor[]`) - `toolKeys` (`ToolKeys | false`) `BoardOptions`, the options of `Board`, has `shapeElementAttributes` and `docs`. `BoardStorage` is what the board keeps in `editor.storage.board`, see [Extensions](https://tiptap.dev/docs/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.dev/docs/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. ## `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.dev/docs/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 not a board file, or when a newer version of the whiteboard wrote it. ### Properties - `code` (`BoardFileErrorCode`): Why the file can't be opened. ### `BoardFileErrorCode` Type: `'not-a-board-file' | 'version-too-new'`. ## `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. ### `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. ## `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[]`) ## `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.dev/docs/editor/whiteboard/api-reference/utilities.md#attachstage) | | `ZoomAtStageCenterOptions` | [`zoomAtStageCenter`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#zoomatstagecenter) | | `StepZoomOptions` | [`stepZoom`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#stepzoom) | | `ZoomToFitShapesOptions` | [`zoomToFitShapes`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#zoomtofitshapes) | | `ScrollShapesIntoViewOptions` | [`scrollShapesIntoView`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#scrollshapesintoview) | | `FitCameraToRectOptions` | [`fitCameraToRect`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#fitcameratorect) | | `VisibleBoardRectOptions` | [`visibleBoardRect`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#visibleboardrect) | | `ClientToBoardOptions` | [`clientToBoard`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#clienttoboard) | | `TextShapeContentOptions` | [`textShapeContent`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#textshapecontent) | | `StickyNoteContentOptions` | [`stickyNoteContent`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#stickynotecontent) | | `FreehandFromPointsOptions` | [`freehandFromPoints`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#freehandfrompoints) | | `FindShapesOptions` | [`findShapes`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#findshapes) | | `InsertShapesInFrontOptions` | [`insertShapesInFront`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#insertshapesinfront) | | `RemoveShapesOptions` | [`removeShapes`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#removeshapes) | | `RestackShapesOptions` | [`restackShapes`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#restackshapes) | | `ShapeNodeViewOptions` | [`shapeNodeView`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#shapenodeview) | | `DataAttributeOptions` | [`dataAttribute`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#dataattribute) | | `ExportBoardOptions` | [`exportBoard`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#exportboard) | | `ImportBoardOptions` | [`importBoard`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#importboard) | | `ExportBoardSvgOptions` | [`exportBoardSvg`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#exportboardsvg) | | `ExportBoardImageOptions` | [`exportBoardImage`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#exportboardimage) | | `InsertShapeOptions` | [`insertShape`](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md#insertshape) | | `InsertStickyNoteOptions` | [`insertStickyNote`](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md#insertstickynote) | | `MoveShapesOptions` | [`moveShapes`](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md#moveshapes) | | `DuplicateShapesOptions` | [`duplicateShapes`](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md#duplicateshapes) | | `EditShapeTextOptions` | [`editShapeText`](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md#editshapetext) | | `SetShapeStyleOptions` | [`setShapeStyle`](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md#setshapestyle) |