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

Inline blocks

Define inline atoms such as mentions, render them with snippets, insert and remove them from code, and export and import them as plain text and HTML.

An inline block, or atom, is a non-editable element inside a block’s text: a mention, a date chip, a footnote marker. It sits between text runs, moves with the text, and is selected, copied and deleted as one unit. Atoms live in a plugin’s inlineBlocks map.

In the document an atom is a part of the block’s content, with a type and data:

{
	"type": "paragraph",
	"content": [{ "text": "Thanks " }, { "type": "mention", "data": { "label": "Ada" } }, { "text": "!" }]
}

Content always starts and ends with text, and text runs separate atoms; the editor inserts empty text runs where needed.

Definition

PropType
snippetSnippet<[InlineBlockSnippetPayload]>

The atom's markup.

TypeSnippet<[InlineBlockSnippetPayload]>
plain?(data) => string

The atom's plain-text form on copy. Without one, it copies as nothing.

Type(data) => string
html?(data) => string

The atom's HTML on copy, inline markup you escape yourself. Without one, an empty `<span data-edytor-inline-block>`.

Type(data) => string
markdown?(data) => string

The atom's markdown (toMarkdown), escaped by you. Without one, its plain form.

Type(data) => string
parse?(element: HTMLElement) => Record<string, SerializableContent> | undefined

HTML import: the atom's data when `element`, met inside a line of pasted or dropped HTML, is this atom, else `undefined`. Its contents are then not read as text.

Type(element: HTMLElement) => Record<string, SerializableContent> | undefined

The snippet receives { block }, a view of the atom:

PropType
id?string

The atom's id.

Typestring
type?string

The atom's type.

Typestring
data?object

The atom's data. Reactive.

Typeobject
selected?boolean

The atom is selected. Reactive. Always false for a suggested atom.

Typeboolean
handle?InlineBlock | undefined

The atom's handle, for commands. undefined for an atom shown in an inline suggestion.

TypeInlineBlock | undefined

The core wraps the snippet in <span data-edytor-inline-block="<type>" data-edytor-id="<id>" contenteditable="false">. In HTML copied to the clipboard an atom is its html form, by default an empty span with the same data-edytor-inline-block attribute; content pasted into an Edytor keeps its atoms through the editor’s own clipboard format, and HTML from elsewhere becomes atoms where a parse hook claims an element (the equation plugin’s inline equation reads MathML this way).

A mention atom

For people mentions, use the mention plugin: @ opens a menu of your app’s people and inserts a mention atom. Your own atom is a definition and a way to insert it, usually a trigger. This plugin inserts a date chip from a menu that @ opens:

<script module lang="ts">
	import {
		withRulesAndTriggers,
		type InlineBlockSnippetPayload,
		type Plugin,
		type Trigger
	} from 'edytor';

	const days: Trigger<string> = {
		char: '@',
		items: (query) => ['today', 'tomorrow'].filter((day) => day.startsWith(query)),
		// `from` is where the `@` was: the atom goes there, the caret after it.
		onPick: (day, { edytor, block, from, caret }) => {
			const atom = edytor.insertInline(block.id, from, { type: 'date', data: { day } });
			if (atom.status === 'applied') caret(from + 1);
			return atom.status === 'applied';
		}
	};

	export const datePlugin: Plugin = (edytor) =>
		withRulesAndTriggers(
			edytor,
			{ inlineBlocks: { date: { snippet: date, plain: (data) => `@${data?.day ?? ''}` } } },
			{ triggers: [days] }
		);
</script>

{#snippet date({ block }: InlineBlockSnippetPayload)}
	<span class="date" class:selected={block.selected}>@{block.data.day}</span>
{/snippet}
.date {
	padding: 0 3px;
	border-radius: 3px;
	background: #eef3ff;
	color: #2f5bd3;
}
.date.selected {
	outline: 2px solid #2f5bd3;
}

Inserting, updating and removing atoms

Insert an atom with insertInline, at an offset of its block’s content (block offsets, an atom counting 1; the caret’s):

const caret = edytor.selection.caret; // { block, offset }, or null when the selection is not a caret
if (caret) {
	const { block, offset } = caret;
	const atom = edytor.insertInline(block.id, offset, { type: 'mention', data: { label: 'Ada' } });
	// The caret goes right after the atom.
	if (atom.status === 'applied') edytor.selection.setCaret({ block, offset: offset + 1 });
}

It is an insertInline operation, visible to plugins. An atom’s id is generated when you leave id out. An atom inserted at the caret keeps the caret’s pending marks for the text typed after it.

An atom’s handle is an InlineBlock: atom.data is its data, read and written like plain state (each write a patchData on { block, atom }, visible to plugins and refused in a readonly view; see Properties), atom.parent is its block and atom.index its position in block.content. Remove it with removeInline:

import { InlineBlock } from 'edytor';

const atom = block.content.find((part) => part instanceof InlineBlock && part.id === 'mention-1');
if (atom instanceof InlineBlock) atom.data.label = 'Ada L.';
edytor.removeInline(block.id, 'mention-1');

Users select an atom with the arrow keys or a click; Backspace or Delete removes a selected atom, and typing replaces it.

Atoms can also be part of the initial value, as in the JSON at the top of this page.

Was this page helpful?