Tiptap Docs

Whiteboard commands

Pilot programAlpha

All editor commands of the Whiteboard extension. WhiteboardKit adds all of them.

  • Shapes are found by their ids.
  • Positions and sizes are in board units.

The other text commands come from the Tiptap extensions in the kit, like toggleBold, setHighlight, setLink and toggleTaskList. setHighlight takes a board color, like setHighlight({ color: 'blue' }).

insertShape

Adds a shape in front of all other shapes, with the styles from setShapeStyle() unless the options set them. Puts the caret inside when the shape holds text, and selects it otherwise.

editor.commands.insertShape({ type: 'geo', kind: 'ellipse', x: 100, y: 100 })

Parameters (InsertShapeOptions)

  • type (string): The node type of the shape, like geo, freeText or arrow.
  • id? (string): An id that no shape on the board has. Generated unless given.
  • Other attributes (unknown): The attributes of the shape, like x, y or color.

Returns (boolean)

false, and adds nothing, when an attribute is NaN or infinite, when the type isn't a shape, or when a shape on the board has the id already.

updateShape

Changes attributes of the shape with the given id. Like updateShapes(), it skips what wouldn't change.

editor.commands.updateShape({ id: 'note-1', attributes: { color: 'blue' } })

Parameters

  • update (ShapeUpdate): The id of the shape and the attributes to change.

Returns (boolean)

false when nothing would change.

updateShapes

Changes attributes of several shapes in one step. Skips ids that are not on the board, updates that would change an id or hold NaN or an infinite number, attributes that a shape does not have, and shapes that already have the attributes.

editor.commands.updateShapes([
  { id: 'idea', attributes: { x: 0 } },
  { id: 'plan', attributes: { x: 300 } },
])

Parameters

  • updates (readonly ShapeUpdate[]): The id of each shape, with the attributes to change.

Returns (boolean)

false when nothing would change.

moveShapes

Moves the shapes with the given ids. Arrows move their free ends.

editor.commands.moveShapes({ ids: ['note-1', 'note-2'], delta: { x: 40, y: 0 } })

Parameters (MoveShapesOptions)

  • ids (readonly string[]): The ids of the shapes.
  • delta (Point): How far to move them, in board units.

Returns (boolean)

false when nothing would move.

duplicateShapes

Adds copies of the shapes with new ids, moved by offset, in front of all other shapes, and selects them. A copied doc frame gets a copy of its document from the docs option. A copied frame comes with copies of its shapes.

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

editor.commands.duplicateShapes({ ids: getSelectedShapeIds(editor.state) })

Parameters (DuplicateShapesOptions)

  • ids (readonly string[]): The ids of the shapes.
  • offset? (Point): How far from the shapes their copies land, in board units. Default: 24 right and down.

Returns (boolean)

false, and adds nothing, when none of the shapes is on the board, or when the offset is NaN or infinite.

insertConnectedShape

Adds a shape like the one with the given id on its side, 100 board units away, with an arrow to it, in one step, and puts the caret inside. The new shape has the kind, size and styles of the first, but no text. When other shapes take its spot, it takes the nearest free spot along that side, first after the spot and then before it, like below and then above. When they take the whole side, like a tall doc frame, it goes further out, past them. With at, it goes past that point instead, facing the first shape, and with kind, it is a geometric shape of that kind. The arrow leaves the first shape on side. It gets the styles from setShapeStyle(), and bends at right angles, like in FigJam, unless setShapeStyle() chose another arrowKind. The stage of attachStage moves the camera to show the new shape.

The connect handles and Control + Enter (Cmd + Enter on macOS) run it.

editor.commands.insertConnectedShape({ id: 'step-1', side: 'right' })
editor.commands.insertConnectedShape({
  id: 'step-1',
  side: 'right',
  at: { x: 600, y: 80 },
  kind: 'diamond',
})

Parameters (InsertConnectedShapeOptions)

  • id (string): The id of the shape to start from, a geometric shape or a sticky note.
  • side (ShapeSide): The side of the shape where the new shape goes, and where the arrow leaves it: top, right, bottom or left.
  • at? (Point): Where the arrow ends, in board units, like where a drag from a connect handle stops. The new shape goes past it, with the middle of the side that faces the first shape there.
  • kind? (GeoKind): The kind of geometric shape to add, instead of a shape like the first.

Returns (boolean)

false, and adds nothing, for other shapes, for an id, side or kind that doesn't exist, or when the new shape would be at an infinite position.

deleteShapes

Deletes the shapes with the given ids in one step, and the shapes in the frames among them. Arrows that connect a deleted shape stay, with a free end where they touched it.

editor.commands.deleteShapes(['note-1'])

Parameters

  • ids (readonly string[]): The ids of the shapes.

Returns (boolean)

false when none of the shapes is on the board.

frameShapes

Puts shapes in a new frame around them, with 32 board units of room, and selects the frame. Shapes in another frame move to the new one. Frames and arrows stay out.

editor.commands.frameShapes({ ids: ['note-1', 'note-2'], name: 'Ideas' })

Parameters (FrameShapesOptions)

  • ids (readonly string[]): The ids of the shapes to put in the frame.
  • id? (string): The id of the new frame. Defaults to a new one.
  • name? (string): The name of the new frame. Without one, it shows "Frame".

Returns (boolean)

false without a shape that can be in a frame, or when a shape already has the id.

removeFrame

Removes a frame and keeps its shapes on the board. deleteShapes deletes them along with the frame.

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

Parameters

  • id (string): The id of the frame.

Returns (boolean)

