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();
CallEffect
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

ModeUse it whenCallWhat survives
InlineThe editor renders in your page.attach(element), or container at creationEverything, while mounted
Not yet mountedThe 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
DetachedThe editor leaves one place before it enters another.detach()Document, undo, selection, and collaboration
IframeThe editor renders in a same-origin iframe.attach(element) with an element of the iframeEverything
Pop-out windowThe editor renders in its own window.DocxEditor.Window, DocxEditorWindow, or openEditorWindow()Everything
Without a DOMA server or job edits with no page.DocxEditor.createServer() from @docx-editor.dev/editor-apiNot 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 eventBehavior
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 eventFires on first attach, on each move, and on detach. Reports document: null while detached.
invalidTarget errorThe 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, and openEditorWindow() 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. A Teleport that only changes to leaves an open popover or menu bound to the old window until it closes.

See also