Document refresh API

Use createDocumentRefresh(editor) to display complete DOCX files that your server returns. The controller keeps the editor instance, subscriptions, and scroll position. Your application receives each result; the editor does not watch files or URLs.

The controller is a host integration API, separate from the Office.js-shaped automation model. If your agent can issue document edits, use Revisions instead.

API overview

Call createDocumentRefresh(editor) after the editor mounts. Repeated calls for one editor return the same controller. Import it from your adapter or @docx-editor.dev/core/editor.

The flow is capture(), then your server job, then applyUpdate(), then finish().

Apply an updated DOCX

Capture the document, send its bytes to your backend, and apply the response:

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

const refresh = createDocumentRefresh(editor);
const submission = await refresh.capture();

try {
  const response = await fetch('/api/update-document', {
    method: 'POST',
    body: submission.bytes,
  });
  if (!response.ok) throw new Error('Processing failed');

  const result = await refresh.applyUpdate({
    submission,
    sequence: 1,
    bytes: await response.arrayBuffer(),
  });
  if (result.ok) {
    refresh.highlightChanges();
  } else {
    showRefreshError(result.code);
  }
} finally {
  refresh.finish(submission);
}

Get editor from useDocxEditor() inside the editor root. React returns an instance or null; Vue returns a shallow ref.

• capture() commits buffered input and form input, and waits for text composition to end.
• Pass the same submission object to applyUpdate(). A copied, superseded, or other editor's token cannot authorize replacement.
• Any edit after capture makes applyUpdate() return local-edits, even after undo. Capture again; do not replay the old result.
• applyUpdate() resolves after the replacement lays out its opening pages and accepts clicks.

Receive cumulative results

The processor assigns each result a nonnegative integer sequence. Each file holds the complete cumulative output for the submission:

const submission = await refresh.capture();

try {
  for await (const update of receiveProcessorUpdates(submission.bytes)) {
    const result = await refresh.applyUpdate({
      submission,
      sequence: update.sequence,
      bytes: update.bytes,
      changes: update.changes,
      failures: update.failedOperationIds,
    });
    if (!result.ok) {
      if (result.code === 'out-of-order') continue;
      showRefreshError(result.code);
      break;
    }
    showChanges(result.changes);
    showPartialFailures(result.failures);
  }
} finally {
  refresh.finish(submission);
}

Do not start processing from every change event. Replacement events have source: 'refresh' or source: 'recovery', loads have source: 'load', and user edits omit source:

editor.on('change', (change) => {
  if (change.source) return;
  scheduleProcessing();
});

Provide change locations

A plain file does not identify its changes, and the controller does not compare files. Without metadata or tracked revisions, the result reports changeInformation: 'unavailable'. Supply metadata with stable IDs across cumulative results:

const result = await refresh.applyUpdate({
  submission,
  sequence: 2,
  bytes: updatedBytes,
  changes: [
    {
      id: 'delivery-date',
      description: 'Changed the delivery date',
      location: { paragraphId: '00A12B34', start: 10, end: 20, text: 'October 12' },
    },
    { id: 'removed-clause', description: 'Removed a clause', unavailableReason: 'deleted' },
    { id: 'footer-version', description: 'Updated the footer version' },
  ],
});

Invalid location metadata does not reject valid document bytes. That change gets a non-available status and a diagnostic.code, with the requested diagnostic.location:

If you omit changes, a registered review module supplies tracked revision locations. Revisions present at capture do not count as new. The review module requires the EigenPal Pro License.

Present changes

Highlight new available changes after a successful applyUpdate(), then navigate:

const target = refresh
  .snapshot()
  .changes.find((change) => change.isNew && change.status === 'available');

if (target && refresh.navigateToChange(target.id, { block: 'centerIfNeeded' })) {
  refresh.highlightChanges({ changeIds: [target.id], timeoutMs: 3000 });
}

• isNew marks new IDs, changed text, and changed descriptions within one submission.
• Locations stay valid until the next accepted result or local edit.
• Highlights change presentation only. They add no saved bytes and no undo entries.
• Keep a text change list beside the document, because color alone does not explain a change.

This simulation shows highlights, navigation, and refusals with sample text:

Customize highlights and motion

RefreshHighlightOptions extends AnchorHighlightOptions. The shared color, border, padding, timing, and animation options are listed in Highlight a paragraph reference. Refresh differs in these options:

Each call starts from the defaults, so reuse one options object. Repeated calls reset the timeout without replaying the entrance. To replay it, call clearHighlights({ animation: false }) first.

• highlightChanges() validates options even when change locations are stale or unavailable.
• animation.exitDurationMs defaults to durationMs and accepts 0 through 10000 milliseconds.
• Expiration removes the styling. Change metadata and navigation stay available.
• Without overrides, clearHighlights() uses the last requested exit duration and easing. snapshot().highlightsVisible becomes false when dismissal starts, before the exit animation ends.

Control change navigation

navigateToChange() takes NavigateToChangeOptions:

Navigation returns false for an unavailable location or during replacement. It does not wait for smooth scrolling. Invalid modes throw TypeError; invalid padding throws RangeError.

Handle refusals and recovery

applyUpdate() returns { ok: false, code } with a RefreshFailureCode. capture() rejects with DocumentRefreshError, whose code is a RefreshFailureCode. Handle codes, not messages:

Do not retry a refused result blindly. Connect your cancel control to both the transport and the controller, because cancellation does not reverse accepted files:

const transport = new AbortController();
// Pass transport.signal to your fetch calls.
function cancelProcessing() {
  transport.abort();
  refresh.cancel();
}

When refresh.snapshot().recoveryAvailable is true, offer two controls:

• await refresh.recover() reloads the previous document, resets selection and undo history, and resolves false on failure.
• refresh.recoveryBytes() returns the document from before the failed replacement, for download.

Recovery bytes are not an undo archive for accepted files.

Limits

• Each accepted file replaces the whole document and resets selection, undo history, and some review state.
• Refresh refuses collaborative sessions, including disconnected ones.
• Scroll uses pixel offsets. A shorter file clamps the offset; neither case keeps the same subject in view.
• The controller does not compare document meaning or reject unrelated content. Check document and job identity in your application before applyUpdate().
• An ordinary editor.load() invalidates pending submissions and recovery.
• Highlight numbers must be finite. padding, borderRadius, and borderWidth must be nonnegative. timeoutMs accepts 0 through 2147483647 milliseconds, or null.
• Reduced-motion preferences cap fades at 125 milliseconds and make smooth navigation instant.

See also

• Connect an agent to a document
• Navigate a document
• DOCX document refresh example