hooks - docx-editor-react

React hooks for editor history, table selection, find/replace, autosave, clipboard, and zoom. Use alongside the main DocxEditor component.

Functions (23)

`clampZoom`functionSource ↗

Clamp zoom to valid range

declare function clampZoom(zoom: number, minZoom?: number, maxZoom?: number): number;

`findNearestZoomPreset`functionSource ↗

Find nearest zoom preset

declare function findNearestZoomPreset(zoom: number): number;

`formatZoom`functionSource ↗

Format zoom level for display

declare function formatZoom(zoom: number): string;

`generateOverlayElements`functionSource ↗

Generate selection overlay elements (for use in JSX)

Usage:

tsx const { highlightRects } = useSelectionHighlight({ ... }); return ( <div style={{ position: 'relative' }}> {generateOverlayElements(highlightRects)} <div>... content ...</div> </div> );

declare function generateOverlayElements(rects: HighlightRect[], config?: SelectionHighlightConfig): React__default.ReactNode[];

`getNextZoomPreset`functionSource ↗

Get next zoom preset (for zoom in)

declare function getNextZoomPreset(zoom: number): number;

`getPreviousZoomPreset`functionSource ↗

Get previous zoom preset (for zoom out)

declare function getPreviousZoomPreset(zoom: number): number;

`getZoomPresets`functionSource ↗

Get zoom presets

declare function getZoomPresets(): number[];

`isZoomPreset`functionSource ↗

Check if zoom level is at a preset

declare function isZoomPreset(zoom: number): boolean;

`parseZoom`functionSource ↗

Parse zoom from percentage string

declare function parseZoom(zoomString: string): number | null;

`useAspectLockedSize`functionSource ↗

declare function useAspectLockedSize(): UseAspectLockedSizeReturn;

`useAutoHistory`functionSource ↗

Simplified hook that just tracks state changes automatically

declare function useAutoHistory<T>(value: T, options?: UseHistoryOptions<T>): Omit<UseHistoryReturn<T>, 'push'>;

`useAutoSave`functionSource ↗

declare function useAutoSave(document: Document | null | undefined, options?: UseAutoSaveOptions): UseAutoSaveReturn;

`useClipboard`functionSource ↗

declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

`useDocumentHistory`functionSource ↗

Hook for document history with specialized comparison

declare function useDocumentHistory<T extends {
    package?: {
        document?: unknown;
        headers?: unknown;
        footers?: unknown;
    } | null;
} | null>(document: T, options?: Omit<UseHistoryOptions<T>, 'isEqual'>): UseHistoryReturn<T>;

`useDragAutoScroll`functionSource ↗

declare function useDragAutoScroll(input: DragAutoScrollOptions): {
    updateMousePosition: (clientX: number, clientY: number) => void;
    stopAutoScroll: () => void;
};

`useFindReplace`functionSource ↗

Hook for managing find/replace dialog state

declare function useFindReplace(hookOptions?: FindReplaceOptions): UseFindReplaceReturn;

`useFixedDropdown`functionSource ↗

declare function useFixedDropdown(input: UseFixedDropdownOptions): UseFixedDropdownReturn;

`useHistory`functionSource ↗

Custom hook for managing undo/redo history

declare function useHistory<T>(initialState: T, options?: UseHistoryOptions<T>): UseHistoryReturn<T>;

`useSelectionHighlight`functionSource ↗

Hook to manage selection highlighting in the editor

declare function useSelectionHighlight(options: UseSelectionHighlightOptions): UseSelectionHighlightReturn;

`useTableSelection`functionSource ↗

declare function useTableSelection(input: UseTableSelectionOptions): UseTableSelectionReturn;

`useTrackedChanges`functionSource ↗

Returns tracked changes (and the comment→revision overlap map for threading) derived from the latest PM state. Memoized on state identity, so derivation only re-runs when PM state changes (which happens on every doc-changing transaction, including remote ones via ySyncPlugin).

No debounce: a single O(N) doc walk, cheap enough to run per transaction. If you see jank on huge documents, wrap the setter that drives the state argument in requestAnimationFrame rather than reintroducing a delay here — a delay makes the sidebar feel laggy.

declare function useTrackedChanges(state: EditorState | null): TrackedChangesResult;

`useVisualLineNavigation`functionSource ↗

