DOCX Editor highlighting and shading FAQ

DOCX files can put a colored background behind text in two ways: text highlighting and character shading. They look the same on screen, but other DOCX editors can treat them as different features. This page explains the difference, how the WebViewer DOCX Editor decides which one to save, and how to apply a highlight that Word recognizes.

Highlighting vs. shading

What's the difference between text highlighting and character shading?

Text highlighting is the digital equivalent of a highlighter pen. In the DOCX format, it draws a reader's attention to a span of text. Because it models a real highlighter, the DOCX format only permits a fixed palette of named colors (yellow, green, cyan, and so on).

Character shading represents a background fill applied to the characters themselves. Semantically, it's a formatting or styling property, not a way to mark up text. It describes how the text should be painted, much like font color or borders, and is meant to be part of the document's visual design. Because it's a general fill, it accepts any color.

This distinction matters when the file is opened in another DOCX editor. Editors such as Microsoft Word usually have a separate tool for each: the highlight tool edits or removes text highlights, and the shading tool edits character shading.

	Text highlighting	Character shading
Purpose	Draws attention to text	Formats the text
Colors	A fixed set of standard highlight colors	Any color
Usually edited with	The highlight tool	The shading tool

Saving highlights

Why does my highlight save as character shading?

When you save a DOCX file, the DOCX Editor checks each highlight's color. If it matches a standard highlight color, it's saved as a text highlight. Any other color is saved as character shading because DOCX only allows standard colors for text highlighting.

Why can't I remove a highlight in Microsoft Word?

The highlight was probably saved as character shading. Word's highlight tool, including No Color, only affects text highlights. To remove shading in Word, use the shading tool instead.

Applying highlights

How do I make sure a highlight saves as a text highlight?

Use a standard highlight color. In the UI, the highlight color picker offers the standard highlight colors, so highlights you apply there save as text highlights.

In your code, use a value from Core.Document.OfficeEditor.HighlightColors. For examples of usage, you can see our Text Formatting guide.

Can I use a custom highlight color?

Yes. The text formatting APIs accept any valid color. Colors outside HighlightColors display normally in the DOCX Editor, but they're saved as character shading, so highlight tools in other editors won't recognize them.