Customize revision markup

Set tracked change marks, colors, and change bars, save user preferences, and configure the Track changes options dialog.

revisionMarkup sets how each viewer sees tracked changes: marks, colors, change bars, and table cell shading. The API and the Track changes options dialog share these settings. They never change revision records, saved DOCX content, or another participant's view.

The review module requires an EigenPal Pro License. For setup, see Tracked changes.

Set markup preferences

Pass initial preferences when you create the editor. Omitted fields use the defaults:

import { createDocxEditor, DEFAULT_REVISION_MARKUP } from '@docx-editor.dev/core/editor';
import { reviewModule } from '@docx-editor.dev/pro';

const editor = createDocxEditor({
  document: bytes,
  modules: [reviewModule()],
  revisionMarkup: {
    insertions: { mark: 'underline', color: 'blue' },
    deletions: { mark: 'doubleStrikethrough', color: 'red' },
  },
});

editor.setRevisionMarkup({ insertions: { color: 'green' } }); // Merges; the mark stays underline.
const preferences = editor.snapshot().revisionMarkup; // Complete, immutable settings.
editor.setRevisionMarkup(DEFAULT_REVISION_MARKUP); // Resets everything.

setRevisionMarkup merges a partial update, so {} changes nothing. Invalid fields or values throw TypeError before any setting changes.

Choose marks and colors

SettingDefault markDefault color
insertionsunderlinebyAuthor
deletionsstrikethroughbyAuthor
movedFromdoubleStrikethroughgreen
movedTodoubleUnderlinegreen
formattingnonebyAuthor
changedLinesoutsideBorderauto
cells.inserted, cells.deleted, cells.merged, cells.splitlightBlue, pink, lightYellow, lightOrange
trackMoves, trackFormattingtrue
FieldAccepted values
Text marknone, colorOnly, bold, italic, underline, doubleUnderline, strikethrough, doubleStrikethrough. Deletions and movedFrom also accept hidden, caret (shows ^), and pound (shows #). none drops marks and text color but keeps an explicit background. For color without a mark, use colorOnly.
changedLines.marknone, leftBorder, rightBorder, outsideBorder.
Text and bar colorauto, byAuthor, or a name from REVISION_MARKUP_COLORS. Text auto keeps the document color. Bar auto uses the display mode's bar color.
backgroundnone (default), byAuthor, or a named color. byAuthor uses the author's revisionStyles background, or a light tint of the author color.
Cell colorsnone, byAuthor, or a named color.

Named colors map to theme tokens. revisionMarkup does not accept arbitrary CSS color strings. Keep a mark on each category, so color is not the only indicator:

editor.setRevisionMarkup({
  insertions: { mark: 'underline', color: 'darkGreen', background: 'lightGreen' },
  deletions: { mark: 'strikethrough', color: 'darkRed', background: 'pink' },
});

background: 'none' keeps document highlighting and author backgrounds from revisionStyles. Explicit backgrounds take precedence over both. Cell none keeps authored cell shading.

Persist user preferences

revisionMarkupChange emits the complete settings after each effective change from the API or the dialog. An unchanged value emits nothing:

import { saveUserPreferences } from './revision-preferences'; // Your storage.

const unsubscribe = editor.on('revisionMarkupChange', (preferences) => {
  saveUserPreferences(userId, preferences); // Scope to the signed-in user.
});

In React and Vue, control the settings with the revisionMarkup prop and its change callback. Load saved values after mount when you render on the server, and remount the editor when the user changes:

import { useEffect, useState } from 'react';
import { DocxEditor } from '@docx-editor.dev/react';
import { reviewModule } from '@docx-editor.dev/pro/react';
import { DEFAULT_REVISION_MARKUP } from '@docx-editor.dev/core/editor';
import type { ResolvedRevisionMarkup } from '@docx-editor.dev/core/editor';
import { loadUserPreferences, saveUserPreferences } from './revision-preferences';

const modules = [reviewModule()];

export function ReviewEditor({ bytes, userId }: { bytes: Uint8Array; userId: string }) {
  const [preferences, setPreferences] = useState(DEFAULT_REVISION_MARKUP);
  useEffect(() => setPreferences(loadUserPreferences(userId)), [userId]);

  function update(next: ResolvedRevisionMarkup) {
    setPreferences(next);
    saveUserPreferences(userId, next);
  }

  return (
    <DocxEditor
      document={bytes}
      modules={modules}
      revisionMarkup={preferences}
      onRevisionMarkupChange={update}
    />
  );
}

Validate stored values with resolveRevisionMarkup from @docx-editor.dev/core/editor, and fall back to DEFAULT_REVISION_MARKUP.

The controlled prop is the source of truth. Store each callback value in it, or the next render restores the old value. Omitted prop fields resolve to defaults, unlike setter updates.

For partial declarative settings, mount DocxEditor.RevisionMarkup (Vue: DocxEditorRevisionMarkup) inside the root instead. Do not combine it with the controlled prop.

Configure the dialog

Users open the dialog from Review > Track changes options. Configure it through these hooks:

HookEffect
review.revisionMarkup toolbar slotAdds a toolbar control. Place it in a Toolbar.Group.
popups.revisionMarkup with definePopup()Wraps or replaces the dialog. Use DocxEditor.RevisionMarkupDialog to keep focus, labels, and keyboard behavior.
popups.revisionMarkup: falseCancels dialog requests. The toolbar control stays.

The dialog edits a draft and applies it in one update on OK. An effective API update replaces an open draft, and an unchanged update keeps it. For full examples, see Customize track changes options.

Limits

  • trackFormatting: false stops future formatting revisions. Text edits stay tracked, and existing formatting revisions stay reviewable.
  • The document's w:doNotTrackFormatting setting takes precedence over trackFormatting: true.
  • trackMoves: false shows imported moves as insertions and deletions. The editor does not create move revisions.
  • hidden deleted text stays a pending change. It does not remove a structurally deleted row.
  • Marks, colors, and backgrounds show in All Markup. Other display modes omit revision text backgrounds.
  • No markup setting makes an unsupported tracked operation available.
  • For PDF output, see Export the same preferences.

See also