Menus and controls
The slash menu, the block handle and block menu, the formatting bubble, table and media controls, and the framework-free bubble and floating menus.
BlockEditor and PageEditor share one set of controls. Most come from the commercial @gotipe/block-editor; the table bars, media controls and menu primitives are part of the MIT packages.
| Control | Package | Appears |
|---|---|---|
| Slash menu | @gotipe/ |
Typing / at the start of a block or after a space |
| Block handle and block menu | @gotipe/ |
Pointer over a block row in the notion view, or a touch |
| Formatting bubble | @gotipe/ |
A selection in an editable editor |
| Table column and row menus | @gotipe/ |
Editable tables in the ready editors |
| Table bars, resize handles, media controls | @gotipe/react |
Editable tables, image and file blocks |
BubbleMenu, FloatingMenu |
@gotipe/react |
Your own React menus; see React |
create, create |
@gotipe/ |
Your own menus without a framework |
| «@» and «:» lists, emoji picker, formula popover | @gotipe/ |
Typing @ or :, «/» → Emoji, a click on a formula; needs atom |
Slash menu
The menu opens when you type / at the start of a block or after a space, and from the handle's + button. The text after / filters it. A space, deleting the /, Escape or a click outside closes it; running a command removes the / and the query.
Filtering matches the name and the aliases: a prefix ranks first, then a substring, then letters in order. Built-in commands show in the UI language and keep their English names as aliases. A row shows its Markdown shortcut where one exists (#, -, 1., [], >, ```, ---). Commands are grouped as AI, Style, Insert and Upload, in that order.
Keys: ↑ and ↓ move, Home and End jump, Enter runs, Escape closes and keeps the caret.
Commands come from the extensions (editor.getSlashCommands()). Pass slashCommands to change the list:
import { BlockEditor } from "@gotipe/block-editor";
import type { SlashCommandDef } from "@gotipe/core";
import { FullPreset } from "@gotipe/core/presets";
import { useEditor } from "@gotipe/react";
import { useMemo } from "react";
const warning: SlashCommandDef = {
name: "Warning",
aliases: ["warn", "caution"],
icon: "alert-circle",
group: "insert",
execute: (editor) => editor.chain().setBlockType("callout", { type: "warning" }).run(),
};
export function DocumentEditor() {
const editor = useEditor({ extensions: [FullPreset] });
const commands = useMemo(() => (editor ? [...editor.getSlashCommands(), warning] : undefined), [editor]);
return <BlockEditor editor={editor} slashCommands={commands} showAiCommandBar={false} />;
}To change groups, labels or row icons, render SlashMenu yourself as a child of BlockEditor with showSlashMenu={false}:
| Prop | Type | Default | Description |
|---|---|---|---|
editor |
GoTipeEditor |
— | The editor. |
commands |
Slash |
[] |
Commands to offer. |
groups |
{ id: string; label: string }[] |
AI, Style, Insert, Upload | Group order and labels; groups not listed are hidden. |
renderIcon |
( |
built-in icons | Row icon. By default an icon name outside the built-in set draws the command's first letter. |
renderMeta |
( |
Markdown shortcut | Right-hand side of a row. |
labels |
{ menu?, list?, empty?, results?( |
i18n strings | Accessible names, the empty state and the result count. |
className |
string |
— | Added to .. |
Mentions, emoji and formulas
GoTipe Atlas, frames 22–24. All four need the editor to include atomExtensions() from @gotipe/block-editor; the data comes from the mentions and emoji props of BlockEditor and PageEditor (Inline atoms).
The «@» list. Typing @ at the start of a word opens it at the caret with the host's people and pages for the text after @: initials for a person, the page glyph for a page, the match in bold, a group label wherever the kind changes («People», «Pages»). The first row is chosen and shows ↵. ArrowDown and ArrowUp move the choice, Enter or a click inserts the mention in place of @query, Escape closes the list until the caret leaves the trigger, and so does moving the focus away. An empty answer is one line: «No one found». Return people before pages from mentions.items, as the list groups consecutive rows.
The «:» list. Typing : at the start of a word lists Unicode emoji by shortcode and, with the Russian interface, by Russian name (:пра → 🎉 праздник, ✅ правильно, ✍️ правка, 👉 направо), then the team's emoji from emoji.custom. Right after : it shows the recent emoji. The keys are those of the «@» list; Enter inserts the character (a custom emoji as an atom) and moves it to the front of the recent list.
The emoji picker. «/» → Emoji opens it at the caret: a search field with the focus, the categories as glyphs (recent, faces, nature, food, activities, travel, objects, symbols, flags, the team's own), the recent row first, then a grid of nine columns. A tab scrolls to its category and the tab of the category in view is marked. ArrowDown from the field enters the grid; the arrow keys walk it row by row across the categories, ArrowUp from the first row goes back to the field; Enter or Space inserts, Enter in the field inserts the first result. The name of the emoji under the pointer or the focus shows in a tooltip. Escape or a click outside closes it and returns the caret.
The formula popover. A click on a formula, Enter with a formula selected, «/» → Inline formula and typing $x^2$ open it under the formula. The closing $ makes the formula only when the opening one starts a word and is followed by neither a space nor a digit, so costs $5-$ stays text, and Escape right after it brings the typed dollars back. The popover holds the TeX in a monospace field with the caret at its end, a confirm button and the drawing under it as you type. TeX that cannot be read marks the field red and names the reason in a tooltip («Missing closing “}”»); it can still be confirmed and then shows in the line as TeX on a red tint. Enter or the button confirms in one undo step (updateInlineMath or insertInlineMath), Escape or a click outside cancels. The formula stays selected while the popover is open.
Every list and popover is measured before it shows, flips above the caret when there is no room below and follows the caret on scroll and resize. The lists keep the focus in the document: the editor element carries aria-controls, aria-expanded and aria-activedescendant of the chosen row, as the slash menu does. In the picker and the formula popover Tab cycles through their own controls; when the focus leaves them (a click elsewhere) they close and leave it there. Keys of an input method's composition never choose or move.
Block handle
In the notion view a handle appears beside the block under the pointer, from about 120 px left of the text to 560 px right of its start. Touching a block shows it too. It is hidden while the editor is read-only.
+adds an empty block below; Alt-click (Option-click on macOS) adds it above. On a list row the new block is a row of the same list. With the slash menu on, the new block starts with/and the menu opens; the insertion is one undo step.- The grip drags the block. On a list row it moves the row, with the blocks inside it; Alt-drag moves the whole list. A column left without blocks gets an empty paragraph. With touch or a pen, hold the grip for 300 ms, then drag; moving more than 10 px before that cancels. Near the top or bottom edge the page scrolls. Escape cancels a touch drag. A drop is one undo step.
- Clicking the grip (or a short tap) opens the block menu.
| Block menu item | Action |
|---|---|
| Turn into | Text, Heading 1–3, Bullet list, Numbered list, To-do list, Quote, Code block |
| Copy link to block | Copies the page URL with ?gotipe-block=<; a page opened with it scrolls to the block. A heading's anchor in the docs view copies the same link. A refused clipboard is a CLIPBOARD_FAILED error in the toast |
| Duplicate | Copies the block below itself, with its children and new IDs |
| Reset formatting | Turns the block into a paragraph and removes the marks of its text — bold, colours, links; mentions, formulas and custom emoji stay. A block with children (a toggle, a callout) keeps its type and loses only the marks; a block without text of its own (an image, a divider, a table) is left as it is |
| Copy to clipboard | Copies the plain text of the block and its children |
| Delete | Removes the block with its children; a list's only row takes the list with it, and a column left without blocks gets an empty paragraph |
The menu acts on the block its grip moves. On a list row — a bullet, numbered or to-do item, nested or inside a column — that is the row with its nested rows, never the whole list, and a block inside a row (a paragraph after the row's text) belongs to that row. Duplicate puts the copy into the same list; Turn into and Reset formatting lift the row out of the list. Elsewhere it is the top-level block under the pointer. Each action is one undo step.
Formatting bubble
The bubble appears over a selection while the editor is editable. From left to right:
- Improve asks the AI extension to rewrite the selection. Shown with
showAiCommandBarwhen the editor hasdefineAianddefineAiContext; without them the bubble starts with the block type. - Block type: Paragraph, Heading 1–3, Bullet list, Numbered list, Todo list, Quote, Code. Disabled in table cells.
- Bold, Italic, Underline, Strikethrough, Code; each tooltip shows its shortcut.
- Link opens the link editor; Mod+K opens it too. It accepts
http:,https:,mailto:and relative links, and reports anything else in the field. Enter applies, Remove link appears when the selection has a link, and Escape returns the caret to the selection. - Colour: text Gray, Red, Amber, Green, Blue; highlight Yellow, Green, Blue, Red, Gray; and Reset. A mark stores the colour for a light page; the editor draws it through the
--gt-tc-*and--gt-bg-*tokens, so it follows dark mode. - More: alignment; Superscript and Subscript when the editor has those marks (
FullPresetdoes,DefaultPresetdoes not); Clear formatting; Copy as Markdown.
Tables
| Control | Where | Action |
|---|---|---|
| Add row bar | Under the table | Adds a row at the end |
| Add column bar | Right of the table | Adds a column at the end and scrolls to it |
| Resize handle | Right edge of the topmost cell ending each column | Drag between 64 and 1600 px, or ← and → by 16 px |
| Column menu | Chevron in a header cell | Type: Text, Code, Number, Yes / no; Cells: Merge cells, Split cell; Add row; Add column after it; Delete column (Delete columns under a header over several columns, which has no type) |
| Row menu | Beside the first cell of a body row | Row: Add row above, Add row below; Cells: Merge cells, Split cell; Delete row |
Number aligns the column right. Code puts every body cell in inline code. Yes / no stores ✓ and —, the same in every interface language: values such as yes, да, true, 1 or x become ✓, empty or negative ones —; other values stay. A column holding the words an earlier version wrote — the interface's yes and no — still reads as Yes / no. Deleting the last row deletes the table. Merge cells is available while two or more cells are selected (drag across cells, Shift+click or Shift+arrows); Split cell while the menu's cell or the caret's cell is merged; ⌘⇧M (Ctrl+Shift+M) does either from the table. An unavailable row stays focusable, is paler and shows the reason in its tooltip. PageEditor refuses a merge that Markdown could not keep (a table with mentions, formulas or fonts, or inside a list or quote). After an action the document takes the keys back, so ⌘Z undoes it. A wide table scrolls inside its block. Each action is one undo step. The bars and resize handles come with @gotipe/react; the column and row menus need the ready editors. More in tables.
Images and files
An image shows a toolbar on hover or focus: Alternative text, Original size, Fit to width, Caption, Zoom, Download and More options. More options has a search field and: Edit alternative text, Crop image, Replace image, Copy image URL, Download image, Edit caption, Copy link to block, Duplicate image, Move up, Move down, Delete image. The side handles resize the image from 80 px to the width of its container; with focus, ← and → resize by 16 px. Crop takes percentages and saves a PNG through the host. An empty image offers upload, a link, your host's image sources, or a dropped file. A file block opens or downloads on its name and offers Replace and Remove. See media.
Menus without a framework
@gotipe/core/menus positions your own elements:
import type { GoTipeEditor, ViewState } from "@gotipe/core";
import { createBubbleMenu, createFloatingMenu } from "@gotipe/core/menus";
const hasRange = ({ selection }: ViewState) =>
selection.anchor.blockId !== selection.head.blockId ||
selection.anchor.offset !== selection.head.offset;
export function attachMenus(editor: GoTipeEditor, bubble: HTMLElement, insert: HTMLElement) {
const menus = [
createBubbleMenu(editor, {
element: bubble,
shouldShow: ({ editor, state }) => editor.isEditable && hasRange(state),
}),
createFloatingMenu(editor, { element: insert }),
];
return () => menus.forEach((menu) => menu.destroy());
}| Option | Type | Default | Description |
|---|---|---|---|
element |
HTMLElement |
— | Your menu. It gets position: fixed, a z-index and display: none until shown. |
shouldShow |
( |
see below | When to show the element; replaces the default condition. |
offset |
{ x: number; y: number } |
{ x: 0, y: 0 } |
Bubble only: added to its position. |
By default the bubble shows for a non-empty selection inside one block, centred 8 px above it; the floating menu shows when the caret is in an empty top-level paragraph, 8 px left of it. Both update on selection changes, not on scroll or resize, and do not check editability. destroy() hides the element and stops listening.
Limitations
- Mod+K opens the link field only over selected text: with a caret alone it opens nothing, as GoTipe Atlas draws the field only over a selection. One field opens: the bubble's, or without a bubble the
FixedToolbarone while its Link tool is on the bar (not in a closed More). - The block handle and block menu have no keyboard path, and show only in the
notionview. - Reset formatting is offered on every block, and on a block without text of its own (an image, a divider, a table) it does nothing.
- The Vue package has only a minimal slash menu and toolbar; see Vue.