Anchor API

An anchor keeps a path, point, or range mapped through canonical DocumentChange values. Choose its API by lifetime: editor.anchor is persistent, while tx.anchor is limited to one transaction callback.

Persistent anchors

editor.anchor(value, options) => Anchor

const selection = editor.read.selection();
 
if (!selection) return;
 
const target = editor.anchor(selection, {
  association: "inward",
  deletion: "drop",
});Copy

const selection = editor.read.selection();
 
if (!selection) return;
 
const

deletion is required:

• "drop" resolves to null when the target is deleted. Undo does not resurrect the dropped value.
• "nearest" resolves to the nearest valid location. Saved undo and redo restore the exact value recorded on each side of the history batch.

Paths and points accept "backward" or "forward" association. Ranges also accept "inward" and "outward". Pass root for a rootless value that belongs to a named document root.

Persistent anchors remain active across commits and history actions until release() is called.

const current = target.resolve();
const finalValue = target.release();Copy

const current = target.resolve();
const finalValue = target.release();Copy

resolve() returns the current mapped value without ending tracking. release() returns the current value and permanently detaches the anchor. Both return null after a dropped target or release.

Use persistent anchors for application-owned runtime state such as local annotations. Release them when their owner is removed.

Transaction anchors

tx.anchor(value, options) => EditorTransactionAnchor

Transaction anchors track a location only while the update or detached transaction builder is active.

editor.update((tx) => {
  const target = tx.anchor(range, {
    association: "inward",
    deletion: "nearest",
  });
 
  tx.text.delete({ at: range });
 
  const mapped = target.resolve();
 
  if (mapped) tx.selection.set(mapped);
});Copy

editor.

EditorTransactionAnchor exposes only resolve(). The transaction releases its backing anchor automatically. Calling resolve() after the callback ends throws because the transaction is no longer active.

Anchors are runtime values. Persist the resolved path, point, or range only when the application owns a durable serialization policy.