Commands
The chain API and every built-in GoTipe editor command, grouped by what they change.
Commands turn an intent such as "make this bold" into a transaction based on the current selection. editor.chain() starts a chain, each call stages one command, and run() dispatches everything as one transaction and one undo step.
Run a chain
editor.chain().focus().toggleBold().run();
editor
.chain()
.setSelection({ type: "text", blockId: "intro", from: 0, to: 5 })
.setBlockType("heading", { level: 2 })
.toggleItalic()
.run();run() returns true when it dispatched a transaction or only moved focus, and false when nothing was staged or a transaction filter cancelled the change. It throws VALIDATION_ERROR or TRANSFORM_ERROR when the result is invalid, for example when a command inserts a block type the editor's extensions don't declare. Each chain() call returns a new chain; use it once.
How a chain reads the document
Commands in one chain all read the document and selection as they were when the chain started; they don't see each other's changes.
chain().insertBlockAfter("paragraph").insertBlockAfter("divider")inserts both right after the current block, so the divider ends up first.setSelection()is the exception: later commands in the chain use the staged selection, and it becomes the selection after the transaction. The same holds forselectAll()andselectBlock(). When the chain's own steps remove the staged block or shorten its text, the selection moves as the caret does. Text merged into the previous block keeps its place there. A removed block gives way to the start of the next remaining text block, or the end of the previous one. An offset past the end of the text goes to the end. A removed selected block leaves a caret. Chains such aschain().selectAll().deleteBlock().run()andsetSelection(…).mergeWithPrevious()rely on this.undo()andredo()replace the chain:run()performs only the undo or redo and drops the other staged commands.
Chain commands that touch different parts of the document, or run separate chains.
Buttons and focus
A toolbar button takes focus away from the document. Cancel mousedown on the button and start the chain with focus(), so the command uses the document's selection and the caret returns afterwards:
import type { GoTipeEditor } from "@gotipe/core";
export function BoldButton({ editor }: { editor: GoTipeEditor }) {
return (
<button
type="button"
onMouseDown={(event) => event.preventDefault()}
onClick={() => editor.chain().focus().toggleBold().run()}
>
Bold
</button>
);
}Marks
Mark commands apply to every rich-text block the selection covers, including the list items and table cells of a selection across blocks or of a selected list or table. Lists, tables, dividers, images and code blocks themselves are passed over. With a caret and no selected text, toggle* commands switch the mark on or off for the next text the user types.
| Command | Description |
|---|---|
toggleBold(), toggleItalic(), toggle, toggle, toggleCode() |
Toggle bold, italic, underline, strikethrough or code. |
toggle, toggle |
Toggle superscript or subscript. |
toggle |
Toggle highlight, with { color } when given. |
toggle |
Remove the mark when all selected text has it, otherwise add it. |
add |
Add a mark to the selection, or to [from, to) in the block at the selection anchor. Text that has the mark takes the new attributes. |
set |
addMark on the selection. |
remove |
Remove a mark from the selection or the given range. |
unsetMark(type) |
removeMark on the selection. |
set |
Add a link mark with href and target ("_blank" by default). |
removeLink() |
Remove links from the selection. |
clear |
Remove every formatting mark from the selected text; inline atoms (mentions, formulas, custom emoji, inline images) stay. |
Adding a mark replaces a mark of the same type, so setLink(href) changes the address of a link and setMark("textColor", { color }) recolours text, as one undo step. Attributes you leave out get the defaults the mark declares: setLink stores target and rel. Superscript and subscript share an exclusive group: adding one removes the other.
Blocks
| Command | Description |
|---|---|
set |
Turn the block at the selection anchor into type, replacing its attributes and keeping its ID. A list item turned into another type leaves its list, which splits around it. |
set |
Merge attrs into a block's attributes. |
insert, insert |
Insert an empty block next to the current one. Inside a parent that doesn't accept type (a list, a table), it goes next to that parent instead. The caret doesn't move. |
insert |
Replace the selection with unformatted text and put the caret after it. Works across blocks. |
insert |
insert: a line break inside the block. |
delete |
Delete a block with its children; the current block by default. |
duplicate |
Insert a copy with new IDs after the block. |
move, move |
Swap the block with its previous or next sibling. |
move |
Move a block to targetIndex among the top-level blocks. |
splitBlock() |
Split the block at the caret; the new block below gets a new ID. The caret stays in the first block. |
merge |
Append the block to its previous sibling. |
setBlockType, insertBlockAfter, insertBlockBefore and the list commands give the new block the declared default of every attribute you leave out, such as type: "info" for a callout or language: "" (plain text) for a code block. A heading level that the Heading extension doesn't offer stages nothing (see values in attributes).
The content follows the content the type declares, for built-in node types and your own alike: a new block starts with empty rich text ([]), raw text ("") or none (null), and setBlockType keeps the text as spans or as raw text without marks, or drops it for a type without content. In an editor without a schema (extensions: []) no type declares one: a new block gets rich text and setBlockType leaves the content as it is.
Lists
| Command | Description |
|---|---|
toggle, toggle, toggle |
Wrap the current block in a list when its type holds text, rich or raw (a paragraph, heading, formula, toggle or a node of your own): the block becomes the only item with its text and child blocks. A block without text stays as it is. In a list of another kind, convert that list. In a list of the same kind, turn all its items into paragraphs. |
setBulletList(), set, setTodoList() |
Like the toggles, but never unwrap a list of the same kind. |
indent() |
Nest the list item under the previous item. |
outdent() |
Move a nested list item one level out. |
splitListItem() |
Same as splitBlock(). |
Structures
| Command | Description |
|---|---|
insert |
Insert a table after the current block; withHeader makes the first row header cells. At most 5,000 cells. |
insert |
Insert 1 to 12 columns, each with an empty paragraph. Needs the Columns extension. |
insertToggle() |
Insert an open toggle with an empty summary and an empty paragraph. |
goToNextCell(), goToPrevCell() |
Select the text of the next or previous cell of the same table; at its last or first cell, return false from run(). |
Rows and columns of an existing table change with editTable, a function rather than a chain command. It dispatches one transaction and returns its result:
import { editTable } from "@gotipe/core";
editTable(editor, "table-1", { type: "insertRow", index: 1 });
editTable(editor, "table-1", { type: "resizeColumn", index: 0, width: 240 });| Edit | Description |
|---|---|
{ type: "insert, { type: "delete |
Insert an empty row, or delete one; deleting the only row deletes the table. |
{ type: "insert, { type: "delete |
Insert an empty cell in every row, or delete a column; deleting the only column deletes the table. |
{ type: "resize |
Set the column width in pixels, rounded and kept between 64 and 1600. |
editTable returns false on a read-only or destroyed editor and throws VALIDATION_ERROR when the table is missing, the index is out of range or the table has merged cells.
Selection, focus and history
| Command | Description |
|---|---|
set |
Stage a selection for the following commands without moving the live caret first. |
selectAll() |
Select from the start of the first text block to the end of the last. |
select |
Select a whole block; the current one by default. |
focus( |
Focus the mounted editor when the chain runs; "start" or "end" also moves the caret. |
undo(), redo() |
Undo or redo instead of the other staged commands. |
run() |
Dispatch the staged commands as one transaction. |
Keyboard shortcuts
The built-in extensions bind these keys. Mod is Cmd on macOS and Ctrl elsewhere.
| Keys | Command |
|---|---|
Mod-B, Mod-I, Mod-U, Mod-E |
toggleBold, toggleItalic, toggleUnderline, toggleCode |
Mod-Shift-X, Mod-Shift-H |
toggle, toggleHighlight |
Mod-., Mod-, |
toggle, toggleSubscript |
Mod-Alt-1 … Mod-Alt-6 |
set for the configured heading levels |
Mod-Shift-7, Mod-Shift-8, Mod-Shift-9 |
toggle, toggle, toggleTodoList |
Mod-Shift-B |
set |
Tab, Shift-Tab in a list |
indent, outdent |
Tab, Shift-Tab in a table |
goToNextCell, goToPrevCell |
Mod-Z; Mod-Shift-Z or Mod-Y |
undo; redo |
Mod-K |
Emits openLinkDialog: the link field of BlockEditor or FixedToolbar opens over selected text, or your own link interface |
The full list, including the editor UI's keys, is in keyboard.
Reading state
Interfaces decide what to show from the view state:
| Method | Returns |
|---|---|
editor. |
true when name is an active mark at the selection, or the current block has type name and the given attribute values. |
editor. |
{ type, id, attrs, is of the block at the selection anchor, or null. |
editor. |
activeMarks, activeBlockType, active, canUndo, canRedo. |
editor. |
true when the editor was created with an extension of that name, alone or in a preset; fixed for the editor's life. |
Active marks are read at the caret, or at the start of the selected range. In React, useEditorState(editor, (state) => state.toolbar) re-renders when they change.
Limitations
insertTextinserts unformatted text; it ignores marks toggled with a caret.
Related
- Transactions for edits that commands don't cover.
- Extensions: bind your own keys to commands.
- Menus in the ready UI.