@docx-editor.dev/react

v2.1.3 · 1 published subpath with full TypeScript signatures and JSDoc.

Package root

React adapter for the DOCX editor. A thin renderer over the Editor contract from @docx-editor.dev/core: it supplies DOM and paints the engine's positioned display list, and holds no editing-engine state.

Functions (78)

ContextMenuCellVerticalAlignmentfunctionSource ↗

Compact vertical-alignment picker for selected table cells.

declare function ContextMenuCellVerticalAlignment(input: ContextMenuCommandProps): react.JSX.Element | null;

ContextMenuItemfunctionSource ↗

A host-owned context-menu row, styled and behaved like the packaged ones.

The toolbar's Action for the right-click surface: no slot, no command, no engine wiring — enabled state and the action are the host's, because the engine has no opinion about an action it does not model. Selecting it closes the menu.

declare function ContextMenuItem(input: ContextMenuItemProps): react.JSX.Element;

ContextMenuPastefunctionSource ↗

Paste the clipboard's text at the selection.

THE ROW READS THE CLIPBOARD, not the engine. exec is synchronous and clipboard read is not — it prompts in Chrome and is refused outright by Firefox and Safari — so the read happens here, inside the click that asked for it, where the permission gesture belongs, and the text goes to the engine as an argument.

Nothing can know whether the read will succeed BEFORE it is attempted, so the row starts enabled (when the engine would accept a paste at all) and disables itself, with the browser's own reason, once a read has actually been refused. Guessing the answer up front would either grey out a working Paste on Chrome or advertise a dead one on Safari.

declare function ContextMenuPaste(input: ContextMenuCommandProps): react.JSX.Element | null;

DocumentNamefunctionSource ↗

declare function DocumentName(input: DocumentNameProps): react__default.JSX.Element;

DocxEditorContentfunctionSource ↗

The element the engine paints pages into. Must render inside a DocxEditor.Viewport; the facade attaches here and detaches on unmount (stashing the live document bytes, so remounting elsewhere restores the content).

Its centring margin lives in the STYLESHEET, not in an inline style here, and behind :where() so it carries no specificity: a host that places the page itself — inside its own stage, beside its own art — overrides it with a plain class and no !important. An inline style could not be beaten by a class at all, which is exactly the trap that makes a library feel like something to fight.

declare function DocxEditorContent(input: DocxEditorContentProps): react.JSX.Element;

DocxEditorContextMenufunctionSource ↗

The packaged right-click menu over the painted document.

Mounted by default inside DocxEditor.Viewport; contextMenu={false} on DocxEditor removes it. Rendered as a child of the viewport so it finds its own surface, but positioned in client space, so it is never clipped by the scroller.

declare function DocxEditorContextMenu(input: DocxEditorContextMenuProps): react.JSX.Element;

DocxEditorDocumentOutlinefunctionSource ↗

The document outline as a context-fed part (DocxEditor.DocumentOutline): headings from Editor.getOutline(), in document order; clicking one moves the caret to that heading. The panel positions absolutely — give it a position: relative container.

Renders nothing while the editor has no document — a floating panel saying "no headings" about a document that is not there is the same false claim the rulers made.

declare function DocxEditorDocumentOutline(props: DocxEditorDocumentOutlineProps): ReactElement | null;

DocxEditorFontNoticefunctionSource ↗

Word-style font compatibility notice.

Shown when the open document declares font families this platform cannot resolve — not installed, not embedded in the file, not supplied by the app's font configuration — so the text is rendering in a substitute face. Dismissing hides the notice for that set of families; a different document (or a font arriving) changes the set and surfaces it again.

declare function DocxEditorFontNotice(input: DocxEditorFontNoticeProps): react.JSX.Element | null;

DocxEditorHeaderFooterChromefunctionSource ↗

Thin overlay while a header or footer scope is open: region label and contextual options. Mount beside DocxEditor.Content.

declare function DocxEditorHeaderFooterChrome(input: DocxEditorHeaderFooterChromeProps): ReactElement | null;

DocxEditorHorizontalRulerfunctionSource ↗

The horizontal ruler as a context-fed part (DocxEditor.HorizontalRuler): page width, margins and zoom straight from the editor. Left/right margin handles are draggable when the engine supports page-setup writes; the drag previews locally and commits one undoable step on release.

Renders nothing while the editor holds no document — see [selectDocumentAbsent](selectDocumentAbsent).

declare function DocxEditorHorizontalRuler(props: DocxEditorRulerProps): ReactElement | null;

DocxEditorImagePropertiesDialogfunctionSource ↗

Properties dialog for the selected picture.

declare function DocxEditorImagePropertiesDialog(input: DocxEditorImagePropertiesDialogProps): react.JSX.Element | null;

DocxEditorLoadingSpinnerfunctionSource ↗

The packaged spinner, on its own. Exposed because children replaces the default screen wholesale — a host that wants "spinner plus my own label" would otherwise have to hand-copy an internal class name.

Decorative: it carries aria-hidden, so the surrounding live region needs its own text. DocxEditor.Loading supplies a translated one when you pass no children.

declare function DocxEditorLoadingSpinner(input: DocxEditorLoadingSpinnerProps): react.JSX.Element;

DocxEditorNavigationfunctionSource ↗

The document navigation pane — headings and find — over the left gutter.

declare function DocxEditorNavigation(props: DocxEditorNavigationProps): ReactElement;

DocxEditorNotesChromefunctionSource ↗

declare function DocxEditorNotesChrome(input: DocxEditorNotesChromeProps): ReactElement | null;

DocxEditorPageSetupDialogfunctionSource ↗

Page Setup dialog: size preset, orientation, margins in inches. Reads the section through usePageSetup() and applies the whole form as one undoable command.

declare function DocxEditorPageSetupDialog(input: DocxEditorPageSetupDialogProps): ReactElement | null;

DocxEditorRootfunctionSource ↗

Creates and owns a DocxEditorInstance and provides it to the subtree. Renders no DOM — compose it with DocxEditor.Viewport + DocxEditor.Content for the painted pages, and any hook-built chrome anywhere inside.

declare function DocxEditorRoot(props: DocxEditorRootProps): react.JSX.Element;

DocxEditorShellfunctionSource ↗

Outer chrome of the editor: i18n + error provider wrappers, the scroll container with its background-click handler, horizontal and vertical rulers, the floating page indicator, document outline panel + toggle button, plus slots for the toolbar, paged-area body, overlays, dialogs, and hidden file inputs.

The expanded-sidebar-item highlight styles are computed here from expandedSidebarItem + trackedChanges because they need to live inside the editor-content <div> for proper scoping.

declare function DocxEditorShell(input: {
    i18n: React.ComponentProps<typeof LocaleProvider>['i18n'];
    isDark?: boolean;
    onEditorError: (error: Error) => void;
    containerRef: React.Ref<HTMLDivElement>;
    scrollContainerRef: React.Ref<HTMLDivElement>;
    editorContentRef: React.Ref<HTMLDivElement>;
    className: string | undefined;
    containerStyle: CSSProperties;
    mainContentStyle: CSSProperties;
    editorContainerStyle: CSSProperties;
    showRuler: boolean;
    readOnlyProp: boolean | undefined;
    showOutline: boolean;
    showOutlineButton: boolean;
    sidebarOpen: boolean;
    minLayoutWidth: number;
    toolbarHeight: number;
    editorScrollLeft: number;
    expandedSidebarItem: string | null;
    trackedChanges: readonly TrackedChangeSummary[];
    onScrollContainerMouseDown: (e: React.MouseEvent) => void;
    onEditorBgMouseDown: (e: React.MouseEvent) => void;
    onEditorContextMenu: (e: React.MouseEvent) => void;
    horizontalRulerProps: HorizontalRulerProps;
    verticalRulerProps: VerticalRulerProps$1;
    outlineProps: OutlineProps;
    onToggleOutline: () => void;
    scrollPageInfo: ScrollPageInfo;
    toolbar: ReactNode;
    pagedArea: ReactNode;
    overlays: ReactNode;
    dialogs: ReactNode;
    fileInputs: ReactNode;
}): react.JSX.Element;

DocxEditorVerticalRulerfunctionSource ↗

The vertical ruler as a context-fed part (DocxEditor.VerticalRuler): page height, margins and zoom straight from the editor. Top/bottom margin handles are draggable when the engine supports page-setup writes, committing one undoable step on release.

Renders nothing while the editor holds no document — see [selectDocumentAbsent](selectDocumentAbsent).

declare function DocxEditorVerticalRuler(props: DocxEditorRulerProps): ReactElement | null;

DocxEditorViewportfunctionSource ↗

The sole scroll container for the painted document. Put DocxEditor.Content inside it; the engine discovers this element by class and manages scrolling against it.

declare function DocxEditorViewport(input: DocxEditorViewportProps): react.JSX.Element;

HorizontalRulerfunctionSource ↗

declare function HorizontalRuler(input: HorizontalRulerProps$1): react__default.ReactElement;

ImageAltTextfunctionSource ↗

Opens a small panel to edit image description (and optional title).

declare function ImageAltText(input: ImageAltTextProps): react.JSX.Element | null;

ImageInsertProviderfunctionSource ↗

declare function ImageInsertProvider(input: ImageInsertProviderProps): react.JSX.Element;

ImageInsertTriggerfunctionSource ↗

Toolbar insert-image control — opens the shared file picker.

declare function ImageInsertTrigger(input: ImageInsertTriggerProps): react.JSX.Element | null;

ImagePropertiesTriggerfunctionSource ↗

Opens the image properties dialog for the selected drawing.

declare function ImagePropertiesTrigger(input: ImagePropertiesTriggerProps): react.JSX.Element | null;

ImageWrapfunctionSource ↗

Wrap-text dropdown presenting all nine Word choices.

declare function ImageWrap(input: ImageWrapProps): react.JSX.Element | null;

LocaleProviderfunctionSource ↗

declare function LocaleProvider(input: LocaleProviderProps): react.JSX.Element;
declare function Logo(input: LogoProps): react__default.JSX.Element;
declare function MenuBar(): react__default.JSX.Element;

The back arrow that closes the pane.

declare function NavigationClose(input: NavigationPartProps): ReactElement;

The find panel: a query box, a result counter with previous/next, the match-case and whole-word toggles, and the result list. Selecting a result moves the caret onto the match and reveals its page.

declare function NavigationFind(input: NavigationPartProps): ReactElement;

The pane's title row. With no children it renders the close arrow and the title.

declare function NavigationHeader(input: NavigationPartProps): ReactElement;

The heading list, indented by outline depth. Clicking a row moves the caret to that heading and brings it into view.

The filter box narrows the list CLIENT-SIDE — it hides rows whose text does not contain what you typed. It is deliberately not the document search: filtering an outline and searching a document are different questions, and the Find tab answers the second one.

declare function NavigationHeadings(input: NavigationPartProps): ReactElement;

Total left space an open pane needs before the page may start.

declare function navigationPaneReservation(paneWidth?: number): number;

The viewport's left padding, in px, that puts the page's left edge exactly at reservation — and 0 whenever the gutter is already wide enough.

Returns 0 for a degenerate measurement (a viewport that has not been laid out yet, a document with no page setup) rather than guessing: shifting on a zero measurement would make the pane jump on the first frame and settle on the second.

declare function navigationShift(input: NavigationShiftInput): number;

One tab button. Children replace the label.

declare function NavigationTab(input: NavigationTabProps): ReactElement;

The tab strip. With no children it renders one Tab per tab the pane supports.

A real role="tablist", so arrow keys move between tabs and a screen reader announces the panel each one controls.

declare function NavigationTabs(input: NavigationPartProps): ReactElement;

The pane's heading text.

declare function NavigationTitle(input: NavigationPartProps): ReactElement;

The collapsed pane's disc button. DocxEditor.Navigation renders one for you while the pane is closed; place it yourself (a toolbar, a menu) with toggle={false} on the root.

declare function NavigationToggle(input: NavigationPartProps): ReactElement;

normalizeImageBytesfunctionSource ↗

Preflight raster bytes for insert/replace. Never allocates from file-supplied dimensions alone.

declare function normalizeImageBytes(bytes: Uint8Array): NormalizedImagePayload;

PageIndicatorfunctionSource ↗

