# Review tracked changes

> Propose an edit, accept or reject it, and keep undecided changes in the saved DOCX.



Use tracked changes when an edit needs review before it becomes accepted text. Each proposal records what changed and
who changed it. Use [comments](/editor/comments) for a discussion that does not change the passage.

## Try the review flow [#try-the-review-flow]

Select the marked change from `30 days` to `60 days`, then use the built-in toolbar to accept or reject it. Reset the
sample to compare both decisions. Accept keeps `60 days`; Reject restores `30 days`.

> **Interactive editor: Decide a proposed edit**
>
> Sample: [open the fixture](/fixtures/tracked-review.docx).
>
> Preset: `tracked-review`.
>
> Tracked-change review: select a marked proposal and use the built-in toolbar to accept or reject it. Reset the sample to compare both decisions.
>
> Local DOCX selection: disabled.


For the complete project, open the [review example](https://go.superdoc.dev/examples/document-modes?workflow=review).
Accept the existing proposal, make two more edits, reject one, and export with the other undecided. Reopen the DOCX to
check which text and proposals remain.

| Decision        | Result                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------- |
| Accept          | Keeps the proposed result and removes its revision mark.                                    |
| Reject          | Removes the proposed edit and its revision mark. For a deletion, the original text returns. |
| Leave undecided | Keeps the proposal available for another reviewer.                                          |

Both decisions change the open document. The demo does not save it to a server.

## Open the Editor for review [#open-the-editor-for-review]

Keep the project and export button from the [Quickstart](/editor/quickstart). Create `src/review-options.ts`:

```ts
import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'suggesting',
  user: {
    name: 'Jordan Lee',
    email: 'jordan@example.com',
  },
} satisfies Pick<Config, 'documentMode' | 'user'>;

```

Import `reviewOptions` into `src/main.ts` in Vanilla or `src/App.tsx` in React:

```ts
import { reviewOptions } from './review-options';
```

Add `...reviewOptions` inside your existing `new SuperDoc({ ... })` configuration, or add `{...reviewOptions}` to
the `SuperDocEditor` component. Keep `/sample.docx`, the ready/error handlers, and **Export DOCX**.

Replace the effective date in `/sample.docx`. In `suggesting` mode, the edit becomes a proposal attributed to Jordan Lee.
Your application supplies the signed-in user's identity instead of this example user.
You do not need to enable tracking separately. In `suggesting` mode, supported edits create tracked changes by default.

Select a proposed change to reveal its review actions. You can keep the built-in UI or use
[custom review controls](/editor/custom-ui/tracked-changes); the document workflow is the same.

## Save and reopen the review [#save-and-reopen-the-review]

Make three separate edits. Accept one, reject another, and leave the third undecided. Use **Export DOCX** in your project,
then open the exported file in Word or load it back into SuperDoc:

1. The accepted result should remain without a revision mark.
2. The rejected edit should be absent.
3. The undecided proposal and its author should remain available for review.

Use your normal [load and save flow](/editor/load-and-save-documents) to persist the exported bytes. Exporting does not
accept pending changes. Choosing not to export comments does not accept or reject revisions either.

## Choose the right mode [#choose-the-right-mode]

Use `suggesting` to record edits as proposals, `editing` for direct edits, and `viewing` to read without editing.
Switching to editing does not accept proposals already in the document.

For a read-only review, replace the contents of `src/review-options.ts` with:

```ts
import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'viewing',
  viewing: { trackedChanges: 'markup' },
} satisfies Pick<Config, 'documentMode' | 'viewing'>;
```

The display and the review decision are separate:

| `viewing.trackedChanges` | What the reader sees                                        |
| ------------------------ | ----------------------------------------------------------- |
| `original` (default)     | The text before the proposed edits, without revision marks. |
| `markup`                 | Proposed insertions and deletions with revision marks.      |
| `final`                  | The proposed result, without revision marks.                |

Viewing mode stays read-only in all three cases. Use the [document modes demo](/editor/document-modes#choose-how-tracked-changes-appear)
to compare them. A clean-looking final view is not an accepted document.

## Control review decisions [#control-review-decisions]

Use [Control a document review workflow](/editor/review-workflow) to let contributors propose without deciding,
configure reviewer actions, and hand off the saved document. Comment actions are configured separately.

Editor modes and client-side review controls are not an authorization boundary. Your application owns document access,
trusted identity, and permission to save. See [Configuration](/editor/configuration) for the full startup contract,
including replacement grouping and author colors.

## Choose how replacements are reviewed [#choose-how-replacements-are-reviewed]

Typing over selected text creates a deletion beside an insertion. By default, SuperDoc groups those parts into one
proposal. One Accept or Reject action decides the complete replacement.

Use separate replacement review when your workflow must decide the deletion and insertion independently:

```ts
import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'suggesting',
  trackChanges: {
    replacementMode: 'separate',
  },
} satisfies Pick<Config, 'documentMode' | 'trackChanges'>;
```

Keep the default `'grouped'` mode when a replacement such as `30 days` to `60 days` should remain one decision. This
setting changes the review items and decisions exposed by the Editor. It does not change the accepted text.

## Keep review decisions explicit [#keep-review-decisions-explicit]

Use [Document API tracked changes](/document-api/tracked-changes) when code needs to list revisions, inspect a known
change, create a tracked edit, or decide changes by ID. Do not infer revision targets from rendered DOM attributes.

Use the [custom review panel](/editor/custom-ui/tracked-changes) when your application owns the queue and its controls.
It observes `superdoc.ui.trackChanges` rather than maintaining a second list of document revisions.

## Report permission-filtered bulk decisions [#report-permission-filtered-bulk-decisions]

Accept All and Reject All can leave changes undecided when `permissionResolver` allows only some decisions.
The [review workflow guide](/editor/review-workflow#report-partial-bulk-decisions) shows how to report those results
through `onTrackedChangesBulkDecision`, without confusing a review decision with a saved file.