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
| Setting | Default mark | Default color |
|---|---|---|
insertions | underline | byAuthor |
deletions | strikethrough | byAuthor |
movedFrom | doubleStrikethrough | green |
movedTo | doubleUnderline | green |
formatting | none | byAuthor |
changedLines | outsideBorder | auto |
cells.inserted, cells.deleted, cells.merged, cells.split | lightBlue, pink, lightYellow, lightOrange | |
trackMoves, trackFormatting | true |
| Field | Accepted values |
|---|---|
Text mark | none, 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.mark | none, leftBorder, rightBorder, outsideBorder. |
Text and bar color | auto, byAuthor, or a name from REVISION_MARKUP_COLORS. Text auto keeps the document color. Bar auto uses the display mode's bar color. |
background | none (default), byAuthor, or a named color. byAuthor uses the author's revisionStyles background, or a light tint of the author color. |
| Cell colors | none, 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}
/>
);
}<script setup lang="ts">
import { onMounted, shallowRef } from 'vue';
import { DocxEditor } from '@docx-editor.dev/vue';
import { reviewModule } from '@docx-editor.dev/pro/vue';
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 props = defineProps<{ bytes: Uint8Array; userId: string }>();
const modules = [reviewModule()];
const preferences = shallowRef(DEFAULT_REVISION_MARKUP);
onMounted(() => {
preferences.value = loadUserPreferences(props.userId);
});
function update(next: ResolvedRevisionMarkup) {
preferences.value = next;
saveUserPreferences(props.userId, next);
}
</script>
<template>
<DocxEditor
:document="bytes"
:modules="modules"
:revision-markup="preferences"
@revision-markup-change="update"
/>
</template>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:
| Hook | Effect |
|---|---|
review.revisionMarkup toolbar slot | Adds 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: false | Cancels 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: falsestops future formatting revisions. Text edits stay tracked, and existing formatting revisions stay reviewable.- The document's
w:doNotTrackFormattingsetting takes precedence overtrackFormatting: true. trackMoves: falseshows imported moves as insertions and deletions. The editor does not create move revisions.hiddendeleted 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.