Floating page indicator shown next to the scrollbar while the user scrolls a multi-page document. Wrapped so the {current} of {total} template runs through t(); useTranslation() only works inside <LocaleProvider>, which DocxEditor's own body is not.

declare function PageIndicator(input: {
    currentPage: number;
    totalPages: number;
    visible: boolean;
}): react.JSX.Element;

PaginatedDocxEditorfunctionSource ↗

declare function PaginatedDocxEditor(input: PaginatedDocxEditorProps): react.JSX.Element;

PaginatedDocxEditorShellfunctionSource ↗

declare function PaginatedDocxEditorShell(input: PaginatedDocxEditorShellProps): react.JSX.Element;

SlotfunctionSource ↗

Renders its single child element with the slot's props merged in.

declare function Slot(input: SlotProps): ReactElement<unknown, string | react.JSXElementConstructor<any>> | null;

TitleBarfunctionSource ↗

TitleBar layout (Google Docs style):

┌──────────┬────────────────────────────┬──────────────────┐ │ │ Document Name │ │ │ Logo │ │ Right Actions │ │ │ File Format Insert │ │ └──────────┴────────────────────────────┴──────────────────┘

Logo and TitleBarRight span full height. DocumentName + MenuBar stack vertically in the center column.

declare function TitleBar(input: TitleBarProps): react__default.JSX.Element;

TitleBarRightfunctionSource ↗

declare function TitleBarRight(input: TitleBarRightProps): react__default.JSX.Element;

ToolbarfunctionSource ↗

Icon-based formatting toolbar — undo/redo, zoom, styles, fonts, bold/italic/underline, colors, alignment, lists, table/image context, clear formatting.

declare function Toolbar(explicitProps: ToolbarProps): react__default.JSX.Element;

ToolbarButtonfunctionSource ↗

Individual toolbar button with shadcn styling

declare function ToolbarButton(input: ToolbarButtonProps): react__default.JSX.Element;

ToolbarGroupfunctionSource ↗

Toolbar button group with modern styling

declare function ToolbarGroup(input: ToolbarGroupProps): react__default.JSX.Element;

useChromeTranslatefunctionSource ↗

The catalogue-backed resolver for composed chrome, ready to pass as any part's t.

useTranslation().t is keyed by the strict TranslationKey union, which does not assign to the parts' plain-string t props — so before this hook, every composing host hand-wrote the same cast wrapper <DocxEditor> builds internally. This is that wrapper, exported: it resolves through the active LocaleContext catalogue (bundled English by default), with overrides consulted first for key-level renames.

```tsx const MY_LABELS = new Map([['toolbar.bold', 'Heavy']]); // module-level: stable identity

const t = useChromeTranslate(MY_LABELS); <DocxEditor.Toolbar t={t} /> ```

Keep the overrides Map identity stable (module-level or memoized) — the returned resolver is memoized on it, and an inline new Map(...) re-creates the resolver, and with it every consuming part's props, on each render.

overrides is a Map on purpose: the key is caller input, and an object literal would answer constructor and toString off the prototype chain. Parts pass no params today for overridden keys, so override values are literal strings.

declare function useChromeTranslate(overrides?: ReadonlyMap<string, string>): ChromeTranslate;

useContentControlfunctionSource ↗

Headless content-control chrome. Mount under DocxEditor.Root.

Both the context-provided instance and a local fallback run every render (same order), matching useHyperlinkPopup.

declare function useContentControl(): UseContentControlResult;

useContentControlInstancefunctionSource ↗

Create the content-control chrome state. Used by DocxEditor.Root to publish one shared instance; also usable in tests without the provider.

declare function useContentControlInstance(): UseContentControlResult;

useContextMenuTargetfunctionSource ↗

The element the opening right-click landed on, or null while the menu is closed.

Public so capability packages can render contextual sections — a row that only exists when the press landed on their own painted chrome — without a second listener.

declare function useContextMenuTarget(): HTMLElement | null;

useDocumentOutlinefunctionSource ↗

The document outline's behavior, with no UI attached: the headings, their nesting depth, and the jump. DocxEditor.Navigation.Headings is this hook plus rows; a host that wants a different list takes the hook and renders its own.

declare function useDocumentOutline(): UseDocumentOutlineResult;

useDocumentSearchfunctionSource ↗

The find panel's behavior, with no UI attached.

declare function useDocumentSearch(): UseDocumentSearchResult;

useDocxEditorfunctionSource ↗

The editor instance from the nearest DocxEditor.Root, or null before the Root's mount effect has created it (and outside any Root). Deliberately not a throwing variant: pre-mount is a normal frame every consumer renders through, and the state hooks built on this already answer it with a typed loading snapshot.

declare function useDocxEditor(): DocxEditorInstance | null;

useDocxSourcefunctionSource ↗

Load a document (and optionally fonts) for DocxEditor.

tsx const { document, fonts, error } = useDocxSource(url, { fonts: defaultFonts }); if (error) return <p>{error.message}</p>; return <DocxEditor document={document} fonts={fonts} />;

FONTS NEVER FAIL THE DOCUMENT. A face that will not load degrades that family to fixed-width measurement — the document still opens, it just paginates less like Word — so a font failure leaves error null and is the loader's to report. A document failure is different: there is nothing to show, so it lands on error.

THE DOCUMENT WAITS FOR THE FONTS. They fetch concurrently, but document stays undefined until fonts have settled — resolved OR failed — because layout MEASURES with them. Handing the editor bytes first paginates the whole document on the fixed fallback and then re-paginates when the real faces arrive, which the reader sees as the text jumping. One slightly longer wait beats a visible reflow. Without a fonts option there is nothing to wait for and the bytes go straight through.

A URL is fetched with the browser's own fetch, exactly as the caller wrote it. Validate it first if it came from user input: this hook adds no allowlist of its own, and inventing one would only give callers a false sense of where the trust boundary is.

declare function useDocxSource(source: DocxSource | null | undefined, options?: UseDocxSourceOptions): UseDocxSourceResult;

useEditorCaretfunctionSource ↗

The caret's paragraph and offset, or null when nothing is placed.

Compared by value, so a consumer re-renders only when the caret actually moves.

tsx const caret = useEditorCaret(); // …later, in a menu row that inserts at where the user was reading: insertCustomNode(editor, citation, attrs, label, caret ? { at: caret } : {});

declare function useEditorCaret(): EditorCaret | null;

useEditorCommandfunctionSource ↗

Bind a chrome slot ('text.bold', 'history.undo', …) or a raw EditorCommand ({ type: 'selectAll' }) to the editor. The result object is identity-stable while its fields are unchanged, so it can sit in dependency arrays and memo props without churn.

declare function useEditorCommand(target: ChromeSlotId | EditorCommand): EditorCommandState;

useEditorEventfunctionSource ↗

Subscribe to an editor event ('change', 'selectionChange', 'error', …) for the lifetime of the component. No-op until the nearest DocxEditor.Root has created the editor; resubscribes automatically when the instance is replaced.

declare function useEditorEvent<E extends keyof EditorEvents>(event: E, handler: EditorEvents[E]): void;

useEditorSnapshotfunctionSource ↗

Re-render the caller whenever the editor commits a change, moves the selection, or republishes display. Returns a counter that changes on each such event, so it can also be used as a dependency.

declare function useEditorSnapshot(editor: Editor | null): number;

useEditorStatefunctionSource ↗

Subscribe to a slice of the editor's read model. Re-renders the component ONLY when selector's result changes (by isEqual, default Object.is).

Before the editor exists — outside a DocxEditor.Root, pre-mount, and on the server — the selector receives a frozen loading snapshot (isLoading: true, page: {current: 0, total: 0}), never null.

declare function useEditorState<T>(selector: (snapshot: EditorSnapshot) => T, isEqual?: (a: T, b: T) => boolean, options?: UseEditorStateOptions): T;

useEditorValueCommandfunctionSource ↗

Bind a value-typed chrome slot (image.wrap, image.altText) to the editor.

declare function useEditorValueCommand(slotId: 'image.wrap'): EditorValueCommandState<ImageWrapTarget>;

useEditorValueCommandfunctionSource ↗

declare function useEditorValueCommand(slotId: 'image.altText'): EditorValueCommandState<string>;

useFontFamilyfunctionSource ↗

The font-family picker's behavior, UI-free.

declare function useFontFamily(): UseFontFamilyResult;

useFontsfunctionSource ↗

Merge font origins into one stable value for DocxEditor.Root's fonts prop.

```tsx // On demand: only the families this document names are fetched. const fonts = useFonts(googleFonts());

// On demand, plus brand faces you always want. const fonts = useFonts(googleFonts(), brandFragment);

// Eager, from the bundled substitutes. const fonts = useFonts(defaultFonts());

return <DocxEditor.Root fonts={fonts}>{children}</DocxEditor.Root>; ```

Origins compose first-wins in argument order, exactly like composeFontConfiguration: the first argument beats later ones, and any of them beats a substitution for a family some origin supplies directly.

The returned resolver never changes identity, so the editor is never rebuilt on account of this prop — which also means the arguments are re-read per LOAD rather than per render. Changing them mid-document does not re-resolve fonts; load a document, or remount, for new fonts to take effect.

declare function useFonts(source: FontsInput, ...fragments: readonly (FontConfigurationFragment | undefined)[]): FontResolver;

useHeaderFooterStatefunctionSource ↗

Subscribe to getHeaderFooterState() with reference-stable results when unchanged.

declare function useHeaderFooterState(): HeaderFooterState | null;

useHyperlinkPopupfunctionSource ↗

The hyperlink popover's behavior.

Inside a DocxEditor.HyperLink (which the packaged editor mounts by default) this is the SHARED state that compound is driving, so a custom toolbar button and the popover agree. Outside one it is a standalone instance that registers with the engine itself — a host building its own link UI from scratch needs nothing else.

declare function useHyperlinkPopup(): UseHyperlinkPopupResult;

useHyperlinkPopupInstancefunctionSource ↗

A popover instance. active gates ENGINE REGISTRATION only — an instance created inside a provider still exists, it just does not compete for the surface's chrome handlers.

declare function useHyperlinkPopupInstance(active?: boolean): UseHyperlinkPopupResult;

useNavigationPanefunctionSource ↗

The navigation pane's behavior, with no UI attached: open state, the active tab, and the document displacement an open pane is entitled to.

DocxEditor.Navigation calls this and shares the result with its parts. Call it directly to drive a pane of your own.

declare function useNavigationPane(options?: UseNavigationPaneOptions): UseNavigationPaneResult;

useNavigationShiftfunctionSource ↗

The px the chrome is currently displaced by an open navigation pane. 0 when no pane is mounted, when it is closed, and whenever the left gutter was already wide enough.

declare function useNavigationShift(): number;

useNotePropertiesStatefunctionSource ↗

Subscribe to getNotePropertiesState() with reference-stable results when unchanged.

declare function useNotePropertiesState(): NotePropertiesState | null;

useNoteScopeStatefunctionSource ↗

Subscribe to the active note view scope with reference-stable results when unchanged.

declare function useNoteScopeState(): Extract<ViewScope, {
    kind: 'note';
}> | null;

usePageSetupfunctionSource ↗

The section's page setup — size, orientation, margins — plus the command to change it.

Reads snapshot().pageSetup, which is reference-stable across ticks that did not move the section, so a subscriber re-renders only when the page actually changes shape. In a multi-section document it reflects the CARET's section, as Word's ruler does.

declare function usePageSetup(): UsePageSetupReturn;

useParagraphIndentfunctionSource ↗

The selection's paragraph indent — left, right, and the signed first line — plus the command to change it.

This is what DocxEditor.HorizontalRuler drives its four handles from. A host that wants its own indent chrome takes the hook and renders whatever it likes; the ruler's drag geometry is separately available as pure functions (dragIndent / handlePosition from the engine).

declare function useParagraphIndent(): UseParagraphIndentReturn;

useParagraphStylefunctionSource ↗

The paragraph-style picker's behavior, UI-free.

declare function useParagraphStyle(): UseParagraphStyleResult;

useTableBorderTargetLabelfunctionSource ↗

Resolved label for the active border target in the shared draft.

For custom table chrome that shows the current target name outside the packaged picker.

