Hooks

Call these hooks from components inside <DocxEditor.Root>. The packaged <DocxEditor> provides that root for its children.

Connect a command button

This button runs a toolbar command and shows why the command cannot run:

import { useEditorCommand } from '@docx-editor.dev/react';

function BoldButton() {
  const bold = useEditorCommand('text.bold');
  return (
    <button
      onMouseDown={(e) => e.preventDefault()}
      onClick={() => bold.execute()}
      disabled={!bold.isEnabled}
      data-active={bold.isActive || undefined}
      title={bold.disabledReason ?? 'Bold'}
    >
      B
    </button>
  );
}

useEditorCommand(target: ChromeSlotId | EditorCommand): EditorCommandState takes a slot ID from the chrome slot reference, or a raw EditorCommand such as { type: 'setEditingMode', mode: 'suggesting' }.

Read state and events

useEditorState subscribes to one slice of the snapshot. The component renders only when that slice changes:

import { useEditorState } from '@docx-editor.dev/react';

function PageIndicator() {
  const page = useEditorState((s) => s.page);
  return (
    <span>
      {page.current} / {page.total}
    </span>
  );
}

Pass a comparator for an object slice. Common fields include page, selection, formatting, editable, isLoading, editingMode, canUndo, pageSetup, and lastRejection.

selectionChange also fires when other state moves without a document change, such as the page count. Compare snapshot.selection with the previous value before you react.

useDocxEditor

Use the instance for actions and one-time reads:

import { useDocxEditor } from '@docx-editor.dev/react';

function SaveButton({ upload }: { upload: (bytes: ArrayBuffer) => Promise<void> }) {
  const editor = useDocxEditor();
  return (
    <button
      disabled={!editor}
      onClick={async () => {
        const bytes = await editor?.save();
        if (bytes) void upload(bytes);
      }}
    >
      Save
    </button>
  );
}

Calling editor.snapshot() during render does not subscribe. For scrollToAnchor and highlightAnchor, see Navigation.

Choose a hook

Formatting and page setup

apply sends one command and returns true when it applied.

In useParagraphFormat().format, a field is null when the selected paragraphs differ. usePageSetup uses twips for sizes and margins, and scope takes 'section' or 'document'.

useZoom

For a complete zoom control, see Zoom.

Document content

useWatermark

apply sends one setWatermark command, so each call is one undo step. Pass null to remove the watermark. read() returns the current watermark as a setWatermark value, including picture bytes.

useBookmarks

Each action sends one command and returns ExecResult. goTo works in a read-only document; isWritable reports whether edits are accepted.

Each name has one entry; duplicates counts copies, and keepFirst(name) removes them without moving the selection.

useGoToBookmark({ enabled }) reads bookmarks only while your UI is open. For details, see Bookmarks.

go(name?) targets name, then the highlighted row. For a nonempty query, it then tries an exact name match, ignoring case, then the first result. It returns ExecResult.

useCommentDraftRequest

Register this handler for your own comment UI. review.addComment stays disabled until a handler is registered, and the latest registration wins. Pass null while your UI cannot open a draft.

The handler takes no arguments. Read the selection with editor.getSelectionPlacement(), and pin it with editor.retainSelection() while the draft is open.

Navigation and search

Each outline item is { heading, depth }, and depth counts from the shallowest heading.

setQuery waits 150 milliseconds; find searches at once. truncated means the search stopped at 2,000 matches. For examples, see Navigation.

useHighlights

A function source reruns after document changes, so wrap it in useCallback. For options, see Highlight text ranges.

Loading, fonts, and locale

useDocxSource

useDocxSource fetches the document and its fonts. It accepts a URL string, URL, Uint8Array, or ArrayBuffer, and cancels on change.

For font origins, see Fonts. For refused opens, see Open failures.

Review

@docx-editor.dev/pro/react adds useReview, useReviewOf, useReviewItem, useReviewAuthor, useStackedReviewPositions, and useReviewRailMetrics. See Tracked changes.

Popovers, scopes, and toolbar helpers

Dialog draft contexts

Call these hooks in a child of the matching dialog. Each returns values, setValue(name, value), errors, isEnabled, apply(), and cancel():

Most custom Field names match draft keys, with two exceptions:

Page sizes, margins, and indents use twips (1,440 per inch). Paragraph spacing uses points, except lineValue with lineRule: 'multiple', which is a line multiple. For the compare dialog's progress and cancel state, see Compare documents.

For a custom input, see Connect a custom input.

Apply a value

useEditorValueCommand reads the selected value and applies a new one. This slider sets the font size:

import { useState } from 'react';
import { useEditorValueCommand, useHistoryGroup } from '@docx-editor.dev/react';

export function FontSizeSlider() {
  const size = useEditorValueCommand('font.size');
  const gesture = useHistoryGroup({ kind: 'range' });
  const [error, setError] = useState<string | null>(null);

  return (
    <label title={size.disabledReason ?? undefined}>
      {size.value === null ? 'Mixed' : `${size.value / 2} pt`}
      <input
        ref={gesture.ref}
        type="range"
        min={16}
        max={144}
        value={size.value ?? 22}
        disabled={!size.isEnabled}
        onChange={(event) => {
          const result = size.execute(Number(event.currentTarget.value), gesture.options());
          setError(result.ok ? null : result.reason);
        }}
      />
      <output aria-live="polite">{error}</output>
    </label>
  );
}

Font size uses half-points: 24 means 12 pt. null means mixed or unavailable, and value follows undo and redo. Other value slots include text.color (six hex digits without #), font.family, text.highlight, styles.style, list.lineSpacing, and image slots.

execute(value, options?) returns ExecResult:

useEditorCommand().execute(options) takes the same options but returns a boolean. For the full result of a raw command, call editor.exec(command, options).

Group an input gesture

useHistoryGroup({ kind }): { ref, options } makes a continuous gesture one undo step. Attach ref to the control, and pass options() to each command from that gesture:

The binding disposes the group on unmount or editor replacement. For repeat, your app owns the timer. A native color change does not guarantee that the picker closed.

useEditorEvent('historyDiagnostic', handler) reports interrupted groups. To group a review decision, see Group a review decision.

Limits

• Call hooks inside DocxEditor.Root. Outside it, useDocxEditor() returns null.
• canUndo reports undo availability, not unsaved changes. Track save completion yourself.
• selectionChange also fires for state unrelated to the selection.
• Dialog draft hooks read a draft; they do not open the dialog.
• Image value commands reject the historyGroup option.
• useContentControlWidget().showMonth(year, month) accepts integer years 100 through 9999 and zero-based months 0 through 11.

See also

• React composition
• Chrome slot reference
• React API reference