---
title: "Whiteboard frames"
description: "Group shapes on a whiteboard in frames, which take their shapes along and cut them off at their edges."
canonical_url: "https://tiptap.dev/docs/editor/whiteboard/guides/frames"
---

# Whiteboard frames

Group shapes on a whiteboard in frames, which take their shapes along and cut them off at their edges.

A frame groups shapes. The shapes in it move along with it and are cut off at its edges, and its name shows above its top left corner. Unlike a [doc frame](https://tiptap.dev/docs/editor/whiteboard/guides/doc-frames.md), which shows a document, a frame holds other shapes.

## Add frames

With the `frame` tool, users draw a frame with a drag, or add one with a click. Its key is F. A new frame takes in the shapes that lie all in it and are in no other frame.

`frameShapes` puts shapes in a new frame around them, with 32 board units of room, and selects the frame:

```js
import { getSelectedShapeIds } from '@tiptap-pro/extension-whiteboard'

editor.commands.frameShapes({ ids: getSelectedShapeIds(editor.state), name: 'Ideas' })
```

`insertShape` adds a frame like other shapes:

```js
editor.commands.insertShape({ type: 'frame', name: 'Ideas', width: 600, height: 400 })
```

## Shapes in a frame

The `frameId` of a shape is the id of its frame, or `null`. The board keeps it as the board changes:

- A shape that is added, moved or resized goes into the frontmost frame under its middle, or out of its frame. A shape added with the id of a frame that it overlaps stays in it.
- A frame that moves takes its shapes along, also when `updateShapes` or `moveShapes` moves it.
- A frame that is resized lets go of the shapes that it no longer overlaps. Its shapes keep their size.
- A copy of a frame, made by `duplicateShapes` or a paste, comes with copies of its shapes, which are in the copy. It takes in no other shapes.

Frames and arrows are in no frame, so a frame holds no other frames. A change that comes through Yjs keeps the frames that the editor that made it gave the shapes. Changes of two editors at the same time can leave a shape apart from its frame, like a shape that one adds in a frame that the other moves away. A shape that doesn't overlap its frame counts as in no frame.

## Select, delete and stack

- A press inside a frame goes to the board and the shapes there, so a drag there draws a selection box. Users select and move a frame by its edge or its name. A selection box picks a frame only when the frame lies all in it.
- `deleteShapes` deletes a frame with its shapes. `removeFrame` removes the frame and keeps its shapes:

```js
editor.commands.removeFrame('frame-1')
```

- Frames are behind all other shapes, whatever their `zIndex`. The eraser leaves them alone.
- A shape in a frame shows only as far as the frame reaches, unless the shape is selected. Image exports, the fit to the shapes, the selection box and the eraser count it only that far too.
- An image export of a frame draws its shapes and its name too.

## Names

The `name` of a frame shows above its top left corner, or "Frame" when it has none. A name wider than the frame ends in an ellipsis. A double click on the name renames the frame in a field, unless the board is read-only. Enter keeps the new name, and Escape drops it. Style the name through `data-frame-title`, see [Styling](https://tiptap.dev/docs/editor/whiteboard/api-reference/styling.md#parts-of-shapes).

## Next steps

- Choose the tools and their keys in [Shapes and tools](https://tiptap.dev/docs/editor/whiteboard/guides/shapes-and-tools.md)
- See all [commands](https://tiptap.dev/docs/editor/whiteboard/api-reference/commands.md)