declare function useTableBorderTargetLabel(): string;

useTranslationfunctionSource ↗

declare function useTranslation(): {
    t: TFunction;
};

VerticalRulerfunctionSource ↗

declare function VerticalRuler(input: VerticalRulerProps): react__default.ReactElement;

Interfaces (102)

ContentControlActionPropsinterfaceSource ↗

Props for action parts that also take an icon.

interface ContentControlActionProps extends ContentControlPartProps
MemberTypeSummary
icon?ReactNode

ContentControlInspectorStateinterfaceSource ↗

Live inspector model for the control at the caret.

locked is the content-edit axis. Removal lock is reported separately via removalLocked from the boundary's effective lock / surface disabled reason.

interface ContentControlInspectorState
MemberTypeSummary
aliasstring | null
boundboolean
controlTypeContentControlType
effectiveLockContentControlLock | null
idstring
lockedbooleanContent-edit locked (`contentLocked` / `sdtContentLocked` union).
placeholderboolean
removalLockedbooleanWrapper removal refused (`sdtLocked` / `sdtContentLocked` union).
tagstring | null

ContentControlPartPropsinterfaceSource ↗

Shared props for every part.

interface ContentControlPartProps
MemberTypeSummary
asChild?boolean
children?ReactNode
className?string
hidden?boolean

ContentControlPropsinterfaceSource ↗

Props for DocxEditor.ContentControl.

interface ContentControlProps extends ContentControlPartProps
MemberTypeSummary
preset?booleanRender the packaged arrangement. `false` mounts only the shell and whatever parts you pass as children.

ContextMenuAnchorinterfaceSource ↗

Where the panel opened, in client coordinates.

interface ContextMenuAnchor
MemberTypeSummary
xnumber
ynumber

ContextMenuCommandPropsinterfaceSource ↗

Props for a packaged context-menu row.

interface ContextMenuCommandProps
MemberTypeSummary
className?string
hidden?booleanRender nothing — inside the default set this removes the row.
icon?ReactNodeIcon override. Defaults to the row's own Material Symbol.
labelKey?stringi18n key for the label, overriding the packaged one.
shortcutKey?stringi18n key for the shortcut column, overriding the packaged one.

ContextMenuItemPropsinterfaceSource ↗

Props for DocxEditor.ContextMenu.Item: a host-owned row.

interface ContextMenuItemProps
MemberTypeSummary
active?booleanChecked state, for a row that toggles. Leave undefined on a row that just acts.
className?string
disabled?boolean
disabledReason?stringTooltip when disabled. Say why — never invent a reason the engine did not give.
icon?ReactNode
labelstringLabel, as a resolved STRING rather than an i18n key — the row belongs to the host's own action, so the host's own catalogue resolves it. The packaged rows go the other way.
onSelect?() => void
shortcut?stringRight-aligned shortcut text, already resolved.

ContextMenuTableRowPropsinterfaceSource ↗

Props for packaged table context-menu rows.

interface ContextMenuTableRowProps extends ContextMenuCommandProps
MemberTypeSummary
destructive?booleanWhen true, the row uses the destructive treatment.

DocxEditorContentControlNamespaceinterfaceSource ↗

The content-control inspector compound. Parts live on the namespace statics.

interface DocxEditorContentControlNamespace
MemberTypeSummary
(member-0)
Fieldstypeof ContentControlFields
Headertypeof ContentControlHeader
Removetypeof ContentControlRemove

DocxEditorContentPropsinterfaceSource ↗

Props for DocxEditor.Content.

interface DocxEditorContentProps
MemberTypeSummary
className?stringAppended after the load-bearing `docx-paginated-surface` class.

DocxEditorContextMenuNamespaceinterfaceSource ↗

DocxEditor.ContextMenu with its rows attached as statics.

interface DocxEditorContextMenuNamespace
MemberTypeSummary
(member-0)
CellVerticalAlignmenttypeof ContextMenuCellVerticalAlignment
Copytypeof ContextMenuCopy
Cuttypeof ContextMenuCut
Deletetypeof ContextMenuDelete
DeleteTabletypeof ContextMenuDeleteTable
DeleteTableColumntypeof ContextMenuDeleteTableColumn
DeleteTableRowtypeof ContextMenuDeleteTableRow
Grouptypeof MenuGroupA named section of rows: a visible heading plus a real ARIA group.
InsertColumnLefttypeof ContextMenuInsertColumnLeft
InsertColumnRighttypeof ContextMenuInsertColumnRight
InsertRowAbovetypeof ContextMenuInsertRowAbove
InsertRowBelowtypeof ContextMenuInsertRowBelow
Itemtypeof ContextMenuItemA host-owned row: no slot, no command, the host's own label and action.
Pastetypeof ContextMenuPaste
RefreshToctypeof ContextMenuRefreshToc
RefreshTocPageNumberstypeof ContextMenuRefreshTocPageNumbers
Rowtypeof MenuRowBare row presentation, for a host building something the parts do not cover.
SelectAlltypeof ContextMenuSelectAll
Separatortypeof MenuSeparator
Slottypeof MenuItemAny chrome slot as a live row (`<ContextMenu.Slot slot="text.bold" />`).
Submenutypeof MenuSubmenu

DocxEditorContextMenuPropsinterfaceSource ↗

Props for DocxEditor.ContextMenu.

interface DocxEditorContextMenuProps
MemberTypeSummary
children?ReactNode
className?stringAppended after the base `docx-contextmenu` class.
disabled?boolean`true` suppresses the panel entirely and lets the browser's own menu through. For a host that wants the native menu back on some documents without unmounting the part.
onOpenChange?(open: boolean) => voidNotified whenever the panel opens or closes.
preset?boolean`false` renders children verbatim with no default set. Default `true`: a child naming a packaged row overrides it in place, others append.
t?ToolbarTranslatei18n resolver for row labels; without it the raw keys show (never English).

DocxEditorDocumentOutlinePropsinterfaceSource ↗

Props for the context-fed outline part.

interface DocxEditorDocumentOutlineProps
MemberTypeSummary
leftOffset?numberLeft anchor (px) inside the panel's positioning container.
onClose?() => voidClose-button handler; without one the panel simply stays open.
topOffset?numberVertical offset (px) inside the panel's positioning container.

DocxEditorFontNoticePropsinterfaceSource ↗

Props for DocxEditor.FontNotice.

interface DocxEditorFontNoticeProps
MemberTypeSummary
className?stringAppended after the default notice classes.
style?CSSPropertiesInline presentation overrides for the notice element.
t?TFunctionTranslator override; defaults to the ambient locale context.

DocxEditorHeaderFooterChromePropsinterfaceSource ↗

Props for DocxEditor.HeaderFooterChrome.

interface DocxEditorHeaderFooterChromeProps
MemberTypeSummary
className?string

DocxEditorHyperLinkNamespaceinterfaceSource ↗

The link popover compound.

interface DocxEditorHyperLinkNamespace
MemberTypeSummary
(member-0)
Applytypeof HyperLinkApply
Canceltypeof HyperLinkCancel
Copytypeof HyperLinkCopy
Edittypeof HyperLinkEdit
Errortypeof HyperLinkError
Fieldstypeof HyperLinkFields
Urltypeof HyperLinkUrl

DocxEditorImagePropertiesDialogPropsinterfaceSource ↗

Props for DocxEditor.ImagePropertiesDialog.

interface DocxEditorImagePropertiesDialogProps
MemberTypeSummary
className?string
onClose() => void
openboolean
triggerRef?React.RefObject<HTMLElement | null>

DocxEditorLoadingComponentinterfaceSource ↗

The loading part with the packaged spinner attached as a static.

interface DocxEditorLoadingComponent
MemberTypeSummary
(member-0)Renders the loading screen, or nothing once a document is available.
Spinnertypeof DocxEditorLoadingSpinnerThe packaged indicator, for composing into custom children.

DocxEditorLoadingPropsinterfaceSource ↗

Props for DocxEditor.Loading.

interface DocxEditorLoadingProps
MemberTypeSummary
children?ReactNodeThe loading screen. Omitted, a neutral spinner rendered from the `--doc-*` tokens is used, so the batteries-included path has something to show. Compose your own around `DocxEditor.Loading.Spinner` to keep the packaged indicator beside your own copy.
className?stringAppended after the load-bearing `docx-editor docx-editor__loading` classes.
style?CSSPropertiesInline styles for the loading container, as on `DocxEditor.Viewport`.
when?booleanAn extra host-owned condition, OR-ed with the editor's own. OPTIONAL: the default already holds the screen up while the editor has nothing painted, including a `DocxEditor.Root` mounted before its document arrives. Pass this for state the editor cannot see — bytes still downloading, fonts not settled — when you mount the provider only after those resolve.

DocxEditorLoadingSpinnerPropsinterfaceSource ↗

Props for DocxEditor.Loading.Spinner.

interface DocxEditorLoadingSpinnerProps
MemberTypeSummary
className?stringAppended after the load-bearing `docx-editor__loading-spinner` class.

DocxEditorMenuNamespaceinterfaceSource ↗

The menu bar with its parts attached as statics.

interface DocxEditorMenuNamespace
MemberTypeSummary
(member-0)
Entrytypeof MenuEntryOne registry entry as its row, for a host arranging registry data itself.
FileMenuPartComponent
FormatMenuPartComponent
Grouptypeof MenuGroupA named section of rows: a visible heading plus a real ARIA group.
HelpMenuPartComponent
InsertMenuPartComponent
Itemtypeof MenuItemOne chrome slot as a live row.
Menutypeof MenuA menu of the bar, addressed by registry id.
Opentypeof MenuOpen
PageSetuptypeof MenuPageSetup
ReportIssuetypeof MenuReportIssueHelp › Report issue, so a host can drop it or point it elsewhere by name.
Rowtypeof MenuRowA presentational row, for a host action that is not a chrome slot.
Savetypeof MenuSave
Separatortypeof MenuSeparator
Submenutypeof MenuSubmenu
TableGridtypeof MenuTableGridWord's 6×6 insert-table size picker.

DocxEditorMenuPropsinterfaceSource ↗

Props for DocxEditor.Menu.

interface DocxEditorMenuProps
MemberTypeSummary
children?ReactNode
className?stringAppended after the base `docx-menubar` class.
fileName?stringName for the file the packaged Save writes, without the extension. Ignored when `onSave` is given.
onOpen?() => voidReplaces File › Open. The default opens a file picker and hands the bytes to `Editor.load` — a user-driven file READ, never a fetch.
onOpenFile?(file: File) => voidFired when the packaged Open reads a file, before its bytes are loaded — so a host can reflect the file's name in its own title chrome. Not fired when `onOpen` replaced the packaged picker: the host is reading the file itself and already holds the name.
onPageSetup?() => voidReplaces File › Page setup. The default opens the packaged Page Setup dialog.
onReportIssue?() => voidReplaces Help › Report issue. The default opens THIS project's issue tracker, prefilled with the current page URL and user agent — so a host embedding the editor in its own product should point this at its own support channel, or drop the row with `reportIssue={false}`.
onSave?() => voidReplaces File › Save. The default runs `Editor.save()` and downloads the bytes.
preset?boolean`false` renders children verbatim with no default arrangement. Default `true`: menu children override their menu in place, others append.
reportIssue?boolean`false` removes Help › Report issue, and the Help menu with it. Default `true`.
t?ToolbarTranslatei18n resolver for row labels; without it the raw keys show (never English).

DocxEditorNamespaceinterfaceSource ↗

The composed editor component with its composition primitives attached as statics, so <DocxEditor.Root>, <DocxEditor.Viewport>, and <DocxEditor.Content> work without extra imports.

