@eigenpal/docx-editor-react

React adapter: <DocxEditor>, hooks, dialogs, toolbar, plugin host. Works with Next.js, Vite, Remix, Astro.

npmv1.5.0 downloads30.9k/molicenseApache-2.0sourcegithub

Install

npm install @eigenpal/docx-editor-react

Pulls in @eigenpal/docx-editor-core and @eigenpal/docx-editor-i18n. Add @eigenpal/docx-editor-agents if you need the agent toolkit.

Quickstart

import { DocxEditor } from '@eigenpal/docx-editor-react';
import '@eigenpal/docx-editor-react/styles.css';

export default function App() {
  return <DocxEditor documentBuffer={null} />;
}

On Next.js App Router, render this inside a "use client" component. ProseMirror touches the DOM at mount, so there's nothing to SSR. The Next.js DOCX editor guide walks through file uploads, saving to an API route, and the common errors.

Subpaths

@eigenpal/docx-editor-react: <DocxEditor>, DocxEditorRef, DocxEditorProps, EditorMode, createEmptyDocument (re-exported from -core in 1.0.1)
@eigenpal/docx-editor-react/ui: Toolbar, EditorToolbar, ResponsiveToolbar, TableToolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator, ColorPicker, font/color pickers
@eigenpal/docx-editor-react/hooks: useHistory, useFindReplace, useAutoSave, useClipboard, useTableSelection, useWheelZoom, useDragAutoScroll
@eigenpal/docx-editor-react/dialogs: hyperlink, find/replace, paste special, page setup, keyboard shortcuts
@eigenpal/docx-editor-react/plugin-api: PluginHost, plugin registration types
@eigenpal/docx-editor-react/styles: CSS

Every export is in the API reference.

Loading a document

documentBuffer accepts the DocxInput union: File, Blob, ArrayBuffer, or Uint8Array. Pass a File from an <input type="file" accept=".docx"> directly, or a fetched buffer. null mounts an empty document; undefined defers mount until the input arrives. Full patterns (URL, file input, saving) are in Loading and saving.

Ref methods

DocxEditorRef exposes imperative methods through forwardRef:

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

const editorRef = useRef<DocxEditorRef>(null);

editorRef.current?.addComment({ paraId: 'ABC12300', text: 'Tighten this.', author: 'Jess Lin' });
editorRef.current?.scrollToParaId('DEF45600');

paraId is Word's w14:paraId attribute. It survives concurrent edits and round-trips through OOXML, which is why we use it instead of positional addressing. Every method signature is in the API reference.

The ref also reaches block-level content controls in the live document: getContentControls lists them (filtered by tag, alias, id, or type), scrollToContentControl brings one into view, and setContentControlContent / setContentControlValue / removeContentControl edit one by tag as normal undoable edits. Locked controls are refused unless forced. The Vue adapter pairs the same methods.

@eigenpal/docx-editor-react/ui exports the toolbar pieces. EditorToolbar is the full toolbar used by the default editor UI; Toolbar is the formatting-button strip on its own; ResponsiveToolbar wraps either with adaptive layout. Compose your own from ToolbarButton, ToolbarGroup, and ToolbarSeparator:

import { DocxEditor } from '@eigenpal/docx-editor-react';
import {
  EditorToolbar,
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
} from '@eigenpal/docx-editor-react/ui';

In 0.x the formatting buttons were called FormattingBar and the composite was Toolbar. We renamed: the formatting buttons are now Toolbar, the composite is EditorToolbar. See migration for the rename table.

Agent integration

Wire AI tools to a live editor with @eigenpal/docx-editor-agents/react:

import { DocxEditor } from '@eigenpal/docx-editor-react';
import { useDocxAgentTools } from '@eigenpal/docx-editor-agents/react';

Full client + server wiring is on Agents → Live editor.