Tiptap Docs

Whiteboard commands

AlphaPilot program

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.

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.

deleteShapes

Deletes the shapes with the given ids in one step. 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.

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.

PreviouslyAPI reference