declare function useVisualLineNavigation(input: VisualLineNavigationOptions): {
    stickyXRef: React$1.RefObject<number | null>;
    lastVisualLineIndexRef: React$1.RefObject<number>;
    getCaretClientX: (pmPos: number) => number | null;
    findLineElementAtPosition: (pmPos: number) => HTMLElement | null;
    findPositionOnLineAtClientX: (lineEl: HTMLElement, clientX: number) => number | null;
    handlePMKeyDown: (view: EditorView, event: KeyboardEvent) => boolean;
};

`useWheelZoom`functionSource ↗

React hook for Ctrl+scroll zoom functionality

declare function useWheelZoom(options?: UseWheelZoomOptions): UseWheelZoomReturn;

Classes (1)

`HistoryManager`classSource ↗

Create a history manager for non-React usage

declare class HistoryManager<T>

Member	Type	Summary
(constructor)		Constructs a new instance of the `HistoryManager` class
canRedo	`boolean`
canUndo	`boolean`
clear
push
redo
reset
state	`T`
undo

Interfaces (23)

`DragAutoScrollOptions`interfaceSource ↗

Drag Auto-Scroll Hook

When the user is drag-selecting text and moves the mouse near the top or bottom edge of the scroll container, this hook auto-scrolls the container and continues extending the selection.

interface DragAutoScrollOptions

Member	Type	Summary
onScrollExtendSelection	`(clientX: number, clientY: number) => void`	Called during auto-scroll to extend the selection at the current mouse position.
pagesContainerRef	`React.RefObject<HTMLDivElement \| null>`	Ref to the pages container (used to find the scroll parent).

`FindReplaceOptions`interfaceSource ↗

Options for the useFindReplace hook

interface FindReplaceOptions

Member	Type	Summary
initialReplaceMode?	`boolean`	Whether to show replace functionality initially
onCurrentMatchChange?	`(match: FindMatch \| null, index: number) => void`	Callback when current match changes
onMatchesChange?	`(matches: FindMatch[]) => void`	Callback when matches change

`FindReplaceState`interfaceSource ↗

State for the find/replace hook

interface FindReplaceState

Member	Type	Summary
currentIndex	`number`	Current match index
isOpen	`boolean`	Whether the dialog is open
matches	`FindMatch[]`	All matches found
options	`FindOptions`	Find options
replaceMode	`boolean`	Whether in replace mode
replaceText	`string`	Current replace text
searchText	`string`	Current search text

`HistoryEntry`interfaceSource ↗

History entry containing state and metadata

interface HistoryEntry<T>

Member	Type	Summary
description?	`string`	Optional description of what changed
state	`T`	The state at this point
timestamp	`number`	Timestamp when this entry was created

`SelectionOverlayProps`interfaceSource ↗

Props for selection overlay component

interface SelectionOverlayProps

Member	Type	Summary
className?	`string`	Additional class name
config?	`SelectionHighlightConfig`	Style configuration
rects	`HighlightRect[]`	Highlight rectangles to render

`TableSelectionState`interfaceSource ↗

useTableSelection Hook

Thin React wrapper around the framework-agnostic TableSelectionManager. Provides table selection tracking and table operation dispatch.

interface TableSelectionState

Member	Type	Summary
columnIndex	`number \| null`
context	`TableContext \| null`
rowIndex	`number \| null`
table	`Table \| null`
tableIndex	`number \| null`

`UseAspectLockedSizeReturn`interfaceSource ↗

Width/height inputs with an optional aspect-ratio lock. width/height are number | '' so a cleared field shows empty instead of 0.

interface UseAspectLockedSizeReturn

Member	Type	Summary
handleHeightChange	`(raw: string) => void`
handleWidthChange	`(raw: string) => void`	Number-input onChange handlers. Empty string clears, otherwise clamps to = 1.
height	`number \| ''`
lockAspect	`boolean`
seed	`(w: number \| null \| undefined, h: number \| null \| undefined) => void`	Seed both fields and re-lock. Null/undefined values clear the input.
setLockAspect	`(locked: boolean) => void`
width	`number \| ''`

`UseAutoSaveOptions`interfaceSource ↗

Options for useAutoSave hook

interface UseAutoSaveOptions

