Whiteboard

With the Whiteboard extension, a Tiptap editor becomes a whiteboard. Users add sticky notes, shapes, text, arrows, pen lines and doc frames to a board, and pan and zoom around it. The extension is headless: it draws the board and its shapes, and your app adds the toolbar and the stage around the board.

Install

First, contact our team to join the Tiptap Whiteboard pilot program.

Then, configure your package manager by following the private registry guide.

Then, install the package:

npm install @tiptap/core @tiptap/pm @tiptap-pro/extension-whiteboard

Collaboration is optional and lives in @tiptap-pro/extension-whiteboard/collaboration, the only entry that needs Yjs. See Collaboration on the board.

Basic setup

A board needs two elements on your page: the stage, which takes pointer and wheel events, and the viewport inside it, which the camera moves. Create the editor in viewport, and connect it to stage with attachStage:

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

const editor = new Editor({ element: viewport, extensions: [WhiteboardKit] })
let camera = { x: 0, y: 0, zoom: 1 }

// Pan, zoom, draw and select in the stage, the element around the board
const detach = attachStage({
  stage,
  editor,
  updateCamera: (update) => {
    camera = update(camera)
    viewport.style.transform = toCssTransform(camera)
    viewport.style.setProperty('--zoom', String(camera.zoom))
  },
})

attachStage calls updateCamera with a function that turns the old camera into the new one, and returns a function that detaches everything again.

The stage needs position: relative, overflow: clip and touch-action: none. The viewport sits in its top left corner, with position: absolute, top: 0, left: 0 and transform-origin: 0 0:

.stage {
  height: 32rem;
  overflow: clip;
  position: relative;
  touch-action: none;
}

.viewport {
  left: 0;
  position: absolute;
  top: 0;
  transform-origin: 0 0;
}

/* The board's origin sits in the corner of the viewport, so the editor keeps no margin */
.viewport .tiptap {
  margin: 0;
}

How it works

The board is one Tiptap document

WhiteboardKit brings its own top node. The document holds one board node, and the board holds the shapes. So a board loads, saves and syncs like any other Tiptap document, for example as JSON or through Yjs.

Shapes are nodes

Each shape is a node on the board. Its position and size are attributes, in board units. Sticky notes, geometric shapes and free text hold paragraphs and lists, and users edit their text like any other content. Arrows, pen lines and doc frames are atom nodes.

Every shape has an id, and the commands find shapes by their ids. The board keeps the selected shapes apart from the text selection, also by id. While no text is edited, keys act on the board: they choose tools, and move, delete or restack the selected shapes.

A camera pans and zooms

The stage is the element around the board. Inside it, a viewport element holds the editor. The camera, { x, y, zoom }, is part of your app's state. attachStage turns pointer and wheel events and shortcuts in the stage into camera changes, and your app moves the viewport with toCssTransform(camera). See Stage and camera.

Doc frames hold documents of their own

A doc frame is a shape that shows a rich text document in an editor of its own. The board stores the frame and the id of its document. Your app keeps the documents and creates their editors. See Doc frames.

Next steps

To build the board into your app, set up a board in React, with buttons for the tools. Then, add and change shapes, and choose tools, show documents on the board with doc frames, draw components of your app in custom shapes, and save boards as files or images with export and import.

To edit a board together, add collaboration. To let an AI add notes, draw diagrams and write documents on the board, use the Server AI Toolkit.