# Actions

> The EditorActions surface - every dispatcher exposed by useEditor() and useDocumentState().

Source: https://docs.docmosaic.com/docs/reference/actions

`actions` is a flat, referentially stable object of dispatchers. Same surface whether you reach it through `useEditor().actions` (compound primitives) or `useDocumentState().actions` (BYO-UI).

## Sections

| Method                      | Effect                                                                                                                                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `addSection(opts?)`         | Append a new section to the **current page** (there is no `pageIndex` option). `opts` carries `{ type, shape, maskShape, rect }`. `type` accepts `'frame'`; an image may pass `maskShape` for a placeholder/image-mask frame. Returns the created `Section`. |
| `updateSection(section)`    | Replace the section sharing this `id` with the updated `Section` object.                                                                                                                                                                                     |
| `deleteSection(id)`         | Remove the section. Deleting a container frame also removes its children (`parentFrameId`). Clears selection if it was selected.                                                                                                                             |
| `duplicateSection(section)` | Clone the `Section` onto the same page with a small offset. Duplicating a container frame also clones its children, re-pointed at the new frame.                                                                                                             |
| `setHidden(id, hidden)`     | Explicitly set the hidden flag.                                                                                                                                                                                                                              |
| `toggleHidden(id)`          | Flip the hidden flag.                                                                                                                                                                                                                                        |
| `setLocked(id, locked)`     | Explicitly set the locked flag.                                                                                                                                                                                                                              |
| `toggleLocked(id)`          | Flip the locked flag.                                                                                                                                                                                                                                        |

## Layers

| Method             | Effect                                                |
| ------------------ | ----------------------------------------------------- |
| `bringToFront(id)` | `zIndex = max(peers) + 1`.                            |
| `sendToBack(id)`   | `zIndex = min(peers) - 1`.                            |
| `moveForward(id)`  | Swap `zIndex` with next-higher peer on the same page. |
| `moveBackward(id)` | Swap `zIndex` with next-lower peer on the same page.  |

## Pages

| Method                                     | Effect                                                              |
| ------------------------------------------ | ------------------------------------------------------------------- |
| `addPage()`                                | Append a new empty page.                                            |
| `deletePage(pageIndex)`                    | Remove the page and every section on it.                            |
| `reorderPages(from, to)`                   | Move a page within the list; rewrites the `page` field on sections. |
| `setPageBackground(pageIndex, background)` | Update the page's background color or image.                        |
| `addGuide(pageIndex, axis, position)`      | Add a vertical / horizontal guide line on the page.                 |
| `removeGuide(pageIndex, axis, position)`   | Remove the matching guide.                                          |

## Document properties

| Method                           | Effect                            |
| -------------------------------- | --------------------------------- |
| `updateName(name)`               | Update `Document.name`.           |
| `updatePageSize(size)`           | Switch the document's `pageSize`. |
| `updateOrientation(orientation)` | Switch portrait / landscape.      |

## History

| Method   | Effect                          |
| -------- | ------------------------------- |
| `undo()` | Step backwards on the timeline. |
| `redo()` | Step forwards.                  |

## UI

Selection, preview, and generation control live on the `ui` and `pdfApi` objects from `useEditor()`, not on `actions` — only `changePage` is an `actions` method.

| Method                                   | Effect                                                        |
| ---------------------------------------- | ------------------------------------------------------------- |
| `changePage(pageNumber)`                 | Switch the active page in the canvas (1-based, on `actions`). |
| `ui.setSelectedSectionId(id \| null)`    | Set / clear the current selection.                            |
| `ui.openPreview()` / `ui.closePreview()` | Toggle the preview dialog.                                    |
| `pdfApi.abort()`                         | Abort the in-flight PDF/PNG generation.                       |

## Stability

`actions` is referentially equal across renders. Safe to put in dependency arrays without triggering re-runs.

## See also

-   [Hooks reference](/docs/reference/hooks)
-   [Types reference](/docs/reference/types)