Props

DocxEditor is the single component the React entry exports. This page lists its props and the handle behind its ref; the guides linked from each row carry the longer explanation.

Props

Prop	Type	Default	What it does
`document`	`ArrayBuffer \| Uint8Array \| Blob`	required	The document to open. Bytes open immediately; a `Blob` or `File` is read first, and whichever document arrived last is the one opened.
`mode`	`DocxEditorMode`	`{ kind: "edit" }`	What the editor is for. See Mode.
`renderImportError`	`(error: DocxImportError) => ReactNode`	built-in panel	What to render in place of the editor when the document was refused.
`showPageGuides`	`boolean`	`true`	Whether to draw approximate page boundaries over the document's paper. Drawn in read-only mode too.
`zoom`	`DocxEditorZoom`	uncontrolled	The visual scale, when the host owns the selection.
`defaultZoom`	`DocxEditorZoom`	`"fit-width"`	The initial scale when the editor owns the selection.
`onZoomChange`	`(zoom: DocxEditorZoom) => void`	—	Receives toolbar requests. A controlled host must update `zoom` for one to take effect.
`fontFallbacks`	`FontFallbacks`	`DEFAULT_FONT_FALLBACKS`	The fonts drawn in place of names missing from the reader's machine. See Styling.
`presets`	`DocxEditorPresets`	package defaults	The lists the built-in pickers offer. See Custom controls.
`commentAuthor`	`CommentAuthor`	`{ name: "Anonymous" }`	The identity written by the built-in comment and reply composers.
`plugins`	`readonly Plugin[]`	—	ProseMirror plugins placed ahead of the built-in ones, so a host keymap sees an event first.
`className`	`string`	—	Added to the editor's outer frame alongside its own class.
`style`	`CSSProperties`	—	Applied to that same frame.
`onReady`	`(view: EditorView) => void`	—	Called with the view once the editor has mounted a document.
`onChange`	`() => void`	—	Called on every editor state change, which includes cursor and selection moves.

DocxEditorProps, DocxEditorMode, DocxEditorZoom, DocxEditorPresets, CommentAuthor, and DocxSource are all exported from the root entry, so a wrapper component can name them without restating their shapes.

Mode

mode is a union rather than a set of independent booleans, because a read-only editor accepts no edits and therefore has no toolbar and no context menus to offer.

type DocxEditorMode =
  | { kind: "readOnly" }
  | {
      kind: "edit";
      toolbar?: boolean;
      contextMenus?: boolean;
      locking?: boolean;
    };

toolbar and contextMenus both default to true. contextMenus: false leaves the right button to the browser, which is what a host drawing menus of its own wants. locking defaults to false and adds the controls for settling part of a document; a lock the document already carries is honored in every mode. See Locked content for the commands behind it.

The handle

interface DocxEditorHandle {
  view: EditorView;
  exportBytes: () => Uint8Array;
}

The ref holds null until a document has been opened, and holds null again for a document that was refused, so a control that exports should read it at click time rather than caching it. exportBytes writes the state currently on screen and throws DocxExportError when it cannot do so safely. Getting started covers downloadDocx, which wraps the handle for the ordinary browser download.

Props read once

Most props take effect on the render that changes them. Four are read when the editor mounts, because they go into the ProseMirror state and the view built around it:

plugins
fontFallbacks
defaultZoom
mode.contextMenus

Building any of them inline on every render is therefore harmless. To change one, change the component's key and let it remount, which is also how the component asks for a document to be swapped.

Props

Props

Mode

The handle

Props read once

On this page