Slash menu
The slash menu plugin opens a filtered command menu when you type a slash, listing every block kind preset and every plugin command.
createSlashMenuPlugin({ menu }) opens a command menu at the caret when you type /. Typing after the slash filters it; Enter runs the highlighted command and removes the /query text. The menu is your menu snippet: the plugin ships the behavior and no markup (see Markup).
<script lang="ts">
import { Edytor, createSlashMenuPlugin, type SlashMenuController } from 'edytor';
const plugins = [createSlashMenuPlugin({ menu })];
</script>
{#snippet menu(slash: SlashMenuController)}
<ul {@attach slash.popup}>
{#each slash.commands as command, index (command.id)}
<li {@attach slash.option(index)} onclick={() => void slash.run(command)}>{command.label}</li>
{/each}
</ul>
{/snippet}
<Edytor {plugins} />
The / is a trigger, as a plugin’s triggers are (Input rules and triggers): the same rules open and close it, track its query and replace it. Without a menu, nothing shows and the keys still work: /divider and Enter insert a divider.
Try it
Click the empty line and type /, then h2 or todo, and press Enter; the block handle’s + opens the same menu. The editor is local to this page: a reload resets it.
Customize
This replaces the menu snippet: a dark command palette with the groups as small caps, the hints as keycaps and a filter field for the +.
<script lang="ts">
import {
Edytor,
createSlashMenuPlugin,
type EditorCommand,
type JSONDoc,
type Plugin,
type SlashMenuController
} from 'edytor';
// The page's document and the rest of your editor's plugins.
let { value, plugins = [] }: { value?: JSONDoc; plugins?: Plugin[] } = $props();
// The slash menu, drawn with the snippet below.
const slash = createSlashMenuPlugin({ menu });
/** The rows by group, in order. */
function sections(commands: EditorCommand[]) {
const runs: { name: string; rows: { command: EditorCommand; index: number }[] }[] = [];
commands.forEach((command, index) => {
const name = command.group ?? '';
const run = runs.at(-1);
if (run && run.name === name) run.rows.push({ command, index });
else runs.push({ name, rows: [{ command, index }] });
});
return runs;
}
</script>
<!-- A dark palette: a command line on top, groups as small caps, hints as keycaps. -->
{#snippet menu(slash: SlashMenuController)}
<div class="palette" role="presentation" onmousedown={(event) => event.preventDefault()}>
{#if slash.addition}
<input
aria-label="Filter commands"
placeholder="Filter commands…"
value={slash.query}
oninput={(event) => slash.search(event.currentTarget.value)}
{@attach slash.keys}
/>
{:else}
<div class="query" aria-live="polite">/{slash.query}</div>
{/if}
<div class="list" {@attach slash.popup}>
{#each sections(slash.commands) as section, at (`${at}:${section.name}`)}
<div role="group" aria-label={section.name || undefined}>
{#if section.name}<div class="group" aria-hidden="true">{section.name}</div>{/if}
{#each section.rows as { command, index } (command.id)}
<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_static_element_interactions -->
<div
class="row"
data-selected={slash.index === index}
onmousemove={() => (slash.index = index)}
onclick={() => void slash.run(command)}
{@attach slash.option(index)}
>
<span>{command.label}</span>
{#if command.hint}<kbd>{command.hint}</kbd>{/if}
</div>
{/each}
</div>
{/each}
{#if slash.commands.length === 0}
<div class="none" role="status">No command</div>
{/if}
</div>
</div>
{/snippet}
<Edytor {value} plugins={[slash, ...plugins]} aria-label="Slash menu demo" />
<style>
.palette {
width: 280px;
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;
}
.query {
padding: 2px 8px 8px;
color: #7ee787;
}
input {
box-sizing: border-box;
width: 100%;
margin-bottom: 8px;
padding: 6px 8px;
border: 1px solid #3d444d;
border-radius: 8px;
background: #151b23;
color: inherit;
font: inherit;
outline: none;
}
.list {
max-height: 260px;
overflow-y: auto;
}
.group {
padding: 6px 8px 2px;
color: #9198a1;
font-size: 10px;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.row {
display: flex;
align-items: center;
justify-content: space-between;
padding: 4px 8px;
border-radius: 6px;
cursor: pointer;
}
.row[data-selected='true'] {
background: #2f81f7;
color: #fff;
}
kbd {
padding: 0 5px;
border-radius: 4px;
background: rgb(255 255 255 / 0.12);
font: inherit;
font-size: 11px;
}
.none {
padding: 4px 8px;
color: #9198a1;
}
</style>
What it lists
The menu lists edytor.commands:
- one command per block kind preset, such as
block.heading2“Heading 2” (see Blocks); - every command a plugin declares in
commands(see Writing plugins).
A command with searchOnly is listed only once a query names it: the block menu’s colours (/red: “Red text”, “Red background”, under Color) stay out of the bare / list. A command whose isEnabled(edytor) answers false is hidden (except in the menu the block handle’s + opens, below). Block kind commands are enabled when the caret’s block is convertible, which excludes void blocks, island blocks and blocks inside them. A kind picked in a list’s item takes the item out of the list (Containers).
Commands come grouped by their group, as in Notion: Basic blocks first, then the other groups in the order they first appear; a group is a key, which your markup shows in its words. Kind commands take their preset’s group (default Basic blocks; the image and code blocks are under Media); a command without a group has none. With the columns plugin, “2 columns” to “5 columns” are under Layout (/col3, /columns3 and /column 3 find them too), except in a column, where no layout goes. A command’s hint is its shortcut to show on its row; kind commands use their first markdown prefix, such as ## for Heading 2.
The query matches, case-insensitively, the start of a word in a command’s label or keywords (hyphens are ignored, so /todo finds “To-do list”). /h2, /head and /subtitle all find “Heading 2”; /eading finds nothing. A query of several words keeps the menu open while each word, in order, starts a word of the same label or keyword, or continues the word the one before it started: /bullet list finds “Bulleted list”, /to do finds “To-do list”, and /list bullet finds nothing. A command’s keywords carry the orders it is found in: the columns plugin’s “3 columns” has col3, columns3 and column 3, so /col 3, /columns 3 and /column 3 find it as /3 col does (Notion). The command id (block.heading2) is not searched. The block menu’s search matches with the same rule.
Keys
While the menu is open:
| Keys | Action |
|---|---|
| ↑, ↓ | Move the highlight (wraps around), across sections; typing moves it back to the first match |
| Enter | Run the highlighted command |
| Escape | Close the menu, keep the typed text |
| Hover | Highlight that command |
| Click | Run that command |
Enter is claimed only when at least one command matches. With no match it inserts a new block as usual.
Behavior
- The menu opens when
/is typed at a collapsed caret in a convertible block, at the start of a text or after whitespace, as in Notion. A/inside a word stays text:see 1/2,a/bandand/orfollowed by Enter keep their text and start a new block. An IME that commits/together with more text (/h) opens it with that query. - It closes when the caret leaves the query, the selection expands, the
/is deleted, or the query matches no command (a/in a URL or a path stays text, and ↑/↓ move the caret again). A space right after the/closes it too, and so does a query of only hyphens:yes / no,1 / 2andx /-followed by Enter keep their text and start a new block. “No results” shows only for a bare/when no command is enabled. It does not open in a readonly editor, and it closes when the editor turns readonly. - The query range is anchored in the document, so a collaborator’s edits elsewhere in the text do not break it.
- Running a command removes the
/querytext in the same step as the command, separate from the typing before it, so one undo restores both:hi /h2+ Enter undoes to a paragraphhi /h2. If the command is refused, the trigger text stays. - After a conversion the caret goes back to where the
/was. A command that moves the caret elsewhere keeps its own caret: the code block conversion puts it in the first line, and/dividerin a fresh block of the default kind where the divider lands, after it (a divider renders no content, so it cannot hold the caret). - A kind that replaces the block’s content (
/divider,/code) converts the block in place only when it holds nothing but the query. In a block with other text or with children, the new block goes after it and the block stays intact:keep me /divider+ Enter leaveskeep meabove a divider. After a list’s item, the new block goes outside the list, which splits after the item; in an empty item, the item leaves the list as the new kind. The query’s removal and the insertion are one step.
From the block handle
The block handle’s + opens the menu too, without typing anything (Block handles). The menu opens below the + and holds the keyboard on the element your markup gives keys (a search field, focused), instead of reading a /query from the text. Picking a command adds an empty block of the default kind below the block (above with Alt) and runs the command in it, as one undo step. controller.addition is set while it is open this way.
- Keys. ↑/↓, Enter and Escape work in the field as above (not while an IME composes: the Enter or Escape that ends a composition is the IME’s); a query that matches nothing shows “No results” and keeps the menu open.
- One keyboard owner. The field is the menu’s one keyboard owner: make the rows no Tab stops (
option(index)gives themtabindex="-1"); a row that takes focus anyway (a screen reader) becomes the highlighted row and hands the focus back to the field, so Enter always runs the highlighted row. - Which commands are listed. The commands that can run in the block being added: each command’s
isEnabled(edytor)is asked of a view whoseselection.caretis at the start of that block, an empty block of the parent’s default kind in its place. It does not exist yet, so the caret’sblockis a stand-in with thattype, the realparent, no content and nonode(when the+reuses an empty block of that kind, it is that block). A command that applies only in its own context, such as one enabled on a to-do only, is not listed beside a to-do, since the block added there is a paragraph (Writing plugins). - Where the kind lands. Where it fits, as the slash menu places it on an empty line: beside a list’s item, a heading splits the list after the item, and a list’s own kind adds an item to it; a divider leaves the caret on an empty line after it. When the block beside the
+is already an empty block of the default kind, the command runs in it instead.
| Edge case | What happens |
|---|---|
The command’s isEnabled answers false once the block exists, or the document or an extension refuses the command before it changes anything |
The addition and the command are one transaction: the block is taken back inside it, the document, its undo and redo steps and the selection are as they were, and edytor.dispatcher.last reads refused. |
Escape, controller.dismiss(), a press outside, focus moving to an element outside the menu, or the editor turning readonly |
The menu closes with nothing added and no undo step, and gives the selection back as it was. Escape and dismiss() also give the editor its focus back. |
A block’s grip is activated, or the block beside the + is deleted (a collaborator’s, say) |
The same: the menu closes and gives the selection back. |
The + was clicked while the selection was still the block selection a grip click made |
The selection given back is the one from before the grip was clicked, never the grip’s block selection. |
Placement
Your menu mounts in the editor’s overlay, in a position: fixed host with the attribute data-edytor-slash-menu-host and z-index: 50. The plugin opens it below the caret (below the + it was opened from), or above when there is no room, and keeps it inside the viewport while you scroll. Its look is yours: the demo’s Notion-style menu (sections with a heading, 28px rows with a line icon, the hint on the right, a “Close menu · esc” footer) is SlashMenu.svelte in the repository’s registry/edytor/chrome (the edytor-chrome registry item, in your app after shadcn-svelte add).
The rows are a listbox of options (popup and option(index); a section may be a group named by its heading). While the menu is open the element holding the keyboard names the list (aria-controls) and the highlighted row (aria-activedescendant): the editor’s root for a typed /, your search field (a combobox) for a +. See Accessibility.
Markup
createSlashMenuPlugin takes the menu’s markup as a snippet. The plugin keeps everything else: opening on /, the query, the filtering, ↑/↓, Enter and Escape, and the placement.
menu?Snippet<[SlashMenuController]>
The menu, rendered while controller.isOpen. Without it, nothing shows (the keys still run commands).
Snippet<[SlashMenuController]>A menu snippet receives the SlashMenuController. Read controller.commands (the filtered, enabled commands in menu order), controller.index and controller.query; call controller.run(command) to run one and controller.close() to close the menu and keep the typed text. Its attachments give your markup the keyboard and the ARIA: {@attach controller.popup} on your list (its id, listbox role and name, presses that keep the caret, the root naming it and its highlighted row) and {@attach controller.option(index)} on each row (its id, role="option", aria-selected, and the scroll into view of the keyboard’s row; draw its highlight from controller.index === index).
When the block handle’s + opens the menu (controller.addition is set), the menu holds the keyboard. Put {@attach controller.keys} on your search field: it is focused, ↑/↓, Enter and Escape work as above, and it names the list and its highlighted row; call controller.search(query) from its input. On an element that is not a field (the menu itself, with tabindex="-1"), keys takes the typed characters and Backspace into controller.query, so nothing typed reaches the document. Call controller.dismiss() rather than close() to close it: it gives the editor back its focus and selection.
Keep a press on the menu from moving the caret out of the query: popup cancels the mousedown of every press in its element but on a field; cancel it on anything else of yours. A complete menu, with its field for the +, is on Menus and handles, with every other menu.
Placement. The package places no popup: your markup places itself by controller.anchor (the caret; for a + menu, the +), 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.