Member	Type	Summary
debounceDelay?	`number`	Debounce delay for saveOnChange in milliseconds (default: 2000)
enabled?	`boolean`	Whether auto-save is enabled (default: true)
interval?	`number`	Save interval in milliseconds (default: 30000 - 30 seconds)
maxAge?	`number`	Maximum age of auto-save in milliseconds before it's considered stale (default: 24 hours)
onError?	`(error: Error) => void`	Callback when save fails
onRecoveryAvailable?	`(savedDocument: SavedDocumentData) => void`	Callback when recovery data is found
onSave?	`(timestamp: Date) => void`	Callback when save succeeds
saveOnChange?	`boolean`	Whether to save immediately when document changes (debounced)
storageKey?	`string`	Storage key for localStorage (default: 'docx-editor-autosave')

`UseAutoSaveReturn`interfaceSource ↗

Return value of useAutoSave hook

interface UseAutoSaveReturn

Member	Type	Summary
acceptRecovery	`() => Document \| null`
clearAutoSave	`() => void`
disable	`() => void`
dismissRecovery	`() => void`
enable	`() => void`
getRecoveryData	`() => SavedDocumentData \| null`
hasRecoveryData	`boolean`
isEnabled	`boolean`
lastSaveTime	`Date \| null`
save	`() => Promise<boolean>`
status	`AutoSaveStatus`

`UseClipboardOptions`interfaceSource ↗

useClipboard Hook

Thin React wrapper around the framework-agnostic ClipboardManager. Handles clipboard operations with formatting preservation.

interface UseClipboardOptions

Member	Type	Summary
cleanWordFormatting?	`boolean`
editable?	`boolean`
onCopy?	`(selection: ClipboardSelection) => void`
onCut?	`(selection: ClipboardSelection) => void`
onError?	`(error: Error) => void`
onPaste?	`(content: ParsedClipboardContent, asPlainText: boolean) => void`
theme?	`Theme \| null`	Document theme — used to resolve themed colors in the HTML clipboard payload.

`UseClipboardReturn`interfaceSource ↗

interface UseClipboardReturn

Member	Type	Summary
copy	`(selection: ClipboardSelection) => Promise<boolean>`
cut	`(selection: ClipboardSelection) => Promise<boolean>`
handleCopy	`(event: ClipboardEvent) => void`
handleCut	`(event: ClipboardEvent) => void`
handleKeyDown	`(event: KeyboardEvent) => void`
handlePaste	`(event: ClipboardEvent) => void`
isProcessing	`boolean`
lastPastedContent	`ParsedClipboardContent \| null`
paste	`(asPlainText?: boolean) => Promise<ParsedClipboardContent \| null>`

`UseFindReplaceReturn`interfaceSource ↗

Return type for the useFindReplace hook

interface UseFindReplaceReturn

Member	Type	Summary
close	`() => void`	Close the dialog
getCurrentMatch	`() => FindMatch \| null`	Get current match
goToMatch	`(index: number) => void`	Go to a specific match by index
goToNextMatch	`() => number`	Go to next match
goToPreviousMatch	`() => number`	Go to previous match
hasMatches	`() => boolean`	Check if has matches
openFind	`(selectedText?: string) => void`	Open the find dialog
openReplace	`(selectedText?: string) => void`	Open the replace dialog
setMatches	`(matches: FindMatch[], currentIndex?: number) => void`	Set search results
setOptions	`(options: Partial<FindOptions>) => void`	Update find options
setReplaceText	`(text: string) => void`	Update replace text
setSearchText	`(text: string) => void`	Update search text
state	`FindReplaceState`	Current state
toggle	`() => void`	Toggle dialog visibility

`UseFixedDropdownOptions`interfaceSource ↗

Hook for toolbar dropdowns that need position:fixed to escape overflow:auto/hidden ancestors.

Returns refs and styles for a dropdown that positions itself below its trigger using fixed coordinates (like MenuDropdown), so it isn't clipped by the toolbar's overflow-x-auto container.

interface UseFixedDropdownOptions

Member	Type	Summary
align?	`'left' \| 'right'`	'left' aligns dropdown left edge to trigger, 'right' aligns right edge
isOpen	`boolean`
onClose	`() => void`

`UseFixedDropdownReturn`interfaceSource ↗

interface UseFixedDropdownReturn

