Skip to content
Edytor
Esc
↑↓navigate↵open⌘Jpreview
On this page

Block handles

The block handles plugin adds a + button and a drag grip beside each block, with drag and drop, keyboard moves, a drop indicator and an activation hook for block menus.

Block handles are the two buttons left of each block, as in Notion: a + that adds a block, then the ⋮⋮ grip. Drag the grip to reorder, nest or outdent a block, or every block the selection covers; focus it and use Alt with the arrow keys to move it; click it to select the block and open a block menu, such as the bundled block menu. The plugin ships the placement, the hover, the drag and drop and the keys; the two buttons are your handle snippet.

Try it

Hover a block, then drag its grip to reorder, click the grip for the block menu, or click + to pick a block to add below. The editor is local to this page: a reload resets it.

Customize

The handle snippet draws both buttons, so they can look like anything. Here, a round indigo + and a tinted grip pill that fills on hover; the plugin keeps the placement, the drag and the keys.

<script lang="ts">
	import {
		Edytor,
		createBlockHandlesPlugin,
		type BlockHandleSnippetPayload,
		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();

	// A round + and a tinted grip pill, drawn by the handle snippet below.
	const handles = createBlockHandlesPlugin({ handle });
</script>

{#snippet handle({ label, grip, plus, readonly, beside, draggable }: BlockHandleSnippetPayload)}
	{#if !readonly}
		<button
			class="plus"
			contenteditable="false"
			aria-label={beside ? `Add a column beside ${label}` : `Add a block below ${label}`}
			title="Add below (Alt: above)"
			{@attach plus}
		>
			+
		</button>
		<button
			class="grip"
			contenteditable="false"
			data-draggable={draggable ? 'true' : undefined}
			aria-label={`${label} block: drag to move, click for actions`}
			title={label}
			{@attach grip}
		>
			<span aria-hidden="true">⠿</span>
		</button>
	{/if}
{/snippet}

<Edytor {value} plugins={[handles, ...plugins]} aria-label="Block handles demo" />

<style>
	.plus,
	.grip {
		display: inline-flex;
		align-items: center;
		justify-content: center;
		height: 22px;
		padding: 0;
		border: 0;
		cursor: pointer;
		font: 600 14px/1 system-ui, sans-serif;
		transition:
			background-color 80ms ease,
			color 80ms ease;
	}
	.plus {
		width: 22px;
		border-radius: 50%;
		background: #eef0ff;
		color: #4f46e5;
	}
	.grip {
		width: 20px;
		margin-left: 2px;
		border-radius: 6px;
		background: #f1efe9;
		color: #8a857b;
	}
	.grip[data-draggable='true'] {
		cursor: grab;
	}
	.plus:hover,
	.plus:focus-visible {
		background: #4f46e5;
		color: #fff;
		outline: 0;
	}
	.grip:hover,
	.grip:focus-visible {
		background: #4f46e5;
		color: #fff;
		outline: 0;
	}
</style>

Enabling and configuring

List createBlockHandlesPlugin({ handle }) in plugins; handle draws the + and the grip of each block (without it, no handle shows and no block drags):

<script lang="ts">
	import { Edytor, createBlockHandlesPlugin, type BlockHandleSnippetPayload } from 'edytor';

	// Handles and keyboard moves, no pointer drag.
	const plugins = [createBlockHandlesPlugin({ handle, draggable: false })];
</script>

{#snippet handle({ label, grip, plus, readonly }: BlockHandleSnippetPayload)}
	{#if !readonly}
		<button aria-label={`Add a block below ${label}`} {@attach plus}>+</button>
		<button aria-label={`${label} block`} {@attach grip}>⠿</button>
	{/if}
{/snippet}

<Edytor {plugins} />
PropType
handle?Snippet<[BlockHandleSnippetPayload]>

The + and the grip, beside each block. Without it, no handle shows. See The handle below.

TypeSnippet<[BlockHandleSnippetPayload]>
draggable?boolean

false keeps the handle and its keyboard moves, but disables pointer dragging and drop targets.

Typeboolean
Defaulttrue

The configuration is read when the editor mounts.

Handles

A handle sits in the editor’s overlay layer, left of its block, aligned with the block’s first line of text. For an island block it aligns with the block’s header (a direct child marked use:block.void, such as the code block’s header), and for a void block with the top of the block. Handles follow layout changes, moves and scrolling.

  • A handle exists only for blocks that can move, and is hidden while the editor is readonly.
  • Handles mount lazily, for blocks within about one screen of the viewport and for blocks that are hovered, selected, focused or being dragged. Large documents do not pay for a handle per block.
  • A handle is transparent until you hover its block, and its block stays hovered while the pointer goes from the text to the handle and rests on it (the handle sits flush with the block). On touch devices (no hover), a handle shows for the block the selection is in, as in Notion’s mobile editor: tap into a block to get its handle. A hidden handle takes no tap there, so a tap in the margin never opens a block’s menu.
  • In a column’s gap the column resize band is the gap’s left part, 10px wide and the layout’s height: wherever its gray guide shows, at any height, a press resizes. A block’s handle spans the rest of the gap, its + (18px there) and its grip together flush with the block (Notion’s + ⋮⋮; at the default 46px gap, 10 + 18 + 18, neither is under the band), and its box covers the block’s whole row: a pointer anywhere in it hovers the block, shown or not, so the grip is reached from any side, as in Notion. Column 1’s handles sit in the editor’s gutter, over no gap, as a root block’s do.
  • While a text selection runs (a press in the editor, until its release), the handles and the column resize bands take no pointer, so the browser computes the selection against the text, never selecting a block (Notion; over the bare gap between two columns, see the columns’ limitations).
  • Name the buttons in your words after the block’s kind (payload.label, its preset label in the view’s labels): “Heading 1 block: drag to move, click for actions”, “Add a block below Heading 1 (Alt: above)” (Alt adds a column when beside). While the menu a + or a grip opened is open, its attachment gives that button aria-expanded="true", aria-controls and aria-haspopup. See Accessibility. The demo’s Notion-style handle (gray #ada9a3 buttons, a 6px-rounded hover background) is BlockHandle.svelte in the repository’s registry/edytor/chrome (the edytor-chrome registry item, in your app after shadcn-svelte add).

The + button

Clicking + opens the slash menu below it and adds nothing yet: the menu has its own search field, and typing filters the menu, never the document. Picking a kind inserts a block of it below the block (above with Alt) with the caret in it, as one undo step. Escape closes the menu with the document and the undo history unchanged and the caret where it was. The menu lists only the commands that can run in the block being added (From the block handle).

Case What + does
A block directly in a column, with Alt Adds a column instead, right of the block’s column, holding the new block (as Notion: one edytor.move with position: 'right' in the same undo step).
The picked kind does not fit where the block is It lands where it fits, as the slash menu places it: beside a list’s item, a heading splits the list after the item and a list’s own kind adds an item; a divider or code block follows the block.
The block is already an empty block of the parent’s default kind The picked kind converts it instead of adding another.
A press outside the menu, focus leaving it, or the editor turning readonly The menu closes as Escape does (a press outside then places the caret).
The selection is still the block selection a grip click made (its menu open, or closed on a divider) + first gives back the selection held before the grip was clicked (a text caret when there was none), so Escape never leaves the grip’s block selection for the next key to replace.
A plugin vetoes the insertion Nothing is added, and edytor.dispatcher.last reads refused.
No slash menu is listed + inserts an empty block of the default kind at once and puts the caret in it (a slash menu listed without its menu snippet answers it, and shows nothing).
A readonly editor The button does nothing.

The + dispatches BLOCK_ADD_EVENT ('edytor-block-add', detail { block, anchor, insert }, a BlockAddition) on the editor’s root. A menu of your own answers it with event.preventDefault(), and calls insert(then?) once the user picks: it adds the block, puts the caret in it and runs then, as one undo step. The addition and then’s writes are one transaction. When then answers false, or the command it runs is refused (by the document or an extension’s veto) before changing anything, insert takes the block back inside that transaction and answers false: the document, its undo and redo steps and the selection are as they were.

The handle

The handle snippet draws the + and the grip of every handle. The plugin places it beside the block’s first line, shows it on hover and mounts it lazily. The snippet receives a BlockHandleSnippetPayload:

PropType
block?Block

The block's handle.

TypeBlock
label?string

The block's kind as people read it, from its preset label ("Heading 1"): name your buttons with it.

Typestring
grip?Attachment<HTMLElement>

{@attach grip} makes an element the grip: dragging (when draggable), a click that selects the block and opens its menu, the Alt+arrow moves while it has focus (its aria-keyshortcuts), and the ARIA of the menu it opened (aria-expanded, aria-controls, aria-haspopup) while it is open.

TypeAttachment<HTMLElement>
plus?Attachment<HTMLElement>

{@attach plus} makes an element the +: its click calls add (Alt+click with true) under it, its press keeps the editor's focus, and it carries the ARIA of the menu it opened while it is open.

TypeAttachment<HTMLElement>
add?(alt?: boolean, anchor?: HTMLElement | null) => void

What + does, from your own code: the slash menu offers what to add below (with true: above, or for a block directly in a column a new column right of its column); nothing is added until a row is picked. The menu opens under anchor, else under the block.

Type(alt?: boolean, anchor?: HTMLElement | null) => void
beside?boolean

Alt+click on the + adds a column right of the block's (a block directly in a layout's column): say so in its name.

Typeboolean
readonly?boolean

The editor is readonly: hide your buttons.

Typeboolean
draggable?boolean

Pointer dragging is on.

Typeboolean

Your markup renders inside the handle’s host, [data-edytor-block-handle-host] (a flex row right-aligned to the block’s left edge, which carries the hover fade; over a column gap, data-over-gap="true", it spans the gap). The +’s attachment cancels its mousedown, so the click does not move the caret first. Menus and handles shows it with the other snippets.

Drag and drop

Drag and drop uses Atlassian’s Pragmatic drag and drop (a copy of its code inside the editor, not a dependency) and its auto-scroll. Its drop zones follow the tree guidance of its list item hitbox: each level of the tree is a list, and an expanded item offers no “after” on its own row. While you drag, each block is a drop target. As in Notion, the editor splits the block’s own row (not its children) into two halves, and the pointer’s horizontal position decides nesting and the level:

The placements that nest a block (inside a block, or among the children of a block that does not already hold it) need the view’s allowNesting, off by default: without it a drop over a block is before or after it, never inside, except in a block made to hold children (a list, a toggle’s or a callout’s body, a column), and Alt + → moves nothing.

Pointer position Drop
Top half of the row Before the block
Bottom half, left of the nest threshold After the block, as a sibling
Bottom half, more than one nesting step right of the block’s text start Inside it, as its last child
Bottom half of a block whose children show (not a closed toggle), one of them not dragged Before its first child not dragged: the bar under the block’s text, indented to that child’s column, never below the whole subtree
Bottom half of the last block of a nested group, or the gap below it After the block or one of the ancestors it ends: the level whose text column is nearest the pointer, one level per nesting step to the left, down to the root
Bottom half of a block every shown child of which is dragged, or the rows those children leave under it The same levels, from the block’s own down to the root: dragging a nested block’s only child out below its parent works even when the parent is the last block at every level. Never inside the block when only its children are dragged: they would stay put
In the handle column left of the editor’s blocks (the drag’s handle width), at any row’s height The row there, by its halves as above, the pointer’s horizontal position picking the outermost level, but only before or after a block, never inside one; over a list’s item where the dragged blocks do not fit (a paragraph over a bulleted list’s items), the list is the row: its upper half before it, its lower half after it; between two rows the bar shown stays, so a drag straight down or up the handles reorders row after row. A block reaching into the column (a list item’s marker) hands the pointer to this rule, so no placement of a row passed on the way is held
Outside the blocks, left or right, within the editor’s height and the drop reach The row at that height, as if the pointer were at the nearest edge of the blocks: on the left as in the handle column, on the right as at the row’s right edge

The nest threshold is the block’s first text line’s start plus one nesting step: --edytor-nest-indent in px (see Nested blocks), else 24px. So in the lower half of a row, move right to nest and back left to drop beside it; below the last child of a nested group, move left to drop it one, two or more levels out. The bar is indented to the chosen level, and the nest backdrop shows on that level’s parent (none at the root).

  • A closed toggle’s children do not show, so its lower half is after it, and moving right nests at the end of its body (the toggle opens on the drop).
  • Nesting never takes a band of the row: the two halves keep the whole height, so the gap between two blocks stays easy to hit.
  • Pointed beside a nested block, over its ancestors’ indent, the pointer is on that block’s row. While you drag, the other blocks’ handles let the pointer through to the blocks under them.

Only placements the document allows are offered:

  • A block that cannot hold children (a divider, an image) never nests, and a level where the blocks do not fit gives way to the next nearest.
  • A half the document refuses entirely is blocked: the drop takes the other half’s placement, and the indicator carries data-blocked="true".
  • The dragged blocks’ own rows and their children offer nothing, so letting go over them changes nothing (as in Notion), even for the last block of a nested group, whose levels would otherwise move it out of its parent. The one exception is a parent they leave with no other shown child: their rows are then the gap under that parent’s row, and offer its levels.

The placement is sticky, so the indicator does not flicker:

  • A short gap between blocks keeps the last valid placement (its row and half; the pointer’s horizontal position still picks nesting and the level), from a nested block’s row too.
  • Below the document’s last block the placement stays however far down you go, as in Notion: move left or right there to pick the level, and let go to drop at the end of the document; leaving the editor’s width clears it.
  • Another block’s own row never keeps it, so dragging up from a child onto its parent’s row targets the parent.
  • A list container has no row of its own, so its padding counts as a gap: overshooting a list’s first item keeps “before” that item.

Dropping outside the blocks

You do not have to aim at the blocks themselves. While a drag is in the editor’s height, a pointer left or right of its blocks still drops on the row at that height, so you can move along the margin, or past the end of the text, and still see the bar:

  • Left: the handle column, then the page margin past it, take the drop before or after the row at that height, as the handle column does (never inside it, at the outermost level that row ends).
  • Right: past the blocks’ right edge, the drop is the one the row offers at its own right edge: before it in its top half, after it or inside it in its bottom half, exactly as just inside the text, so nothing changes as the pointer leaves the blocks.
  • Columns: over a layout, left of it is its first column’s row, right of it its last column’s row; a drop from outside never lands in another column.
  • With the columns plugin, the first 120px of each margin are the beside bands (a new column), and the reorder starts past them. Without a layout kind the whole reach reorders.
  • The reach is 240px past the handle column on the left and past the blocks’ right edge on the right. Further out nothing shows, and letting go there moves nothing. Set it with --edytor-drop-reach (in px) on the editor or any ancestor; a reach under 120px also shortens the beside bands, and 0px leaves only the handle column:
[data-edytor] {
	--edytor-drop-reach: 320px;
}

A block’s own drop target keeps the pointer first: its 20px slop beside the block answers before the margin does. Auto-scroll works there as anywhere during a drag.

Dragging several blocks

As in Notion, dragging the handle of a block the selection covers moves every block it covers, together:

  • A block selection: its blocks as clicked (a selected list is one block: dragging one of its items, or pressing Alt + an arrow on the item’s handle, moves that item alone, as with a selected paragraph’s child).
  • A text range across blocks: every block it spans, as Tab and Turn into read them (a list the range only enters counts through the items it spans; a code block’s lines count as the code block).

The outermost of those blocks move, in document order, wherever they sit: their children, and a closed toggle’s hidden body, travel with them. The drop is one edytor.move call, one undo step.

  • Preview. The drag preview shows them all, and neither it nor the indicator shows a count badge (their count is data-count on [data-edytor-drop-indicator] and on [data-edytor-drag-preview], for your own styling).
  • Selection. While the drag lasts the moving blocks are block-selected (a text range becomes the block selection of the blocks it covers, and stays so when the drag is cancelled), and after the drop they stay selected (a moved block’s selected children too). Undo puts the blocks back and restores the selection you had before the drag (the text range, or the caret), redo the moved blocks’ selection.
  • All or none. The document’s rules apply to the whole group, so a placement where one of them does not fit (a paragraph directly in a list) is not offered, and a refused or vetoed move moves none of them. A block a collaborator deletes during the drag is left out.

Dragging the handle of a block outside the selection moves that block alone and selects it (a parent’s handle while only its child is selected: the parent alone). A single drop is one undo step too.

After a drop the editor holds the keys, as in Notion: its root takes the focus (without scrolling, and without placing a caret: the moved blocks stay block-selected), so Mod+Z undoes the move at once, and Mod+Shift+Z redoes it, even when the undo gave back no selection (a drag started with none); with no selection, typing does nothing until a click places a caret. Resizing columns does the same.

The drag preview

As in Notion, every handle drag shows a copy of the dragged blocks under the pointer, rendered as they look in the editor, never the grip alone: for one block, one selected block, or every block of a several-block drag in document order. Each block’s rendered element is cloned with its whole subtree (its children, a toggle’s shown body) when the drag starts, and removed once the browser has taken its picture, as Pragmatic drag and drop’s setCustomNativeDragPreview does.

  • Look: the blocks’ own look, only scaled down to 0.8 from the top left: no card, background, shadow, border radius, opacity or fade is added (the browser applies its own drag-image translucency). The blocks are laid out at their own width (the widest of them, at most 600px: a block in a column keeps its column’s width), the ghost is sized to the scaled box so the browser crops nothing, and content past 300px is cut cleanly. The pointer keeps its place on the first block, where you grabbed it.
  • Theme: the clones sit in a wrapper, [data-edytor-drag-preview] (with data-count), that carries the editor root’s classes and its data-edytor attribute inside its ancestors’ classes, with the root’s text style and CSS variables. Theme rules such as .edytor-notion [data-edytor-type='quote'] apply to it, and the default nesting indent too. The clones sit one level below that root, so root-child rules (the theme’s leading Heading 1 as the page title) do not apply: a dragged title shows as a Heading 1.
  • Inert: a clone keeps data-edytor-type, data-edytor-children and the kinds’ own styling attributes, and loses what is editable, focusable or view-only: contenteditable, id, tabindex, the selected-block highlight, placeholders, render anchors, suggestions and peers’ carets, and every attribute the editor finds live nodes by (data-edytor-id, data-edytor-block, data-edytor-text, data-edytor-inline-block, data-edytor-mark, data-edytor-void, …). A [data-edytor-id] lookup never matches it. A block’s own padding and margin, which the theme sets on [data-edytor-block], are copied onto its clone.

Style the ghost through [data-edytor-drag-preview], for instance [data-edytor-drag-preview] [data-edytor-type='heading'] { … }. It is mounted under body, so scope rules to it rather than to the overlay.

Beside: columns

When the document has a layout kind (the columns plugin’s columns), a block row also has two beside bands, checked before its halves, while the pointer is within the row’s height, as in Notion:

  • Right: the row’s last 15% (at least 32px), the slop past its right edge, and the page margin right of the blocks (up to 120px, then the reorder) at the row’s height, however the pointer got there. The drop puts the blocks right of the block: in a new column after its column, or, at the root, in a new two-column layout with the block on the left.
  • Left: the page margin past the handle column (up to 120px further left, then the reorder) at the row’s height, even entered from above or below, and, inside the editor, the 20px slop left of a row in a column (in the gap); only for a block at the root or directly in a column, a list’s item standing for its list (a nested block keeps the pointer’s horizontal position for its levels, and its row in the page margin reorders). The blocks go first. The handle column itself (as wide as the drag’s handle, left of the blocks’ text) is never a beside band: there the row at the pointer’s height takes the drop before or after it, by its halves, row after row, gaps between rows included, so a drag straight down the handles reorders.
  • The gap between two columns: a new column between them.

Beside a list item or a code line, the layout wraps the whole list or code block. Beside any other block it wraps that block where it is: a toggle’s or a callout’s child gets its layout inside the toggle or callout (a toggle’s child inside a column, where no layout may go, gets a new column beside its column instead). The drop is one edytor.move call with position: 'left' | 'right' (one undo step that restores the selection held before the drag; the moved blocks end selected).

  • Refused bands. A band the document refuses (a whole layout dragged beside a block, since no layout goes into a column) shows nothing, and letting go there moves nothing. No band is offered where the layout would stack its columns (under 480px wide).
  • Over a layout, only the column under the pointer is measured, and a short gap never keeps a placement across a column boundary.
  • The bar is vertical: at the block’s edge and its height, or, when the drop adds a column to a layout, the layout’s height, in the middle of the gap or at the layout’s edge.
  • The preview clones each block at its own width, so a column’s block keeps its column’s width.

The drop indicator

The indicator is a 4px bar (Notion’s) the plugin places in the overlay rather than on the block, so rounded or padded block styles cannot bend it. The editor draws the same indicator, by the same rules, for files dragged from your desktop, with or without this plugin (Pasted and dropped files). It is [data-edytor-drop-indicator] (with data-position, data-count, data-blocked); the plugin gives it its place and size, a theme its look:

  • Before or after: the bar spans the blocks at the drop slot. Between two siblings it is centered in the gap and spans both blocks, so hovering the bottom of one block and the top of the next shows the same bar.
  • Before a first child (the lower half of a block whose children show): at that child’s top, indented to its column.
  • After an ancestor (below the last block of a nested group): below that block’s row, indented to the ancestor’s level.
  • Inside: the same bar where the new child will land (after the target’s last visible child, else after its own row), indented to the child’s column and running to the target’s right edge. With no visible child to measure, the column is one nesting step past the target’s text: --edytor-nest-indent in px (see Nested blocks), else 24px.

The Notion theme paints it in --edytor-drop-indicator-color (Notion’s rgba(35, 131, 226, 0.43)); the plugin carries that variable from the target block onto the indicator, since the overlay is not inside the editor. Without the theme it is unpainted: give it a color (Without the theme):

[data-edytor-overlay] [data-edytor-drop-indicator] {
	background: var(--edytor-drop-indicator-color, #2eaadc);
}

The nest backdrop

When the drop will nest the dragged blocks in another block, that future parent also gets Notion’s soft backdrop: a rounded tint over its own row (its own content, not its children), drawn by the same overlay layer as the bar, so block styles cannot distort it. It shows for an inside drop (on the target, or, inside a list, on the last item the blocks nest under), and for a before/after drop among the children of a block that is not already their parent; a before/after drop that keeps the blocks’ parent, or lands them at the root, shows the bar alone. The drop commits the placement it showed. It is [data-edytor-drop-backdrop] in the overlay, with data-shown="true" and the parent’s data-block-id while it applies; the plugin hides it otherwise.

Its look is a theme’s too, and the plugin carries --edytor-drop-backdrop-color onto it as it does the bar’s. The Notion theme’s is Notion’s light tint, fading in and out as the placement changes. Without the theme, paint it yourself, for instance with the same fade:

[data-edytor-overlay] [data-edytor-drop-backdrop] {
	border-radius: 4px;
	background: var(--edytor-drop-backdrop-color, rgba(35, 131, 226, 0.14));
	opacity: 0;
	transition:
		opacity 120ms ease,
		visibility 120ms ease;
}
[data-edytor-overlay] [data-edytor-drop-backdrop][data-shown='true'] {
	opacity: 1;
}

Give it one plain color. Avoid light-dark(): CSS minifiers such as lightningcss (Vite’s default) rewrite it into variables that exist only beside a color-scheme declaration, and without one the backdrop paints nothing.

Auto-scroll

While you drag a block, the page scrolls when the pointer nears its top or bottom edge, and so does every scrolling element around the editor (the editor too, if it scrolls), the way Atlassian’s auto-scroll package (@atlaskit/pragmatic-drag-and-drop-auto-scroll) does it:

  • Speed: the closer the pointer is to the edge, and the longer it stays near it, the faster it scrolls, up to a limit, and at the same speed on 60 Hz and 120 Hz screens.
  • Which element: the innermost scrolling element under the pointer scrolls first, then the ones around it, one per direction.
  • Scope: it reacts only to this editor’s block drags. It is registered when a drag starts and released when it ends, so a page with several editors, or other drag and drop, is unaffected.

There is nothing to configure. The browser’s own drag scrolling at the window’s very edge still applies on top, as no page can turn it off.

Keyboard moves

While a handle has focus, Alt with an arrow key moves its block:

Keys Move
Alt + ↑ Up: before the previous sibling, or before the parent from a first child
Alt + ↓ Down: after the next sibling, or after the parent from a last child
Alt + → In: the last child of the previous sibling (with allowNesting)
Alt + ← Out: after the parent (a list’s item leaves the list, as Shift+Tab)

The handle claims every Alt+arrow while it has focus. A handle of a block the selection covers moves the same blocks a drag of it would (Dragging several blocks), and they end selected as after a drop: a block selection holding them stays, a text range over them stays as it was (as with Mod+Shift+arrow), and a block moved alone is selected alone. Undo restores the selection you had. As a relative step, they must share one parent, else nothing moves. A move never puts a block directly in a list it is no item of, but a block already there (an image a merge left among the items) moves among them like an item, by key, menu or drag. A move never hides a block you saw: moving a block into a closed toggle, with Alt + → or a drop inside it, opens the toggle, as Tab does. To move the caret’s block from the text, or a block selection, see Arrow move.

Building a block menu

The block menu plugin is a complete Notion-style menu’s behavior: list createBlockMenuPlugin({ menu }). A grip click, after selecting the block (a block selection that already holds it stays; over a text range across blocks, the blocks it covers are selected), dispatches a DOM event on the editor’s root, which that plugin (or your own) listens for. A menu that takes the keyboard answers it with event.preventDefault(). Unanswered (no menu), the editor takes the focus, so the keys act on the selected block as in Notion: Backspace deletes it, Shift+arrows extend the selection, typing replaces it. (The grip keeps its Alt+arrow moves while it has focus, from Tab.)

import { BLOCK_ACTIVATE_EVENT, type BlockActivation, type Plugin } from 'edytor';

export const myMenuPlugin: Plugin = () => ({
	onEdytorAttached: ({ node }) => {
		const open = (event: Event) => {
			// The menu takes the keyboard; without this the editor takes the focus.
			event.preventDefault();
			const { block, anchor } = (event as CustomEvent<BlockActivation>).detail;
			// Open a menu for block, next to anchor.
		};
		node.addEventListener(BLOCK_ACTIVATE_EVENT, open);
		return () => node.removeEventListener(BLOCK_ACTIVATE_EVENT, open);
	}
});

To build your own menu instead, listen for that event (as above): its detail gives you the block and the grip element; the click has already selected the block. A typical menu converts or moves the block with the editor’s commands and then returns the caret to the text:

import type { BlockActivation } from 'edytor';

export const onActivate = async ({ block, anchor }: BlockActivation) => {
	const { edytor } = block;
	const rect = anchor.getBoundingClientRect();
	// Show your menu at rect.right, rect.top, listing edytor.kinds and move actions.
	// For example, "Turn into heading 2": the kind's command converts what the
	// click selected, a selected list's items too (a list itself never converts).
	await edytor.runCommand('block.heading2');
	// Or "Move down":
	if (edytor.canMove({ blocks: [block], direction: 'down' })) {
		edytor.move({ blocks: [block], direction: 'down' });
	}
};

The same edytor.move and edytor.canMove calls move blocks from anywhere, with direction (up, down, in, out) or with a target and position (before, after, inside). Like the handles, a move opens a closed toggle the blocks land in, or that takes blocks as children, so a moved block is never hidden. See Commands.

A click leaves a block selection behind, and a DOM range alone does not replace it. To put the caret back in the block after a menu action, call selection.setCaret({ block, offset: 0 }) once — it replaces the block selection and the projector draws it after the flush — then focus the editor. A kind whose own content is not displayed (a list container) takes the caret in its first child:

const target = block.firstText ? block : block.children[0];
if (target) {
	edytor.selection.setCaret({ block: target, offset: 0 });
	edytor.node?.focus({ preventScroll: true });
}

Was this page helpful?