@eigenpal/docx-editor-react
v1.8.3 · 6 published subpaths with full TypeScript signatures and JSDoc.
Subpaths
@eigenpal/docx-editor-react/ui
UI entry point — Toolbar, pickers, dialogs, and UI components.
@eigenpal/docx-editor-react/dialogs
Modal dialogs for hyperlinks, find/replace, paste-special, page setup, and keyboard shortcuts. Pair with the hooks under `@eigenpal/docx-editor-react/hooks` when wiring custom UI.
@eigenpal/docx-editor-react/hooks
React hooks for editor history, table selection, find/replace, autosave, clipboard, and zoom. Use alongside the main `DocxEditor` component.
@eigenpal/docx-editor-react/plugin-api
Generic plugin interface and host component for integrating external plugins with the editor. Pairs with the framework-agnostic plugin types exported from `@eigenpal/docx-editor-core/plugin-api`.
@eigenpal/docx-editor-react/styles
CSS import entry. Bring in the editor's base styles by importing `@eigenpal/docx-editor-react/styles.css` directly; this module exists for tooling that prefers a JS-style import.
Package root
Framework-agnostic document utilities live in @eigenpal/docx-editor-core. Agent/MCP surfaces live in @eigenpal/docx-editor-agents.
Functions (3)
LocaleProviderfunctionSource ↗
declare function LocaleProvider(input: LocaleProviderProps): React.JSX.Element;renderAsyncfunctionSource ↗
Render a DOCX editor into a container element.
declare function renderAsync(input: DocxInput, container: HTMLElement, options?: RenderAsyncOptions): Promise<DocxEditorHandle>;useTranslationfunctionSource ↗
declare function useTranslation(): {
t: TFunction;
};Interfaces (4)
DocxEditorHandleinterfaceSource ↗
React-specific handle that extends the framework-agnostic EditorHandle with zoom control.
interface DocxEditorHandle extends EditorHandle| Member | Type | Summary |
|---|---|---|
| scrollToParaId | (paraId: string, options?: ScrollToParaIdOptions) => boolean | Scroll to a body paragraph by Word `w14:paraId`. |
| scrollToPosition | (pmPos: number) => void | Scroll to a raw ProseMirror document position. |
| setZoom | (zoom: number) => void | Set zoom level (1.0 = 100%). |
DocxEditorPropsinterfaceSource ↗
DocxEditor props
interface DocxEditorProps| Member | Type | Summary |
|---|---|---|
| agentPanel? | AgentPanelOptions | Mount a controllable agent panel on the right side of the editor. The panel is the chrome (header, close button, drag-resize); the consumer supplies whatever content goes inside via `render` — typically a chat UI from `@ai-sdk/react`'s `useChat`, `assistant-ui`, or any other framework. We do not ship message bubbles, a composer, or a chat engine. |
| author? | string | Author name used for comments and track changes |
| className? | string | Additional CSS class name |
| colorMode? | 'light' | 'dark' | 'system' | Color theme mode for UI styling. `'system'` follows the OS preference. |
| comments? | Comment[] | Controlled comments array. When provided, the editor reads comment thread metadata (text, author, replies, resolved status) from this prop instead of internal state, and emits every change through `onCommentsChange`. |
| commentsSidebarOpen? | boolean | Controlled comments-sidebar visibility; source of truth when set. Pair with `onCommentsSidebarOpenChange`; omit for the default self-managed behavior. |
| disableFindReplaceShortcuts? | boolean | When true, the editor does not intercept Cmd/Ctrl+F or Cmd/Ctrl+H. This lets the browser or host app handle native find/history shortcuts. |
| document? | Document | null | Pre-parsed document (alternative to documentBuffer) |
| documentBuffer? | DocxInput | null | Document data — ArrayBuffer, Uint8Array, Blob, or File |
| documentName? | string | Document name shown in the title bar |
| documentNameEditable? | boolean | Whether the document name is editable (default: true) |
| externalContent? | boolean | When true, the editor treats the `document` prop as a schema seed only and does not load it into ProseMirror on mount. Content is expected to come from external sources — typically `externalPlugins` such as `ySyncPlugin` from `y-prosemirror`, but also any code that dispatches transactions directly. |
| externalPlugins? | prosemirror_state.Plugin[] | External ProseMirror plugins (from PluginHost) |
| fontFamilies? | ReadonlyArray<string | FontOption> | Custom list of fonts shown in the toolbar's font-family dropdown. Strings render in the "Other" group; pass `FontOption[]` for category grouping and CSS fallback chains. Omit to use the built-in 12-font default. An empty array renders an empty (but enabled) dropdown. |
| fonts? | ReadonlyArray<FontDefinition> | Custom font faces to register with the browser before the editor measures text. Each entry injects an `@font-face` rule. Pass a URL (woff2/woff/ ttf/otf), an ArrayBuffer, or omit `src` to load by name from Google Fonts. Multiple entries can share `family` to register different weights/styles. |
| i18n? | Translations | Translation overrides. Import a locale JSON file and pass it directly. |
| initialZoom? | number | Initial zoom level (default: 1.0) |
| loadingIndicator? | ReactNode | Loading indicator |
| marginGuideColor? | string | Color for margin guides (default: '#c0c0c0') |
| mode? | EditorMode | Editor mode: 'editing' (direct edits), 'suggesting' (track changes), or 'viewing' (read-only). Default: 'editing' |
| onChange? | (document: Document) => void | Callback when document changes |
| onCommentAdd? | (comment: Comment) => void | Callback when a comment is added via the UI |
| onCommentDelete? | (comment: Comment) => void | Callback when a comment is deleted via the UI |
| onCommentReply? | (reply: Comment, parent: Comment) => void | Callback when a reply is added to a comment via the UI |
| onCommentResolve? | (comment: Comment) => void | Callback when a comment is resolved via the UI |
| onCommentsChange? | (comments: Comment[]) => void | Fires whenever the comments array changes (controlled mode). |
| onCommentsSidebarOpenChange? | (open: boolean) => void | Fires with the next open state whenever the editor wants to show or hide the comments sidebar. Fires in both controlled and uncontrolled modes. |
| onCopy? | () => void | Callback when content is copied |
| onCut? | () => void | Callback when content is cut |
| onDocumentNameChange? | (name: string) => void | Callback when document name changes |
| onEditorViewReady? | (view: prosemirror_view.EditorView) => void | Callback when editor view is ready (for PluginHost) |
| onError? | (error: Error) => void | Callback on error |
| onFontsLoaded? | () => void | Callback when fonts are loaded |
| onModeChange? | (mode: EditorMode) => void | Callback when the editing mode changes |
| onOpen? | (file: File) => void | Promise<void> | Callback when a DOCX file is selected through `File > Open` or Cmd/Ctrl+O. Pass it to route the picked file through your own import pipeline. Omit it to keep the built-in local document load behavior. |
| onPaste? | () => void | Callback when content is pasted |
| onPrint? | () => void | Callback when print is triggered. Pass it to enable the `File > Print` menu entry; omit to hide. The imperative `ref.current.print()` also invokes this callback. |
| onRenderedDomContextReady? | (context: RenderedDomContext) => void | Callback when rendered DOM context is ready (for plugin overlays). Used by PluginHost to get access to the rendered page DOM for positioning. |
| onSave? | (buffer: ArrayBuffer) => void | Callback when document is saved |
| onSelectionChange? | (state: SelectionState | null) => void | Callback when selection changes |
| placeholder? | ReactNode | Placeholder when no document |
| pluginOverlays? | ReactNode | Plugin overlays to render inside the editor viewport. Passed from PluginHost to render plugin-specific overlays. |
| pluginRenderedDomContext? | RenderedDomContext | null | Rendered DOM context from PluginHost (for sidebar position resolution). |
| pluginSidebarItems? | ReactSidebarItem[] | Sidebar items from plugins (passed from PluginHost). |
| printOptions? | PrintOptions | Print options for print preview |
| readOnly? | boolean | Whether the editor is read-only. When true, hides toolbar and rulers |
| renderLogo? | () => ReactNode | Custom logo/icon for the title bar |
| renderTitleBarRight? | () => ReactNode | Custom right-side actions for the title bar |
| rulerUnit? | 'inch' | 'cm' | Unit for ruler display (default: 'inch') |
| showFileOpen? | boolean | Whether to show `File > Open` and enable Cmd/Ctrl+O (default: true). Set false when you provide your own open action elsewhere. |
| showHelpMenu? | boolean | Whether to show the Help menu in the menu bar (default: true) |
| showMarginGuides? | boolean | Whether to show page margin guides/boundaries (default: false) |
| showOutline? | boolean | Whether to show the document outline sidebar (default: false) |
| showOutlineButton? | boolean | Whether to show the floating outline toggle button (default: true) |
| showRuler? | boolean | Whether to show horizontal ruler (default: false) |
| showToolbar? | boolean | Whether to show toolbar (default: true) |
| showZoomControl? | boolean | Whether to show zoom control (default: true) |
| style? | CSSProperties | Additional inline styles |
| theme? | Theme | null | Document theme schema object |
| toolbarExtra? | ReactNode | Custom toolbar actions |
| watermarkPresets? | readonly string[] | Text-watermark presets shown in the watermark dialog's preset dropdown. Omit to use the built-in MS Word phrases (`DEFAULT_WATERMARK_PRESETS`: CONFIDENTIAL, DRAFT, DO NOT COPY, SAMPLE, URGENT, ASAP). Pass an empty array to hide the preset dropdown and require custom text. |
DocxEditorRefinterfaceSource ↗
DocxEditor ref interface
interface DocxEditorRef| Member | Type | Summary |
|---|---|---|
| addComment | (options: {
paraId: string;
text: string;
author: string;
search?: string;
}) => number | null | Add a comment programmatically. Anchored by Word `w14:paraId` so it survives unrelated edits. Returns the comment ID, or null if the paraId is unknown or the search text isn't found / is ambiguous. |
| applyFormatting | (options: {
paraId: string;
search?: string;
marks: {
bold?: boolean;
italic?: boolean;
underline?: boolean | {
style?: string;
};
strike?: boolean;
color?: {
rgb?: string;
themeColor?: string;
};
highlight?: string;
fontSize?: number;
fontFamily?: {
ascii?: string;
hAnsi?: string;
};
};
}) => boolean | Apply character formatting (bold / italic / color / size / font / etc.) to a paragraph or to a unique phrase within it. This is a direct edit, not a tracked change. Returns false on missing paraId or ambiguous search. |
| findInDocument | (query: string, options?: {
caseSensitive?: boolean;
limit?: number;
}) => Array<{
paraId: string;
match: string;
before: string;
after: string;
}> | Locate every paragraph containing `query` (case-insensitive substring). Returns a stable handle (paraId + the matched phrase) the agent can pass back to `addComment` / `proposeChange`. |
| focus | () => void | Focus the editor |
| getAgent | () => DocumentAgent | null | Get the DocumentAgent for programmatic access |
| getComments | () => Comment[] | Get all comments. |
| getContentControls | (filter?: ContentControlFilter) => PMContentControl[] | List block-level content controls (SDTs) in the live document, optionally filtered by `tag`/`alias`/`id`/`type`. Each result includes the control's text and PM position. Anchors for templates and document automation. |
| getCurrentPage | () => number | Get current page number |
| getDocument | () => Document | null | Get the current document |
| getEditorRef | () => PagedEditorRef | null | Get the editor ref |
| getPageContent | (pageNumber: number) => {
pageNumber: number;
text: string;
paragraphs: Array<{
paraId: string;
text: string;
styleId?: string;
}>;
} | null | Read the contents of a single page. 1-indexed; returns null if the page does not exist. Each paragraph is returned with its stable paraId so the agent can comment on or modify it without an extra round-trip. |
| getSelectionInfo | () => {
paraId: string | null;
selectedText: string;
paragraphText: string;
before: string;
after: string;
} | null | Read the user's current cursor / selection — what's highlighted right now. |
| getTotalPages | () => number | Get total page count |
| getZoom | () => number | Get current zoom level |
| highlightRange | (from: number, to: number) => void | Select the ProseMirror position range `[from, to]` so the selection overlay highlights it, and scroll its start into view. The selection persists until it next changes (there is no auto-clearing flash). No-op for a malformed range or a `from` past the document end; `to` is clamped to the document size. |
| insertBreak | (options: {
paraId: string;
type: 'page' | 'sectionNextPage' | 'sectionContinuous';
}) => boolean | Insert a page or section break after the paragraph identified by `paraId`. `'page'` adds a page break; `'sectionNextPage'` / `'sectionContinuous'` start a new section on a new page / the same page. Direct edit, not a tracked change. Returns false if paraId is unknown. |
| loadDocument | (doc: Document) => void | Load a pre-parsed document programmatically |
| loadDocumentBuffer | (buffer: DocxInput) => Promise<void> | Load a DOCX buffer programmatically (ArrayBuffer, Uint8Array, Blob, or File) |
| onContentChange | (listener: (document: Document) => void) => () => void | Subscribe to document changes. Fires after every committed edit. Returns unsubscribe. |
| onSelectionChange | (listener: (selection: SelectionState | null) => void) => () => void | Subscribe to selection changes (cursor moves / selection changes). Returns unsubscribe. |
| openPrintPreview | () => void | Open print preview |
() => void | Print the document directly | |
| proposeChange | (options: {
paraId: string;
search: string;
replaceWith: string;
author: string;
}) => boolean | Suggest a tracked change. Pass `replaceWith: ''` to delete the matched text; pass `search: ''` to insert at paragraph end. Returns false on missing paraId, missing/ambiguous search, or attempt to layer on an existing tracked change. |
| removeContentControl | (filter: ContentControlFilter, options?: {
force?: boolean;
keepContent?: boolean;
}) => boolean | Remove the first control matching `filter`. With `{ keepContent: true }` the inner blocks are unwrapped in place. Returns false if no match. Throws if the control is deletion-locked unless `{ force: true }`. |
| replyToComment | (commentId: number, text: string, author: string) => number | null | Reply to an existing comment. Returns the reply comment ID. |
| resolveComment | (commentId: number) => void | Resolve (mark as done) a comment. |
| save | (options?: {
selective?: boolean;
}) => Promise<ArrayBuffer | null> | Save the document to buffer. Pass selective: false to force full repack. |
| scrollToChangeId | (revisionId: number) => boolean | Scroll the paginated view to the tracked change with the given Word revision `w:id` and select its range so the selection overlay highlights it. Resolves the id against the live tracked-change marks at call time (matching coalesced revisions the way the changes sidebar does). |
| scrollToCommentId | (commentId: number) => boolean | Scroll the paginated view to the comment with the given id and select its anchored range so the selection overlay highlights it. Resolves the id against the live comment marks at call time. |
| scrollToContentControl | (filter: ContentControlFilter) => boolean | Scroll the first content control matching `filter` into view. Returns false if none. |
| scrollToPage | (pageNumber: number) => void | Scroll the paginated view so the given page is in view. Page numbers are 1-indexed (matches `getCurrentPage` / `getTotalPages`). No-op for out-of-range or non-integer values. |
| scrollToParaId | (paraId: string, options?: ScrollToParaIdOptions) => boolean | Scroll the paginated view to the paragraph with the given Word `w14:paraId`. Pass `options.highlight` to briefly flash it in a custom color. |
| scrollToPosition | (pmPos: number) => void | Scroll the paginated view to a specific ProseMirror document position. Use this when you have a raw PM offset; for Word `w14:paraId` use `scrollToParaId` instead. |
| setContentControlContent | (filter: ContentControlFilter, text: string, options?: {
force?: boolean;
}) => boolean | Replace the content of the first control matching `filter` with `text` (newlines become paragraphs). Returns false if no match. Throws if the control is content-locked unless `{ force: true }`. |
| setContentControlValue | (filter: ContentControlFilter, value: ContentControlValue, options?: {
force?: boolean;
}) => boolean | Set a typed value on the first control matching `filter`: a dropdown selection (`{ kind: 'dropdown', value }`), checkbox (`{ kind: 'checkbox', checked }`), or date (`{ kind: 'date', date }`). Updates the visible content and structured state. Returns false if no match; throws if content-locked (unless `force`) or the value doesn't fit the control type. |
| setParagraphStyle | (options: {
paraId: string;
styleId: string;
}) => boolean | Apply a paragraph style by styleId (e.g. `'Heading1'`, `'Quote'`). Direct edit, not a tracked change. Returns false if paraId is unknown. |
| setZoom | (zoom: number) => void | Set zoom level |
LocaleProviderPropsinterfaceSource ↗
interface LocaleProviderProps| Member | Type | Summary |
|---|---|---|
| children | ReactNode | |
| i18n? | Translations |
Type aliases (2)
EditorModetypeSource ↗
EditorMode union + the catalog the editing-mode dropdown renders. Lives next to DocxEditor.tsx so the dropdown component and the parent forwardRef body share one source of truth.
type EditorMode = 'editing' | 'suggesting' | 'viewing';RenderAsyncOptionstypeSource ↗
Options for [renderAsync](renderAsync). A subset of DocxEditorProps minus documentBuffer / document (passed as the first argument instead).
type RenderAsyncOptions = Omit<DocxEditorProps, 'documentBuffer' | 'document'>;Variables (2)
DocxEditorconstSource ↗
DocxEditor - Complete DOCX editor component
DocxEditor: React.ForwardRefExoticComponent<DocxEditorProps & React.RefAttributes<DocxEditorRef>>VERSIONconstSource ↗
eigenpal/docx-editor-react
Curated root entry for the documented React editor API. Advanced surfaces stay public through explicit subpaths: - @eigenpal/docx-editor-react/ui - @eigenpal/docx-editor-react/dialogs - @eigenpal/docx-editor-react/hooks - @eigenpal/docx-editor-react/plugin-api
Framework-agnostic document utilities live in @eigenpal/docx-editor-core. Agent/MCP surfaces live in @eigenpal/docx-editor-agents.
VERSION = "0.0.2"