Skip to content

Writing in the editor

What the editor offers depends on the field's text format, which the site builder sets up. The features with settings of their own describe the author's side next to those settings:

The keys and the block menu are below.

Accessibility

The accessibility baseline for the editor and the public output is WCAG 2.1 level AA.

In the editor

The editing area takes its name from the field's label and its description from the field's description, and it carries the field's required and error states. An error message is referenced from the editor only when the Inline Form Errors module prints one beside the field. The notices shown above the editor when it opens, naming removed formatting, blocks the format cannot hold or inline content it cannot show, are part of the editing area's description, and so is the notice of a size limit the document is over, or of files in it that could not be found, whenever one is shown. Those two are also announced to screen readers when they appear after the editor opened, and a document already over a size limit is announced as the editor opens when focus is already in the field, as after switching its text format. A failed upload is announced when it happens, and so are leaving the editor with Escape, described in the keyboard table below, and the first Enter pressed after the editor gains focus in a format restricted to a single paragraph, where Enter inserts nothing. A plain URL picked from the [[ search that the format does not permit inserts nothing and shows no notice, so that refusal is announced instead. When the widget's Placeholder setting is not empty, the editing area also carries it as aria-placeholder, because BlockNote's own placeholder is CSS generated content that assistive technology does not announce.

BlockNote shows its side menu and its table handles only under the pointer. Every function in them has a keyboard route through the block menu. The side menu's two buttons are not tab stops, so Tab passes over the menu when the pointer shows it. These are the keyboard routes, where Ctrl is Cmd on macOS:

Keys Where What they do
/ In text Opens the slash menu. Up and Down choose an item, Enter inserts it, and Escape closes the menu.
[[ In text, in a format that enables the content link Opens the content search, with the same keys as the slash menu; Enter inserts the chosen result as a content link, or the typed URL as a plain link.
Tab With text selected, or a media block selected by a click on its preview Moves focus into the formatting toolbar. Tab moves between its controls, and Escape returns to the text.
Ctrl+, With text selected, in a format that permits subscript Toggles subscript.
Ctrl+. With text selected, in a format that permits superscript Toggles superscript.
Ctrl+K With text selected Opens the link form for the selected text, which links that text and no more: a selection inside an existing link, saved with a different address, becomes a link of its own, and the rest of the link keeps its text and address. Edit link in the link toolbar edits the whole link.
Enter, Escape In the link form Enter, or the form's Save button, makes the link, or keeps the form open with a message when the format does not permit the address; with a content result chosen by Up or Down, Enter inserts a content link instead. Where the format permits a new tab, Space toggles the Open in a new tab checkbox beside Save. Escape closes the form and returns to the text.
Enter, Escape In a media block's alternative text form Enter, or the form's Save button, stores the override; Space toggles Decorative image, which empties the text field. Escape, or Cancel, closes the form without storing anything. Focus returns to the formatting toolbar when the form was opened from it, and to the editor when it was opened from the block menu or a saved change drew the toolbar again.
Tab With the caret in a link Moves focus into the link toolbar: Edit link, Open link and Remove link. Escape returns to the caret.
Tab With the caret in a content link Moves focus into the content link's toolbar. Escape returns to the caret.
Ctrl+click On a link Opens the link in a new tab. A plain click places the caret in the linked text; with Click into links off, a plain click opens the link instead.
Alt+F10 In the editor Opens the block menu for the block holding the caret.
Up, Down, Home, End In the block menu Move between items. Up and Down wrap around.
Enter, Space In the block menu Activate the item, which closes the menu and returns focus to the caret. On an item that holds a submenu, such as Colors, Cell colors or a media block's View mode and Alignment, they open it, as Right does.
Left, Escape In a submenu Close the submenu and return to its item.
Escape, Shift+Tab In the block menu Close the menu and return focus to the caret. Tab closes it and moves focus on.
Tab, Shift+Tab In a table Move to the next or previous cell.
Tab, Shift+Tab In any other block, with no text selected Indent or outdent the block; where it cannot be, Tab and Shift+Tab move focus on, as the next two rows say.
Tab In a code block Inserts two spaces.
Shift+Tab In any block that is not nested Moves focus backward to the previous field.
Escape In the editor Leaves the editor and announces it; with the slash menu open, closes the menu instead and stays. In Chrome, Tab then reaches the next focusable after the caret; Shift+Tab returns to the editor, and a second Shift+Tab is then the ordinary one, which would outdent a nested block or otherwise move to the previous field.
Ctrl+Shift+Up, Ctrl+Shift+Down In a block Move the block up or down.
Ctrl+Z; Ctrl+Y or Ctrl+Shift+Z In the editor Undo; redo.

The block menu offers a Style group on a block whose type the format lists styles for, with Default style and each style, then Move up, Move down, Indent and Outdent where the block can move that way, Checked on a checklist item, Expanded on a toggle list item or a toggleable heading, Colors with the colors the format permits, and Delete. With the caret in a table it also offers Header row, Header column, Add row above, Add row below, Add column left, Add column right, Delete row, Delete column, Merge cells once Shift and the arrow keys have selected two or more cells and the format permits merged cells, Split cell in a merged cell, and Cell colors. The block items follow the Block side menu toggle, except Expanded, which is offered whatever that toggle is set to: the button it operates is part of the block's own content, not of the side menu. Header row and Header column follow whichever of the Block side menu and Table handles toggles is on, because a pointer author reaches them through the side menu's drag handle menu with the first and through the table's own row and column handle menus with the second; with both off, neither is offered. Neither is offered, on any surface, when the format's Permit header rows and columns setting is off, and Cell colors is offered only while Permit cell colors is on. The remaining row, column, merge and cell color items follow the Table handles toggle; Split cell is offered whatever that toggle says, so a merged cell can always be taken apart.

The menu the side menu's drag handle opens offers, ahead of Delete and Colors, the groups the block menu offers ahead of its block items, such as a media block's Media group, a gallery's Gallery group, which an item in it offers after its own, a callout's Callout group and the Style group, so a pointer reaches them without selecting text first.

One route has a limit in this release. Tab reaches a block's own controls, described next, only from a block that cannot be indented, because Tab indents a block that can, whatever its own controls are; the reliable route is the caret into the block plus Alt+F10, when the block registers its controls with the block menu the way the media block's own do.

The media block draws a control of its own only while nothing is chosen: an empty block with a library offers a Select media button, and the preview of a chosen item is a group named by the media item's label, shortened with an ellipsis where it is too long for the preview's response header, past 55 characters of Georgian or Chinese. Tab from the text before an empty block reaches its button, Enter opens the Media Library, and Shift+Tab returns to the text. Once an item is chosen in the Media Library, focus returns to the editor with the media block selected when the dialog was opened from the formatting toolbar, and otherwise with the caret in its caption. A chosen item draws no button and no select inside the block. Clicking it selects the block and shows its functions on the formatting toolbar: the view mode (a named menu button, shown only with a choice of more than one), Replace media, Toggle preview, the alignments the format permits, Override media image alternative text for an image item or a block holding an override, and Toggle caption, in that order, and only those; when the format no longer permits any media type, Convert to paragraph takes the place of Replace media and turns the block into a paragraph holding the caption's text; selecting text in the caption shows the text tools instead, without the block's functions. Alt+F10 opens the block menu for the block holding the caret, whose Media group carries the same functions, whether or not the block is selected. The sample callout block that docs/extending.md uses as its worked example still draws its controls inside the block, and is checked the same way, as the pattern for a module whose block keeps its own controls in the editable rather than putting them on the shared toolbar.

The nine text colors reach a contrast ratio of 4.5:1 against the editor's background in both its light and dark color schemes. The border the editor draws around the editing area reaches 3:1 against that background in both, which is what WCAG 2.1 asks of the boundary of a form control. The editing area always shows a focus ring: the theme's, or its own where a theme draws none, as Administration themes describes. Block animations are off for a reader whose system asks for reduced motion.

On the public page

A checklist item's checkbox and its text sit inside one <label>, so the text names the checkbox, which is disabled. An image's alternative text is the image block's name: an upload names the image after its file, an author changes the name with Rename image in the editor, and an image with no name renders an empty alt. Rename an uploaded image to describe it. The public stylesheet's default text colors reach 4.5:1 against white, for which it darkens BlockNote's gray, red, orange and yellow.

WCAG 2.2 measurements

WCAG 2.2 is not the baseline, but two of its criteria were measured in Claro, and target size again in Default Admin, and ADR 0011 records each measurement. Every control measured meets target size (2.5.8, at least 24 by 24 pixels), and the formatting toolbar covers neither the selection nor the Title field above the editor (focus not obscured, 2.4.11). Whether a focused toolbar button is ever covered was not measured.