Track changes with Apryse DOCX Editor

Requirements

These packages are required to use these features in production. Trial keys have unlimited access to all features

Package: DOCX EditorLive demo

Deprecation notice

With version 12.0, the namespace for tracked change APIs has moved from Core.Document.OfficeEditor to Core.Document.OfficeEditor.TrackedChangeManager. See the migration guide for details.

Tracked changes let users suggest, review, and manage edits in a DOCX document, making it easier to collaborate while preserving a clear history of what changed, who made each change, and when.

Tracked changes in the document and review sidebar.

Tracked changes can be created by typing in reviewing mode. They may be accepted or rejected from the reviewing panel while in reviewing mode or by clicking the tracked change in editing mode.

Inline tracked change in Editing mode with accept and reject controls.

TrackedChangeManager API

The Core.Document.OfficeEditor.TrackedChangeManager API provides programmatic control over tracked changes in the DOCX Editor. You can manage review workflows entirely through code, without relying on the default editor UI.

You can also use the API to build a fully custom review experience without relying on the default UI. For example, you can create a custom tracked changes panel, integrate changes into your own UI, or implement tailored review workflows using the provided methods and related events:

• Retrieve changes – Access all tracked changes in document order.
• Navigate within the document – Move the text cursor to a specific change and scroll it into view.
• Work with selection – Select tracked changes programmatically and respond to selection changes using events.
• Perform actions – Accept or reject individual or multiple tracked changes programmatically.
• Handle updates incrementally – Listen for events indicating changes being added, modified, or removed.

Get tracked changes

Tracked changes can be retrieved by using the getTrackedChanges API.

JavaScript

WebViewer(...)
  .then(instance => {
    instance.Core.documentViewer.addEventListener('documentLoaded', async () => {
      const trackedChangeManager = instance.Core.documentViewer.getDocument().getOfficeEditor().getTrackedChangeManager();
      // Retrieves a list of tracked changes ordered by their position in the document
      const trackedChanges = await trackedChangeManager.getTrackedChanges();
    });
  });

getTrackedChanges()

Tracked changes are returned as an array of TrackedChange objects, ordered by their position in the document.

JSON

{
  "id": "number - The unique identifier of the object",
  "type": "'inserted'|'deleted' | 'formatted' - The type of tracked change",
  "author": "string - The author of the tracked change",
  "date": "Date - The date of the tracked change",
  "plainText": "string - The content of the tracked change to be inserted or deleted",
  "getPagePositions": "function - Returns a promise that resolves to an array of objects containing {pageNumber: number, rect: Core.Math.Rect} for each annotation related to the tracked change"
}

TrackedChange

Navigate tracked changes

Jump to a tracked change by ID using the navigateToTrackedChange API. This moves the text cursor to the beginning of the change and scrolls it into view.

JavaScript

WebViewer(...)
  .then(instance => {
    instance.Core.documentViewer.addEventListener('documentLoaded', async () => {
      const trackedChangeManager = instance.Core.documentViewer.getDocument().getOfficeEditor().getTrackedChangeManager();
      const trackedChanges = await trackedChangeManager.getTrackedChanges();
      
      // Get id of last tracked change and navigate to it
      const lastTrackedChangeId = trackedChanges[trackedChanges.length - 1];
      await trackedChangeManager.navigateToTrackedChange(lastTrackedChangeId);
    });
  });

navigateToTrackedChange()

Select tracked changes

You can programmatically select a tracked change by ID using the selectTrackedChange API, which highlights the change in the UI. You can also listen for selection changes using the trackedChangeSelected event, which is triggered whenever a tracked change is selected or deselected.

JavaScript

WebViewer(...)
  .then(instance => {
    instance.Core.documentViewer.addEventListener('documentLoaded', async () => {
      const trackedChangeManager = instance.Core.documentViewer.getDocument().getOfficeEditor().getTrackedChangeManager;
      const trackedChanges = await officeEditor.getTrackedChanges();
      
      // Set up listener for tracked change selection
      instance.Core.documentViewer.getDocument().addEventListener('trackedChangeSelected', (trackedChange, action) => {
        // Contains tracked change object and 'selected' or 'deselected' action
        console.log(trackedChange, action);
      });
      
      // Find tracked change ID to select
      const firstChangeId = trackedChanges[0].id;
      
      // Programatically select a tracked change with an API
      await trackedChangeManager().selectTrackedChange(firstChangeId);
    });
  });

