Props — docx-editor Docs | DOCX Editor for React and Vue

<DocxEditor> is configured through props. Groups below match how you'd reach for them in practice. The full generated reference (every prop, every type signature) is at /docs/1.x/api/react.

Document input

How the editor receives the document. Use documentBuffer for raw bytes; use document when you've already parsed.

Prop	Type	Description
`documentBuffer`	`DocxInput \| null`	`ArrayBuffer`, `Uint8Array`, `Blob`, or `File`. Most common entry. `null` mounts an empty document.
`document`	`Document \| null`	Pre-parsed `-core` document tree. Skip the parser if you already have one.

// From a fetch
const buf = await fetch("/template.docx").then((r) => r.arrayBuffer());
<DocxEditor documentBuffer={buf} />;
 
// From a file input
<input type="file" accept=".docx" onChange={(e) => setBuf(e.target.files?.[0] ?? null)} />
<DocxEditor documentBuffer={buf} />
 
// Empty document (mounts with no content; useful when collecting input from scratch)
<DocxEditor documentBuffer={null} />

Mode and read-only

Editing mode and the suggest/view/read-only states. Pair with onModeChange for controlled mode.

Prop	Type	Default	Description
`mode`	`EditorMode`	`"editing"`	`"editing"` \| `"suggesting"` \| `"viewing"`. For read-only, use the `readOnly` boolean below.
`onModeChange`	`(mode) => void`		Controlled mode handler. Without it, the editor manages mode internally.
`readOnly`	`boolean`	`false`	Independent of `mode`. Disables every input affordance (typing, toolbar buttons, dialogs) regardless of which mode is active.

const [mode, setMode] = useState<EditorMode>("editing");
 
<DocxEditor
  documentBuffer={buf}
  mode={mode}
  onModeChange={setMode}
/>;

"suggesting" wraps every edit as a tracked change. Use it for review flows.

Comments and collaboration

Pull author identity in, push comment state back out.

Prop	Type	Description
`author`	`string`	Author name attached to new comments and tracked changes.
`comments`	`Comment[]`	Controlled comments. Pair with `onCommentsChange`.
`onCommentsChange`	`(comments) => void`	Fires on any comment mutation. Mirror into Y.Array for live sync.
`onCommentAdd` / `onCommentResolve` / `onCommentDelete` / `onCommentReply`	callbacks	Granular events when you want to log or trigger side effects, not own state.

const [comments, setComments] = useState<Comment[]>([]);
 
<DocxEditor
  documentBuffer={buf}
  author="Jess Lin"
  comments={comments}
  onCommentsChange={setComments}
/>;

For Yjs-backed sync, see Realtime collaboration.

Toggle the built-in UI on or off.

Prop	Type	Default	Description
`showToolbar`	`boolean`	`true`	Toolbar visibility. Pass `false` and compose your own from `/ui`.
`showZoomControl`	`boolean`	`true`	Bottom-right zoom widget.
`showRuler`	`boolean`	`false`	Page ruler above the document body.
`rulerUnit`	`"inch" \| "cm"`	`"inch"`	Ruler unit.
`showMarginGuides`	`boolean`	`false`	Faint guides at page margins.
`marginGuideColor`	`string`	`"#c0c0c0"`	CSS color for the guides above.
`showOutline`	`boolean`	`false`	Document outline / table of contents drawer.
`showOutlineButton`	`boolean`	`true`	Outline toggle button in the toolbar.
`initialZoom`	`number`	`1.0`	Starting zoom (`1.0` = 100%).
`fontFamilies`	`ReadonlyArray<string \| FontOption>`	.	Constrain the font picker to a specific list.

// Headless-feeling editor: drop chrome and compose your own.
<DocxEditor documentBuffer={buf} showToolbar={false} showZoomControl={false} />

Title bar customization

The header strip is fully overridable.

Prop	Type	Description
`documentName`	`string`	Display name in the title bar.
`onDocumentNameChange`	`(name) => void`	Fires when the user edits the title in-place.
`documentNameEditable`	`boolean`	Default `true`. Set `false` to lock the title.
`renderLogo`	`() => ReactNode`	Left-side logo slot. Default renders the document icon.
`renderTitleBarRight`	`() => ReactNode`	Right-side slot. Wire your save status, share button, avatars.
`toolbarExtra`	`ReactNode`	Extra items appended to the toolbar.