Member	Type	Summary
containerRef	`RefObject<HTMLDivElement \| null>`
dropdownRef	`RefObject<HTMLDivElement \| null>`
dropdownStyle	`CSSProperties`
handleMouseDown	`(e: React.MouseEvent) => void`

`UseHistoryOptions`interfaceSource ↗

Options for the useHistory hook

interface UseHistoryOptions<T>

Member	Type	Summary
containerRef?	`React.RefObject<HTMLElement>`	Ref to the container element for keyboard events
enableKeyboardShortcuts?	`boolean`	Whether to enable keyboard shortcuts (default: true)
groupingInterval?	`number`	Time in ms to group rapid changes (default: 500)
isEqual?	`(a: T, b: T) => boolean`	Custom comparison function for detecting changes
maxEntries?	`number`	Maximum number of entries in history (default: 100)
onRedo?	`(state: T) => void`	Callback when redo is triggered
onUndo?	`(state: T) => void`	Callback when undo is triggered

`UseHistoryReturn`interfaceSource ↗

Return type of the useHistory hook

interface UseHistoryReturn<T>

Member	Type	Summary
canRedo	`boolean`	Whether redo is available
canUndo	`boolean`	Whether undo is available
clear	`() => void`	Clear all history
getRedoStack	`() => HistoryEntry<T>[]`	Get all redo entries (for debugging/display)
getUndoStack	`() => HistoryEntry<T>[]`	Get all undo entries (for debugging/display)
push	`(newState: T, description?: string) => void`	Push a new state to history
redo	`() => T \| undefined`	Redo to next state
redoCount	`number`	Number of entries in redo stack
reset	`(newInitialState?: T) => void`	Reset to initial state and clear history
state	`T`	Current state
transformAll	`(fn: (state: T) => T) => void`	Transform all stored states (current + undo/redo stacks)
undo	`() => T \| undefined`	Undo to previous state
undoCount	`number`	Number of entries in undo stack

`UseSelectionHighlightOptions`interfaceSource ↗

Options for the useSelectionHighlight hook

interface UseSelectionHighlightOptions

Member	Type	Summary
config?	`SelectionHighlightConfig`	Custom highlight configuration
containerRef	`React__default.RefObject<HTMLElement>`	Reference to the container element
debounceMs?	`number`	Debounce delay for rect updates in ms (default: 16)
enabled?	`boolean`	Whether to enable selection highlighting
onSelectionChange?	`(hasSelection: boolean, text: string) => void`	Callback when selection changes
useOverlay?	`boolean`	Whether to use overlay rectangles (default: false, uses CSS)

`UseSelectionHighlightReturn`interfaceSource ↗

Return value from the useSelectionHighlight hook

interface UseSelectionHighlightReturn

Member	Type	Summary
getOverlayStyle	`(rect: HighlightRect) => CSSProperties`	Get styles for a highlight rect overlay
hasSelection	`boolean`	Whether there is an active selection
highlightRects	`HighlightRect[]`	Highlight rectangles (only populated if useOverlay is true)
isSelectionInContainer	`boolean`	Whether selection is within the container
refresh	`() => void`	Refresh the highlight state
selectedText	`string`	The selected text

`UseTableSelectionOptions`interfaceSource ↗

interface UseTableSelectionOptions

Member	Type	Summary
document	`Document \| null`
onChange?	`(document: Document) => void`
onSelectionChange?	`(context: TableContext \| null) => void`

`UseTableSelectionReturn`interfaceSource ↗

interface UseTableSelectionReturn

Member	Type	Summary
applySplitCell	`(rows: number, cols: number) => void`
clearSelection	`() => void`
getSplitCellConfig	`() => TableSplitConfig \| null`
handleAction	`(action: TableAction) => void`
handleCellClick	`(tableIndex: number, rowIndex: number, columnIndex: number) => void`
isCellSelected	`(tableIndex: number, rowIndex: number, columnIndex: number) => boolean`
state	`TableSelectionState`
tableContext	`TableContext \| null`

`UseWheelZoomOptions`interfaceSource ↗

Options for useWheelZoom hook

interface UseWheelZoomOptions

