Browse docs

OverviewInstallationCanvasAll ComponentsFilesPDFCADAnnotationMeasurementPlacementAPI Key ManagementSymbol ManagementCollaborationCompareBatch ExportNavigationAll CapabilitiesStyles
Message API/docs/components/revision/compare

Compare

Send two source files to the viewer and receive a completion or error event for comparison.

Overview

The compare workflow posts a `compare` message with a background file URL and an overlay file URL. The viewer processes both inputs and emits either a completion event or an error event.

Optional compare settings let the host tune rendering DPI and output colors for the generated diff.

Quick Examples

A compare request needs the two file URLs. DPI and output styling are optional.

Send compare

viewerWindow.postMessage({
  type: 'compare',
  payload: {
    backgroundUrl: 'https://example.com/rev-a.pdf',
    overlayUrl: 'https://example.com/rev-b.pdf',
    dpi: 300
  }
}, '*');

Listen for completion

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'comparisonComplete') return;

  console.log(event.data.payload.fileUrl);
});

Listen for errors

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'comparisonError') return;

  console.error(event.data.payload.reason || event.data.payload.message);
});

Control flow

The compare lifecycle is request-driven. The host submits URLs, then waits for either success or failure from the viewer.

Host Sends

1. Host posts compare

Send the two source URLs and any optional compare settings.

javascript
viewerWindow.postMessage({
  type: 'compare',
  payload: {
    backgroundUrl: bgUrl,
    overlayUrl: overlayUrl,
    dpi: 300
  }
}, '*');
Canvas Emits

2. Viewer emits comparisonComplete

On success, the viewer returns a completion payload that can include the output file URL.

javascript
window.addEventListener('message', (event) => {
  if (event.data?.type !== 'comparisonComplete') return;

  const payload = event.data.payload;
  openResult(payload.fileUrl);
});
Canvas Emits

3. Viewer emits comparisonError

On failure, surface the reason to the user and keep the compare form editable.

javascript
window.addEventListener('message', (event) => {
  if (event.data?.type !== 'comparisonError') return;

  showError(event.data.payload.reason || 'Compare failed');
});

Complete Implementation

This host-side pattern sends compare requests and handles both completion and failure events from the viewer.

function compareFiles(backgroundUrl, overlayUrl) {
  viewerWindow.postMessage({
    type: 'compare',
    payload: {
      backgroundUrl,
      overlayUrl,
      dpi: 300
    }
  }, '*');
}

window.addEventListener('message', (event) => {
  const data = event.data;
  if (!data) return;

  if (data.type === 'comparisonComplete') {
    console.log('Compare result:', data.payload.fileUrl);
    return;
  }

  if (data.type === 'comparisonError') {
    console.error(data.payload.reason || data.payload.message);
  }
});
Complete Implementation

Additional Resources

Use align when the two source files need point matching before comparison.