w:snapToGrid (Snap to Document Grid)

Description

w:snapToGrid is a toggle property that controls whether content snaps to the document grid. The document grid (w:docGrid in w:sectPr) defines a character-pitch grid used in East Asian typography to align characters evenly across a page.

It is defined in ECMA-376 Part 1 §17.3.1.32 (paragraph context) and §17.3.2.34 (run context).

• In w:pPr: the entire paragraph’s lines snap to the grid.
• In w:rPr: individual runs within a paragraph snap to the grid independently.

When true (default when a document grid is defined), characters are positioned on grid points. When false, the content flows without grid alignment, which can be useful for inline Latin text within an East Asian paragraph.

Attributes

Examples

<!-- Paragraph that does not snap to the document grid -->
<w:p>
  <w:pPr>
    <w:snapToGrid w:val="false"/>
  </w:pPr>
  <w:r><w:t>Free-flow paragraph ignoring the document grid.</w:t></w:r>
</w:p>

<!-- Run that opts out of snapping within a grid-snapped paragraph -->
<w:p>
  <w:pPr><w:snapToGrid/></w:pPr>
  <w:r>
    <w:rPr><w:snapToGrid w:val="false"/></w:rPr>
    <w:t>Latin text not snapped</w:t>
  </w:r>
</w:p>

using DocumentFormat.OpenXml.Wordprocessing;

// Paragraph level
var para = new Paragraph(
    new ParagraphProperties(
        new SnapToGrid { Val = false }
    ),
    new Run(new Text("Free-flow paragraph ignoring the document grid."))
);

// Run level (opt-out within a grid-aligned paragraph)
var run = new Run(
    new RunProperties(new SnapToGrid { Val = false }),
    new Text("Latin text not snapped")
);

Notes

• The document grid is defined by w:docGrid in w:sectPr. If no grid is defined, w:snapToGrid has no visual effect.
• East Asian documents commonly define grids to enforce consistent character pitch (chars-per-line and lines-per-page).
• Setting w:snapToGrid w:val="false" on runs with Latin text inside an East Asian paragraph is a common pattern in bilingual documents.