Slate

PreviousNext

API reference for @platejs/slate.

@platejs/slate is the framework-free editor runtime. It owns document values, roots, operations, schema extensions, state fields, read APIs, transaction groups, and pure node/location helper namespaces.

Installation

pnpm add @platejs/slate
pnpm add @platejs/slate

Use @platejs/slate in package code that should not import React or Plate core. Framework packages such as @platejs/slate-react and @platejs/core/react mount this runtime instead of replacing it.

Quick Use

Create a framework-free editor
import { createEditor } from '@platejs/slate';
 
const editor = createEditor({
  initialValue: [{ children: [{ text: 'Hello' }], type: 'p' }],
});
 
editor.update((tx) => {
  tx.text.insert(' world');
});
 
const text = editor.read((state) => state.text.string([]));
Create a framework-free editor
import { createEditor } from '@platejs/slate';
 
const editor = createEditor({
  initialValue: [{ children: [{ text: 'Hello' }], type: 'p' }],
});
 
editor.update((tx) => {
  tx.text.insert(' world');
});
 
const text = editor.read((state) => state.text.string([]));

createEditor returns an editor with explicit read(...) and update(...) boundaries. Reads observe committed state. Writes run inside transaction groups.

Package Surface

SurfaceExportUse
Editor factorycreateEditorCreates a framework-free Slate editor.
Runtime viewscreateEditorRuntime, createEditorViewCreate one committed runtime and optional root-scoped editor views.
Editor typesEditor, BaseEditor, Value, InitialValue, Selection, ValueOfType editor instances, document values, and selection state.
Read APIEditorStateView, EditorStateValueApi, EditorStateSelectionApi, EditorStateTextApiRead committed state inside editor.read(...).
Transaction APIEditorUpdateTransaction, EditorTransactionValueApi, EditorTransactionNodesApi, EditorTransactionSelectionApiMutate editor state inside editor.update(...).
InterfacesElementApi, NodeApi, TextApi, PathApi, PointApi, RangeApi, OperationApiTyped helpers for Slate data structures.
RefsPathRef, PointRef, RangeRefMutable location refs that track editor operations.
ExtensionsdefineEditorExtension, defineStateField, elementPropertyRegister schema facts, state groups, tx groups, normalizers, middleware, and commit hooks.

Editor Shape

An Editor contains committed document state plus explicit read and update entrypoints.

FieldTypeUse
childrenValuePrimary document children.
selectionSelectionCurrent selection.
operationsOperation[]Operations applied since the last change flush.
marksEditorMarks | nullMarks applied to the next inserted text.
read<T>(fn: (state) => T) => TRead committed state.
update(fn: (tx, context) => void, options?) => voidCommit model, selection, mark, root, operation, and state-field writes.

API Map

PageCovers
Editor APIRead methods on editor.read(...) state groups.
Editor TransformsTransaction methods on editor.update(...) tx groups.
NodeNode, descendant, ancestor, and node-entry helpers.
ElementElement types, element props, and element guards.
TextText node types, mark objects, and text guards.
PathPath comparison, movement, ancestry, and transform helpers.
PointPoint comparison, edge checks, and point transforms.
RangeRange checks, edge helpers, intersection, inclusion, and transforms.
LocationPath, Point, Range, and Span location unions.
Location RefPathRef, PointRef, and RangeRef affinity behavior.
OperationSlate operation types, operation lists, and operation inversion.

History

Batch history
editor.update((tx) => {
  tx.history.withNewBatch(() => {
    tx.text.insert('Title');
    tx.text.insertBreak();
  });
 
  tx.history.withoutSaving(() => {
    tx.selection.select([]);
  });
});
Batch history
editor.update((tx) => {
  tx.history.withNewBatch(() => {
    tx.text.insert('Title');
    tx.text.insertBreak();
  });
 
  tx.history.withoutSaving(() => {
    tx.selection.select([]);
  });
});

History is a Slate extension. It stores undo and redo batches, exposes history state through read groups, and exposes undo/redo plus batching helpers through transaction groups.

Extension Authoring

Extensions register schema facts, state groups, transaction groups, normalizers, operation middleware, commit listeners, and runtime APIs.

Use api for mounted host/runtime services. Use tx for feature commands that change Slate model state.

import {
  defineEditorExtension,
  defineStateField,
  elementProperty,
} from '@platejs/slate';
import {
  defineEditorExtension,
  defineStateField,
  elementProperty,
} from '@platejs/slate';

Helper Namespaces

Pure data helpers live on ElementApi, LocationApi, NodeApi, OperationApi, PathApi, PathRefApi, PointApi, PointRefApi, RangeApi, RangeRefApi, SpanApi, and TextApi.

Inside editor.read(...) and editor.update(...), prefer grouped state.* and tx.* APIs. Use helper namespaces when library code needs pure operations on Slate data outside an editor transaction.

Related APIs

  • Plate shows where @platejs/slate is re-exported from the platejs umbrella package.
  • Plate Editor covers the React/Core editor layer built on top of this package.