selectTrackedChange() trackedChangeSelected

Modify tracked changes

You can programmatically accept or reject tracked changes by calling the appropriate APIs with the IDs obtained from the tracked changes list.

JavaScript

WebViewer(...)
  .then(instance => {
    instance.Core.documentViewer.addEventListener('documentLoaded', async () => {
      const trackedChangeManager = instance.Core.documentViewer.getDocument().getOfficeEditor().getTrackedChangeManager();
      const trackedChanges = await trackedChangeManager.getTrackedChanges();
      
      // Accept tracked change by ID
      await trackedChangeManager.acceptTrackedChange(trackedChanges[0].id);
      
      // Reject tracked change by ID
      await trackedChangeManager.rejectTrackedChange(trackedChanges[1].id);
    });
  });

acceptTrackedChange() rejectTrackedChange()

Multiple tracked changes can also be programmatically accepted or rejected by using an array of tracked change IDs.

JavaScript

WebViewer(...)
  .then(instance => {
    instance.Core.documentViewer.addEventListener('documentLoaded', async () => {
      const trackedChangeManager = instance.Core.documentViewer.getDocument().getOfficeEditor().getTrackedChangeManager;
      const trackedChanges = await officeEditor.getTrackedChanges();
      const allTrackedChangeIds = trackedChanges.map(c => c.id);
      
      // Accept all tracked changes by their IDs
      await trackedChangeManager.acceptTrackedChanges(allTrackedChangeIds);
      
      // Reject all tracked changes by their IDs
      await trackedChangeManager.rejectTrackedChanges(allTrackedChangeIds);
    });
  });

acceptTrackedChanges() rejectTrackedChanges()

Get tracked change positions

Use the getPagePositions() method to retrieve the on-page locations of a single tracked change, including its bounding rectangles and page numbers. This shows where the tracked-change markup appears in the document when the method is called. It can be useful for positioning UI elements such as tooltips, highlights, or custom overlays.

JavaScript

WebViewer(...)
  .then(instance => {
    instance.Core.documentViewer.addEventListener('documentLoaded', async () => {
      const trackedChangeManager = instance.Core.documentViewer.getDocument().getOfficeEditor().getTrackedChangeManager();
      const trackedChanges = await trackedChangeManager.getTrackedChanges();
      
      // Check positions of first tracked change in document
      const trackedChangePositions = await trackedChanges[0].getPagePositions();
      const startRect = trackedChangePositions[0].rect; // the first rect position of the tracked change
      const startPageNumber = trackedChangePositions[0].pageNumber; // the first page the tracked change appears
      const endRect = trackedChangePositions[trackedChangePositions.length - 1].rect; // the last rect position of the tracked change
      const endPageNumber = trackedChangePositions[trackedChangePositions.length - 1].pageNumber; // the last page the tracked change appears
    });
  });

TrackedChange Core.Math.Rect

Listen for change updates

Listen for tracked change updates using the trackedChangesUpdated event. This event is triggered when a tracked change is added, modified, or deleted.

JavaScript

WebViewer(...)
  .then(instance => {
    instance.Core.documentViewer.addEventListener('documentLoaded', async () => {
      const officeEditor = instance.Core.documentViewer.getDocument().getOfficeEditor();
      let trackedChanges = await officeEditor.getTrackedChanges();
      
      // Set up listener to respond to updates about tracked changes
      instance.Core.documentViewer.getDocument().addEventListener('trackedChangesUpdated', (trackedChange, action) => {
        switch (action) {
          case 'add':
            trackedChanges = [...trackedChanges, trackedChange];
            break;
          case 'delete':
            trackedChanges = trackedChanges.filter(tc => tc.id !== trackedChange.id);
            break;
          case 'modify':
            trackedChanges = trackedChanges.map(tc => tc.id === trackedChange.id ? trackedChange : tc);
            break;
        }
      });
    });
  });

trackedChangesUpdated