Use tracked changes and editor modes

Install Nutrient Document Authoring SDK and load it in your app. If you haven’t set it up, start with the getting started guide.

Use tracked changes to review edits in Nutrient Document Authoring SDK. Authorized users can create revisions, inspect them, and accept or reject them in the editor.

The examples omit error handling. Add it before using this code in production.

Understand the editor modes

Nutrient Document Authoring SDK supports three editor modes:

edit — Changes apply directly, while existing tracked changes remain visible.
review — The editor records supported edits as tracked revisions, while tracked changes remain visible.
view — The editor disables editing, while tracked changes remain visible.

Use editor.getEditorMode() to inspect the current mode:

const mode = editor.getEditorMode();
console.log(mode);

Switch modes at runtime

Use editor.setEditorMode(mode) to move between editing states:

editor.setEditorMode('edit');
editor.setEditorMode('review');
editor.setEditorMode('view');

Use each mode for a different workflow: drafting, review, or read-only access.

Create tracked changes in review mode

In review mode, the editor records supported edits as tracked changes instead of applying them directly:

editor.setAuthor('Jane Reviewer');
editor.setEditorMode('review');

The editor attributes each revision to the current author.

Supported changes and limitations

These support details apply to Nutrient Document Authoring SDK 2.0.0.

Tracked changes, also called redlines, record supported edits as revisions that reviewers can accept or reject. Formatting revisions may appear as change descriptions instead of inserted or crossed-out text.

Support depends on the operation and how you apply it. Creating a revision, resolving an imported revision, and preserving revisions through DOCX export and import are separate capabilities.

Changes that create revisions

The table lists editing operations supported in review mode. Programmatic edits require a review transaction; switching editor modes alone doesn’t enable tracking for host-owned transactions.

Document change	Tracking behavior
Insert, delete, or replace text	Creates insertion or deletion revisions. A replacement can create both.
Insert or delete paragraphs and paragraph marks	Creates revisions for paragraph content and structure.
Insert or delete tabs, line breaks, and page breaks	These inline elements can carry insertion or deletion revisions.
Change text formatting	Tracks font, size, bold, italic, underline, strikeout, color, and highlight changes.
Change paragraph formatting	Tracks paragraph styles, alignment, spacing, indentation, tab stops, shading, and borders.
Change lists and numbering	Tracks changes to a paragraph’s list and numbering properties.
Edit hyperlinks in the editor	Tracks hyperlink changes through the editor’s review operations.
Insert or delete tables, rows, columns, and cells	Tracks supported structural operations. Whole-table changes use revisions on the table’s rows and cells.
Change table, cell, or column formatting in the editor	Creates table-property, cell-property, or table-grid revisions.
Edit content in an existing header or footer	Supports tracked text and formatting edits, including content in tables within the header or footer.
Edit text inside shapes, footnotes, or endnotes	Supports revisions through their content editing operations.
Insert images, shapes, or fields	Supported insertion operations create revisions. Changes to an existing object’s properties have separate limitations below.

Formatting applied to inserted content in the same review transaction can become part of its insertion revision and may not create a separate formatting revision. If you insert and remove content in the same transaction, the insertion can be canceled.

Headers and footers

Tracked changes support text edits inside existing headers and footers. Replacing a company name in a footer, for example, can create deletion and insertion revisions. The revision API identifies these locations, including default, first-page, and even-page variants.

Header and footer configuration has separate limitations:

Review mode doesn’t support changing the document’s odd/even header and footer mode.
Changing the different-first-page setting isn’t fully reversible through tracked changes. Rejecting an associated section revision doesn’t restore that setting.
Changing header or footer distances follows the page-margin behavior described below.

Page setup and section changes

The editing method determines whether page setup changes create revisions:

Operation	Tracking behavior
Change page size or margins through the editor’s section-formatting commands	Creates a section-property revision that stores the previous page setup.
Change page size or margins through programmatic page-setup setters	Applies directly without a revision, including header and footer distances.
Drag page margins using the ruler	Applies directly without a revision.
Add or remove a section break through the programmatic API	Applies directly without a revision.

Edits applied without tracking

The following operations don’t create tracked revisions. Permissions can block an operation, and review mode doesn’t guarantee that every permitted edit creates a revision.

Document change	Limitation
Resize, rotate, reposition, or reorder an existing image or shape	Object-property changes apply without revisions.
Set a shape’s geometry, fill, or outline programmatically	Applies directly without a revision.
Reposition a floating table	Applies directly without a revision.
Merge or unmerge cells in the editor	Does not create a cell-merge revision. The SDK can import and resolve existing cell-merge revisions.
Refresh or change a field’s computed result	Updates the result without a revision. Field insertion and formatting changes are separate tracked operations.

Comments use a separate review workflow. Adding, editing, replying to, resolving, or deleting comments doesn’t create tracked-change revisions.

The SDK doesn’t create revisions for table-row property changes, but it does create revisions for row insertions and deletions.

DOCX import converts move revisions into insertion and deletion pairs, so the SDK doesn’t preserve the original move as a distinct revision type.

Set the author used for tracked changes

Use editor.setAuthor(name) to control the author name used for new tracked changes, comments, and replies:

editor.setAuthor('Legal Team');

Read the current author with editor.getAuthor():

const author = editor.getAuthor();
console.log(author);

Clear the author name to use the default anonymous label:

editor.setAuthor('');

Review and resolve tracked changes in the UI

Review tracked changes in the editor UI. Revisions can show inserted or deleted content, along with supported formatting and document property changes.

Authorized users can inspect each revision and accept or reject it in the editor.

Choose a review task

Refer to these guides to control review in your application:

Refer to the control review permissions guide to restrict editor operations and assign participant roles.
Refer to the manage tracked changes programmatically guide to query, accept, reject, and withdraw revisions in transactions.
Refer to the observe review events guide to distinguish editor attempts from committed document changes.

Use tracked changes with Document Authoring AI

Document Authoring AI uses the same editor modes as the rest of the editor. Your app decides how AI write operations apply:

In edit mode, AI writes can apply immediately.
In review mode, AI writes can use tracked changes. Authorized users can accept or reject them.
In view mode, the editor blocks AI writes. Read-only AI tools can still inspect the document.

Set the editor author before you run AI writes in review mode. This attributes tracked changes to the right user or team. For AI-specific policy and writeMode: "track_changes" examples, refer to the review and approval in Document Authoring AI guide.

Use review transactions together with programmatic editing

Use review transactions to create tracked revisions from code with DocAuthDocument.transaction(). The transaction records supported changes as revisions for the supplied author. Changes that tracked-change markup can’t represent apply directly, without creating revisions.

const currentDoc = editor.currentDocument();

await currentDoc.transaction(
  async ({ draft }) => {
    const paragraph = draft.body().content().addParagraph();
    paragraph.asTextView().setText('This change is authored in review mode.');

    return true;
  },
  {
    review: {
      author: 'Nutrient Docs',
    },
  },
);

For revision queries and decisions, refer to the manage tracked changes programmatically guide. For the transaction model, refer to the programmatic editing guide.

Learn more

Use these references for related review and editing workflows:

Document Authoring API reference
Refer to the comments guide to use comments in review workflows.
Refer to the review permissions guide to control review permissions.
Refer to the programmatic tracked changes guide to manage tracked changes.
Refer to the review events guide to observe review events.
Refer to the programmatic editing guide to run document transactions.
Refer to the review and approval in Document Authoring AI guide to review AI writes.