interface DocxEditorNamespace extends ForwardRefExoticComponent<DocxEditorProps & RefAttributes<DocxEditorRef>>
MemberTypeSummary
Contenttypeof DocxEditorContent
ContentControltypeof DocxEditorContentControlThe content-control inspector — alias, tag, type, lock, placeholder, bound — and remove-keeping-content. Mounted by default inside the viewport; opens from the `contentControl.inspector` chrome slot.
ContextMenutypeof ContextMenuThe right-click menu over the painted document, with its rows as statics (`.Cut`, `.Copy`, `.Paste`, `.Delete`, `.SelectAll`, `.Item`, `.Slot`, `.Submenu`, …). Mounted by default inside the viewport; `contextMenu={false}` removes it and lets the browser's own menu through.
DocumentOutlinetypeof DocxEditorDocumentOutlineContext-fed heading outline over `Editor.getOutline()`.
FontNoticetypeof DocxEditorFontNoticeWord-style notice when document fonts render in substitute faces.
HeaderFooterChrometypeof DocxEditorHeaderFooterChromeHeader/footer scope chrome while editing page furniture.
HorizontalRulertypeof DocxEditorHorizontalRulerContext-fed horizontal ruler with draggable margins (props-driven export stays).
Loadingtypeof DocxEditorLoadingConditional loading screen: renders while there is no document to paint.
Menutypeof DocxEditorMenuThe menu bar — File · Format · Insert · Help — with its parts as statics (`.File`, `.Format`, `.Insert`, `.Help`, `.Item`, `.Row`, `.Submenu`, `.TableGrid`, …). Mounted by default under the title; `menu={false}` removes it.
Navigationtypeof NavigationThe navigation pane — Headings and Find — with its parts as statics (`.Header`, `.Close`, `.Title`, `.Tabs`, `.Tab`, `.Headings`, `.Find`, `.Toggle`). Mounted by default; `navigation={false}` removes it.
NotesChrometypeof DocxEditorNotesChrome
PageNumbertypeof DocxEditorPageNumberFloating localized page readout for the active viewport.
PageSetupDialogtypeof DocxEditorPageSetupDialogPage Setup dialog — size, orientation, margins — applied as one undo step.
Roottypeof DocxEditorRoot
Toolbartypeof DocxEditorToolbar
VerticalRulertypeof DocxEditorVerticalRulerContext-fed vertical ruler with draggable margins (props-driven export stays).
Viewporttypeof DocxEditorViewport

DocxEditorNavigationNamespaceinterfaceSource ↗

DocxEditor.Navigation with its parts attached as statics.

interface DocxEditorNavigationNamespace
MemberTypeSummary
(member-0)
Closetypeof NavigationClose
Findtypeof NavigationFind
Headertypeof NavigationHeader
Headingstypeof NavigationHeadings
Tabtypeof NavigationTab
Tabstypeof NavigationTabs
Titletypeof NavigationTitle
Toggletypeof NavigationToggle

DocxEditorNavigationPropsinterfaceSource ↗

Props for DocxEditor.Navigation.

interface DocxEditorNavigationProps extends UseNavigationPaneOptions
MemberTypeSummary
children?ReactNodeReplaces the default composition (header, tabs, both panels).
className?string
style?CSSProperties
t?(key: string, params?: Record<string, string | number>) => stringLabel resolver. Defaults to the active `LocaleContext` catalogue (bundled English unless a provider swapped it), matching `<DocxEditor>`'s own default.
toggle?boolean | NavigationPartPropsThe collapsed disc button. `false` removes it; an OBJECT is props for the packaged one, so a host can give it a class without restyling the library's.

DocxEditorNotesChromePropsinterfaceSource ↗

Props for DocxEditor.NotesChrome.

interface DocxEditorNotesChromeProps
MemberTypeSummary
className?string

DocxEditorPageSetupDialogPropsinterfaceSource ↗

Props for DocxEditor.PageSetupDialog.

interface DocxEditorPageSetupDialogProps
MemberTypeSummary
className?string
onClose() => voidCalled on Cancel, Escape, overlay click, and after a successful Apply.
openbooleanWhether the dialog is shown. The host owns this state.

DocxEditorPropsinterfaceSource ↗

Props for the React DocxEditor. The adapter is a thin renderer over the Editor contract; it holds no editing-engine state of its own and never imports ProseMirror or OOXML feature logic.