false when the board has no frame with the id.

bringToFront

Puts the shapes in front of all other shapes and keeps their order among each other.

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

editor.commands.bringToFront(getSelectedShapeIds(editor.state))

Parameters

  • ids (readonly string[]): The ids of the shapes.

Returns (boolean)

false when none of the shapes is on the board.

sendToBack

Puts the shapes behind all other shapes and keeps their order among each other.

editor.commands.sendToBack(['note-1'])

Parameters

  • ids (readonly string[]): The ids of the shapes.

Returns (boolean)

false when none of the shapes is on the board.

insertStickyNote

Adds a sticky note in front of all other shapes and puts the caret inside it. Notes are yellow unless setShapeStyle() chose another color.

editor.commands.insertStickyNote({ x: 100, y: 100 })

Parameters (InsertStickyNoteOptions)

  • x (number): Where the note's left edge goes.
  • y (number): Where the note's top edge goes.
  • width? (number): Default: the width of stickyNoteSize, 220.
  • height? (number): Default: the height of stickyNoteSize, 160.
  • id? (string): An id that no shape on the board has. Generated unless given.

Returns (boolean)

false, and adds nothing, when an option is NaN or infinite, or when a shape on the board has the id already.

selectShapes

Selects the shapes with the given ids. Unknown ids are ignored.

editor.commands.selectShapes(['idea', 'plan'])

Parameters

  • ids (readonly string[]): The ids of the shapes, in the order they were selected.

Returns (boolean)

Always true.

toggleShapeSelection

Adds the shape to the selection, or removes it when it is already selected.

editor.commands.toggleShapeSelection('idea')

Parameters

  • id (string): The id of the shape.

Returns (boolean)

Always true.

selectAllShapes

Selects every shape on the board.

editor.commands.selectAllShapes()

Parameters

None.

Returns (boolean)

Always true.

clearShapeSelection

Unselects all shapes and ends text editing, so keys act on the board.

editor.commands.clearShapeSelection()

Parameters

None.

Returns (boolean)

Always true.

editShapeText

Unselects all shapes and puts the caret into the shape's text: at pos when it lies in that text, otherwise at the end. A doc frame starts editing its document instead. A read-only board selects the shape.

editor.chain().focus().editShapeText({ id: 'note-1' }).run()

Parameters (EditShapeTextOptions)

  • id (string): The id of the shape.
  • pos? (number): The caret's position in the document, inside the shape's text. Default: the end.

Returns (boolean)

false when no shape has the id, for shapes without text, like pen lines, and for doc frames on a board without docs.

focusBoard

Focuses the board, or the text while it is edited, after the chain's transaction. Unlike focus, it also works while the text is read-only. For code outside a chain, like a toolbar button's click handler, call the focusBoard() function, which focuses right away.

editor.chain().selectShapes(['note-1']).focusBoard().run()

Parameters

None.

Returns (boolean)

Always true.

selectShapeText

Selects all text of the shape that holds the selection.

editor.chain().editShapeText({ id: 'note' }).selectShapeText().run()

Parameters

None.

Returns (boolean)

false when no shape holds the selection. While the board has the keyboard, it returns true but selects nothing, so start editing first, like with editShapeText.

setTextColor

Colors the selected text with a board color. The mark stores the name of the color, so your CSS decides how it looks.

editor.commands.setTextColor('red')

Parameters

  • color (ShapeColor): The name of a board color, like red.

Returns (boolean)

false when none of the selected text can take the mark.

unsetTextColor

Gives the selected text its shape's color again.

editor.commands.unsetTextColor()

Parameters

None.

Returns (boolean)

Always true.

setTool

Chooses what a press on the board does, and ends text editing, so keys act on the board. It doesn't move the focus: after a click on a toolbar button, call the focusBoard() function. A read-only board goes back to select from the tools that change the board. The doc tool needs the docs option.

editor.commands.setTool('pen')

Parameters

  • tool (Tool): The tool, like select, note or pen.

Returns (boolean)

false for the doc tool on a board without docs, and true for every other tool.

setShapeStyle

Gives the selected shapes, or the shape whose text is edited, the style in one step, and shapes added later get it too. Shapes that don't have the style stay as they are.

editor.commands.setShapeStyle({ name: 'color', value: 'blue' })

Parameters (SetShapeStyleOptions<Name>)

  • name (ShapeStyleName): The style, like color or fontSize.
  • value (ShapeStyleValue<Name>): The name of its value, like blue or l.

Returns (boolean)

Always true.

undoBoard

Undoes the last change and selects the shapes it changed. An undo that only changed text goes back to editing that text. Works with Tiptap's UndoRedo and with Collaboration.

editor.commands.undoBoard()

Parameters

None.

Returns (boolean)

false when there is nothing to undo, or when the editor has neither UndoRedo nor Collaboration.

redoBoard

Redoes the last undone change and selects the shapes it changed. A redo that only changed text goes back to editing that text.

editor.commands.redoBoard()

Parameters

None.

Returns (boolean)

false when there is nothing to redo, or when the editor has neither UndoRedo nor Collaboration.

setRemoteSelections

Shows the shapes that other users select, instead of what showed before. See Collaboration.

editor.commands.setRemoteSelections([{ color: '#be185d', ids: ['idea'] }])

Parameters

  • selections (readonly RemoteSelection[]): The shapes that each user selects, with the user's color.

Returns (boolean)

Always true.

Colors need the form #RRGGBB, and a selection with another color doesn't show. When several users select a shape, the first one with a valid color shows.

PreviouslyExtensions