Props

DocxEditor is the single component the React entry exports.

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. The document that arrived last is the one opened.
`mode`	`DocxEditorMode`	required	What the editor is for, and whose comments it writes. 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, in every mode.
`zoom`	`DocxEditorZoom`	uncontrolled	The visual scale, when the host owns it.
`defaultZoom`	`DocxEditorZoom`	`"fit-width"`	The initial scale when the editor owns it.
`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 Presets.
`plugins`	`readonly Plugin[]`	-	ProseMirror plugins placed ahead of the built-in ones.
`contextMenus`	`boolean`	`true`	Whether the right click opens the editor's own menus; `false` leaves it to the browser.
`className`	`string`	-	Added to the editor's outer frame.
`style`	`CSSProperties`	-	Applied to that frame.
`onReady`	`(view: EditorView) => void`	-	Called with the view once a document is mounted.
`onChange`	`() => void`	-	Called on every state change, cursor and selection moves included.
`onEditRefused`	`(refusal: EditRefusal) => void`	-	Called when the editor turns down an edit in the document body, such as typing into locked content. See When an edit is refused.

DocxEditorProps, DocxEditorMode, DocxEditorZoom, DocxEditorPresets, CommentAuthor, EditableComments, DocxSource, EditRefusal, and the types it is made of are exported from the root entry.

Mode

type DocxEditorMode =
  | { kind: "readOnly" }
  | {
      kind: "comment";
      author: CommentAuthor;
      editableComments?: EditableComments;
    }
  | {
      kind: "edit";
      author: CommentAuthor;
      editableComments?: EditableComments;
      toolbar?: boolean;
      locking?: boolean;
    };

interface CommentAuthor {
  id: string;
  name: string;
  initials?: string;
}

type EditableComments = "own" | "all";

Modes describes what each kind lets a reader do, and Modes and locks how a control of your own reads it.

author is the identity the built-in composers write: id is an opaque string of your choosing, such as your user id, recorded in the document beside name; initials is optional. Give each id a distinct name within the document. A reused name resolves to no identity, so the default editableComments: "own" leaves those comments editable by everyone, and a file written under a name another identity already holds is refused by server verification as comment-author-forged.

editableComments is whose comments the panel offers to edit or delete: "own" (the default) is a comment carrying this id or no identity, "all" is every comment. toolbar defaults to true; locking defaults to false and adds the controls for locking part of a document.

The kind, author, and editableComments may change on an open document; the editor switches in place and keeps the view, its history, and the plugins.

The handle

interface DocxEditorHandle {
  view: EditorView;
  exportBytes: () => Uint8Array;
  exportProblems: () => readonly ExportProblem[];
}

The ref holds null until a document has been opened, and again for a refused document, so read it at click time. exportBytes throws DocxExportError when it cannot write safely; exportProblems reports every reason it would, each under the same code and with the reason and pos naming the content to put back (Checking before export). A thrown DocxExportError carries the entry it was raised for as problem. Getting started covers downloadDocx, which wraps the handle for a browser download.

Props read once

plugins, fontFallbacks, defaultZoom, and contextMenus are read when the editor mounts; later changes are ignored, so building them inline is harmless. To change one, or to swap the document, change the component's key and let it remount. Every other prop, mode included, takes effect on the render that changes it.

Props

Props

Mode

The handle

Props read once

On this page