interface DocxEditorProps
MemberTypeSummary
author?string
children?ReactNodeExtra chrome rendered INSIDE the viewport, after the painted pages — the slot pro or host chrome mounts into without leaving the sugar (e.g. `DocxEditorReview` from `@docx-editor.dev/pro/react`). For more control, compose `DocxEditor.Root`/`Viewport`/`Content` directly.
chrome?booleanRenders the packaged chrome — title bar and toolbar — around the document. Default `true`. Set `false` for the painted surface alone when the host supplies its own chrome; the composition primitives (`Root` / `Viewport` / `Content`) are the better starting point if you are replacing more than the frame.
className?string
colorMode?'light' | 'dark' | 'system'Chrome colour mode. `'system'` follows the OS and re-resolves when it changes. Only the editor CHROME is themed — the document canvas stays Word-faithful.
contextMenu?boolean | DocxEditorContextMenuPropsRender the packaged right-click menu (`false` removes it, restoring the browser's own).
document?DocumentSourceA document to load: DOCX bytes or an existing handle.
fonts?FontConfiguration | FontConfigurationFragment | FontResolverImmutable byte-backed font sources sampled at mount. Remount to replace this configuration atomically.
hyperlinkPopup?booleanRender the packaged hyperlink popover (`false` removes it).
locale?string
menu?boolean | DocxEditorMenuPropsThe packaged menu bar — File · Format · Insert · Help — under the document title.
mode?EditorMode'edit' (default) or 'view' (read-only). Applied at mount only — not reactive; remount to change.
modules?readonly EditorModule[]Capability modules to register (`@docx-editor.dev/pro`'s review module, custom nodes). Applied at mount only, like `mode`.
navigation?booleanRender the packaged navigation pane — headings and find — over the document's left gutter (`false` removes it and its toggle).
onChange?(change: DocumentChange) => voidFired when the document changes (revision + identity deltas, not bytes).
onFontError?(error: EditorFontError) => voidFired with the same typed font failure shown by the accessible alert UI.
onOpen?() => voidOpen handler for the menu's File › Open row.
onReady?(editor: Editor) => voidFired after the underlying `Editor` is created.
onSave?() => voidSave handler for the chrome's save control and the menu's File › Save row. Runs `Editor.save()` at the host.
onTitleChange?(title: string) => voidCalled when the title is edited. Omitting it makes the title read-only.
renderTitleBarLeft?() => ReactNodeTitle-bar slots. The host owns what goes here — brand lockup, switchers, theme toggle, Open/New/Save controls — and passes them in; the editor renders them verbatim on either side of the document title.
renderTitleBarRight?() => ReactNode
rulers?booleanHorizontal and vertical rulers, on by default with the packaged chrome.
t?(key: string, params?: Record<string, string | number>) => stringResolves i18n keys for the editor chrome.
title?stringDocument title shown in the chrome's title bar.
zoom?number

DocxEditorRefinterfaceSource ↗

The imperative handle, identical on both adapters (enforced by bun run check:parity-contract). Every member forwards to the Editor facade and is safe to call before the editor has mounted — mutations no-op, reads return the honest empty answer (null, a notFound refusal, a loading snapshot) — so a host can hold the ref from first render without guarding it.

The ref deliberately stays small: everything else (zoom, paging, formatting queries, document state) is reachable through the full facade via getEditor, so the ref never mirrors capabilities the Editor contract already names.

interface DocxEditorRef
MemberTypeSummary
execRun a typed command through the facade; refused with `notFound` before mount.
focus
getDocumentHandleIdentity and revision of the loaded document; `null` before mount.
getEditorThe full `Editor` facade for advanced callers; `null` before mount.
loadLoad a document: DOCX bytes or an existing handle. No-op before mount.
saveSerialize the current document; `null` when no editor is mounted.
snapshotThe current read model; a loading, non-editable snapshot before mount.

DocxEditorRootPropsinterfaceSource ↗

Props for DocxEditor.Root. Creation parameters (document, fonts, author, locale, and the initial mode/zoom) are sampled when the instance is created; only document and fonts identity remount it. Later mode and zoom changes flow through Editor.setZoom so edits, the caret, and the undo history survive.

interface DocxEditorRootProps
MemberTypeSummary
author?string
children?ReactNode
document?DocumentSourceA document to load: DOCX bytes or an existing handle. Identity change remounts.
fonts?FontConfiguration | FontConfigurationFragment | FontResolverFont bytes for Word-accurate (HarfBuzz-shaped) wrap and pagination. Omitted, layout uses a fixed-width estimate; fonts embedded in the document are wired automatically either way. Pass `await loadDefaultFonts()` from `@docx-editor.dev/fonts` for Word's default faces — a bare fragment is accepted — or compose several origins with `composeFontConfiguration`. Sampled at mount; identity change remounts; failures degrade to the fixed measurer and report through `onFontError`.
imageDecodePort?ImageDecodePortOptional decode port for embedded image insertion and paint in tests or custom hosts.
locale?string
mode?'edit' | 'view'`'edit'` (default) or `'view'` (read-only). Sampled at mount only.
modules?readonly EditorModule[]Capability modules to register (`@docx-editor.dev/pro`'s review module, custom nodes). Sampled at mount only, like `mode`: module registration is construction-time in the engine.
onChange?(change: DocumentChange) => voidFired when the document changes (revision + identity deltas, not bytes).
onFontError?(error: EditorFontError) => voidFired with the typed font failure when the shaped-font pipeline rejects.
onReady?(editor: Editor) => voidFired once per instance, after it is published to the tree (and after any `DocxEditor.Content` in the same commit has attached its mount point).
tableInteractionLabel?(key: 'table.insertRowBelow' | 'table.insertColumnRight') => stringLocalized labels for table insertion furniture. When omitted, core falls back to bundled English through [defaultTableLabel](defaultTableLabel).
translate?(key: string, params?: Record<string, string | number>) => stringDrawing refusal labels for painted placeholders; defaults to the active locale catalogue.
zoom?number

DocxEditorRulerPropsinterfaceSource ↗

Props for the context-fed ruler parts.

interface DocxEditorRulerProps
MemberTypeSummary
className?string
style?CSSProperties
unit?'inch' | 'cm'Measurement unit for tick labels. Defaults to inches.

DocxEditorToolbarNamespaceinterfaceSource ↗

The toolbar with its parts attached as statics.

interface DocxEditorToolbarNamespace
MemberTypeSummary
(member-0)
Actiontypeof ToolbarActionA host-owned action the chrome registry does not describe.
AlignCenterToolbarPartComponent
AlignJustifyToolbarPartComponent
AlignLeftToolbarPartComponent
AlignmentToolbarAlignmentComponent
AlignRightToolbarPartComponent
BoldToolbarPartComponent
BulletListToolbarPartComponent
Buttontypeof ToolbarButton$1
ClearFormattingToolbarPartComponent
CommentsToolbarPartComponent
ContentControlFormFillToolbarPartComponent
ContentControlInspectorToolbarPartComponent
ContentControlRemoveToolbarPartComponent
ContentControlShowAllToolbarPartComponent
EditingModeToolbarSlotPartComponent
FontColorToolbarColorSplitComponent
FontFamilytypeof FontFamily
FontSizeToolbarSlotPartComponent
HighlightToolbarColorSplitComponent
ImageAltTextImageAltTextPartComponent
ImageInsertToolbarPartComponent
ImagePropertiesToolbarPartComponent
ImageWrapImageWrapPartComponent
IndentToolbarPartComponent
ItalicToolbarPartComponent
LineSpacingToolbarSlotPartComponent
NumberedListToolbarPartComponent
OutdentToolbarPartComponent
RedoToolbarPartComponent
SaveToolbarSlotPartComponent
Separatortypeof ToolbarSeparator
StrikeToolbarPartComponent
StylePickertypeof ParagraphStyle
SubscriptToolbarPartComponent
SuperscriptToolbarPartComponent
TableBorderColorTableBorderColorNamespaceBorder-colour split compound (quick-apply main + swatch dialog).
TableBorderStyleTableBorderStyleNamespaceBorder line-style menu compound.
TableBorderTargetTableBorderTargetNamespaceBorder-edge target picker compound for contextual table chrome.
TableBorderWidthTableBorderWidthNamespaceBorder width menu compound.
TableCellFillTableCellFillNamespaceCell background fill split compound (quick-apply main + swatch dialog).
TableInsertToolbarPartComponent
UnderlineToolbarPartComponent
UndoToolbarPartComponent
ZoomToolbarSlotPartComponent

DocxEditorToolbarPropsinterfaceSource ↗

Props for DocxEditor.Toolbar.

interface DocxEditorToolbarProps
MemberTypeSummary
children?ReactNode
className?stringAppended after the base `docx-toolbar` class.
onSave?() => voidHandler for the `file.save` control. Save is not an engine command (`Editor.save()` returns bytes the host must deliver), so without a handler the control renders disabled — same contract as the Vue toolbar's `onSave`.
overflow?boolean`false` lets the bar WRAP to more rows instead of collapsing groups into the "⋯" menu when it runs out of width. Default `true`.
preset?boolean`false` renders children verbatim with no default arrangement. Default `true`: part children override their slots in place, others append.
t?ToolbarTranslatei18n resolver for control labels; without it the raw keys show (never English).

DocxEditorViewportPropsinterfaceSource ↗

Props for DocxEditor.Viewport.

interface DocxEditorViewportProps
MemberTypeSummary
children?ReactNode
className?stringAppended after the load-bearing viewport classes (e.g. `dark` for chrome theming).
style?CSSProperties

EditorCaretinterfaceSource ↗

A caret position: a paragraph and a UTF-16 offset inside it — the shape the write APIs take as their at.

interface EditorCaret
MemberTypeSummary
offsetnumber
paragraphIdstring

EditorCommandStateinterfaceSource ↗

The live state of one editor control, plus its action.

interface EditorCommandState
MemberTypeSummary
disabledReasonstring | nullThe engine's reason when disabled — surface it as a tooltip, never invent one.
execute() => booleanRun the command through the can-before-exec path.
isActivebooleanWhether the command is currently applied at the selection (bold on bold text).
isEnabledbooleanWhether the engine will honour the command right now.

EditorValueCommandStateinterfaceSource ↗

Live state for a value-typed toolbar control.

interface EditorValueCommandState<T extends string | number>
MemberTypeSummary
disabledReasonstring | null
execute(value: T) => void
isEnabledboolean
optionsreadonly T[]
valueT | null

FontFamilyItemPropsinterfaceSource ↗

Props for FontFamily.Item.

interface FontFamilyItemProps extends FontFamilyPartProps
MemberTypeSummary
valuestringThe family this item applies.

FontFamilyNamespaceinterfaceSource ↗

The compound part with its sub-parts attached as statics.

interface FontFamilyNamespace
MemberTypeSummary
(member-0)
Contenttypeof FontFamilyContent
docxSlot'font.family'
Itemtypeof FontFamilyItem
Triggertypeof FontFamilyTrigger

FontFamilyPartPropsinterfaceSource ↗

Props for DocxEditorToolbar.FontFamily and its sub-parts.

interface FontFamilyPartProps
MemberTypeSummary
asChild?boolean
children?ReactNode
className?string

FontFamilyPropsinterfaceSource ↗

Props for the compound root.

interface FontFamilyProps extends FontFamilyPartProps
MemberTypeSummary
hidden?booleanRender nothing — inside the default arrangement this removes the slot.

HorizontalRulerPropsinterfaceSource ↗

interface HorizontalRulerProps$1
MemberTypeSummary
className?string
editable?booleanWhether the MARGIN handles drag.
indent?RulerIndent | nullThe paragraph's indent in twips; `firstLine` is SIGNED, negative for a hanging.
indentEditable?booleanWhether the INDENT handles drag — a different capability from `editable`.
onIndentChange?(indent: RulerIndent) => voidFires continuously through an indent drag, for the host to preview.
onIndentDragEnd?() => voidFires when an indent drag is released — the moment to commit one undoable step.
onLeftMarginChange?(marginTwips: number) => void
onMarginDragEnd?() => voidFires when a margin drag is released — the moment to commit what the drag previewed.
onRightMarginChange?(marginTwips: number) => void
onTabMarkRemove?(positionTwips: number) => void
pageSetup?RulerPageSetup | null
showIndentHandles?booleanPaint the four indent handles.
style?CSSProperties
tabMarks?RulerTabStop[] | null
unit?'inch' | 'cm'
zoom?number

HyperLinkActionPropsinterfaceSource ↗

Props for the action parts, which also take an icon.

interface HyperLinkActionProps extends HyperLinkPartProps
MemberTypeSummary
icon?ReactNodeIcon override; falls back to `children`, then to the part's default glyph.

HyperLinkPartPropsinterfaceSource ↗

Shared props for every part.

interface HyperLinkPartProps
MemberTypeSummary
asChild?booleanMerge this part's wiring onto the single child element instead of the default one.
children?ReactNode
className?string
hidden?booleanRender nothing — inside the default arrangement this removes the part.

HyperlinkPopupAnchorinterfaceSource ↗

Where the popover sits, in viewport coordinates.

interface HyperlinkPopupAnchor
MemberTypeSummary
leftnumber
topnumber

HyperlinkPopupStateinterfaceSource ↗

The popover's observable state.

interface HyperlinkPopupState
MemberTypeSummary
anchorHyperlinkPopupAnchor | nullViewport position for the panel; null means "the host places it".
canEditbooleanWhether the document can be edited right now; read-only trims the actions.
copiedbooleanTrue after a copy, until the next state change — for a "Copied" confirmation.
errorbooleanTrue when the last Apply was refused, so the panel can say so instead of sitting there.
modeHyperlinkPopupMode
textstringDraft display text, in edit mode.
urlstringDraft target, in edit mode.

HyperLinkPropsinterfaceSource ↗

Props for DocxEditor.HyperLink.

interface HyperLinkProps extends HyperLinkPartProps
MemberTypeSummary
preset?booleanRender the packaged arrangement. `false` mounts only the popover shell and whatever parts you pass as children — the rung for "I want the wiring, not the layout".

IndentUpdateinterfaceSource ↗

The fields apply accepts — twips throughout, like every other read shape here.

Omitted fields are left as authored; null CLEARS one, so the paragraph falls back to its style. That is a different thing from zero, which blocks the cascade — the same distinction setParagraphSpacing draws.

firstLine is ONE SIGNED offset from the left indent: negative IS the hanging indent. OOXML spells it as two mutually exclusive attributes, and a caller should not have to know which of them wins.

interface IndentUpdate
MemberTypeSummary
firstLine?number | null
left?number | null
right?number | null

Props for the pinned File rows.

interface MenuActionProps
MemberTypeSummary

Props for DocxEditor.Menu.Group: a titled section of rows.

interface MenuGroupProps
MemberTypeSummary

Props for DocxEditor.Menu.Item: one chrome slot as a menu row.

interface MenuItemProps
MemberTypeSummary

A menu pinned to one registry id, for DocxEditor.Menu.File and friends.

interface MenuPartComponent
MemberTypeSummary

Props for DocxEditor.Menu.Menu and the four pinned menu parts.

interface MenuProps
MemberTypeSummary

Props for DocxEditor.Menu.ReportIssue.

interface MenuReportIssueProps
MemberTypeSummary

Props for DocxEditor.Menu.Row: one presentational menu row.

interface MenuRowProps
MemberTypeSummary

Props for DocxEditor.Menu.Separator.

interface MenuSeparatorProps
MemberTypeSummary
interface MenuSubmenuProps
MemberTypeSummary

Props for DocxEditor.Menu.TableGrid.

interface MenuTableGridProps
MemberTypeSummary

Shared props for the pane's structural parts.

interface NavigationPartProps
MemberTypeSummary
interface NavigationShiftInput
MemberTypeSummary

Props for one tab.

interface NavigationTabProps extends NavigationPartProps
MemberTypeSummary

OutlineHeadingIteminterfaceSource ↗

A heading plus how deep to indent it in a rendered list.

interface OutlineHeadingItem
MemberTypeSummary
depthnumberIndent depth RELATIVE to the shallowest heading present, not the absolute level. A memo whose top sections are Heading 2 should left-align them at the base instead of carrying a phantom first-level indent.
headingOutlineHeading$1

PageSetupUpdateinterfaceSource ↗

The fields apply accepts — twips throughout, like every read shape. Omitted fields are left as authored. scope is Word's "Apply to": 'document' (the default) writes every section, 'section' only the one the selection is in.

interface PageSetupUpdate
MemberTypeSummary
marginBottomTwips?number
marginLeftTwips?number
marginRightTwips?number
marginTopTwips?number
orientation?'portrait' | 'landscape'
pageHeightTwips?number
pageWidthTwips?number
scope?'document' | 'section'

PaginatedDocxEditorHandleinterfaceSource ↗

What a host can drive from outside.

Commands only. There is no accessor for the document or the layout, because a caller holding either could act on a revision the model has already left behind.

interface PaginatedDocxEditorHandle
MemberTypeSummary
focus
formattingFormatting at the selection, for a toolbar to reflect.
navigate
redo
saveSerialize the current document.
sectionPropertiesThe section the document declares — what a ruler is made of.
selectAll
setParagraphProperty
setRunProperty
toggleRunProperty
type
undo

PaginatedDocxEditorPropsinterfaceSource ↗

interface PaginatedDocxEditorProps
MemberTypeSummary
className?string
documentFontFamily?stringThe face runs naming no font are painted in.
measurer?TextMeasurerHost-supplied font metrics; layout stays DOM-free without it.
onError?(reason: string, detail?: string) => voidCalled once if the document cannot be opened, with the engine's typed reason.
onStateChange?(state: PaginatedSurfaceState) => voidCalled on every committed revision and every selection change.
ref?Ref<PaginatedDocxEditorHandle>
scale?numberPoints to CSS pixels.
sourceUint8ArrayThe document to open. Replacing it remounts the surface.

PaginatedDocxEditorShellPropsinterfaceSource ↗

interface PaginatedDocxEditorShellProps
MemberTypeSummary
className?string
colorMode?'light' | 'dark'Applies the editor's own dark palette; the document canvas stays Word-faithful.
documentFontFamily?stringThe face the document is painted in; never applied to the chrome.
documentName?stringShown in the title bar.
measurer?TextMeasurer
onError?(reason: string, detail?: string) => void
onSave?(bytes: Uint8Array) => voidCalled with the serialized document when File ▸ Save is used.
onStateChange?(state: PaginatedSurfaceState) => void
onZoomChange?(zoom: number) => voidReported when the zoom control changes, so the host can re-scale the surface.
ref?Ref<PaginatedDocxEditorHandle>Commands, forwarded from the editor the shell hosts.
renderTitleBarLeft?() => ReactNodeTitle-bar slots, owned by the HOST.
renderTitleBarRight?() => ReactNode
scale?number
sourceUint8Array

ParagraphStyleItemPropsinterfaceSource ↗

Props for ParagraphStyle.Item.

interface ParagraphStyleItemProps extends ParagraphStylePartProps
MemberTypeSummary
valuestringThe styleId this item applies.

ParagraphStyleNamespaceinterfaceSource ↗

The compound part with its sub-parts attached as statics.

interface ParagraphStyleNamespace
MemberTypeSummary
(member-0)
Contenttypeof ParagraphStyleContent
docxSlot'styles.style'
Itemtypeof ParagraphStyleItem
Triggertypeof ParagraphStyleTrigger

ParagraphStyleOptioninterfaceSource ↗

One pickable paragraph style, as the document defines it.

interface ParagraphStyleOption
MemberTypeSummary
namestring
preview{ readonly fontFamily: string | null; readonly fontSizePt: number | null; readonly bold: boolean; readonly italic: boolean; readonly color: string | null; }How the style looks, for rendering the row in its own face. Every value arrives already bounded by the engine's derivation (family against the CSS-sink shape, colour against six hex digits), which is what makes it safe to put in a style object.
styleIdstring

ParagraphStylePartPropsinterfaceSource ↗

Props for DocxEditorToolbar.StylePicker and its sub-parts.

interface ParagraphStylePartProps
MemberTypeSummary
asChild?boolean
children?ReactNode
className?string

ParagraphStylePropsinterfaceSource ↗

Props for the compound root.

interface ParagraphStyleProps extends ParagraphStylePartProps
MemberTypeSummary
hidden?booleanRender nothing — inside the default arrangement this removes the slot.

ReviewRailRegistryinterfaceSource ↗

Whether a review rail is mounted under this Root, and how much room it wants.

The GUTTER is the reason this exists. DocxEditor.Viewport reserves space beside the page for the pane, and the ruler shifts by the same amount — but neither of them can see whether a rail was actually composed in. Keyed on the pane's open state alone, every consumer of the tier-2 <DocxEditor> sugar (which mounts no rail) had its page pushed 158px off centre beside an empty column.

A rail registers on mount and unregisters on unmount, so the reservation follows what is really on screen. Count rather than boolean: StrictMode mounts twice, and a host may legitimately compose two rails.

interface ReviewRailRegistry
MemberTypeSummary
mountednumber
register() => () => void

SlotPropsinterfaceSource ↗

interface SlotProps extends HTMLAttributes<HTMLElement>
MemberTypeSummary
children?ReactNode
ref?Ref<unknown>Fanned out alongside the child's own ref.

TableBorderColorNamespaceinterfaceSource ↗

Border-colour split compound with a quick-apply main button and swatch dialog (DocxEditor.Toolbar.TableBorderColor).

interface TableBorderColorNamespace extends TableChromePartComponent
MemberTypeSummary
Content(props: TableChromePartProps) => ReactNodeOpen swatch dialog for the active border target.
docxSlot'table.borderColor'Chrome slot id: `table.borderColor`.
Item(props: TableChromeItemProps) => ReactNodeOne colour swatch inside the border-colour dialog.
Main(props: TableChromePartProps) => ReactNodeApplies the last swatch without opening the dialog.
Trigger(props: TableChromePartProps) => ReactNodeButton that opens the border-colour swatch dialog.

TableBorderStyleNamespaceinterfaceSource ↗

Border-style menu compound (DocxEditor.Toolbar.TableBorderStyle).

interface TableBorderStyleNamespace extends TableChromePartComponent
MemberTypeSummary
Content(props: TableChromePartProps) => ReactNodeOpen menu listing line styles for the active target.
docxSlot'table.borderStyle'Chrome slot id: `table.borderStyle`.
Item(props: TableChromeItemProps) => ReactNodeOne line-style row inside the style menu.
Trigger(props: TableChromePartProps) => ReactNodeButton that opens the border line-style menu.

TableBorderTargetNamespaceinterfaceSource ↗

Border-target picker compound (DocxEditor.Toolbar.TableBorderTarget).

interface TableBorderTargetNamespace extends TableChromePartComponent
MemberTypeSummary
Content(props: TableChromePartProps) => ReactNodeOpen menu listing edge scopes and clear.
docxSlot'table.borderTarget'Chrome slot id: `table.borderTarget`.
Item(props: TableChromeItemProps) => ReactNodeOne edge scope or clear row inside the target menu.
Trigger(props: TableChromePartProps) => ReactNodeButton that opens the border-edge target menu.

TableBorderWidthNamespaceinterfaceSource ↗

Border-width menu compound (DocxEditor.Toolbar.TableBorderWidth).

interface TableBorderWidthNamespace extends TableChromePartComponent
MemberTypeSummary
Content(props: TableChromePartProps) => ReactNodeOpen menu listing width presets for the active target.
docxSlot'table.borderWidth'Chrome slot id: `table.borderWidth`.
Item(props: TableChromeItemProps) => ReactNodeOne width preset row inside the width menu.
Trigger(props: TableChromePartProps) => ReactNodeButton that opens the border width menu.

TableCellFillNamespaceinterfaceSource ↗

Cell-fill split compound (DocxEditor.Toolbar.TableCellFill).

interface TableCellFillNamespace extends TableChromePartComponent
MemberTypeSummary
Content(props: TableChromePartProps) => ReactNodeOpen swatch dialog for the selected cell(s).
docxSlot'table.cellFill'Chrome slot id: `table.cellFill`.
Item(props: TableChromeItemProps) => ReactNodeOne fill swatch inside the cell-fill dialog.
Main(props: TableChromePartProps) => ReactNodeApplies the last swatch without opening the dialog.
Trigger(props: TableChromePartProps) => ReactNodeButton that opens the cell-fill swatch dialog.

TableChromeItemPropsinterfaceSource ↗

Props for a value-driven row or swatch inside a table compound menu.

interface TableChromeItemProps extends TableChromePartProps
MemberTypeSummary
valuestringThe pick value this item dispatches (target id, style name, width size, or hex without `#`).

TableChromePartComponentinterfaceSource ↗

Shared compound contract for menu-style table chrome parts ([TableBorderTargetNamespace](TableBorderTargetNamespace), [TableBorderStyleNamespace](TableBorderStyleNamespace), [TableBorderWidthNamespace](TableBorderWidthNamespace)).

interface TableChromePartComponent extends ToolbarSlotPartComponent
MemberTypeSummary
Content(props: TableChromePartProps) => ReactNodeThe open menu or dialog panel; omit to use the default item list.
docxSlotTableChromeSlotIdThe chrome slot this compound drives.
Item(props: TableChromeItemProps) => ReactNodeOne selectable value row or swatch inside [Content](Content).
Trigger(props: TableChromePartProps) => ReactNodeOpens the picker menu or dialog.

TableChromePartPropsinterfaceSource ↗

Props shared by contextual table toolbar compound parts.

interface TableChromePartProps
MemberTypeSummary
asChild?booleanMerge props onto the single child element instead of rendering a default host node.
children?ReactNodeCustom panel body or trigger label; defaults to the packaged control chrome.
className?stringAppended to the part root class list.
hidden?booleanWhen true, the part renders nothing.

ToolbarActionPropsinterfaceSource ↗

Props for DocxEditorToolbar.Action.

interface ToolbarActionProps
MemberTypeSummary
active?booleanPressed state, for an action that toggles. Sets `aria-pressed` and `data-active`.
asChild?booleanMerge the behavior onto the single child element instead of rendering a `<button>`.
children?ReactNode
className?string
disabled?boolean
disabledReason?stringTooltip when disabled — say why, the way the engine's controls do.
icon?ReactNodeIcon content. Inline SVG sized ~18px matches the packaged controls.
labelstringAccessible name and tooltip. A resolved STRING, not an i18n key: the label belongs to the host's own action, so the host's own catalogue resolves it. (Registry controls go the other way — they carry keys and the toolbar's `t` resolves them.)
onSelect?() => void

ToolbarAlignmentComponentinterfaceSource ↗

The merged part is keyed by its GROUP id — it stands in for all four slots.

interface ToolbarAlignmentComponent
MemberTypeSummary
(member-0)
docxSlot'alignment'

ToolbarButtonPropsinterfaceSource ↗

Props for DocxEditorToolbar.Button.

interface ToolbarButtonProps$1
MemberTypeSummary
asChild?booleanMerge the button's behavior into the single child element instead of a <button>.
children?ReactNode
className?string
hidden?booleanRender nothing — inside the default arrangement this removes the slot.
icon?ReactNodeIcon override; falls back to `children`, then to the registry's icon paths.
slotChromeSlotIdThe chrome slot this button drives (`'text.bold'`, `'history.undo'`, ...).

ToolbarPartComponentinterfaceSource ↗

interface ToolbarPartComponent
MemberTypeSummary
(member-0)
docxSlotChromeSlotId

ToolbarPropsinterfaceSource ↗

Props for the Toolbar (formatting rail) component

interface ToolbarProps
MemberTypeSummary
canRedo?booleanWhether redo is available
canUndo?booleanWhether undo is available
children?ReactNodeCustom toolbar items to render at the end
className?stringAdditional CSS class name
currentFormatting?SelectionFormattingCurrent formatting of the selection
disabled?booleanWhether the toolbar is disabled
documentFonts?readonly FontOption[]Fonts the loaded document references that the browser can render (embedded faces + system-resolved). Rendered in a "Document fonts" group, deduped against `fontFamilies`. Managed by the editor, not a consumer prop.
documentStyles?readonly DocumentStyleSummary[]Document styles for the style picker (`Editor.getDocumentStyles()`).
editorRef?react__default.RefObject<HTMLElement>Ref to the editor container for keyboard events
enableShortcuts?booleanWhether to enable keyboard shortcuts (default: true)
fontFamilies?ReadonlyArray<string | FontOption>Custom list of fonts in the toolbar dropdown. When omitted, the built-in 12-font default is used. Strings render in the "Other" group; pass `FontOption[]` for category grouping and CSS fallback chains. An empty array renders an empty (but enabled) dropdown.
imageContext?{ wrapType: string; displayMode: string; cssFloat: string | null; } | nullImage context when an image is selected
inline?booleanWhen true, renders with display:contents so children flow in the parent flex container
onFormat?(action: FormattingAction) => voidCallback when a formatting action is triggered
onImageTransform?(action: 'rotateCW' | 'rotateCCW' | 'flipH' | 'flipV') => voidCallback for image transform (rotate/flip)
onImageWrapType?(wrapType: string) => voidCallback when image wrap type changes
onInsertImage?() => voidCallback when user wants to insert an image
onInsertPageBreak?() => voidCallback when user wants to insert a page break
onInsertSectionBreakContinuous?() => voidCallback when user wants to insert a "continuous" section break
onInsertSectionBreakNextPage?() => voidCallback when user wants to insert a "next page" section break
onInsertShape?(data: { shapeType: string; width: number; height: number; fillColor?: string; fillType?: string; outlineWidth?: number; outlineColor?: string; }) => voidCallback when user wants to insert a shape
onInsertTable?(rows: number, columns: number) => voidCallback when a table should be inserted
onInsertTOC?() => voidCallback when user wants to insert a table of contents
onOpen?() => voidCallback to open/import a DOCX file (File → Open)
onOpenImageProperties?() => voidCallback to open image properties dialog (alt text + border)
onPageSetup?() => voidCallback to open page setup dialog
onPrint?() => voidCallback for print action. Set to enable the File Print menu entry.
onRedo?() => voidCallback for redo action
onRefocusEditor?() => voidCallback to refocus the editor after toolbar interactions
onSave?() => voidCallback to save/download the current DOCX (File → Save)
onTableAction?(action: TableAction) => voidCallback when a table action is triggered
onUndo?() => voidCallback for undo action
onWatermark?() => voidCallback to open the watermark dialog
onZoomChange?(zoom: number) => voidCallback when zoom changes
showAlignmentButtons?booleanWhether to show alignment buttons (default: true)
showFontPicker?booleanWhether to show font family picker (default: true)
showFontSizePicker?booleanWhether to show font size picker (default: true)
showHelpMenu?booleanWhether to show the Help menu in the menu bar (default: true)
showHighlightColorPicker?booleanWhether to show highlight color picker (default: true)
showLineSpacingPicker?booleanWhether to show line spacing picker (default: true)
showListButtons?booleanWhether to show list buttons (default: true)
showStylePicker?booleanWhether to show style picker (default: true)
showTableInsert?booleanWhether to show table insert button (default: true)
showTextColorPicker?booleanWhether to show text color picker (default: true)
showZoomControl?booleanWhether to show zoom control (default: true)
style?CSSPropertiesAdditional inline styles
tableContext?{ isInTable: boolean; rowCount?: number; columnCount?: number; canSplitCell?: boolean; hasMultiCellSelection?: boolean; cellBorderColor?: ColorValue; cellBackgroundColor?: string; } | nullTable context when cursor is in a table
theme?Theme | nullTheme for the style picker / color picker theme matrix
zoom?numberCurrent zoom level (1.0 = 100%)

ToolbarSeparatorPropsinterfaceSource ↗

Props for DocxEditorToolbar.Separator.

interface ToolbarSeparatorProps
MemberTypeSummary
className?string

ToolbarSlotPartComponentinterfaceSource ↗

A non-button part pinned to one slot.

interface ToolbarSlotPartComponent
MemberTypeSummary
(member-0)
docxSlotChromeSlotId

ToolbarSlotPartPropsinterfaceSource ↗

Props for the non-button parts (pickers, steppers, color splits, save).

interface ToolbarSlotPartProps
MemberTypeSummary
className?string
hidden?booleanRender nothing — inside the default arrangement this removes the slot.

UseContentControlResultinterfaceSource ↗

What useContentControl answers.

interface UseContentControlResult
MemberTypeSummary
canRemovebooleanDocument is editable, a control is at the caret, and removal is not locked.
canSetValuebooleanDocument is editable and a control at the caret allows value edits.
closeInspector() => void
controlContentControlInspectorState | nullThe control at the caret, or null when the caret is outside every control.
controlsreadonly ContentControlSummary[]Every control in reading order.
formFillbooleanWhether form-fill Tab navigation is on.
inspectorOpenbooleanWhether the inspector panel is open.
openInspector() => void
remove() => ExecResultUnwrap the control at the caret, keeping content.
removeDisabledReasonstring | nullEngine reason when remove would be refused, else null.
setFormFill(on: boolean) => void
setShowAll(show: boolean) => void
setValue(value: string) => ExecResultSet the control's value (string mapped by type inside the engine).
setValueDisabledReasonstring | nullEngine reason when set-value would be refused, else null.
showAllbooleanWhether show-all boundary chrome is on.
toggleFormFill() => void
toggleInspector() => void
toggleShowAll() => void

UseDocumentOutlineResultinterfaceSource ↗

What useDocumentOutline answers.

interface UseDocumentOutlineResult
MemberTypeSummary
goTo(blockId: string) => voidMove the caret to a heading and bring it into view. Unknown ids are a safe no-op.
headingsreadonly OutlineHeading$1[]The document's headings, in document order. Empty when it has none.
isEmptyboolean
itemsreadonly OutlineHeadingItem[]The same headings with their rendering depth resolved.
selectedBlockIdstring | nullThe heading this pane last navigated to, so a list can show it as current. Tracks the PANE's navigation, not the caret: following the caret would mean walking the document on every selection change, and the engine has no derivation for it yet.

UseDocumentSearchResultinterfaceSource ↗

What useDocumentSearch answers.

interface UseDocumentSearchResult
MemberTypeSummary
activeIndexnumberIndex of the match the caret was last sent to, or `-1` before any navigation.
clear() => voidEmpty the box and drop the results, without touching the selection.
goTo(index: number) => voidSelect a match by index and bring its page into view. Out-of-range is a no-op.
isPendingbooleanWhether a typed query is waiting for its debounce to elapse.
matchCaseboolean
matchesreadonly TextMatch[]Matches for the last RUN query, in document order.
next() => voidNext / previous match, wrapping at the ends the way Word's arrows do.
previous() => void
querystringThe text in the search box, updated synchronously as the user types.
setMatchCase(value: boolean) => void
setQuery(query: string) => void
setWholeWord(value: boolean) => void
truncatedbooleanWhether the engine stopped at its cap with matches still ahead of it, so a count should read "2000+" rather than an exact total. A search that lands on exactly the cap reports true; over-reporting by one is the honest direction.
wholeWordboolean

UseDocxSourceOptionsinterfaceSource ↗

Options for [useDocxSource](useDocxSource).

interface UseDocxSourceOptions
MemberTypeSummary
fetchOptions?RequestInitPassed to `fetch` for a URL source — credentials, headers, an AbortSignal's siblings.
fonts?DocxFontsSource

UseDocxSourceResultinterfaceSource ↗

What [useDocxSource](useDocxSource) reports.

interface UseDocxSourceResult
MemberTypeSummary
documentUint8Array | undefinedBytes for `DocxEditor`'s `document` prop; undefined until they arrive.
errorError | nullWhy the DOCUMENT could not be opened. Font failures never land here — see below.
fontsFontConfiguration | undefinedComposed configuration for the `fonts` prop; undefined until fonts settle.
isLoadingbooleanTrue until the document either arrives or fails.

UseFontFamilyResultinterfaceSource ↗

What useFontFamily answers.

interface UseFontFamilyResult
MemberTypeSummary
isEnabledbooleanWhether the engine would honour a font change right now.
optionsreadonly string[]The offerable font catalog (validated, deduplicated, sorted): the editor's configured families merged with the document's declared ones.
setValue(family: string) => voidApply a family through the can-before-exec path; a refusal is a safe no-op.
valuestring | nullThe selection's agreed family, or null (mixed selection, or no document).

UseHyperlinkPopupResultinterfaceSource ↗

What useHyperlinkPopup answers.

interface UseHyperlinkPopupResult
MemberTypeSummary
beginEdit() => voidSwitch to editing, seeded from the link at the caret.
close() => void
commitEdit() => booleanApply the draft. Answers false when the engine refused it (a bad scheme, no text).
copy() => Promise<boolean>Copy the sanitized target. Answers false when there is nothing safe to copy.
open(link?: SurfaceHyperlink | null, anchor?: HyperlinkPopupAnchor | null) => voidOpen in reading mode over a link, or in editing mode when there is none.
openAtCaret() => voidOpen insert-or-edit for the SELECTION — what Ctrl/Cmd+K and the toolbar's link button do. Anchors itself at the caret, seeds the display text from the selection, and opens edit mode pre-filled when the caret is already inside a link.
openTarget() => booleanOpen the target in a new tab, through the engine's single `window.open` gate. Answers false for an inert link — there is nothing to open, and this never invents a URL.
setText(text: string) => void
setUrl(url: string) => void
stateHyperlinkPopupState

UseNavigationPaneOptionsinterfaceSource ↗

How useNavigationPane is configured.

interface UseNavigationPaneOptions
MemberTypeSummary
defaultOpen?booleanOpen state for the first render when the pane is uncontrolled. Defaults to closed.
defaultTab?NavigationTab$1Tab shown first when uncontrolled. Defaults to `'headings'`.
onOpenChange?(open: boolean) => void
onTabChange?(tab: NavigationTab$1) => void
open?booleanControlled open state. Pair with `onOpenChange`.
paneWidth?numberPanel width in px. Defaults to [NAVIGATION_PANE_WIDTH](NAVIGATION_PANE_WIDTH).
tab?NavigationTab$1Controlled tab. Pair with `onTabChange`.

UseNavigationPaneResultinterfaceSource ↗

What useNavigationPane answers.

interface UseNavigationPaneResult
MemberTypeSummary
openboolean
paneWidthnumber
setOpen(open: boolean) => void
setTab(tab: NavigationTab$1) => void
shiftnumberPx the chrome is displaced by, right now. `0` while the pane is closed AND whenever the left gutter was already wide enough to hold it — which is the point.
tabNavigationTab$1
toggle() => void

UsePageSetupReturninterfaceSource ↗

What usePageSetup returns.

interface UsePageSetupReturn
MemberTypeSummary
apply(update: PageSetupUpdate) => booleanWrite the given fields as one undoable step. Returns whether the engine accepted.
isEnabledbooleanWhether the engine can write page setup right now (mounted, editable).
pageSetupPageSetup | nullThe CARET section's page setup, or null while nothing is loaded. Reference-stable.

UseParagraphIndentReturninterfaceSource ↗

What useParagraphIndent returns.

interface UseParagraphIndentReturn
MemberTypeSummary
apply(update: IndentUpdate) => booleanWrite the given fields as one undoable step. Returns whether the engine accepted.
indentIndentFormatting | nullThe EFFECTIVE indent at the selection — style and numbering cascade included — or null with no document, and inside a table.
isEnabledbooleanWhether the engine can write indent right now (mounted, editable).

UseParagraphStyleResultinterfaceSource ↗

What useParagraphStyle answers.

interface UseParagraphStyleResult
MemberTypeSummary
isEnabledbooleanWhether the engine would honour a style change right now.
optionsreadonly ParagraphStyleOption[]The document's paragraph styles — validated ids and display names, in the engine's Word-gallery order (Normal, Title, Subtitle, the headings, then everything else in document order), NOT the order `styles.xml` happens to list them in.
setValue(styleId: string) => voidApply a paragraph style through the can-before-exec path; a refusal is a safe no-op.
valuestring | nullThe selection's agreed paragraph styleId, or null (unstyled/default, or mixed).

VerticalRulerPropsinterfaceSource ↗

VerticalRuler Component

A vertical ruler that displays alongside the document with: - Page height scale with tick marks - Top and bottom margin indicators - Optional dragging to adjust margins - Support for zoom levels

Similar to Google Docs' vertical ruler.

interface VerticalRulerProps
MemberTypeSummary
className?stringAdditional CSS class name
editable?booleanWhether margins can be dragged to adjust
onBottomMarginChange?(marginTwips: number) => voidCallback when bottom margin changes (in twips)
onMarginDragEnd?() => voidFires when a margin drag is released — the moment to commit what the drag previewed.
onTopMarginChange?(marginTwips: number) => voidCallback when top margin changes (in twips)
pageSetup?RulerPageSetup | nullSection page setup (`Editor.getPageSetup()`), twips throughout
style?CSSPropertiesAdditional inline styles
unit?'inch' | 'cm'Unit to display (inches or cm)
zoom?numberZoom level (1.0 = 100%)

Type aliases (17)

ChromeTranslatetypeSource ↗

A chrome-part label resolver: plain string keys, optional interpolation params.

This is the shape every packaged part's t prop accepts. It takes string rather than the TranslationKey union so a host can route its own extra keys through the same resolver.

type ChromeTranslate = (key: string, params?: Record<string, string | number>) => string;

ContentControlLocktypeSource ↗

OOXML content-control lock axis, mirrored from layout boundary records for the React-only inspector surface — adapters must not import the layout package.

type ContentControlLock = 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';

ContentControlSlotIdtypeSource ↗

type ContentControlSlotId = (typeof CONTENT_CONTROL_SLOTS)[keyof typeof CONTENT_CONTROL_SLOTS];

DocxFontsInputtypeSource ↗

A complete configuration, or a fragment this hook composes with the defaults.

type DocxFontsInput = FontConfiguration | FontConfigurationFragment;

DocxFontsSourcetypeSource ↗

How a host supplies fonts: a value, a promise, or a function returning either.

The function form is the useful one — { fonts: defaultFonts } from @docx-editor.dev/fonts — because it defers the work until the hook actually runs it.

type DocxFontsSource = DocxFontsInput | Promise<DocxFontsInput> | (() => DocxFontsInput | Promise<DocxFontsInput>);

DocxSourcetypeSource ↗

What the document itself can be: a URL to fetch, or bytes already in hand.

type DocxSource = string | URL | Uint8Array | ArrayBuffer;

EditorModetypeSource ↗

type EditorMode = 'edit' | 'view';

FontsInputtypeSource ↗

Anything that can describe fonts: a resolved configuration, a bare fragment, a promise for either (what a loader like defaultFonts() returns), or an on-demand [FontResolver](FontResolver).

type FontsInput = FontConfiguration | FontConfigurationFragment | FontResolver | Promise<FontConfiguration | FontConfigurationFragment | undefined> | undefined;

HeaderFooterStatetypeSource ↗

Live furniture scope state from Editor.getHeaderFooterState().

type HeaderFooterState = Exclude<ReturnType<Editor['getHeaderFooterState']>, null>;

HyperlinkPopupModetypeSource ↗

What the popover is showing.

type HyperlinkPopupMode = 
/** Not shown. */
'closed'
/** An existing link: its target, plus copy / edit / unlink. */
 | 'reading'
/** Text + URL fields, for a new link or a change to an existing one. */
 | 'editing';

A menu's identity: one of the registry's four, or a HOST'S OWN.

The (string & {}) arm keeps the registry ids as editor autocomplete while accepting any other string, so a product can add "Review" or "Clauses" without the library having to know about it. Lives here rather than in parts because the bar's open/active state is keyed on it and both modules read that state.

type MenuId = ChromeMenuId | (string & {});

The pane's tabs. Word's Replace tab is a later slice; nothing here pretends it exists.

type NavigationTab$1 = 'headings' | 'find';

NormalizedImagePayloadtypeSource ↗

type NormalizedImagePayload = {
    readonly ok: true;
    readonly bytes: Uint8Array;
    readonly mime: SupportedImageMime;
    readonly widthPoints: number;
    readonly heightPoints: number;
} | {
    readonly ok: false;
    readonly reasonKey: string;
};

NotePropertiesStatetypeSource ↗

type NotePropertiesState = Exclude<ReturnType<Editor['getNotePropertiesState']>, null>;

OutlineHeadingtypeSource ↗

One heading of the engine's outline: text, 0-based level, and the block id Editor.scrollToBlock accepts.

type OutlineHeading$1 = ReturnType<Editor['getOutline']>[number];

ToolbarPartPropstypeSource ↗

Props for the named parts (DocxEditorToolbar.Bold, ...): the slot is pinned.

type ToolbarPartProps = Omit<ToolbarButtonProps$1, 'slot'>;

ToolbarTranslatetypeSource ↗

Resolves an i18n key to display text.

type ToolbarTranslate = (key: string) => string;

Variables (26)

CONTENT_CONTROL_SLOTSconstSource ↗

Chrome slots for the content-control group (design S14).

CONTENT_CONTROL_SLOTS: {
    readonly showAll: "contentControl.showAll";
    readonly formFill: "contentControl.formFill";
    readonly inspector: "contentControl.inspector";
    readonly remove: "contentControl.remove";
}

ContextMenuCopyconstSource ↗

Copy the selection. Stays available in a read-only document.

ContextMenuCopy: (({ icon, labelKey, shortcutKey, className, hidden }: ContextMenuCommandProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuCutconstSource ↗

Cut the selection to the clipboard. Disabled with the engine's reason when nothing is selected.

ContextMenuCut: (({ icon, labelKey, shortcutKey, className, hidden }: ContextMenuCommandProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuDeleteconstSource ↗

Delete the selection.

ContextMenuDelete: (({ icon, labelKey, shortcutKey, className, hidden }: ContextMenuCommandProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuDeleteTableconstSource ↗

Delete the entire table.

ContextMenuDeleteTable: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuDeleteTableColumnconstSource ↗

Delete the current table column.

ContextMenuDeleteTableColumn: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuDeleteTableRowconstSource ↗

Delete the current table row.

ContextMenuDeleteTableRow: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuInsertColumnLeftconstSource ↗

Insert a column to the left of the current column.

ContextMenuInsertColumnLeft: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuInsertColumnRightconstSource ↗

Insert a column to the right of the current column.

ContextMenuInsertColumnRight: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuInsertRowAboveconstSource ↗

Insert a row above the current table row.

ContextMenuInsertRowAbove: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuInsertRowBelowconstSource ↗

Insert a row below the current table row.

ContextMenuInsertRowBelow: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
    docxRow: string;
}

ContextMenuSelectAllconstSource ↗

Select the whole body.

ContextMenuSelectAll: (({ icon, labelKey, shortcutKey, className, hidden }: ContextMenuCommandProps) => react.JSX.Element | null) & {
    docxRow: string;
}

DocxEditorconstSource ↗

DocxEditor: DocxEditorNamespace

DocxEditorContentControlconstSource ↗

DocxEditorContentControl: DocxEditorContentControlNamespace
DocxEditorHyperLink: DocxEditorHyperLinkNamespace

DocxEditorLoadingconstSource ↗

Renders its children while the editor is still waiting for a document, and nothing once one is available. No condition to wire up in the common case:

tsx <DocxEditor.Root document={bytes}> <DocxEditor.Loading> <MySpinner /> </DocxEditor.Loading> <DocxEditor.Viewport> <DocxEditor.Content /> </DocxEditor.Viewport> </DocxEditor.Root>

It clears as soon as bytes are handed over — NOT when pages finish painting — so it is safe to gate a DocxEditor.Content on, and an unmounted viewport does not bring it back. A parse failure clears it too, so a broken document never spins forever; report that from snapshot().parseError or the error event. Add when only for async the editor cannot observe, typically a host that mounts the provider after its own fetch.

Rendered OUTSIDE a DocxEditor.Root it always shows, because there is no editor to report otherwise — the same rule useEditorState documents for a null editor. Place it inside the provider unless a permanently-visible placeholder is what you want.

Carries its own docx-editor, so the theme tokens resolve wherever it is composed.

DocxEditorLoading: DocxEditorLoadingComponent

DocxEditorMenuconstSource ↗

The compound menu bar: <DocxEditor.Menu/> for File · Format · Insert · Help, parts as statics for composition.

Every actionable row is a chrome slot, so a row and its toolbar twin share one label, one icon, one command and one enabled state. Rows the engine cannot honour yet render present and disabled, carrying the engine's own reason.

DocxEditorMenu: DocxEditorMenuNamespace

DocxEditorToolbarconstSource ↗

The compound toolbar: <DocxEditor.Toolbar/> for the full working chrome, parts as statics for composition (<DocxEditor.Toolbar><DocxEditor.Toolbar.Bold/>...).

DocxEditorToolbar: DocxEditorToolbarNamespace

Clearance kept between the panel's right edge and the page.

NAVIGATION_PANE_GAP = 16

Gap between the viewport's left edge and the panel.

Clears a vertical ruler: RULER_WIDTH is 20px pinned at the viewport's left edge, so anything less puts the panel and its collapsed disc on top of the tick marks.

NAVIGATION_PANE_INSET = 32

Panel width, in px, when the host does not choose one.

NAVIGATION_PANE_WIDTH = 280

ReviewRailContextconstSource ↗

ReviewRailContext: react.Context<ReviewRailRegistry | null>

RULER_WIDTHconstSource ↗

RULER_WIDTH = 20

SEARCH_DEBOUNCE_MSconstSource ↗

Milliseconds of quiet before a typed query is run against the document.

SEARCH_DEBOUNCE_MS = 150

SEARCH_MATCH_LIMITconstSource ↗

The engine's cap on one search. A full result array means "at least this many"; the hook reports that as [UseDocumentSearchResult.truncated](UseDocumentSearchResult.truncated).

SEARCH_MATCH_LIMIT = 2000

VERSIONconstSource ↗

docx-editor.dev/react

React adapter for the DOCX editor. A thin renderer over the Editor contract from @docx-editor.dev/core: it supplies DOM and paints the engine's positioned display list, and holds no editing-engine state.

VERSION = "0.0.2"

Namespaces (6)

ContextMenuCellVerticalAlignmentnamespaceSource ↗

declare namespace ContextMenuCellVerticalAlignment
MemberTypeSummary
docxRow"table.cellVerticalAlignment"

ContextMenuPastenamespaceSource ↗

declare namespace ContextMenuPaste
MemberTypeSummary
docxRow"edit.paste"

ImageAltTextnamespaceSource ↗

declare namespace ImageAltText
MemberTypeSummary
docxSlot"image.altText"

ImageInsertTriggernamespaceSource ↗

declare namespace ImageInsertTrigger
MemberTypeSummary
docxSlot"image.insert"

ImagePropertiesTriggernamespaceSource ↗

declare namespace ImagePropertiesTrigger
MemberTypeSummary
docxSlot"image.properties"

ImageWrapnamespaceSource ↗

declare namespace ImageWrap
MemberTypeSummary
docxSlot"image.wrap"

On this page

Package rootFunctionsContextMenuCellVerticalAlignmentContextMenuItemContextMenuPasteDocumentNameDocxEditorContentDocxEditorContextMenuDocxEditorDocumentOutlineDocxEditorFontNoticeDocxEditorHeaderFooterChromeDocxEditorHorizontalRulerDocxEditorImagePropertiesDialogDocxEditorLoadingSpinnerDocxEditorNavigationDocxEditorNotesChromeDocxEditorPageSetupDialogDocxEditorRootDocxEditorShellDocxEditorVerticalRulerDocxEditorViewportHorizontalRulerImageAltTextImageInsertProviderImageInsertTriggerImagePropertiesTriggerImageWrapLocaleProviderLogoMenuBarNavigationCloseNavigationFindNavigationHeaderNavigationHeadingsnavigationPaneReservationnavigationShiftNavigationTabNavigationTabsNavigationTitleNavigationTogglenormalizeImageBytesPageIndicatorPaginatedDocxEditorPaginatedDocxEditorShellSlotTitleBarTitleBarRightToolbarToolbarButtonToolbarGroupuseChromeTranslateuseContentControluseContentControlInstanceuseContextMenuTargetuseDocumentOutlineuseDocumentSearchuseDocxEditoruseDocxSourceuseEditorCaretuseEditorCommanduseEditorEventuseEditorSnapshotuseEditorStateuseEditorValueCommanduseEditorValueCommanduseFontFamilyuseFontsuseHeaderFooterStateuseHyperlinkPopupuseHyperlinkPopupInstanceuseNavigationPaneuseNavigationShiftuseNotePropertiesStateuseNoteScopeStateusePageSetupuseParagraphIndentuseParagraphStyleuseTableBorderTargetLabeluseTranslationVerticalRulerInterfacesContentControlActionPropsContentControlInspectorStateContentControlPartPropsContentControlPropsContextMenuAnchorContextMenuCommandPropsContextMenuItemPropsContextMenuTableRowPropsDocxEditorContentControlNamespaceDocxEditorContentPropsDocxEditorContextMenuNamespaceDocxEditorContextMenuPropsDocxEditorDocumentOutlinePropsDocxEditorFontNoticePropsDocxEditorHeaderFooterChromePropsDocxEditorHyperLinkNamespaceDocxEditorImagePropertiesDialogPropsDocxEditorLoadingComponentDocxEditorLoadingPropsDocxEditorLoadingSpinnerPropsDocxEditorMenuNamespaceDocxEditorMenuPropsDocxEditorNamespaceDocxEditorNavigationNamespaceDocxEditorNavigationPropsDocxEditorNotesChromePropsDocxEditorPageSetupDialogPropsDocxEditorPropsDocxEditorRefDocxEditorRootPropsDocxEditorRulerPropsDocxEditorToolbarNamespaceDocxEditorToolbarPropsDocxEditorViewportPropsEditorCaretEditorCommandStateEditorValueCommandStateFontFamilyItemPropsFontFamilyNamespaceFontFamilyPartPropsFontFamilyPropsHorizontalRulerPropsHyperLinkActionPropsHyperLinkPartPropsHyperlinkPopupAnchorHyperlinkPopupStateHyperLinkPropsIndentUpdateMenuActionPropsMenuGroupPropsMenuItemPropsMenuPartComponentMenuPropsMenuReportIssuePropsMenuRowPropsMenuSeparatorPropsMenuSubmenuPropsMenuTableGridPropsNavigationPartPropsNavigationShiftInputNavigationTabPropsOutlineHeadingItemPageSetupUpdatePaginatedDocxEditorHandlePaginatedDocxEditorPropsPaginatedDocxEditorShellPropsParagraphStyleItemPropsParagraphStyleNamespaceParagraphStyleOptionParagraphStylePartPropsParagraphStylePropsReviewRailRegistrySlotPropsTableBorderColorNamespaceTableBorderStyleNamespaceTableBorderTargetNamespaceTableBorderWidthNamespaceTableCellFillNamespaceTableChromeItemPropsTableChromePartComponentTableChromePartPropsToolbarActionPropsToolbarAlignmentComponentToolbarButtonPropsToolbarPartComponentToolbarPropsToolbarSeparatorPropsToolbarSlotPartComponentToolbarSlotPartPropsUseContentControlResultUseDocumentOutlineResultUseDocumentSearchResultUseDocxSourceOptionsUseDocxSourceResultUseFontFamilyResultUseHyperlinkPopupResultUseNavigationPaneOptionsUseNavigationPaneResultUsePageSetupReturnUseParagraphIndentReturnUseParagraphStyleResultVerticalRulerPropsType aliasesChromeTranslateContentControlLockContentControlSlotIdDocxFontsInputDocxFontsSourceDocxSourceEditorModeFontsInputHeaderFooterStateHyperlinkPopupModeMenuIdNavigationTabValueNormalizedImagePayloadNotePropertiesStateOutlineHeadingToolbarPartPropsToolbarTranslateVariablesCONTENT_CONTROL_SLOTSContextMenuCopyContextMenuCutContextMenuDeleteContextMenuDeleteTableContextMenuDeleteTableColumnContextMenuDeleteTableRowContextMenuInsertColumnLeftContextMenuInsertColumnRightContextMenuInsertRowAboveContextMenuInsertRowBelowContextMenuSelectAllDocxEditorDocxEditorContentControlDocxEditorHyperLinkDocxEditorLoadingDocxEditorMenuDocxEditorToolbarNAVIGATION_PANE_GAPNAVIGATION_PANE_INSETNAVIGATION_PANE_WIDTHReviewRailContextRULER_WIDTHSEARCH_DEBOUNCE_MSSEARCH_MATCH_LIMITVERSIONNamespacesContextMenuCellVerticalAlignmentContextMenuPasteImageAltTextImageInsertTriggerImagePropertiesTriggerImageWrap