# useProgrammaticEditor

Source: https://sdk.pdf.net/docs/v1/reference/useProgrammaticEditor



Reads and edits the document text without any visible UI, for AI-driven and automated workflows. See the [Programmatic editing](https://sdk.pdf.net/docs/v1/guides/programmatic-editing) guide for the walkthrough.

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

## Reading [#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](https://sdk.pdf.net/docs/v1/reference/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.

## Editing [#editing]

`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](https://sdk.pdf.net/docs/v1/reference/useUndoBoundary) to keep them in their own undo step) and change the [document revision](https://sdk.pdf.net/docs/v1/reference/useDocumentRevision), but emit no [viewport events](https://sdk.pdf.net/docs/v1/reference/useViewportEvent).

## Presence [#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.