useProgrammaticEditor

Reads and edits the document text without any visible UI, for AI-driven and automated workflows. See the Programmatic editing guide for the walkthrough.

const {
  getParagraphsByPage,
  getAllParagraphIds,
  getPlainTextParagraphs,
  getParagraphEditor,
  setEditorAwarenessProperties,
  removeEditorAwarenessCursor,
} = useProgrammaticEditor()

Reading

getParagraphsByPage(pageId) loads the page and resolves with its paragraphs in content order. An unknown page id resolves with an empty array.
getAllParagraphIds() resolves with every paragraph id, in page and content order. It loads every page sequentially, which can take a long time for a large document, so prefer getParagraphsByPage when the page is known.
getPlainTextParagraphs(paragraphIds) resolves ids to paragraph entries, skipping ids that no longer exist.

The paragraph entries are PlainTextParagraph snapshots: the paragraph properties, as useSetParagraphProps accepts them, plus:

Field	Meaning
`id`	The paragraph's block id (session-scoped).
`content`	The paragraph text as a plain string.
`pageNumber`	The page the paragraph is on, 1-based; `0` when the page is no longer in the document.
`bounds`	The box the paragraph covers on the page, in user space: `{ x, y, width, height }`. Zero-size at the start of the baseline for an empty paragraph.

x and y among the paragraph properties are the start of the first line's baseline, not a corner of the box: use bounds to locate the paragraph on the page.

getParagraphEditor(paragraphId) returns an EditorMirror for one paragraph, or undefined when the paragraph doesn't exist (it may have been deleted since it was read). The mirror carries the operations of a text editor without a screen:

Method	What it does
`selectAll()`	Selects the whole paragraph text.
`deleteAll()`	Deletes the whole paragraph text, keeping its formatting for the next inserted text.
`insertText(text)`	Inserts the text at the current selection, replacing the selected text if any.

The edits behave like the user's typing: they enter the undo history (see useUndoBoundary to keep them in their own undo step) and change the document revision, but emit no viewport events.

Presence

setEditorAwarenessProperties({ name, color }) gives the programmatic editor a visible text cursor with a name label, so the user sees where an automated edit happens, like another participant's cursor. name is the label text and color a CSS color.
removeEditorAwarenessCursor() hides the cursor when the work is done.

Both throw DocumentNotLoadedError when no document is loaded.

useProgrammaticEditor

Reading

Editing

Presence

On this page