Tiptap Docs

Whiteboard extensions

AlphaPilot program

WhiteboardKit brings every extension of the board. Import it, and each of these extensions, from @tiptap-pro/extension-whiteboard. BoardCollaboration comes from its own entry.

Editor comes from @tiptap/core, and UndoRedoOptions from @tiptap/extensions.

WhiteboardKit

The whiteboard: the board and its shapes, their text, the selection, the tools, the styles for new shapes, and undo. It brings its own document node and text extensions too, so don't add Document or StarterKit to its editor. Your app provides the stage around the board, see attachStage.

import { Editor } from '@tiptap/core'
import { WhiteboardKit } from '@tiptap-pro/extension-whiteboard'

const editor = new Editor({ element: viewport, extensions: [WhiteboardKit] })

Options (WhiteboardKitOptions)

  • undoRedo (Partial<UndoRedoOptions> | false): The options of Tiptap's UndoRedo. Set to false when collaboration handles undo. undoBoard and redoBoard then use it. Default: {}.
  • shapeElementAttributes (ShapeElementAttributes | null): Extra attributes for the element of every shape, from the shape's node. Values become strings, and null or undefined leaves an attribute out. Default: null.
  • docs (BoardDocs | null): Where the documents of doc frames live. Without it, doc frames show no document. Default: null. See Doc frames.
  • colors (readonly ShapeColor[]): The names of the board's colors. Text colors and highlights from pasted HTML keep only these. Default: shapeColors. See Colors.
  • toolKeys (ToolKeys | false): Keys that replace the default keys of their tools, see toolKeys. null leaves a tool without a key, and false turns all tool keys off. Default: toolKeys.
import { getSuggestionHTMLAttributes } from '@tiptap-pro/extension-tracked-changes'
import { shapeColors, WhiteboardKit } from '@tiptap-pro/extension-whiteboard'

WhiteboardKit.configure({
  undoRedo: { depth: 50 },
  // Lets CSS show the shapes that a suggestion changes
  shapeElementAttributes: getSuggestionHTMLAttributes,
  colors: [...shapeColors, 'brand'],
  toolKeys: { pen: 'b', eraser: null },
})

Included extensions

ExtensionNameDescription
WhiteboardDocumentdocThe top node of a board's editor, which holds the board and nothing else
BoardboardThe board, which holds every shape, with the commands that change shapes
StickyNotestickyNoteA sticky note with text
GeogeoA geometric shape with text, like a rectangle or an ellipse
FreeTextfreeTextText without a shape around it
FreehandfreehandA line drawn with the pen
DocFramedocFrameA frame on the board that shows a document of its own, in an editor of its own
ArrowarrowAn arrow between shapes or free points
BoardTextColortextColorColors parts of a shape's text with the name of a board color
BoardHighlighthighlightHighlights parts of a shape's text in a board color. Highlights without a board color are yellow
BoardLinklinkLinks in shape text, which open in a new tab with a click with Control, or Cmd on macOS
BoardTaskItemtaskItemA task item whose checkbox also toggles while no text is edited
KeepSelectionInShapekeepSelectionInShapeStops selections, arrow keys and jumps from leaving the current shape
ShapeSelectionshapeSelectionSelects shapes by id
RemoteSelectionsremoteSelectionsShows the shapes that other users select
BoardHistoryboardHistoryUndo and redo for the board, which select the shapes that they change
BoardToolsboardToolsKeeps the active tool outside of the document, like the selection
ShapeStyleshapeStyleKeeps the styles for new shapes outside of the document

The kit also adds these Tiptap extensions: Paragraph, Text, Bold, Italic, Strike, Code, BulletList, OrderedList, ListItem, TaskList and ListKeymap, and UndoRedo unless undoRedo is false. Task lists can nest.

See Commands for the commands of each extension.

Board

The board, which holds every shape, with the commands that change shapes. It adds the CSS that the board needs to the page, unless the editor's injectCSS is false. Configure it through WhiteboardKit, which passes on shapeElementAttributes and docs.

Storage (BoardStorage)

Available at editor.storage.board.

  • shapeElementAttributes (ShapeElementAttributes | null): The shapeElementAttributes option, for the node views of the shapes.
  • docs (BoardDocs | null): The docs option, for doc frames and their copies.
  • docEditors (Map<string, Editor>): The editors of the documents that doc frames show, by document id.

To read the document editors, prefer getDocEditors. It returns none once the board's editor is destroyed.

BoardCollaboration

Collaboration that also syncs a first change that leaves the document empty, like deleting the last shape. Plain Collaboration drops that change when the editor starts on content from Yjs. Use it instead of Collaboration, and turn off the kit's own undo.

import { Editor } from '@tiptap/core'
import { WhiteboardKit } from '@tiptap-pro/extension-whiteboard'
import { BoardCollaboration } from '@tiptap-pro/extension-whiteboard/collaboration'
import * as Y from 'yjs'

const editor = new Editor({
  element: viewport,
  extensions: [
    WhiteboardKit.configure({ undoRedo: false }),
    BoardCollaboration.configure({ document: new Y.Doc() }),
  ],
})

It comes from @tiptap-pro/extension-whiteboard/collaboration and takes the options of Collaboration. It needs the optional peer dependencies @tiptap/extension-collaboration, @tiptap/y-tiptap and yjs, and y-protocols, which @tiptap/y-tiptap needs.

See Collaboration on the board.

PreviouslyAI agents