Member	Type	Summary
containerRef?	`React.RefObject<HTMLElement>`	Container element ref to attach wheel listener
enabled?	`boolean`	Whether zoom is enabled (default: true)
enableKeyboardShortcuts?	`boolean`	Whether to enable keyboard shortcuts (Ctrl++, Ctrl+-, Ctrl+0)
initialZoom?	`number`	Initial zoom level (default: 1.0)
maxZoom?	`number`	Maximum zoom level (default: 4.0)
minZoom?	`number`	Minimum zoom level (default: 0.25)
onZoomChange?	`(zoom: number) => void`	Callback when zoom changes
preventDefault?	`boolean`	Whether to prevent default browser zoom behavior
zoomStep?	`number`	Zoom step for each scroll event (default: 0.1)

`UseWheelZoomReturn`interfaceSource ↗

Return value of useWheelZoom hook

interface UseWheelZoomReturn

Member	Type	Summary
handleKeyDown	`(event: KeyboardEvent) => void`	Keyboard event handler (for manual attachment)
handleWheel	`(event: WheelEvent) => void`	Wheel event handler (for manual attachment)
isMaxZoom	`boolean`	Whether currently at maximum zoom
isMinZoom	`boolean`	Whether currently at minimum zoom
resetZoom	`() => void`	Reset zoom to initial level
setZoom	`(zoom: number) => void`	Set zoom level directly
zoom	`number`	Current zoom level
zoomIn	`() => void`	Zoom in by step
zoomOut	`() => void`	Zoom out by step
zoomPercent	`number`	Zoom percentage (e.g., 100 for zoom level 1.0)
zoomTo100	`() => void`	Reset zoom to 100%
zoomToFit	`(containerWidth: number, contentWidth: number) => void`	Zoom to fit width

`VisualLineNavigationOptions`interfaceSource ↗

interface VisualLineNavigationOptions

Member	Type	Summary
pagesContainerRef	`React.RefObject<HTMLDivElement \| null>`

Variables (1)

`ZOOM_PRESETS`constSource ↗

Preset zoom levels for snapping

ZOOM_PRESETS: number[]

@eigenpal/docx-editor-react/hooks

Functions (23)

clampZoomfunctionSource ↗

findNearestZoomPresetfunctionSource ↗

formatZoomfunctionSource ↗

generateOverlayElementsfunctionSource ↗

getNextZoomPresetfunctionSource ↗

getPreviousZoomPresetfunctionSource ↗

getZoomPresetsfunctionSource ↗

isZoomPresetfunctionSource ↗

parseZoomfunctionSource ↗

useAspectLockedSizefunctionSource ↗

useAutoHistoryfunctionSource ↗

useAutoSavefunctionSource ↗

useClipboardfunctionSource ↗

useDocumentHistoryfunctionSource ↗

useDragAutoScrollfunctionSource ↗

useFindReplacefunctionSource ↗

useFixedDropdownfunctionSource ↗

useHistoryfunctionSource ↗

useSelectionHighlightfunctionSource ↗

useTableSelectionfunctionSource ↗

useTrackedChangesfunctionSource ↗

useVisualLineNavigationfunctionSource ↗

useWheelZoomfunctionSource ↗

Classes (1)

HistoryManagerclassSource ↗

Interfaces (23)

DragAutoScrollOptionsinterfaceSource ↗

FindReplaceOptionsinterfaceSource ↗

FindReplaceStateinterfaceSource ↗

HistoryEntryinterfaceSource ↗

SelectionOverlayPropsinterfaceSource ↗

TableSelectionStateinterfaceSource ↗

UseAspectLockedSizeReturninterfaceSource ↗

UseAutoSaveOptionsinterfaceSource ↗

UseAutoSaveReturninterfaceSource ↗

UseClipboardOptionsinterfaceSource ↗

UseClipboardReturninterfaceSource ↗

UseFindReplaceReturninterfaceSource ↗

UseFixedDropdownOptionsinterfaceSource ↗

UseFixedDropdownReturninterfaceSource ↗

UseHistoryOptionsinterfaceSource ↗

UseHistoryReturninterfaceSource ↗

UseSelectionHighlightOptionsinterfaceSource ↗

UseSelectionHighlightReturninterfaceSource ↗

UseTableSelectionOptionsinterfaceSource ↗

UseTableSelectionReturninterfaceSource ↗

UseWheelZoomOptionsinterfaceSource ↗

UseWheelZoomReturninterfaceSource ↗

VisualLineNavigationOptionsinterfaceSource ↗