Block menu
The block menu plugin opens Notion's block menu when you click a block handle's grip, with search, Turn into, Color, Duplicate, Move and Delete, and binds Mod+D to duplicate.
createBlockMenuPlugin({ menu }) opens a menu when you click a block handle’s ⋮⋮ grip: a search field, Turn into, Color, Duplicate, Move up, Move down and Delete, as in Notion. The menu is your menu snippet: the plugin ships its rows, actions, keys and ARIA, and no markup (see Markup). It also binds Mod + D to duplicate a block, and adds the colours to the slash menu by name: /red offers “Red text” and “Red background” (Block colors).
<script lang="ts">
import { Edytor, createBlockMenuPlugin, type BlockMenuController } from 'edytor';
const plugins = [createBlockMenuPlugin({ menu })];
</script>
{#snippet menu(controller: BlockMenuController)}
<div class="menu" data-edytor-block-menu>
<input
aria-label="Search actions"
value={controller.query}
oninput={(event) => controller.search(event.currentTarget.value)}
{@attach controller.keys}
/>
<div aria-label="Block actions" {@attach controller.popup}>
{#each controller.rows as row, index (`${index}:${row.id}`)}
<button
{@attach controller.option(index)}
onclick={() => {
controller.index = index;
controller.run(row);
}}>{row.label}</button
>
{/each}
</div>
{#if controller.flyout}
<div {@attach controller.flyoutMenu}>
{#each controller.flyoutRows as row, index (row.id)}
<button
{@attach controller.option(index, true)}
onclick={() => {
controller.flyoutIndex = index;
controller.run(row);
}}>{row.label}</button
>
{/each}
</div>
{/if}
</div>
{/snippet}
<Edytor {plugins} />
The menu opens from block handles (createBlockHandlesPlugin({ handle }), listed beside it). Without a menu, a grip click opens nothing: the plugin still binds Mod + D and the colour commands.
Try it
Hover a block and click its ⋮⋮ grip, then search, open Turn into or Color with →, or press Mod + D to duplicate. The editor is local to this page: a reload resets it.
Customize
The menu is your menu snippet, so it can look like anything. Here, a dark palette with the actions in a column and the Turn into and Color flyouts as chips.
<script lang="ts">
import {
Edytor,
createBlockMenuPlugin,
type BlockMenuController,
type JSONDoc,
type Plugin
} from 'edytor';
// The page's document and the rest of your editor's plugins.
let { value, plugins = [] }: { value?: JSONDoc; plugins?: Plugin[] } = $props();
// The block menu drawn with the snippet below.
const blockMenu = createBlockMenuPlugin({ menu });
</script>
<!-- A dark command palette: the actions in a column, a flyout of chips beside it. -->
{#snippet menu(controller: BlockMenuController)}
<div class="menu" data-edytor-block-menu>
<input
aria-label="Search actions"
placeholder="Search…"
value={controller.query}
oninput={(event) => controller.search(event.currentTarget.value)}
{@attach controller.keys}
/>
<div class="rows" aria-label="Block actions" {@attach controller.popup}>
{#each controller.rows as row, index (`${index}:${row.id}`)}
<button
class="row"
data-selected={controller.index === index}
data-danger={'danger' in row && row.danger}
{@attach controller.option(index)}
onmousemove={() => (controller.index = index)}
onclick={() => {
controller.index = index;
controller.run(row);
}}
>
{row.label}
{#if 'submenu' in row && row.submenu}<span class="more">›</span>{/if}
{#if 'hint' in row && row.hint}<span class="hint">{row.hint}</span>{/if}
</button>
{/each}
{#if controller.rows.length === 0}
<div class="none" role="status">No match</div>
{/if}
</div>
{#if controller.flyout}
<div class="flyout" data-edytor-block-menu-flyout {@attach controller.flyoutMenu}>
{#each controller.flyoutRows as row, index (row.id)}
<button
class="chip"
data-selected={controller.flyoutIndex === index}
{@attach controller.option(index, true)}
onmousemove={() => (controller.flyoutIndex = index)}
onclick={() => {
controller.flyoutIndex = index;
controller.run(row);
}}
>
{row.label}
</button>
{/each}
</div>
{/if}
</div>
{/snippet}
<Edytor {value} plugins={[blockMenu, ...plugins]} aria-label="Block menu demo" />
<style>
.menu {
width: 220px;
padding: 8px;
border-radius: 12px;
background: #1f2328;
color: #e6edf3;
box-shadow: 0 12px 32px rgb(0 0 0 / 0.25);
font: 13px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
}
input {
box-sizing: border-box;
width: 100%;
margin-bottom: 6px;
padding: 6px 8px;
border: 1px solid #3d444d;
border-radius: 8px;
background: #151b23;
color: inherit;
font: inherit;
outline: none;
}
.rows {
display: flex;
flex-direction: column;
gap: 2px;
}
.row,
.chip {
display: flex;
align-items: center;
gap: 6px;
padding: 5px 8px;
border: 0;
border-radius: 6px;
background: transparent;
color: inherit;
font: inherit;
text-align: left;
cursor: pointer;
}
.row[data-danger='true'] {
color: #ff7b72;
}
.row[data-selected='true'],
.chip[data-selected='true'] {
background: #2f81f7;
color: #fff;
}
.more,
.hint {
margin-left: auto;
color: #9198a1;
font-size: 11px;
}
.row[data-selected='true'] .more,
.row[data-selected='true'] .hint {
color: #dbe9ff;
}
.none {
padding: 4px 8px;
color: #9198a1;
}
.flyout {
display: flex;
flex-wrap: wrap;
gap: 4px;
width: 220px;
padding: 8px;
border-radius: 12px;
background: #1f2328;
color: #e6edf3;
box-shadow: 0 12px 32px rgb(0 0 0 / 0.25);
}
.chip {
padding: 3px 10px;
border: 1px solid #3d444d;
border-radius: 999px;
}
</style>
Options
createBlockMenuPlugin(options) takes:
import { createBlockMenuPlugin } from 'edytor';
const blockMenu = createBlockMenuPlugin({
linkTo: (block) => `${location.origin}${location.pathname}#block-${block.id}`
});
linkTo?(block: Block) => string
A URL for the block. Adds a 'Copy link to block' row that writes it to the clipboard. Without it, the row is hidden.
(block: Block) => stringmenu?Snippet<[BlockMenuController]>
The menu's markup. Without it, nothing shows. See Markup below.
Snippet<[BlockMenuController]>The options type is BlockMenuOptions.
What it shows
The menu’s rows are the controller’s (controller.rows); the demo draws them as below. The menu opens beside the grip, top-aligned 8px to its right (to its left when the right has no room, flipped up when the space below is short), follows scrolling and resizing, and closes when the grip leaves the view. The Turn into and Color flyouts open beside the menu, to its right (to its left when the right has no room), top-aligned with it and moved up as far as the viewport needs (8px from its edges, by the flyout’s laid-out size, so its opening animation never leaves it past the bottom); taller than the viewport, it scrolls inside, so every row stays reachable by the mouse ([data-edytor-block-menu-flyout]). From top to bottom:
- A “Search actions…” field, focused (
keys). - A heading naming the block’s kind, such as “Heading 2”.
- The actions:
| Row | Hint | Does |
|---|---|---|
| Turn into › | Opens a flyout of the kinds that keep content, with ✓ on the current one, then the commands that turn the selected blocks into something (EditorCommand.turnsInto): with the columns plugin, “N columns” over N sibling blocks (2 to 5) wraps them in a layout, one per column, and “2 columns” to “5 columns” over one block makes it the first of N columns, each other column holding an empty paragraph (Notion); the blocks stay selected |
|
| Color › | Opens a flyout of Notion’s palette: “Text color” (Default text, Gray text, … Red text) then “Background color” (Default background, … Red background), with ✓ on the block’s own. A pick paints the blocks (see Block colors) and closes the menu; the blocks stay selected | |
| Copy link to block | Writes linkTo(block) to the clipboard. Only with linkTo |
|
| The kind’s rows | Rows the block’s kind adds (BlockDefinition.menu), on that block opened alone: a table’s row and column inserts and deletes, and its Header row and Header column switches. A switch shows its state and the menu stays open when it is toggled; any other row closes the menu |
|
| Duplicate | Mod + D | Inserts a copy after the block, with fresh ids for it, its children and its atoms |
| Move up | Mod + Shift + ↑ | Moves the block one step up |
| Move down | Mod + Shift + ↓ | Moves the block one step down |
| Delete | Del | Removes the block; its children take its place (a list or a code block goes with everything in it) |
A search lists, after the actions it matches, the kinds it names under “Turn into” (/ rules: head finds the headings) and the colours it names under “Color”: red lists “Red text” and “Red background”, red back the background alone (a colour row matches its label, and its palette name and text or background in English whatever the labels’ language). A colour row paints the blocks as the flyout’s does; none is listed when nothing takes a colour.
A row that cannot apply is hidden: Turn into when nothing it applies to is convertible (a void block, an island or a block inside one; a list is never converted, its items are), Color when nothing it applies to takes a colour (a void block such as a divider, a code block or its lines), Move up or Move down when edytor.canMove refuses the step. The hints show the matching shortcuts; Mod + Shift + ↑/↓ need the arrow move plugin.
Typing in the field filters the actions by label, and lists the kinds whose label or keywords match under a “Turn into” heading: type head and pick “Heading 2” without opening the flyout. The query matches as in the slash menu: each word starts a word of the label or of a keyword, hyphens ignored, so todo and to do find “To-do list”, move finds Move up and Move down, and a letter inside a word (o in “Move”) matches nothing. With nothing left, the menu shows “No results”.
Keys
While the menu is open, its search field takes the keys:
| Keys | Action |
|---|---|
| ↑, ↓ | Move the highlight (wraps around); in a flyout, walk its rows |
| Home, End | Highlight the first or last row |
| → | Open the Turn into or Color flyout from its row |
| ← | Close the flyout |
| Enter | Run the highlighted row, open the flyout from Turn into or Color, or run the flyout’s highlighted row (convert, or paint) |
| Delete | Delete the block, or the selected blocks (with an empty search) |
| Escape | Close the flyout, then the menu |
Hovering a row highlights it, in the menu and in the flyout.
The rows are a menu of menuitems (the flyouts other menus: “Turn into”, and “Color”, whose rows are menuitemradios checked on the block’s colours). The search field names the open one (aria-controls) and its highlighted row (aria-activedescendant), so a screen reader reads each row as the arrows move; the grip that opened the menu has aria-expanded="true". See Accessibility.
Behavior
- The handle click selects the block, and it stays selected while the menu is open.
- A list or a code block is one block to the menu, as clicked: Copy link to block shows, Move and Duplicate take it whole, and Escape returns the caret to its first line. Delete removes it with everything in it, and Turn into converts a list’s items, which stay selected (a code block’s lines never convert).
- A click on the grip of a block inside a block selection keeps the selection, and the actions apply to every selected block, as in Notion: Turn into converts them all (a list’s items, never the list itself; an item turned into another kind leaves the list), Duplicate copies each one after itself, Move up and Move down move the group, and Delete removes them, each as one undo step. After Turn into, Move and Escape the blocks stay selected; after Delete the caret goes where the keyboard’s block delete puts it (below). Copy link to block is hidden for several blocks. A click on the grip of a block a text range spans, when the range runs across blocks, first selects the blocks it covers, as a drag of that grip would.
- Every action closes the menu and returns a text caret: at the start of the converted or moved block, of the copy after Duplicate, and after Delete where Backspace on the same block selection puts it: at the start of its first child when it had children (they take its place), else at the end of the nearest text before it, else at the start of the next text; void blocks such as dividers are skipped, and so is a closed toggle’s hidden body (the caret ends the toggle’s header instead). When a plugin refuses the conversion or the deletion, the block stays and the caret returns to its start. Escape also returns the caret to the block. A block that holds no text, such as a divider, stays selected instead after Move, Escape or a refusal, and Duplicate selects its copy; an image’s caret goes to the start of its caption.
- A pointer press outside the menu and the handles closes it without moving the caret, and so does the editor turning readonly. A click on a
+closes it too and opens the slash menu instead, giving back the selection held before the grip was clicked, so the+menu’s Escape returns to it rather than to the grip’s block selection. - Each action is one undo step, separate from the typing before it however soon it follows, through the same commands as the rest of the editor (
convertToKind,duplicateBlock,edytor.moveBlocks,deleteBlocks), so plugins can refuse them. Delete is one command, as the keyboard’s block delete:onDeleteSelectedBlocksruns first, and itsprevent()or a veto keeps every block. Over several blocks, Turn into and Duplicate skip a block a plugin vetoes and apply to the others (Refusing an edit).
Mod + D duplicates every selected block, in document order and as one undo step, each copy after its block, and selects the copies. Without a block selection it duplicates the block holding the caret and puts the caret in the copy. It is claimed only for a block that can move, and never in a readonly editor.
Block colors
Color paints the blocks the menu acts on, its members (a selected list’s items, never the list itself), as Notion does: each block stores its text colour in data.color and its background in data.background, by palette name (gray, brown, orange, yellow, green, blue, purple, pink, red; BLOCK_COLORS). “Default” removes the field. Text colour and background are independent: a block may hold both.
- Only blocks showing their own text take a colour: a paragraph, a heading, a list item, a to-do, a toggle, a callout, a quote. A void block (a divider, an image), a code block and its lines take none.
- A pick is one command and one undo step over every block (
setBlockColor, operationsetBlockColor); each block is its ownpatchDatastep, so a plugin may veto one and the others are painted. - Each field is one property of the block: two people colouring a block at once keep the last write per field, and Turn into, a markdown shortcut and Backspace at a block’s start keep both (a retype keeps the data it does not name).
- The core renders a valid name as
data-edytor-coloranddata-edytor-backgroundon the block element, and its stylesheet paints the nine names from theme tokens with Notion’s values as fallbacks (--edytor-color-<name>,--edytor-background-<name>; see Styling). The colour reaches the block’s children, as in Notion; a text colour mark inside wins.
With the block menu listed, the slash menu offers the same rows by name once a query names one (never in the bare / list, EditorCommand.searchOnly), under the Color group: /red lists “Red text” and “Red background”, /default back “Default background”. A pick paints the caret’s block and removes the typed /red, as one undo step that gives /red back. The commands are color.<name> and background.<name> (color.default removes the text colour), enabled where the caret’s block takes a colour.
A copy writes the colours into its text/html as Notion’s HTML export names them, a class on the block’s element: block-color-red for a text colour, block-color-red_background for a background. A paste of HTML reads them back on its text blocks (Notion’s teal is the palette’s green); a class naming no palette colour adds nothing.
setBlockColor(edytor, blocks, field, value) is the same write from your own UI (a slash command, a shortcut): field is 'color' or 'background', value a name or null, and it answers whether a block changed.
import { setBlockColor, type EdytorInstance } from 'edytor';
// The caret's block on a yellow background, as one undo step.
export const highlightBlock = (edytor: EdytorInstance) => {
const block = edytor.selection.caret?.block;
if (block) setBlockColor(edytor, [block], 'background', 'yellow');
};
How it opens
When a handle is clicked, block handles dispatch a DOM event on the editor’s root:
import { BLOCK_ACTIVATE_EVENT, type BlockActivation } from 'edytor';
// 'edytor-block-activate', detail: { block, anchor }
block is the clicked block and anchor the grip element. The block menu listens for it and answers it with preventDefault(), as it takes the keyboard (unanswered, the editor takes the focus after the click). A plugin of your own can listen for the same event in onEdytorAttached to open a different menu, or to add behavior next to this one.
Placement
The menu mounts in the editor’s overlay, in a position: fixed host with the attribute data-edytor-block-menu-host and z-index: 70, placed beside the grip by the element marked data-edytor-block-menu (else your snippet’s first element); a flyout marked data-edytor-block-menu-flyout is placed beside it. Its look is yours: the demo’s Notion-style panel (265px, line icons, a 140ms fade and scale-in) is BlockMenu.svelte in the repository’s registry/edytor/chrome (the edytor-chrome registry item, in your app after shadcn-svelte add); its rows’ action ids are turn, color, link, duplicate, up, down and delete, a colour row’s <field>.<name> (color.red, background.default).
Markup
A menu snippet draws the menu. It renders while controller.isOpen, in that host. The plugin keeps opening it on a grip click, closing it on a press outside, placing it, and Mod + D. The keys in the table above, and the ARIA, are the controller’s attachments: {@attach controller.keys} on your search field, {@attach controller.popup} on the element holding the rows, {@attach controller.option(index)} on each row, {@attach controller.flyoutMenu} on an open flyout. The example at the top of this page uses them all.
The snippet receives the BlockMenuController:
block?Block | null
The block whose grip opened the menu.
Block | nullblocks?Block[]
The blocks the actions apply to, in document order, as clicked: the block selection when it holds block, else block alone. A grip-selected list is one block.
Block[]members?Block[]
What Delete and Turn into act on: blocks, a list or a code block with its whole subtree (selection.selectedMembers).
Block[]actions?BlockMenuAction[]
The rows that apply, filtered by query: { id, label, icon, hint?, danger?, submenu?, run? }. Turn into has submenu: 'turn', Color submenu: 'color', and no run.
BlockMenuAction[]kinds?KindRow[]
The kinds the block may turn into while keeping its content.
KindRow[]matchingColors?BlockMenuColor[]
With a query, the colour rows it names (empty when nothing takes a colour); rows lists them after the actions and the matching kinds.
BlockMenuColor[]currentKind?KindRow | undefined
The row naming the block: of its kind's rows, the one whose preset data shares the most values with the block's (the first on a tie), so a checked to-do is still To-do list.
KindRow | undefinedturnInto(kind)?(kind: KindRow) => void
Convert the members (a list's items).
(kind: KindRow) => voidcolors?BlockMenuColor[]
The Color flyout's rows: { id, label, field: 'color' | 'background', value: name | null }, the text colours then the backgrounds, each from the default.
BlockMenuColor[]colorable?Block[]
The members that take a colour (no void, code block or code line).
Block[]isCurrentColor(row)?(row: BlockMenuColor) => boolean
Whether every colourable member holds the row's colour (its ✓).
(row: BlockMenuColor) => booleanpaint(row)?(row: BlockMenuColor) => void
Paint the colourable members with the row's colour, as one undo step; the menu closes and the blocks stay selected.
(row: BlockMenuColor) => voidduplicate(blocks, select)?(blocks: Block[], select: boolean) => void
Copy each block after itself as one undo step (fresh ids); select the copies, or, with select false, put the caret in the first copy. The Duplicate action selects them for several blocks.
(blocks: Block[], select: boolean) => voidmove(direction)?('up' | 'down') => void
Move the blocks one step.
('up' | 'down') => voidremove()?() => void
Delete the members; unselected children take their parent's place.
() => voidcopyLink()?() => Promise<void>
Write linkTo(block) to the clipboard.
() => Promise<void>close()?(restoreCaret?: boolean) => void
Close the menu; the caret returns to the block (several blocks stay selected) unless restoreCaret is false.
(restoreCaret?: boolean) => voidquery?string
The search text. Writable: actions filter by it.
stringindex?number
The keyboard's row. Writable.
numberflyout?false | 'turn' | 'color'
The open flyout: the Turn into kinds, the colours, or none. Writable (false closes it).
false | 'turn' | 'color'flyoutRows?Array<KindRow | BlockMenuColor>
The open flyout's rows: kinds, or colours.
Array<KindRow | BlockMenuColor>flyoutIndex?number
The keyboard's row in the open flyout. Writable.
numberopenFlyout(which?)?(which?: 'turn' | 'color') => void
Open a flyout (Turn into by default) on its first row; that flyout already open stays as it is.
(which?: 'turn' | 'color') => voidrows?Array<BlockMenuAction | KindRow | BlockMenuColor>
Every keyboard row: the actions, then the kinds and the colours the query names.
Array<BlockMenuAction | KindRow | BlockMenuColor>run(row)?(row) => void
Run a row of the menu or of its flyout: paint a colour, convert to a kind, open an action's flyout or run it.
(row) => voidsearch(query)?(query: string) => void
What the search field's input does: set query, highlight the first row, close the flyout.
(query: string) => voidkeys?Attachment<HTMLElement>
On the field that holds the keyboard: focused when it mounts, it takes the keys in the table above and names the menu (or the open flyout) and its highlighted row (aria-controls, aria-activedescendant).
Attachment<HTMLElement>popup?Attachment<HTMLElement>
On the element holding the rows: its id, menu role and name, presses that keep the focus, and its publication to the editor's root while it is in the page (the grip is told it opened it).
Attachment<HTMLElement>option(index, flyout?)?(index: number, flyout?: boolean) => Attachment<HTMLElement>
A row's attachment ({@attach controller.option(index)}): its id, role (menuitem, menuitemcheckbox, menuitemradio), aria-checked, aria-haspopup and aria-expanded; the keyboard's row scrolls into view. Draw its highlight from index (flyoutIndex).
(index: number, flyout?: boolean) => Attachment<HTMLElement>flyoutMenu?Attachment<HTMLElement>
On an open flyout: its id, menu role and name, and its placement beside the menu.
Attachment<HTMLElement>Every action closes the menu and returns the caret: it replaces the block selection the grip click left, and the projector draws it after the flush.
To open a different menu without this plugin, listen for edytor-block-activate (see Building a block menu). Menus and handles shows the other snippets.
Placement. The package places no popup: your markup places itself by controller.anchor (the handle that opened it; its flyout beside the menu), a virtual element read live. With Floating UI, computePosition(anchor, element, { strategy: 'fixed', middleware: [offset(8), flip(), shift({ padding: 8 })] }) under autoUpdate; with bits-ui, customAnchor={anchor}. See Menus and handles.