--- title: "Whiteboard commands" description: "All editor commands of the Tiptap Whiteboard extension." canonical_url: "https://tiptap.dev/docs/editor/whiteboard/api-reference/commands" --- # Whiteboard commands All editor commands of the Tiptap Whiteboard extension. 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()`](#setshapestyle) unless the options set them. Puts the caret inside when the shape holds text, and selects it otherwise. ```js 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()`](#updateshapes), it skips what wouldn't change. ```js 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. ```js 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. ```js 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. ```js 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. ```js 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. ```js 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. ```js 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()`](#setshapestyle) chose another color. ```js 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. ```js 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. ```js editor.commands.toggleShapeSelection('idea') ``` ### Parameters - `id` (`string`): The id of the shape. ### Returns (`boolean`) Always `true`. ## `selectAllShapes` Selects every shape on the board. ```js editor.commands.selectAllShapes() ``` ### Parameters None. ### Returns (`boolean`) Always `true`. ## `clearShapeSelection` Unselects all shapes and ends text editing, so keys act on the board. ```js 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](https://tiptap.dev/docs/editor/whiteboard/guides/shapes-and-tools.md#read-only-boards) selects the shape. ```js 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](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#focusboard), which focuses right away. ```js editor.chain().selectShapes(['note-1']).focusBoard().run() ``` ### Parameters None. ### Returns (`boolean`) Always `true`. ## `selectShapeText` Selects all text of the shape that holds the selection. ```js 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. ```js 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. ```js 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](https://tiptap.dev/docs/editor/whiteboard/api-reference/utilities.md#focusboard). A [read-only board](https://tiptap.dev/docs/editor/whiteboard/guides/shapes-and-tools.md#read-only-boards) goes back to `select` from the tools that change the board. The `doc` tool needs the [`docs` option](https://tiptap.dev/docs/editor/whiteboard/guides/doc-frames.md). ```js 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. ```js editor.commands.setShapeStyle({ name: 'color', value: 'blue' }) ``` ### Parameters (`SetShapeStyleOptions`) - `name` (`ShapeStyleName`): The style, like `color` or `fontSize`. - `value` (`ShapeStyleValue`): 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. ```js 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. ```js 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](https://tiptap.dev/docs/editor/whiteboard/guides/collaboration.md#show-what-others-select-and-drag). ```js 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.