---
title: "Whiteboard extensions"
description: "WhiteboardKit and its options, the extensions it brings, and BoardCollaboration."
canonical_url: "https://tiptap.dev/docs/editor/whiteboard/api-reference/extensions"
---

# Whiteboard extensions

WhiteboardKit and its options, the extensions it brings, and BoardCollaboration.

`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`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#attachstage).

```js
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`](https://tiptap.dev/docs/editor/extensions/functionality/undo-redo.md). 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](https://tiptap.dev/docs/editor/whiteboard/guides/doc-frames.md).
- `colors` (`readonly ShapeColor[]`): The names of the board's colors. Text colors and highlights from pasted HTML keep only these. Default: [`shapeColors`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#shapecolors). See [Colors](https://tiptap.dev/docs/editor/whiteboard/api-reference/styling.md#colors).
- `toolKeys` (`ToolKeys | false`): Keys that replace the default keys of their tools, see [`toolKeys`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#toolkeys). `null` leaves a tool without a key, and `false` turns all tool keys off. Default: `toolKeys`.

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

| Extension              | Name                   | Description                                                                                      |
| ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| `WhiteboardDocument`   | `doc`                  | The top node of a board's editor, which holds the board and nothing else                         |
| `Board`                | `board`                | The board, which holds every shape, with the commands that change shapes                         |
| `StickyNote`           | `stickyNote`           | A sticky note with text                                                                          |
| `Geo`                  | `geo`                  | A geometric shape with text, like a rectangle or an ellipse                                      |
| `FreeText`             | `freeText`             | Text without a shape around it                                                                   |
| `Freehand`             | `freehand`             | A line drawn with the pen                                                                        |
| `DocFrame`             | `docFrame`             | A frame on the board that shows a document of its own, in an editor of its own                   |
| `Arrow`                | `arrow`                | An arrow between shapes or free points                                                           |
| `BoardTextColor`       | `textColor`            | Colors parts of a shape's text with the name of a board color                                    |
| `BoardHighlight`       | `highlight`            | Highlights parts of a shape's text in a board color. Highlights without a board color are yellow |
| `BoardLink`            | `link`                 | Links in shape text, which open in a new tab with a click with Control, or Cmd on macOS          |
| `BoardTaskItem`        | `taskItem`             | A task item whose checkbox also toggles while no text is edited                                  |
| `KeepSelectionInShape` | `keepSelectionInShape` | Stops selections, arrow keys and jumps from leaving the current shape                            |
| `ShapeSelection`       | `shapeSelection`       | Selects shapes by id                                                                             |
| `RemoteSelections`     | `remoteSelections`     | Shows the shapes that other users select                                                         |
| `BoardHistory`         | `boardHistory`         | Undo and redo for the board, which select the shapes that they change                            |
| `BoardTools`           | `boardTools`           | Keeps the active tool outside of the document, like the selection                                |
| `ShapeStyle`           | `shapeStyle`           | Keeps 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](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md) 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`](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#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.

```js
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](https://tiptap.dev/docs/editor/extensions/functionality/collaboration.md). 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](https://tiptap.dev/docs/editor/whiteboard/guides/collaboration.md).