Props

<DocxEditor> provides a packaged host for the provider primitives. This page groups its props by task. For all signatures, see the React API reference.

Document and mount state

Use document for the document source. Use fonts to supply font metrics for measurement.

The editor colors tracked changes by author. Changing author preserves the editor instance and all existing revisions. Mount <DocxEditor.AuthorStyle /> to override one author's style. Mount <DocxEditor.ColorByChangeType /> to color changes by type. These settings do not have equivalent props. For details, see Tracked changes.

This example loads DOCX bytes in editing mode:

const response = await fetch('/template.docx');
const bytes = new Uint8Array(await response.arrayBuffer());

<DocxEditor document={bytes} mode="edit" />;

For regional date input, pass locale="en-GB" for day/month input or locale="pl-PL" for Polish dates such as 01.02.2030. The same prop works on DocxEditor.Root. It preserves dates already in the document. Use i18n separately to customize UI strings; see date input behavior for details.

Modules

The modules prop registers capability modules during construction. @docx-editor.dev/pro uses modules for tracked changes, comments, and custom nodes.

The editor reads modules only during construction. A later array change has no effect. To change modules, remount the editor with a different React key:

import { DocxEditor } from '@docx-editor.dev/react';
import { reviewModule } from '@docx-editor.dev/pro/react';

const MODULES = [reviewModule()];

<DocxEditor key={moduleSet} document={bytes} modules={MODULES} author="Jess Lin" />;

Without a module, the editor preserves revisions and comments during save. It renders their final document state. Register the review module to show and manage them. For details, see the Pro package documentation.

Chrome and layout

These props control the packaged frame around the document.

Dark mode

colorMode changes the editor chrome and applies a display transform to the document canvas. The setting does not change authored document colors or saved output. Printing uses a light page regardless of this setting.

This example controls the editor color mode:

const [colorMode, setColorMode] = useState<'light' | 'dark'>('light');

<button onClick={() => setColorMode((m) => (m === 'dark' ? 'light' : 'dark'))}>
  Toggle theme
</button>
<DocxEditor document={bytes} colorMode={colorMode} />

For theme behavior, see the Dark mode guide.

Fonts

fonts supplies font bytes for text measurement. Matching metrics produce line wraps and page breaks that match Word more closely. The editor loads supported embedded fonts without extra configuration. The font picker combines declared document fonts with configured fonts. Use useFontFamily() to read that list.

Use packagedFonts() for the Word default substitutes. The editor calls it once per load with the families that document declares. It loads a family when the document names it, or when that family is the document's default face, so a document pays for what it declares instead of all 20 eager faces. Nothing is fetched from a third party.

The default face counts because a run that names no font still has to be measured in one. That face is Calibri, so Carlito loads for every document.

Wrap it in useFonts to keep one resolver identity:

import { DocxEditor, useFonts } from '@docx-editor.dev/react';
import { packagedFonts } from '@docx-editor.dev/fonts';

function Editor({ bytes }: { bytes: Uint8Array }) {
  const fonts = useFonts(packagedFonts());
  return <DocxEditor document={bytes} fonts={fonts} onFontError={(error) => report(error.code)} />;
}

Add an origin by adding an argument. Arguments compose first-wins:

import { googleFonts } from '@docx-editor.dev/fonts/google';

const fonts = useFonts(packagedFonts(), googleFonts());

The editor samples fonts at mount. Changing its identity remounts the editor, which is why an inline resolver needs useFonts.

packagedFonts() resolves after the document is parsed, so the first layout uses fixed measurement and the editor re-paginates when the faces arrive. Edits made in between survive that; the undo history behind them does not. For a document that must paginate correctly on the first pass, use defaultFonts() instead. For more information, see Fonts and measurement.

A resolver can make network requests while the editor opens a document. The editor does not fetch external fonts without a configured resolver.

For font sources and loadFonts, see the Fonts and measurement guide.

Title bar customization

Use these props to customize the title bar.

<DocxEditor
  document={bytes}
  title={file.name}
  onTitleChange={(name) => updateMetadata({ name })}
  renderTitleBarRight={() => <SaveIndicator dirty={dirty} />}
/>

Callbacks

Use callbacks to connect the editor to your application.

<DocxEditor
  document={bytes}
  onReady={(editor) => console.log(editor.snapshot())}
  onChange={(change) => reportRevision(change.revision)}
  onSave={() => void persist()}
  onOpen={() => void openPicker()}
  onFontError={(err) => reportError(err)}
/>

Ref methods

Use DocxEditorRef to load, save, focus, or access the Editor facade. <DocxEditor> exposes this handle through forwardRef.

This example saves and accesses the editor:

import { useRef } from 'react';
import { DocxEditor, type DocxEditorRef } from '@docx-editor.dev/react';

const editorRef = useRef<DocxEditorRef>(null);

const buffer = await editorRef.current?.save();
const editor = editorRef.current?.getEditor();
editorRef.current?.focus();

The ref has seven methods:

For exact signatures, see the React API reference.

Next steps

• React package overview
• React examples
• React API reference