Tiptap highlight: keep a marked passage in the saved document

A fictional maintenance handover says, “Use the temporary entrance beside the loading bay until the front door reopens.” The author wants the temporary entrance instruction to remain highlighted when the next shift opens the handover. A yellow search result that disappears when the search box closes would not preserve that editorial choice.

Enable the mark in the document schema

In an existing Tiptap application with compatible installed packages, add this extension to the editor's existing extension list:

import Highlight from '@tiptap/extension-highlight';

const handoverHighlight = Highlight.configure({
  multicolor: true
});

Retain the application's base document extensions and initialization. This fragment adds highlight support; it does not create an editor or save a record. If another setup already registers Highlight, configure that registration instead of adding a second copy.

The default multicolor value is false. A single ordinary highlight may be enough for a handover. Enable multiple colors only when the document has a reason to distinguish them, and provide a text explanation of any meaning. Color alone should not determine whether a reader understands an instruction.

Apply a deliberate highlight to selected words

With editor referring to the initialized handover editor, connect an ordinary type="button" control to this handler:

function markTemporaryInstruction() {
  editor.chain().focus()
    .setHighlight({ color: '#fff2a8' })
    .run();
}

function removeSelectedHighlight() {
  editor.chain().focus().unsetHighlight().run();
}

Select “temporary entrance beside the loading bay” before applying the command. Restoring focus lets the command use the editor selection after the author clicks an external button. Check the selected words rather than assuming that the entire paragraph is the target.

setHighlight() applies the mark. toggleHighlight() is useful for a toolbar button whose second activation removes the current highlight. Choose the interaction deliberately: an “Apply yellow” action should not unexpectedly remove yellow from a passage that already has it.

The extension also documents the ==highlighted text== typing shortcut. If your authoring interface exposes that syntax, explain that it becomes document formatting, rather than promising that the literal equals signs will remain in the saved text.

Inspect the stored mark and the reader output

Use this original sentence in a development record:

Use the temporary entrance beside the loading bay until the front door reopens.

After marking only the entrance phrase, inspect editor.getJSON(). The selected text should have a highlight mark, with its configured color when multicolor support is enabled. The text before and after that phrase should retain its intended marks. Inspect editor.getHTML() as well: the highlighted content should be represented with mark, while the actual exported attributes depend on the configured extension.

Capture the representation used by the real application and save through its existing document service. Reopen the same record with Highlight enabled. The Tiptap document integration guide explains the distinction between the editor's JSON document and its HTML output.

If the mark is present in the saved data but invisible to readers, inspect the reader stylesheet and any HTML cleanup step. A rule that removes mark backgrounds or a sanitizer that removes required attributes can change the appearance after editing. Fix that specific conversion or style rule instead of recoloring every paragraph globally.

Keep emphasis separate from review status

The highlight says that an author emphasized a passage. It does not record who approved the entrance route, when the door will reopen, or whether a reader acknowledged the change. Keep those facts in the relevant workflow and wording.

Read the saved handover at a narrow width and with the application's actual reader colors. The temporary entrance should remain understandable when the phrase wraps. Then remove the highlight from a test copy and confirm the instruction still makes sense as text. Once the front entrance reopens, update the instruction itself; removing a background color alone would leave the old direction in place.