New

docx-editor 1.x has shipped. Vue support, i18n, agents. Read the migration guide →

API Referencev1.0.2

@eigenpal/docx-editor-react/dialogs

Modal dialogs for hyperlinks, find/replace, paste-special, page setup, and keyboard shortcuts. Pair with the hooks under `@eigenpal/docx-editor-react/hooks` when wiring custom UI.

Functions(26)

Create HyperlinkData for an internal bookmark

declare function createBookmarkLinkData(bookmark: string, displayText?: string): HyperlinkData;

Create HyperlinkData from a URL string

declare function createHyperlinkData(url: string, displayText?: string): HyperlinkData;

Convert email address to mailto: link

declare function emailToMailto(email: string): string;

Extract bookmarks from document for the dialog

declare function extractBookmarksForDialog(bookmarks: {
    name: string;
    id: number;
}[]): BookmarkOption[];

FindReplaceDialog component - Modal for finding and replacing text

declare function FindReplaceDialog(input: FindReplaceDialogProps): React__default.ReactElement | null;

Format key combination for current platform

declare function formatKeys(keys: string): string;

Get all categories

declare function getAllCategories(): ShortcutCategory[];

Get all paste option definitions

declare function getAllPasteOptions(): PasteOptionDef[];

Get category label translation key

declare function getCategoryLabel(category: ShortcutCategory): string;

Get common/frequently used shortcuts

declare function getCommonShortcuts(): KeyboardShortcut[];

Get default paste option

declare function getDefaultPasteOption(): PasteOption;

Get all default shortcuts

declare function getDefaultShortcuts(): KeyboardShortcut[];

Get display text from HyperlinkData, falling back to URL/bookmark

declare function getDisplayText(data: HyperlinkData): string;

Get paste option definition by id

declare function getPasteOption(id: PasteOption): PasteOptionDef | undefined;

Get shortcuts by category

declare function getShortcutsByCategory(category: ShortcutCategory): KeyboardShortcut[];

Detect URL type from string

declare function getUrlType(url: string): 'web' | 'email' | 'phone' | 'ftp' | 'unknown';

HyperlinkDialog component - Modal for inserting/editing hyperlinks

declare function HyperlinkDialog(input: HyperlinkDialogProps): React__default.ReactElement | null;

Check if HyperlinkData is for an internal bookmark

declare function isBookmarkHyperlinkData(data: HyperlinkData): boolean;

Check if HyperlinkData is for an external URL

declare function isExternalHyperlinkData(data: HyperlinkData): boolean;

Check if paste special shortcut

declare function isPasteSpecialShortcut(event: KeyboardEvent): boolean;

Validate a URL string Supports http, https, mailto, tel, ftp protocols

declare function isValidUrl(url: string): boolean;

Normalize a URL by adding protocol if needed

declare function normalizeUrl(url: string): string;
declare function PageSetupDialog(input: PageSetupDialogProps): React__default.ReactElement | null;

Convert phone number to tel: link

declare function phoneToTel(phone: string): string;

Hook to manage keyboard shortcuts dialog

declare function useKeyboardShortcutsDialog(options?: UseKeyboardShortcutsDialogOptions): UseKeyboardShortcutsDialogReturn;

Hook to manage paste special dialog

declare function usePasteSpecial(options?: UsePasteSpecialOptions): UsePasteSpecialReturn;

Interfaces(12)

Bookmark option for internal link selection

interface BookmarkOption
MemberTypeSummary
label?stringOptional display label
namestringBookmark name/ID

Props for the FindReplaceDialog component

interface FindReplaceDialogProps
MemberTypeSummary
className?stringAdditional CSS class
currentResult?FindResult | nullCurrent match result (from external state)
initialSearchText?stringInitial search text (e.g., from selected text)
isOpenbooleanWhether the dialog is open
onClearHighlights?() => voidCallback to clear highlights
onClose() => voidCallback when dialog is closed
onFind(searchText: string, options: FindOptions) => FindResult | nullCallback when searching for text
onFindNext() => FindMatch | nullCallback when navigating to next match
onFindPrevious() => FindMatch | nullCallback when navigating to previous match
onHighlightMatches?(matches: FindMatch[]) => voidCallback to highlight matches in document
onReplace(replaceText: string) => booleanCallback when replacing current match
onReplaceAll(searchText: string, replaceText: string, options: FindOptions) => numberCallback when replacing all matches
replaceMode?booleanWhether to start in replace mode
style?CSSPropertiesAdditional inline styles

