Hotkeys
The default keymap, the chord syntax for plugin and app hotkeys, precedence, and how to override or disable a default binding.
Every key the editor handles goes through one keymap: your app’s bindings, then each plugin’s in list order, then the built-in ones. This page lists the defaults and shows how to add, override and disable bindings.
In the tables, Mod is Cmd on macOS and iOS and Ctrl elsewhere.
Default keymap
Editing and history
The Command column names the command onBeforeOperation sees first (see commands and steps).
| Keys | Action | Command | Where |
|---|---|---|---|
| Enter | Split the block, or add a block before or after it; what it does depends on the block’s role, see Enter and Backspace by role | splitBlock, insertBlocks, unNestBlock or setBlock |
Text |
| Shift + Enter | Insert a soft line break | insertText |
Text |
| Mod + Enter | Modify the block it is in, as in Notion: open or close a toggle (the document does not change); with the rich text plugin, check or uncheck a to-do. Over a block selection or a text range it acts on each such block the view shows, toggles and to-dos together; a to-do inside a collapsed toggle is left as it is. Elsewhere it does nothing: it never splits or edits text, and it claims the key, so a browser’s own Ctrl + Enter paragraph break never runs | none; setBlock for a to-do |
Text, or selected blocks |
| Tab | With allowNesting (<Edytor allowNesting>, off by default; without it the editor leaves Tab to the browser, which moves the focus on, unless a code line, a table cell or a suggestion takes it): nest the block into its previous sibling (after a list, under its last item; nothing happens when the list ends with a block that holds no children, such as an image, as under that block); selected sibling blocks, or the blocks a text selection spans, nest together and stay selected. A text selection spans the blocks holding its text: a list it starts or ends in is not one of them, its items are, so the keys move the same blocks as selecting those rows; a list it runs through moves whole with the blocks around it. Selected blocks with an unselected block between them move apart, so the keys never reorder the text. A selection across nesting levels nests each group of sibling blocks one level, as one undo step; a selected block’s selected descendants move with it. A closed toggle a block nests into opens, and a moved toggle keeps its open state |
nestBlock; moveBlocks for several |
Text, or selected blocks |
| Shift + Tab | With allowNesting: move the block out one level, after its parent; the blocks nested after it become its children. An item of a list container leaves the list instead and never takes the items after it (see list items). Selected sibling blocks, or the blocks a text selection spans, move out together. Across nesting levels each group of sibling blocks moves out one level, a selected block’s selected descendants with it; top-level blocks stay. A closed toggle that takes the blocks after it as children opens |
unNestBlock; moveBlocks for several |
Text, or selected blocks |
| Backspace, Delete | Delete the selected blocks, the selected atom, the selected range or one character; at a block edge, see by role. With Alt, Mod or Ctrl (a word or line delete), selected blocks or a selected atom go exactly as without it, in every browser | deleteBlocks, removeInline, deleteRange or deleteText |
Anywhere |
| Mod + Z | Undo | none (the history) | Anywhere |
| Mod + Shift + Z | Redo | none | Anywhere |
| Mod + Y | Redo | none | Windows and Linux |
Enter and Backspace by role
This table is the reference for what Enter and Backspace do at a block’s edges. A block’s role comes from its kind’s record (custom blocks); the bundled kinds are listed in Blocks. A block can have more than one role: a toggle continues and is a container.
| Role | Kinds | Enter | Backspace at the start |
|---|---|---|---|
| Plain | paragraph, heading | At the end, a block of the parent’s default child kind after it; at the start, one before it (both insertBlocks); in the middle, a split whose second half takes the default child kind (splitBlock). At the end of a block with text and children, a split that keeps the kind and takes the children. |
A kind the menus offer (one with presets) other than the parent’s default child, such as a heading, turns into that default, keeping its text, children and properties (setBlock). Otherwise, a nested block that is its parent’s last child moves out one level (unNestBlock), and any other merges into the block before it (mergeBackward); a list’s first item leaves the list (see List item). |
Continuing (continues) |
bulleted and numbered items, to-do, toggle | A block of the same kind with its first preset’s data (a new to-do is unchecked), after it at the end and before it at the start; a split in the middle keeps the kind. At the end of one with text and children, a split whose second half keeps the kind, with its first preset’s data (an unchecked to-do), and takes the children. In an empty one without children, it ends the run: it moves out one level when its parent is a continuing kind too (unNestBlock), else it turns into the parent’s default child in place (setBlock). |
As plain: turns into the parent’s default child first. |
Container (container) |
toggle, toggle heading, callout, quote | At the end of one with children, of an open toggle, or of a callout (a kind whose body always shows, body), a first child of its default child kind (insertBlocks). At the end of a closed toggle, a new toggle after it (after a closed toggle heading, which does not continue, a paragraph); its children stay. In the middle of the header of one with children, of an open toggle or of a callout, the text after the caret becomes its first child, of its default child kind, and the children stay with the header (splitBlock, one step); in a closed toggle’s, it goes to a new toggle after it and the children stay. Otherwise as its other role. |
As plain. A closed toggle is one unit, as in Notion: Backspace at the start of the block after it merges that block into the toggle’s header (its children take its place), and Delete at the end of the header merges the block after the toggle, never the hidden children. Either is one command: a plugin that refuses it changes nothing. |
| List item (in a container that renders no content) | list-item in ordered-list and unordered-list (from JSON, the API or an Edytor fragment; an HTML paste gives flat bulleted and numbered items) |
As plain: a new item after it, before it, or a split. In an empty item without children, it outdents the item one level (unNestBlock), as Shift + Tab does, until it ends the list: out of a list nested in an item it becomes an item under that item, then an item of the outer list after it, then a paragraph. Out of a list it lands before the list from its first item, after it from its last, and between the two halves of the list from a middle one. A list left with no item is removed. |
The first item leaves the list the same way, before it, and the caret stays at its start (mergeBackward); the last one moves out after it (unNestBlock); a middle one merges into the item before it. Delete at the end of the block before the list, a closed toggle’s header included, pulls the first item’s text up into that block (mergeForward), and a list left with no item is removed. Shift + Tab lifts an item as an empty item’s Enter does, and Turn into (the menus, the toolbar, the slash menu, a markdown shortcut) takes it out the same way, out of every list it sits in directly (a list nested right in a list): a list holds only items. Turning an item into the kind it shows as (Numbered list in an ordered-list, Bulleted list in an unordered-list, 1. or - typed at its start) keeps it in the list, and the menus and the toolbar name it by that kind; a block a merge left in the list (a heading) turned into that kind becomes one of its items, and turned into its own kind (Heading 2 on a heading, Quote on a quote) it only changes in place. A divider or a code block (the menus, Mod + Alt + 8, typing --- or three backticks) takes an empty item’s place out of the list the same way; after an item with text it goes right after the item, outside the list, which splits there. A vetoed conversion changes nothing, lift included. A pasted list of the list’s own kind (an <ol> into an ordered-list) gives items. The list itself is never converted: its own grip offers no Turn into. See Containers. |
Layout item (in a layout) |
a block directly in a column of columns (columns plugin) |
As plain, inside the column. | At the start of a column’s first block, it merges into the previous line in reading order, as in Notion: the last line of the column before (its text joins that line; an empty block is removed, the caret at that line’s end), or in column 1 the line before the layout (mergeBackward); refused when that line takes no merge (a void, a code line). Any other block of a column merges into the block before it, as plain; it never outdents into the layout (Shift + Tab on a column’s direct block does nothing). Delete at the end of a column’s last line pulls the next column’s first line into it, and at the end of the line before a layout, column 1’s first line (mergeForward); Backspace at the start of the block after a layout joins the last column’s last line. A column a merge empties goes, and a layout left with one column is replaced by its blocks, in the same step. |
Table cell (in a row of a table) |
tableCell (table plugin) |
A line break in the cell (Shift + Enter too): a cell never splits, and no row or cell is added. | Nothing: the caret stays at the cell’s start (no merge, no retype, no outdent), and Delete at a cell’s end does nothing either. Backspace at the start of the block after a table writes nothing and puts the caret at the end of the last cell. |
Void (void) |
divider, image | A void block’s own text (an image caption) never splits. At the caption’s end or start, a block after or before it. | Backspace at the start of the block after a void block selects it; a second Backspace deletes it. Delete at the end of the block before it does the same. A void block never merges. |
Island (island) |
code | Inside, a new line (a codeLine). In an island of lines (code), Enter in the empty last line, when it is not the only line, leaves the island: the line is removed and a block of the parent’s default kind after the island takes the caret, one undo step. An empty line elsewhere, or the only one, is a new line. |
Lines merge inside the island only: the first line never joins the block before it, and with a single line, Backspace selects the whole island. With the code plugin, Delete at the end of the block before a code block removes that block when it is empty (the caret goes to the end of the text before it, or to the start of the code when nothing comes before) and does nothing otherwise, and Backspace in an empty block right after a code block removes that block and puts the caret at the end of the code. |
Selection
| Keys | Action | Where |
|---|---|---|
| Mod + A | Select the block’s text; press again to select the block, then every block | Anywhere |
| ↑, ↓ | Select the previous or next block | One selected block |
| Shift + ↑, Shift + ↓ | Add the next block to the selection, or remove the last one when moving back | Block selection |
| Shift + ↑, Shift + ↓ | Extend the text selection one line; at the end of a block, Shift + ↓ selects a following void block | Text |
| Escape | Leave the block selection, caret at the end of the first selected block’s line (an image’s caption); over dividers alone, the start of the next line, else the end of the one before | Block selection |
| Enter, Shift + Enter | Edit the text (Notion): leave the block selection, caret at the end of the first selected block, as Escape does; nothing is removed and onDeleteSelectedBlocks does not run. Over selected dividers alone, a new line after them. Over a page block selected alone, its open opens the page |
Block selection |
Arrow keys that walk a block selection do not enter an island (such as a code block) from outside, and they skip the hidden body of a closed toggle.
A text selection never reaches a closed toggle’s hidden body. What a key does with it depends on where the selection starts and ends:
| The selection | Backspace, Delete, cut | Typing, Enter, paste | Formatting, copy |
|---|---|---|---|
| From inside a closed toggle’s header to a block after it | Join what is left to the header and keep the body as its children. | The same; a paste of several lines, like Enter, leaves the body under the header and puts the rest in new blocks after it. | Leave the body out. |
| From the header’s start | Delete the toggle with its body, as they do a toggle the selection covers whole. | Keep the header and its body. | Include the body. |
When nothing else would be left, the toggle stays, empty and without its body.
When the selection ends at the end of a closed toggle’s header, every key that removes it (Backspace, Delete, cut, typing, Enter, paste) removes the toggle with it, and its body takes its place, shown, where the caret can land.
Navigation
Every navigation key also has a Shift variant that extends the selection instead of moving the caret.
| Keys | Moves to | Where |
|---|---|---|
| ←, → | The previous or next character, across blocks and atoms | Text |
| Alt + ←, Alt + → | The previous or next word | macOS |
| Mod + ←, Mod + → | The previous or next word | Windows and Linux |
| Home, End | The start or end of the block | Text |
| PageUp, PageDown | The start or end of the document | Text |
| Mod + ↑, Mod + ↓ | The start or end of the document | Text |
| ↑, ↓ | The previous or next line (native); ↓ at the end of the document, out of a nested block (see below) | Text |
With nothing selected (after a drop or a column resize, an undo that gives back no selection, or Escape), the navigation keys and their Shift variants do nothing, as in Notion: the browser places no caret of its own. PageUp and PageDown still scroll, and Mod + A selects every block. A click, a tap or a focus from outside the editor places the caret.
↓ never leaves you stuck at the end of the document. When the caret is on the last line of the last place it can go, and that place is not a top-level paragraph (the body or header of a toggle, a callout, a quote, a nested list item, a column, a table’s last row, a code block’s last line, a heading), ↓ puts the caret in an empty paragraph after the document’s last block, creating it, as one undo step: undo removes it and gives the caret back. When a block follows below the caret, ↓ goes there as usual; the next column of the same layout and the next cell of the same table row are beside the caret, not below it. A closed toggle’s body is not a place the caret can go. Shift + ↓ only extends the selection, and a readonly editor adds nothing. A click below the last block does the same (see Styling).
In a columns layout, left, right and word keys follow document order (from the end of column 1 to the start of column 2), and ↑/↓ stay the browser’s, which differs per engine.
Left, right and word keys follow the visual direction of right-to-left text, and they skip the body of a closed toggle. Over a block selection, the word, Home/End and document keys start from its shown edges: back to the start of its first shown line, forward to the end of its last: a selected block’s own line, never a nested child that is not selected; for a block with no line of its own, such as a list or a code block, its first or last nested line; never a divider; over selected dividers alone they keep the dividers selected, except the document keys, which still go to the document’s start or end.
macOS text bindings
On macOS the Emacs-style Ctrl keys work as in native text fields:
| Keys | Action |
|---|---|
| Ctrl + A, Ctrl + E | Start or end of the block |
| Ctrl + B, Ctrl + F | Previous or next character |
| Ctrl + P, Ctrl + N | Like ↑ and ↓ |
| Ctrl + H, Ctrl + D | Delete backward or forward |
| Ctrl + K | Delete to the end of the block; at the end, join the next block |
| Ctrl + O | Insert a line break, keeping the caret before it |
Plugin keys
Rich text and suggestions are on by default in <Edytor>; the others (arrow move and the block handles among them) apply when you list their plugin.
| Keys | Action | Plugin, where |
|---|---|---|
| Mod + B, I, U, E | Bold, italic, underline, inline code | Rich text |
| Mod + Shift + S, Mod + Shift + X | Strikethrough | Rich text |
| Mod + Shift + H | Red text color | Rich text |
| Mod + K | Open the link field over the selected text, or over the link holding the caret (selected first) | Toolbar, a text range or a caret in a link |
| Mod + Enter | Check or uncheck the to-dos (one undo step) | Rich text, a to-do selected or holding the caret |
| Mod + Alt + 0 to 8 | Turn into text, heading 1 to 3, to-do, bulleted list, numbered list, toggle, code (a block with text or children keeps them, and the code block is inserted after it; after a list’s item, outside the list) | Rich text, when that kind’s command exists |
| Mod + Enter | Accept the latest suggestion | Suggestions, while one is shown |
| Escape | Discard the latest suggestion | Suggestions, while one is shown |
| Tab | Accept the end suggestion of the caret’s block |
Suggestions, a caret in that block, not in a list-like block |
| Tab | Insert a tab at the caret, indent every line a selection touches, or accept an end suggestion |
Code, in a code line |
| Shift + Tab | Remove one leading tab (or up to two spaces) from every line the selection touches | Code, in a code line |
| Shift + Enter | New code line | Code, in a code line |
| Mod + A | Select the whole code block’s text | Code, until its text is selected |
| Escape | Discard the line’s end suggestions (the key goes on) |
Code, in a code line |
| ↑, ↓, Enter, Escape | Navigate, run, close | Slash menu, while open |
| Mod + ↑, Mod + ↓ | Move the selected blocks up or down | Arrow move, block selection |
| Mod + Shift + ↑, Mod + Shift + ↓ | Move the caret’s block (or the selected blocks) up or down; at a column’s first block (↑) or last (↓), out of the layout, before or after it | Arrow move, text or block selection |
| Mod + D | Duplicate the selected block (the first one), or else the caret’s block | Block menu |
| Alt + ↑ ↓ → ← | Move the block up, down, in, out | Block handles, handle focused |
| Mod + F | Open the find and replace bar (over a selection in one line, search for it) | Find and replace, when listed |
| Alt + F10 | Move the focus to the selection toolbar; in it, ←/→, Home, End walk it and Escape returns | Toolbar, while it shows |
| ← → (Shift: by 10%), Home, End | Resize the two columns beside the gap | Columns, a resize band focused |
The Mod + Alt digits follow Notion’s numbering and run the kind’s block.* command, so Mod + Alt + 8 needs the code plugin. The block menu’s own keys (arrows, Enter, Escape) belong to its search field, see Block menu.
A plugin key only claims the key in the situation listed. Otherwise the key falls through to the next binding, for example Mod + ↓ to the document end when no block is selected, or Mod + Enter to the built-in binding (a toggle opens or closes, anything else is left alone) outside a to-do when no suggestion is shown. With the arrow move plugin (a default), Mod + Shift + ↑/↓ moves a movable block instead of extending the selection to the document edge.
Adding hotkeys
A plugin declares bindings in hotkeys. The app can pass its own with the hotkeys prop of <Edytor>. Both take the same functions:
import type { Plugin } from 'edytor';
export const savePlugin: Plugin = () => ({
hotkeys: {
'mod+s': ({ edytor, prevent }) => {
prevent(() => {
localStorage.setItem('doc', JSON.stringify(edytor.value));
});
}
}
});
A binding receives { edytor, prevent, event? }:
prevent()claims the key: later bindings do not run, and the browser’s default action and propagation are stopped.prevent(cb)claims it and runscb. Like everyprevent, it records the claim and returns: the rest of the binding still runs, and the first call decides.- A binding that does not call
preventleaves the key to the next binding, and finally to the browser. eventis theKeyboardEvent. It is absent when the key arrived only as an input event, as with some virtual keyboards on Android.
The hotkeys prop is read once, when the editor mounts.
Chord syntax
A chord is lowercase modifiers and one key, joined with +:
- Modifiers:
mod,alt,ctrl,shift, up to three. Their order does not matter:shift+mod+kandmod+shift+kare the same chord. Case does not matter either at runtime, but the types expect lowercase. - Keys: the letters
atoz, the digits0to9, the punctuation keys (/,.,[,+, …, asKeyboardEvent.keynames them),arrowup,arrowdown,arrowleft,arrowright,tab,enter,backspace,delete,space,escape,home,end,pageup,pagedown,insert,f1tof12.spaceis the space bar. - Other names (
cmd,meta,option,esc,return,del,up…) never match a key press. They fail type-checking, and in development the editor logs a warning naming the chord. modis Cmd on Apple platforms and Ctrl elsewhere.ctrlmatches the Ctrl key only on Apple platforms; elsewhere Ctrl is alwaysmod.- On non-Latin keyboard layouts, a Mod chord also matches by physical key: Mod + Б on a Russian layout runs
mod+b. - AltGr combinations and dead keys produce text and never run a binding.
- A punctuation key is the character the key press types. A character typed with Shift needs
shiftin the chord: Mod + Shift + / ismod+shift+?, somod+?andshift+/never match. On macOS, Option with a character key types a character (Option + B is∫), soalt+bnever matches there; bindmod+alt+binstead. In development the editor logs a warning for these chords too.
A plugin’s hotkeys and the hotkeys prop are type-checked against this syntax (HotKeyCombination).
Enter, Shift + Enter, Backspace and Delete reach bindings too, so a plugin can claim them, as the slash menu does with Enter. Each key press runs its bindings once.
Precedence
For each chord, the bindings run in this order until one calls prevent:
- the
hotkeysprop of<Edytor>; - each plugin’s
hotkeys, in the order of thepluginsarray; - the built-in bindings.
A binding that is not a function, such as an optional callback left undefined ('mod+e': onInlineCode), is skipped: the chord’s next binding runs, and in development the editor logs a warning naming the chord. TypeScript accepts undefined for these optional keys, so add an optional callback only when it is set: ...(onInlineCode && { 'mod+e': onInlineCode }).
Overriding and disabling defaults
To override a default, bind the same chord in the hotkeys prop or in a plugin, and call prevent:
<script lang="ts">
import { Edytor } from 'edytor';
let saved = $state(0);
</script>
<Edytor
hotkeys={{
// Mod+Enter saves (the default only opens toggles and checks to-dos).
'mod+enter': ({ prevent }) => prevent(() => saved++),
// Tab never nests: claim it and do nothing.
tab: ({ prevent }) => prevent(),
// Mod+B does nothing in headings; elsewhere the rich text binding runs.
'mod+b': ({ edytor, prevent }) => {
if (edytor.selection.caret?.block.type === 'heading') prevent();
}
}}
/>
prevent() without a callback disables the key in the editor. It also prevents the browser’s default, so a disabled Tab does not move focus out of the editor either. There is no way to remove a built-in binding and hand the key back to the browser.