Tiptap Docs

Whiteboard frames

AlphaPilot program

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, 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:

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

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

insertShape adds a frame like other shapes:

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:
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.

Next steps

PreviouslyArrows