Editor

The headless editor primitive: schema, state, form and preview layer. Unstyled; styling happens in the consumer's wrapper components (registry). For styled chrome, see Editor UI and the Visual editor guide.

import { Editor, createEditor, useEditor } from '@createcms/react/editor';

Usage

Editor.Root holds the store; Editor.Form renders every declared property of one block as a complete field. Kinds without a built-in control (image, reference, link) come from the fields map:

import type { AnyEditorSchema } from '@createcms/react/editor';
import type { BlockTreeNode } from '@createcms/core';

import { Editor, useFields } from '@createcms/react/editor';

import { MediaField } from './media-field';

function PageForm({
  schema,
  tree,
}: {
  schema: AnyEditorSchema;
  tree: BlockTreeNode;
}) {
  return (
    <Editor.Root
      schema={schema}
      defaultValue={tree}
      fields={{ image: MediaField }}
    >
      <Editor.Form blockId={tree.blockId} />
    </Editor.Root>
  );
}

The same form by hand, for a custom layout: map over useFields(blockId) and compose the parts yourself.

function BlockFields({ blockId }: { blockId: string }) {
  const fields = useFields(blockId);
  return fields.map(({ key }) => (
    <Editor.Field key={key} blockId={blockId} name={key}>
      <Editor.FieldLabel />
      <Editor.FieldControl />
      <Editor.FieldDescription />
      <Editor.FieldError />
    </Editor.Field>
  ));
}

Uncontrolled (key resets): schema, defaultValue, genId, userId and fields are read once at mount; render with a different key to load another document. onChange/onSave are read fresh on every call, so inline handlers are fine.

Editor.FieldControl accepts render only; it does not take className.

Parts

Editor.Preview subscribes to the store version and passes the raw store tree (getTree()) to render after a delay (default PREVIEW_DEBOUNCE_MS, 100 ms, then one animation frame; debounceMs={0} still waits one frame).

Hooks

createEditor

createEditor({ schema }) binds Editor.Root, Preview, FramePreview and every hook above (including useEditorKeyboard) to one schema: Root has schema pre-set and defaultValue typed as TreeOf<typeof schema>; Preview's render callback receives TreeOf<typeof schema>; FramePreview's render callback receives TreeOf<typeof schema> plus { signal }; useBlock/useField narrow on the schema's declared block types; useChildren returns ChildRefOf<S>[] and useBlockActions returns TypedBlockActions<S>; add and usePalette resolve to never for a schema without statically known blocks. Every returned hook first checks that the enclosing Editor.Root uses the SAME schema object (===) and throws otherwise.

Schema helpers

Layer 1 of the editor primitive: pure functions over an EditorSchema (a CollectionDefinition). No React, no DOM.

Store

Layer 2 of the editor primitive: a small getState/subscribe core with no React import. Rapid same-key updates coalesce into one undo step within COALESCE_MS. Dirty tracking uses stableHash.

Use createEditorStore to construct a store. Pure helpers: applyOp applies one op and returns { nodes, rootId, inverse }; createBlockId mints ids; flattenTree and serializeToTree convert between flat nodes and a tree; stableHash hashes a tree for dirty detection.

Field helpers: defaultFieldControls, emptyListElement, toDatetimeLocal, fromDatetimeLocal.

Types

Data attributes

Keyboard

ARIA

Focus