The editor instance

The runtime Edytor object behind every view, its members, the Block, Text and InlineBlock handles, and how to read state reactively.

Each <Edytor> view creates one runtime object, the editor instance. It holds the document the view renders, the selection, the plugins and the command dispatcher. You need it to read or change content from code, or to build UI around the editor (toolbars, menus, status bars).

Getting the instance

From the parent, bind it:

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

	let edytor = $state<EdytorInstance>();
</script>

<Edytor bind:edytor />
<button onclick={() => edytor?.historyUndo()}>Undo</button>

From a component rendered inside the editor (a block snippet, an inline block, a plugin’s UI), call useEdytor(). It reads the instance from Svelte context and throws No Edytor found outside an editor:

<script lang="ts">
	import { useEdytor } from 'edytor';

	const edytor = useEdytor();
</script>

The instance exists as soon as the component is created, but edytor.root stays undefined until the document is ready (edytor.synced is then true). With a sync provider that can take a moment.

Members

edytor.facade and edytor.document

edytor.document is the EdytorDocument: it owns the CRDT document, the shared history, awareness and the facade. Several views can render one document; see Collaboration.

edytor.facade is the document’s facade seen through this view. It has every document operation (insertText, formatRange, insertBlock, moveBlocks, …) and read (toJSON, childrenIds, blockTypeOf, …). It differs from edytor.document.facade in one way: while the document has no block, the view shows a local empty paragraph, and edytor.facade.virtual() returns its id. An operation you issue on that id through edytor.facade creates the block first. The JSON (edytor.value) never contains it.

Facade operations are document writes: they skip plugin hooks and normalization. Handle methods go through the dispatcher and do both. Commands compares them.

Handles

Block, Text and InlineBlock are handles: small objects that name a piece of the document by id and read the current state from the document each time you access a getter.

const block = edytor.idToBlock.get('page-title'); // undefined if not live
if (block) {
	block.type; // 'heading'
	block.data; // { level: 'h1' }
	block.children; // Block[]
	block.firstText?.stringContent; // 'A calmer place to think'
	block.value; // this block's JSONBlock
}

Handles are not reactive. A template that reads block.type does not update when the type changes. Read handles in event handlers and commands, and use the reactive sources below in templates.

Because a Text is a position, don’t keep one across edits to find “the same text” later. Keep the block id and an offset, or a selection anchor.

A handle can outlive what it names. Check block.isInTree, text.isInDocument or atom.isInDocument before acting on one you stored; idToBlock.get(id) returns undefined for a block that is gone.

Inside a command, handle getters see the command’s own earlier writes, so a normalizer or a plugin can read the state its operation produced.

Reading state reactively

Use these in templates, $derived and $effect:

• Block snippets receive a view object, block, whose type, data, selected and focused are reactive. block.handle is the non-reactive handle for commands.

  {#snippet callout({ block, content })}
  	<span>{block.data.icon}</span>
  	{@render content()}
  	{#if block.selected}<small>selected</small>{/if}
  {/snippet}

• edytor.cells is the render state: cells.rootIds (the top-level ids) and cells.get(id), a frozen { id, type, data, childIds, runs } that is replaced whenever the block changes. Both are reactive:

  <script lang="ts">
  	const outline = $derived(
  		(edytor?.cells?.rootIds ?? [])
  			.map((id) => edytor!.cells!.get(id))
  			.filter((cell) => cell?.type === 'heading')
  	);
  </script>

• edytor.value is reactive and recomputes the whole JSON after each change. Fine for a word count or a save button; use cells for anything per block.

• edytor.selection.value, selection.state and selection.projection are reactive, as are selection.selectedBlocks and selection.focusedBlocks.

Everything else, including handles, facade reads and definitions, is imperative: read it when you need it.