w:highlight (Highlight Color)

Applies a highlight color to the background of the run text using a named color value.

Parent elements

w:rPr

Description

w:highlight applies a highlight colour to the background of the run text, simulating a highlighter pen effect. It is defined in ECMA-376 Part 1 §17.3.2.14.

Unlike w:shd (which sets a background via a shading pattern), w:highlight uses a fixed palette of named colours from ST_HighlightColor.

Attributes

Attribute	Type	Possible Values	Description
`w:val`	`ST_HighlightColor`	`black`, `blue`, `cyan`, `darkBlue`, `darkCyan`, `darkGray`, `darkGreen`, `darkMagenta`, `darkRed`, `darkYellow`, `green`, `lightGray`, `magenta`, `none`, `red`, `white`, `yellow`	The highlight colour. `none` removes highlighting.

Examples

<!-- Yellow highlight: standard highlighter effect -->
<w:rPr>
  <w:highlight w:val="yellow"/>
</w:rPr>

new RunProperties(
  new Highlight { Val = HighlightColorValues.Yellow });

<!-- Green highlight with font color for contrast -->
<w:rPr>
  <w:highlight w:val="green"/>
  <w:color w:val="000000"/>  <!-- Black text for contrast -->
</w:rPr>

new RunProperties(
  new Highlight { Val = HighlightColorValues.Green },
  new Color { Val = "000000" });  // Ensure readable contrast

<!-- Remove inherited highlight -->
<w:rPr>
  <w:highlight w:val="none"/>
</w:rPr>

new RunProperties(
  new Highlight { Val = HighlightColorValues.None });  // Cancels style highlight

Highlight Color Palette

Color	Typical RGB	Use Case
`yellow`	#FFFF00	Standard highlighting, emphasis
`green`	#00B050	Success, approval, positive
`cyan`	#00FFFF	Light emphasis, secondary
`magenta`	#FF00FF	Strong emphasis, critical
`blue`	#0070C0	Information, links, comments
`red`	#FF0000	Warnings, errors, deletions
`darkRed`	#C00000	Strong warnings
`darkYellow`	#FFC000	Cautions, medium importance
`black`	#000000	Neutral, printing
`white`	#FFFFFF	High contrast backgrounds
`lightGray`	#D9D9D9	Subtle highlighting
`darkGray`	#808080	Neutral, print-friendly
`none`	—	Remove highlighting

Notes

Fixed Palette: Only named colors supported; w:highlight cannot use arbitrary RGB values.
Custom Colors: Use w:shd for custom background colors with specific RGB hex values.
Contrast: Always ensure text color contrasts with highlight for accessibility.
Print Display: Highlights print as solid background colors; choose print-friendly combinations.
Semantic Use: Yellow (warning), green (complete/positive), red (error/critical), blue (info).
Toggle Pattern: w:val="none" explicitly cancels highlight inherited from style.
Accessibility: Highlighted text should have adequate foreground/background contrast (WCAG 4.5:1 ratio).
Visual Priority: Restrict highlighting to key content; excessive highlighting reduces effectiveness.
Color Blind: Avoid red-green combinations alone; add other visual cues or labels.
Compatibility: Highlight colors render consistently across all Office versions.
PDF Export: Highlights typically preserve as background color in PDF export.