Tiptap Docs

Text color and highlight

Beta

Text color and highlight convert between Word's color model and Tiptap's textStyle and highlight marks. Both round-trip when the right extensions are installed.

What you need

  • Extensions: ConvertKit — its bundled TextStyleKit provides Color (and BackgroundColor), and ConvertKit registers Highlight with multicolor: true preconfigured.
  • Configuration: None required.
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'

new Editor({ extensions: [ConvertKit] })

multicolor: true matters

Without multicolor: true on Highlight, only a single generic highlight is supported and every imported highlight collapses to the default yellow. ConvertKit applies it automatically; if you override the highlight slot, keep the flag on.

Support overview

ImportEditorExport
Text colorSupported (textStyle mark)Supported (TextStyle + Color)Supported (normalized to hex)
HighlightSupported (highlight mark)Supported (Highlight, multicolor)Supported (named or hex)
Shading (<w:shd>)Supported (maps to highlight)SupportedSupported (solid shading)
Theme colorsNot supported (not converted)Not applicableNot applicable

Import

Import text color and highlight using the editor extension or the REST API. Both produce identical output.

The conversion service maps Word color elements to Tiptap marks:

Word elementTiptap markAttribute
<w:color val="FF0000">textStyle{ color: "#FF0000" }
<w:highlight val="yellow">highlight{ color: "yellow" }
<w:shd val="clear" fill="00FFFF">highlight{ color: "#00FFFF" }

Both <w:highlight> and <w:shd> produce the same highlight mark. The developer does not need to distinguish between them.

Theme colors are not imported

Word theme colors (such as accent1, accent2, or themeColor attributes on <w:color>) are not converted during import. If a text run uses only a theme color with val="auto", the color is not included in the output. Only explicit hex color values in <w:color val="..."> are preserved.

Editor rendering

The Color extension adds color support to TextStyle, and the Highlight extension handles background colors. ConvertKit bundles both: TextStyleKit brings TextStyle + Color + BackgroundColor, and Highlight is registered with multicolor: true preconfigured.

Text color renders as an inline style="color: ..." on a <span> element. Highlight renders as a <mark> element with a background-color style.

If you disable ConvertKit.configure({ textStyleKit: false }), text color attributes from import won't be recognised by the schema. Same for highlight: false. See the invalid schema guide for how to manage unrecognised marks and attributes.

Export

Export text color and highlight using the editor extension or the REST API. Both handle color and highlight identically.

On export, color values are normalized to 6-digit hex. The following input formats are accepted:

  • Hex with hash: #FF0000, #F00, #FF0000AA
  • RGB/RGBA: rgb(255, 0, 0), rgba(255, 0, 0, 0.5)
  • Named CSS colors: red, blue, green, yellow, cyan, purple, and 14 others

Highlights export as either a named Word highlight color (when the color matches a Word enum value like yellow or cyan) or as solid character shading with a hex fill value. A highlight mark with no color attribute defaults to yellow.

PreviouslySubscript and superscript