Hyperlink data structure for dialog

interface HyperlinkData
MemberTypeSummary
bookmark?stringInternal bookmark name
displayText?stringDisplay text for the link
tooltip?stringTooltip text
url?stringURL for external link

Props for the HyperlinkDialog component

interface HyperlinkDialogProps
MemberTypeSummary
bookmarks?BookmarkOption[]Available bookmarks for internal links
className?stringAdditional CSS class
initialData?HyperlinkDataInitial data for editing existing hyperlink
isEditing?booleanWhether we're editing an existing hyperlink
isOpenbooleanWhether the dialog is open
onClose() => voidCallback when dialog is closed
onRemove?() => voidCallback when hyperlink is removed
onSubmit(data: HyperlinkData) => voidCallback when hyperlink is inserted/updated
selectedText?stringCurrently selected text (used as default display text)
style?CSSPropertiesAdditional inline styles

Keyboard shortcut definition

interface KeyboardShortcut
MemberTypeSummary
altKeys?stringAlternative key combination
categoryShortcutCategoryCategory for grouping
common?booleanWhether this is a common/frequently used shortcut
descriptionstringDescription of what the shortcut does
descriptionKey?TranslationKeyTranslation key for description (used internally)
idstringUnique identifier
keysstringPrimary key combination (e.g., 'Ctrl+C')
namestringDisplay name
nameKey?TranslationKeyTranslation key for display name (used internally)

Dialog props

interface KeyboardShortcutsDialogProps
MemberTypeSummary
className?stringAdditional className
customShortcuts?KeyboardShortcut[]Custom shortcuts (merged with defaults)
isOpenbooleanWhether the dialog is open
onClose() => voidClose callback
showSearch?booleanWhether to show search

Page Setup Dialog

Modal for editing page layout properties: - Page size (Letter, A4, Legal, etc.) - Orientation (portrait/landscape) - Margins (top, bottom, left, right) in inches

interface PageSetupDialogProps
MemberTypeSummary
currentProps?SectionProperties
isOpenboolean
onApply(props: Partial<SectionProperties>) => void
onClose() => void

Paste special dialog props

interface PasteSpecialDialogProps
MemberTypeSummary
className?stringAdditional className
isOpenbooleanWhether the dialog is open
onClose() => voidCallback when dialog is closed
onPaste(content: ParsedClipboardContent, asPlainText: boolean) => voidCallback when paste is confirmed
position?{ x: number; y: number; }Optional custom position

Hook options

interface UseKeyboardShortcutsDialogOptions
MemberTypeSummary
enabled?booleanWhether the dialog can be opened with Ctrl+? or F1
openShortcut?stringCustom open shortcut (default: Ctrl+/)

Hook return value

interface UseKeyboardShortcutsDialogReturn
MemberTypeSummary
close() => voidClose the dialog
handleKeyDown(event: KeyboardEvent) => voidKeyboard event handler
isOpenbooleanWhether dialog is open
open() => voidOpen the dialog
toggle() => voidToggle the dialog

Options for usePasteSpecial hook

interface UsePasteSpecialOptions
MemberTypeSummary
enabled?booleanWhether paste operations are enabled
onPaste?(content: ParsedClipboardContent, asPlainText: boolean) => voidCallback when paste is confirmed

Hook return value for paste special

interface UsePasteSpecialReturn
MemberTypeSummary
closeDialog() => voidClose the dialog
handleKeyDown(event: KeyboardEvent) => booleanHandle keyboard shortcut (Ctrl+Shift+V)
isOpenbooleanWhether the dialog is open
openDialog() => voidOpen the paste special dialog
pasteAsPlainText() => Promise<void>Paste as plain text directly

Type aliases(2)

Paste option type

type PasteOption = 'formatted' | 'plainText';

Shortcut category

type ShortcutCategory = 'editing' | 'formatting' | 'navigation' | 'clipboard' | 'selection' | 'view' | 'file' | 'other';

Variables(2)

KeyboardShortcutsDialog: React__default.FC<KeyboardShortcutsDialogProps>
PasteSpecialDialog: React__default.FC<PasteSpecialDialogProps>