---
title: "Whiteboard"
description: "Add a whiteboard with sticky notes, shapes, arrows, drawings and doc frames to your app. The whole board is one Tiptap document."
canonical_url: "https://tiptap.dev/docs/editor/whiteboard/getting-started/overview"
---

# Whiteboard

Add a whiteboard with sticky notes, shapes, arrows, drawings and doc frames to your app. The whole board is one Tiptap document.

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.

> **Interactive demo:** [Whiteboard](https://embed-pro.tiptap.dev/preview/Extensions/Whiteboard)

## Install

First, [contact our team](https://tiptap.dev/contact-sales?form=pilot-program) to join the Tiptap Whiteboard pilot program.

Then, configure your package manager by following the [private registry guide](https://tiptap.dev/docs/guides/pro-extensions.md).

Then, install the package:

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

> **Required Tiptap version:**
>
> Make sure all `@tiptap/*` packages are version `3.22.5` or higher and on one version, also the
> text extensions that the package installs, like `@tiptap/extension-bold`.

> **Leave out Document and StarterKit:**
>
> `WhiteboardKit` brings its own document, text extensions and undo, so don't add `Document` or
> `StarterKit` to a board's editor.

Collaboration is optional and lives in `@tiptap-pro/extension-whiteboard/collaboration`, the only entry that needs Yjs. See [Collaboration on the board](https://tiptap.dev/docs/editor/whiteboard/guides/collaboration.md).

## 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`:

```js
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`:

```css
.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](https://tiptap.dev/docs/editor/whiteboard/guides/stage-and-camera.md).

### 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](https://tiptap.dev/docs/editor/whiteboard/guides/doc-frames.md).

## Next steps

To build the board into your app, [set up a board in React](https://tiptap.dev/docs/editor/whiteboard/guides/react.md), with buttons for the tools. Then, add and change [shapes, and choose tools](https://tiptap.dev/docs/editor/whiteboard/guides/shapes-and-tools.md), show documents on the board with [doc frames](https://tiptap.dev/docs/editor/whiteboard/guides/doc-frames.md), draw components of your app in [custom shapes](https://tiptap.dev/docs/editor/whiteboard/guides/custom-shapes.md), and save boards as files or images with [export and import](https://tiptap.dev/docs/editor/whiteboard/guides/export-and-import.md).

To edit a board together, add [collaboration](https://tiptap.dev/docs/editor/whiteboard/guides/collaboration.md). To let an AI add notes, draw diagrams and write documents on the board, use the [Server AI Toolkit](https://tiptap.dev/docs/ai/ai-toolkit/agents/whiteboard.md).