Editor mount modes
Mount one editor inline, in an iframe, or in a pop-out window, keep it detached, and move it without losing state.
An editor instance owns its document, undo history, selection, and collaboration session. Where it paints is separate, so you can attach, detach, and move it. This page covers placement; for editing, suggesting, and viewing modes, see Tracked changes.
Attach or move an editor
The following example mounts an editor in the page, then moves it into a same-origin iframe. Undo history and selection move with it:
import { createDocxEditor, copyEditorStyles } from '@docx-editor.dev/core/editor';
const editor = createDocxEditor({ document: bytes });
editor.attach(document.getElementById('editor')!);
// Later: move the same editor into the iframe.
const slot = frame.contentDocument!.createElement('div');
frame.contentDocument!.body.append(slot);
copyEditorStyles(document, frame.contentDocument!);
editor.attach(slot); // detach() first is optional
// When you are done:
editor.destroy();| Call | Effect |
|---|---|
attach(element, options?) | Mounts the document, or moves the open one into element. |
detach() | Takes the editor out of its element and keeps all state. |
destroy() | Releases the editor. It cannot be attached again. |
Choose a mount mode
| Mode | Use it when | Call | What survives |
|---|---|---|---|
| Inline | The editor renders in your page. | attach(element), or container at creation | Everything, while mounted |
| Not yet mounted | The element does not exist yet, as in the React and Vue adapters. | createDocxEditor() without container, then attach(element) | The document opens on the first attach |
| Detached | The editor leaves one place before it enters another. | detach() | Document, undo, selection, and collaboration |
| Iframe | The editor renders in a same-origin iframe. | attach(element) with an element of the iframe | Everything |
| Pop-out window | The editor renders in its own window. | DocxEditor.Window, DocxEditorWindow, or openEditorWindow() | Everything |
| Without a DOM | A server or job edits with no page. | DocxEditor.createServer() from @docx-editor.dev/editor-api | Not applicable |
A detached editor still saves, runs commands, and receives collaboration edits. It paints again on the next attach. A load while detached replaces the retained document.
Control focus and lifecycle
| Option or event | Behavior |
|---|---|
attach(element, { focus: false }) | Leaves focus where it is. |
attach(element, { focus: true }) | Always focuses the pages. |
attach(element) | Restores focus if the pages had it, or lost it a moment before to a non-text control such as a Pop out button. |
hostChange event | Fires on first attach, on each move, and on detach. Reports document: null while detached. |
invalidTarget error | The target element has no window, or its window closed. The editor stays where it is. |
A move keeps undo history, selection, armed formats, the collaboration session, the reading position, registered font faces, and focus, selection, pointer, scroll, and resize listeners. It closes anything tied to the old window: open menus and popovers, the revision markup dialog, a picture picker, and a pointer drag.
Custom chrome must resolve its document and window from the editor, not from globals. For the host helpers and a listener example, see Pop-out windows and iframes.
Limits
- The target document must have the same origin as your page.
- An iframe or pop-out starts without styles. Call
copyEditorStyles().DocxEditor.Window,DocxEditorWindow, andopenEditorWindow()copy them for you. - A detached editor keeps its document and layout in memory. Call
destroy()to release them. - In Vue, move the editor by remounting the content, for example with
v-if. ATeleportthat only changestoleaves an open popover or menu bound to the old window until it closes.