API Referencev1.0.2
@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`.
Functions(3)
fn
packages/react/src/i18n/LocaleContext.tsx:14LocaleProvider
declare function LocaleProvider(input: LocaleProviderProps): react_jsx_runtime.JSX.Element;fn
packages/react/src/index.ts:27renderAsync
Render a DOCX editor into a container element.
declare function renderAsync(input: DocxInput, container: HTMLElement, options?: RenderAsyncOptions): Promise<DocxEditorHandle>;fn
packages/react/src/i18n/LocaleContext.tsx:27useTranslation
declare function useTranslation(): {
t: TFunction;
};Interfaces(4)
interface
packages/react/src/renderAsync.ts:41DocxEditorHandle
React-specific handle that extends the framework-agnostic EditorHandle with zoom control.
interface DocxEditorHandle extends EditorHandle| Member | Type | Summary |
|---|---|---|
| scrollToParaId | (paraId: string) => 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%). |
interface
packages/react/src/components/DocxEditor.tsx:97DocxEditorProps
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 |
| 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`. |
| 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. |
| 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). |
| 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 |
| 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') |
| 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 | Theme for styling |
| toolbarExtra? | ReactNode | Custom toolbar actions |
interface
packages/react/src/components/DocxEditor.tsx:268DocxEditorRef
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. |
| 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 |
| 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. |
| 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. |
| 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) => boolean | Scroll the paginated view to the paragraph with the given Word `w14:paraId`. |
| 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. |
| 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 |
interface
packages/react/src/i18n/LocaleContext.tsx:9LocaleProviderProps
interface LocaleProviderProps| Member | Type | Summary |
|---|---|---|
| children | ReactNode | |
| i18n? | Translations |
Type aliases(2)
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';type
packages/react/src/renderAsync.ts:35RenderAsyncOptions
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)
const
packages/react/src/components/DocxEditor.tsx:449DocxEditor
DocxEditor - Complete DOCX editor component
DocxEditor: React.ForwardRefExoticComponent<DocxEditorProps & React.RefAttributes<DocxEditorRef>>const
packages/react/src/index.ts:18VERSION
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"