w:shd (Shading)

Description

w:shd applies a background fill (shading) to a paragraph, run, or table cell. It is defined in ECMA-376 Part 1 §17.3.5 (paragraphs/runs) and §17.4.33 (table cells).

The background is composed of a fill colour (w:fill) and an optional pattern colour (w:color) combined via a shading pattern (w:val). For a solid fill with no pattern, use w:val="clear" and set w:fill to the desired colour.

Attributes

Examples

<!-- Solid yellow background on paragraph -->
<w:pPr>
  <w:shd w:val="clear" w:color="auto" w:fill="FFFF00"/>
</w:pPr>

new ParagraphProperties(
  new Shading
  {
    Val = ShadingPatternValues.Clear,
    Color = "auto",
    Fill = "FFFF00"  // Solid yellow
  });

<!-- Horizontal stripe pattern: blue stripes on light yellow -->
<w:rPr>
  <w:shd w:val="horzStripe" w:color="0000FF" w:fill="FFFFCC"/>
</w:rPr>

new RunProperties(
  new Shading
  {
    Val = ShadingPatternValues.HorizStripe,
    Color = "0000FF",    // Blue stripes
    Fill = "FFFFCC"      // Light yellow background
  });

<!-- Table cell: light blue background with theme color -->
<w:tcPr>
  <w:shd w:val="clear" w:fill="E8F4F8" w:themeFill="accent1" w:themeFillTint="9F"/>
</w:tcPr>

new TableCellProperties(
  new Shading
  {
    Val = ShadingPatternValues.Clear,
    Fill = "E8F4F8",
    ThemeFill = ThemeColorValues.Accent1,
    ThemeFillTint = "9F"  // Light tint for contrast
  });

Solid Fill Colors

Shading Patterns

Pattern Examples

Horizontal Stripe (blue on yellow):

<w:shd w:val="horzStripe" w:color="0000FF" w:fill="FFFF00"/>

Gray 50% Solid (using dot pattern):

<w:shd w:val="pct50" w:color="808080" w:fill="FFFFFF"/>

Light Tint (5% dots, subtle background):

<w:shd w:val="pct5" w:color="000000" w:fill="E8E8E8"/>

Common Highlighting Colors

Theme-Based Shading

Using theme colors ensures consistency across document themes:

<!-- Light accent1 tint for flexible theming -->
<w:shd w:val="clear" w:themeFill="accent1" w:themeFillTint="9F"/>

When document theme changes, shading updates automatically.

Advanced Patterns

Diagonal Stripe (pattern emphasis):

<w:shd w:val="diagStripe" w:color="FF0000" w:fill="FFFFFF"/>

Combined Foreground/Background (transparency effect via dots):

<w:shd w:val="pct20" w:color="0000FF" w:fill="FFFFFF"/>
<!-- Result: 20% blue dots on white = light blue tint -->

| vertStripe | Vertical lines | Emphasis, tables | | diagStripe | Diagonal lines (left-to-right) | Emphasis, patterns | | reverseDiagStripe | Diagonal lines (right-to-left) | Emphasis, patterns | | pct5–pct95 | Percentage fill (5% to 95% solid) | Gray scales, tints |

Notes

• Solid Fill: Use w:val="clear" with w:fill for plain background color.
• Pattern + Color: Pattern uses w:color for foreground (pattern) and w:fill for background.
• Context Scope: Applies to paragraphs, runs (characters), or table cells depending on parent.
• Theme Colors: w:themeFill and w:themeFillTint link to document theme; update automatically.
• Tint Effect: w:themeFillTint lightens toward white; w:themeFillShade darkens toward black.
• Nil Pattern: w:val="nil" removes any shading (useful to override style).
• RGB Format: Hex values are RRGGBB (e.g., FF0000 = red).
• Print Preview: Shading may appear lighter in print preview than on screen.
• Accessibility: Ensure shading color has sufficient contrast with text color.
• Compatibility: Shading renders consistently across all Office versions.