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.

Saved field result editing

Set fieldResults to 'editable' to let users edit supported saved field results, such as MERGEFIELD or HYPERLINK text. The same prop works on DocxEditor.Root. Later prop changes have no effect. Remount the editor to change this setting.

Computed fields remain one unit. Collaboration refuses 'editable' with a TypeError. For supported fields and editing rules, see Edit saved field results.

Viewing mode

Set mode="view" to display the document without content edits. Clicks, drags, repeated clicks, and caret keys preserve the selection. The editor hides the caret and uses the arrow pointer over text. Toolbar values remain tied to the preserved selection.

Links, equation previews, and Show/Hide remain available. Search and programmatic selection can still move the selection. Search highlights remain visible without a caret.

Modules

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

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. The drawing renderers from drawingModule() and reviewModule() are different: they serve every editor in the page, and a remount does not remove them. For more information, see Advanced drawing rendering.

This example remounts the editor when the module set changes:

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 ignores colorMode and preserves authored document colors.

This example controls the editor color mode:

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

export function ThemedEditor({ bytes }: { bytes: Uint8Array }) {
  const [colorMode, setColorMode] = useState<'light' | 'dark'>('light');

  return (
    <>
      <button
        type="button"
        onClick={() => setColorMode((mode) => (mode === '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 after parsing and when edits introduce another font family. It loads only requested families and the default font. Nothing is fetched from a third party.

The resolver also requests the configured default font. With the default Calibri configuration, it loads Carlito for text without an explicit font.

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

Each new fonts value replaces the fonts and resolves them again, without a remount. An inline resolver is a new value on every render, which is why it needs useFonts.

packagedFonts() resolves after the document is parsed, so the first layout can use fallback measurement. The editor updates pagination when the fonts arrive. Font arrivals preserve edits, selection, and undo history. 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.

popups

Use definePopup(MyPopup) to customize an automatic popup with your component. Forward its typed props to the default component to retain editor behavior. Render callbacks also work. Set an entry to false to manage its trigger and visibility yourself. For supported popups and defaults, see Customize popups.

Next steps

• React package overview
• React examples
• React API reference

Unsupported-content placeholders

Register DocxEditor.UnsupportedElement components inside DocxEditor or DocxEditor.Root. Customize opaque inline and block content and existing drawing or equation fallbacks. See custom unsupported-content components for framework examples, typed metadata, fallback behavior, and lifecycle details.