w:vMerge (Vertical Merge)

Marks a cell as part of a vertically merged group. The first cell uses w:val='restart'; subsequent cells omit the attribute.

Parent elements

w:tcPr

Description

w:vMerge controls vertical cell merging (merging across rows). It is defined in ECMA-376 Part 1 §17.4.84.

The first cell in a vertical merge group uses <w:vMerge w:val="restart"/>. Every subsequent cell in the same column that is part of the merge uses <w:vMerge/> (no w:val), and must still contain a w:p (which will be ignored for layout purposes). The merge ends at the next row that does not have w:vMerge in that column.

Attributes

Attribute	Type	Possible Values	Description
`w:val`	`ST_Merge`	`restart` (start a new merge group), or omitted/`continue` (continue an existing merge group).	Marks the role of this cell in the vertical merge.

Examples

<!-- Row 1: start of vertical merge -->
<w:tc>
  <w:tcPr><w:vMerge w:val="restart"/></w:tcPr>
  <w:p><w:r><w:t>Merged content</w:t></w:r></w:p>
</w:tc>

<!-- Row 2: continue merge (empty content) -->
<w:tc>
  <w:tcPr><w:vMerge/></w:tcPr>
  <w:p/>  <!-- Required but will be hidden by merge -->
</w:tc>

<!-- Row 3: continue merge (empty) -->
<w:tc>
  <w:tcPr><w:vMerge/></w:tcPr>
  <w:p/>
</w:tc>

// Row 1 (restart merge)
new TableCell(
  new TableCellProperties(new VerticalMerge { Val = MergedCellValues.Restart }),
  new Paragraph(new Run(new Text("Merged content"))));

// Row 2 (continue merge)
new TableCell(
  new TableCellProperties(new VerticalMerge()),  // No Val attribute = continue
  new Paragraph());  // Required but hidden

// Row 3 (continue merge)
new TableCell(
  new TableCellProperties(new VerticalMerge()),
  new Paragraph());

<!-- Complex: column spanning + vertical merge -->
<w:tc>
  <w:tcPr>
    <w:gridSpan w:val="2"/>
    <w:vMerge w:val="restart"/>
  </w:tcPr>
  <w:p><w:r><w:t>2-column merge spanning 3 rows</w:t></w:r></w:p>
</w:tc>

new TableCell(
  new TableCellProperties(
    new GridSpan { Val = 2 },         // Spans 2 grid columns
    new VerticalMerge { Val = MergedCellValues.Restart }),  // Start merge
  new Paragraph(new Run(new Text("2-column merge spanning 3 rows"))));

Notes

First Cell: Must use w:val="restart" to begin a merge group.
Continuation Cells: Must contain w:vMerge (no w:val) and a w:p (even if empty).
Grid Consistency: Continuation cells must maintain grid column count; don’t omit cells.
Merge Scope: Merge continues until a row without w:vMerge in that column.
Content Scope: Only first cell’s content is displayed; continuation cells’ content is hidden.
Grid Spanning: Can combine w:gridSpan with w:vMerge for complex merged regions.
Paragraph Required: Even empty continuation cells need w:p for proper XML structure.
Table Structure: Merges must respect table grid boundaries; improper merges cause rendering issues.
Compatibility: Vertical merging is stable across all Office versions.
Accessibility: Merged cells may impact screen reader navigation; use with caution.