<DocxEditor
  documentBuffer={buf}
  documentName={file.name}
  onDocumentNameChange={(name) => updateMetadata({ name })}
  renderTitleBarRight={() => <SaveIndicator dirty={dirty} />}
/>;

Callbacks

Lifecycle and integration hooks.

Prop	Type	Description
`onChange`	`(doc: Document) => void`	Fires on every document mutation. Throttle for autosave.
`onSave`	`(buf: ArrayBuffer) => void`	Fires when the user invokes Save (Cmd+S or toolbar).
`onSelectionChange`	`(state: SelectionState \| null) => void`	Selection metadata for custom UI (active marks, paragraph style, etc.).
`onError`	`(error: Error) => void`	Errors during parse or render. Send to your error tracker.
`onFontsLoaded`	`() => void`	Fired once the font set is ready. Use to defer measurement-sensitive UI.
`onPrint` / `onCopy` / `onCut` / `onPaste`	`() => void`	Notification hooks for clipboard and print events.

<DocxEditor
  documentBuffer={buf}
  onChange={(doc) => debouncedAutosave(doc)}
  onSave={async (buf) => {
    await fetch("/api/documents/1", { method: "PUT", body: buf });
  }}
  onError={(err) => reportError(err)}
/>;

Styling

Prop	Type	Description
`theme`	`Theme \| null`	Color and density token overrides.
`className`	`string`	Applied to the editor root element.
`style`	`CSSProperties`	Inline styles on the root.
`placeholder`	`ReactNode`	Rendered while there's no document content.
`loadingIndicator`	`ReactNode`	Rendered while the buffer is being parsed.
`printOptions`	`PrintOptions`	Margins, header/footer toggles for the print pipeline.

<DocxEditor
  documentBuffer={buf}
  className="rounded-lg shadow-md"
  loadingIndicator={<Spinner label="Loading document" />}
  placeholder={<EmptyState />}
/>;

i18n

Prop	Type	Description
`i18n`	`LocaleStrings \| PartialLocaleStrings`	Locale data from `@eigenpal/docx-editor-i18n`. See i18n page.

import pl from "@eigenpal/docx-editor-i18n/pl";
 
<DocxEditor documentBuffer={buf} i18n={pl} />;

Agents

Prop	Type	Description
`agentPanel`	`AgentPanelOptions`	Wires a side panel slot. Pair with `useDocxAgentTools`.

<DocxEditor
  ref={editorRef}
  documentBuffer={buf}
  agentPanel={{ render: () => <AgentChatLog messages={messages} /> }}
/>;

Full setup in Agents → Live editor.

Plugins

Prop	Type	Description
`externalPlugins`	`Plugin[]`	ProseMirror plugins appended to the editor's plugin list.
`pluginOverlays`	`ReactNode`	Absolutely-positioned overlay slot for plugin UI.
`pluginSidebarItems`	`ReactSidebarItem[]`	Sidebar entries contributed by plugins.
`pluginRenderedDomContext`	`RenderedDomContext \| null`	Hand-off when you need plugin code to read editor DOM measurements.

See Plugins for the full plugin contract.

Ref methods

Imperative API exposed through forwardRef. Capture a DocxEditorRef and call methods directly when you need to drive the editor from outside React state.

import { useRef } from "react";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-react";
 
const ref = useRef<DocxEditorRef>(null);
 
ref.current?.addComment({ paraId: "ABC12300", text: "Tighten this paragraph." });
ref.current?.scrollToParaId("DEF45600");
ref.current?.save(); // → ArrayBuffer

Common methods:

Method	Returns	What it does
`save()`	`Promise<ArrayBuffer>`	Serialize the current document to a `.docx` buffer.
`addComment({ paraId, text })`	`Comment`	Add a comment anchored to a paragraph by `w14:paraId`.
`proposeChange({ paraId, ... })`	`void`	Insert a tracked change.
`findInDocument(query)`	`FindMatch[]`	Search the document.
`scrollToParaId(paraId)`	`boolean`	Scroll to a paragraph by `w14:paraId`. Returns false if not found.
`scrollToPosition(pos)`	`void`	Scroll to a raw ProseMirror position.
`getDocument()`	`Document`	Snapshot of the parsed tree.

The full method list with signatures is at /docs/1.x/api/react.