The Edytor component
Every prop of the Edytor component, with types and defaults, and how a plugin restyles a block, mark or inline kind.
<Edytor> renders one editable (or readonly) view of a document. This page lists every prop it accepts, and how to replace how a kind renders.
<script lang="ts">
import { Edytor, type JSONBlock } from 'edytor';
const save = (doc: Partial<JSONBlock>) => fetch('/api/note', { method: 'PUT', body: JSON.stringify(doc) });
</script>
<Edytor
value={{ children: [{ type: 'paragraph', content: [{ text: 'Hello' }] }] }}
plugins={[() => ({ placeholder: 'Write something…' })]}
onChange={({ data, children }) => save({ data, children })}
/>
Props
Most props are read once, when the component is created. Changing them later has no effect; recreate the component (for example with {#key}) to apply new ones. The Live column marks the props that follow updates.
| Prop | Type | Default | Live | Description |
|---|---|---|---|---|
plugins |
Plugin[] |
[] |
Block kinds, marks, inline blocks, hotkeys and hooks. Order matters: the first definition of a type wins. The view adds the rich text, arrow move and suggestions plugins unless the list has them. See Plugins. | |
defaultPlugins |
boolean |
true |
false renders exactly plugins, without the default rich text, arrow move and suggestions plugins. |
|
value |
JSONDoc |
{ children: [] } |
The initial content, and the document’s properties in data. Used only to seed a document that has none; an empty value seeds one paragraph. See Document model. |
|
document |
EdytorDocument |
A document created with createDocument, loadDocument or attachDocument. Several views can share one. The view does not destroy it on unmount. |
||
server |
string |
The sync server’s base URL (wss://…/rooms). With room, the view joins <server>/<room> over a WebSocket and keeps a local copy. Read once. See WebSocket. |
||
room |
string |
The document’s id, 1 to 256 characters of any kind. Alone, it names a local IndexedDB copy; with server, the room to join (sent percent-encoded as one path segment). A URL collapses . and .. and cannot encode a lone surrogate, so those ids, an empty one and one over 256 characters are never dialed: the view, editable or readonly, reports them through onSyncRefused as 4400 invalid document id. Read once. |
||
params |
Record<string, string> |
Next dial | Query parameters sent with each connection, such as an auth token. | |
onSyncExpired |
({ reason, attempts, nextRetryMs }) => void |
Yes | With server: the room closed the connection with 4401 (expired credentials). Pass a fresh token in params before the redial, due in nextRetryMs. Until a dial gets in, an empty document is not seeded. If the callback throws, the error is logged and the redial still happens. See WebSocket. |
|
onSyncRefused |
(refusal: SyncRefusedError) => void |
Yes | The server refused a provider of the view’s document for good (4403, 4409, 1008…): called at mount for a refusal already standing, then for each new one. A callback that throws is logged and still hears the next refusal. See refusals. |
|
requireHydration |
boolean |
false |
No | Seed nothing, and keep the view read-only, until its document was fetched once (a provider synced). For the document the view owns; with document, set it there. See require hydration. |
snapshot |
JSONDoc |
No | The document as JSON, shown read-only until the view’s document is ready, then replaced by the live view: a first visit to a room paints at once. Fetch it with documentSnapshot. See first paint from a snapshot. |
|
sync |
EdytorSync |
Advanced: a custom provider factory such as createIndexeddbSync(name) or createWebsocketSync(options). Attached in the browser when the view is editable; the view renders once the document is ready. See Collaboration. |
||
actor |
DocumentActor |
anonymous | The local author { id, name?, color? } of the view’s own document: per-block attribution and the presence profile peers see. Cannot be combined with document (set it in createDocument). |
|
readonly |
boolean |
false |
Yes | Render the document without editing. See Readonly mode. |
allowNesting |
boolean |
false |
No | Let users nest blocks under other blocks: Tab and Shift + Tab nest and unnest (Keyboard shortcuts), and a block handle’s drag or Alt + → may place a block inside another. Off, no gesture nests and Tab is left to the browser, which moves the focus out (a code line, a table cell or a suggestion still takes it). Lists, toggles, callouts and columns keep their bodies either way, and nested blocks already in the document still show and edit. Also new Edytor({ allowNesting }). |
labels |
PartialLabels |
English | The words the package shows and says in this view, any entry of any section (the kinds’ names, the placeholders, the announcements …), and the commands’ slash keywords by id. See Localization. |
|
hotkeys |
Partial<Record<HotKeyCombination, HotKey>> |
Key bindings ('mod+s', 'alt+shift+arrowup', …) checked before the plugins’ and the built-in ones. See Hotkeys. |
||
onChange |
(value: JSONDoc) => void |
Called after every committed change, local or remote, with the document as a JSONDoc, the type value takes: { data?, children } (the object also carries type: 'root'). data holds the document’s properties. A stored value opens as value as it is. |
||
onDocChange |
(change: DocChange) => void |
Called after every committed change, local or remote, with what it changed (the change report: blocks added, removed, moved, retyped or edited) and no whole-document export, unlike onChange. The report is shared and read-only. A throw is logged and never stops the other consumers. Read edytor.value when you need the JSON. See Reading state reactively. |
||
onSelectionChange |
(selection: EdytorSelection) => void |
Called when the selection value changes. See Selection. | ||
edytor |
Edytor |
Bindable | The editor instance. Use bind:edytor. See The editor instance. |
|
class |
string |
Yes | Class on the editable root element. | |
aria-label |
string |
Yes | The editor’s accessible name (the root is a textbox). See Accessibility. |
|
aria-labelledby |
string |
Yes | The id(s) of the element(s) naming the editor, such as the page title. | |
aria-describedby |
string |
Yes | The id(s) of the element(s) describing it, such as a hint. | |
id |
string |
Yes | The root element’s id. | |
spellcheck |
boolean |
true |
Yes | The root’s spellcheck attribute. |
autocorrect |
'on' | 'off' |
'off' |
Yes | The root’s autocorrect attribute. |
autocomplete |
'on' | 'off' |
'off' |
Yes | The root’s autocomplete attribute. |
autocapitalize |
'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters' |
unset | Yes | The root’s autocapitalize attribute. Unset, a phone’s keyboard capitalizes sentences (its own default; a desktop browser ignores it). On iOS it applies to the whole editor, code blocks included, and is read when the editor takes the focus; pass 'none' to keep the keyboard lowercase. |
inputmode |
'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url' |
unset | Yes | Virtual keyboard hint. Omitted from the DOM when unset. While the selection is a block selection (a tapped image), the root says none: a phone shows no keyboard over selected blocks, and a hardware keyboard’s keys still act on them. |
enterkeyhint |
'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send' |
unset | Yes | Label of the virtual keyboard’s action key. Omitted when unset. |
translate |
'yes' | 'no' |
'no' |
Yes | The root’s translate attribute. 'no' keeps page translators from rewriting the editable text. |
presence |
{ share?: 'caret' | 'block' | 'none'; throttle?: number } |
{ share: 'caret', throttle: 50 } |
What this view shares of its selection with peers, and the least ms between two writes. Follows changes. See Sharing less at scale. |
value is the initial content, not a binding: bind:value fails type-checking. Read changes with onChange or edytor.value.
document, room/server/sync and value together
- Only
value: the view creates its own document, seeds it, and destroys it on unmount. room,serverorsync: the view creates its own document and attaches the provider (syncoverridesroom/server). Stored or remote content wins;valueseeds the document only when the provider has nothing, after it answered or timed out. Never pass a changing snapshot (onChangeoutput) asvaluebeside a room: a late seed of it can replace the room’s edits. Pass a fixed template or nothing; see deterministic seeds.document: the view renders that document once it is ready. If the document is still waiting for content and no provider is attached to it, the editable view seeds it withvaluewhen it mounts, unless a server refused it (document.syncRefusal): then an empty document stays waiting, and one that already holds content is shown. Passingdocumenttogether withactororrequireHydrationthrows in development: set them on the document.
A readonly view connects the same way: with room, server or sync it is a live viewer of its room (see Readonly mode).
Block handles
The handles are a plugin whose markup is yours: list createBlockHandlesPlugin({ handle }), the + and the grip drawn by your handle snippet (Block handles). Add createBlockMenuPlugin({ menu }) to open a block menu on a grip click, or listen for its edytor-block-activate event to open your own:
<script lang="ts">
import {
Edytor,
BLOCK_ACTIVATE_EVENT,
createBlockHandlesPlugin,
type BlockActivation,
type BlockHandleSnippetPayload,
type Plugin
} from 'edytor';
let menu = $state<{ blockId: string; anchor: HTMLElement } | null>(null);
/** Your menu answers a grip click (`preventDefault`: it takes the keys). */
const myMenu: Plugin = () => ({
onEdytorAttached: ({ node }) => {
const open = (event: Event) => {
const { block, anchor } = (event as CustomEvent<BlockActivation>).detail;
event.preventDefault();
menu = { blockId: block.id, anchor };
};
node.addEventListener(BLOCK_ACTIVATE_EVENT, open);
return () => node.removeEventListener(BLOCK_ACTIVATE_EVENT, open);
}
});
const plugins = [createBlockHandlesPlugin({ handle }), myMenu];
</script>
{#snippet handle({ label, grip }: BlockHandleSnippetPayload)}
<button aria-label={`${label} block`} {@attach grip}>⠿</button>
{/snippet}
<Edytor {plugins} />
A focused handle moves its block with Alt+↑/↓ and nests or outdents it with Alt+→/←. The drop indicator and the nest backdrop (the tint on the block a drop nests into) are placed by the plugin and painted by the theme: [data-edytor-drop-indicator] and [data-edytor-drop-backdrop], which carry the --edytor-drop-indicator-color and --edytor-drop-backdrop-color the theme sets; without it, style them yourself (see Without the theme).
Restyling a kind
A kind’s markup is its plugin’s snippet. To replace how a bundled kind renders, list a plugin before it that names only that kind’s snippet: the first plugin’s fields win, and a field it leaves out is the next one’s, so the kind keeps its element and content element, void and island flags, presets, hooks and clipboard forms. A quote’s content() still renders inside its blockquote, a heading’s inside its h1–h3.
<script lang="ts">
import { Edytor, type BlockSnippetPayload, type MarkSnippetPayload, type Plugin } from 'edytor';
const restyled: Plugin = () => ({ blocks: { quote: quote }, marks: { bold: bold } });
</script>
{#snippet quote({ content, children }: BlockSnippetPayload)}
<span class="quote-mark" contenteditable="false">“</span>
{@render content()}
{#if children}<div class="quote-children">{@render children()}</div>{/if}
{/snippet}
{#snippet bold({ content }: MarkSnippetPayload)}
<span class="font-semibold">{@render content()}</span>
{/snippet}
<Edytor plugins={[restyled]} />
| Definition | Its snippet receives |
|---|---|
blocks |
{ block, content, children }. block is a reactive view (id, type, data, selected, focused, handle); render content() for the block’s text and children() (or null when it has none) for nested blocks. |
marks |
{ content, mark, text }. mark is the mark’s value. The snippet renders inside a <span data-edytor-mark> instead of the mark’s tag. |
inlineBlocks |
{ block }, a reactive view with id, type, data, selected and handle. |
The core renders the block element itself (the kind’s element, a div by default) and the element around its text (the kind’s contentElement, if any), so a block snippet renders only the markup inside the block element. Mark non-editable chrome inside a block with contenteditable="false", or with the use:block.void action.
To define a new kind rather than restyle one, write a plugin: see Custom blocks. To replace the slash menu, toolbar, block menu or block handle markup, pass snippets to their plugins: see Menus and handles.