Whiteboard types

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 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, 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. Pen lines also have points and strokeWidth.

ShapeGeometry

Type: Pick<ShapeAttributes, 'x' | 'y' | 'width' | 'height'>. 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<Omit<ShapeAttributes, 'id'> & 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 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<Partial<Record<Tool, string | null>>>. The key that chooses each tool. null leaves a tool without a key. See 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.

ShapeStyles

Type: { [Name in ShapeStyleName]: ShapeStyleValue<Name> }. 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<string, unknown>. 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.

Properties

• undoRedo (Partial<UndoRedoOptions> | 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.

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.

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.

Properties

• upload ((options: UploadImageOptions) => Promise<string>): 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.

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<string, JSONContent>): 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, 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: