OOXML.org

w:tblGrid (Table Grid)

Defines the column structure of the table by specifying the width of each column slot.

Parent elements

Child elements

Description

w:tblGrid defines the logical column structure of a table by specifying the width of each column in the table’s grid model. It is defined in ECMA-376 Part 1 §17.4.49.

Each w:gridCol child element represents one column slot with its preferred width in twips (1/20th of a point). The table grid serves as the coordinate system: cell spanning via w:gridSpan and vertical merging via w:vMerge are both specified relative to this grid. The sum of all w:gridCol widths should ideally equal the table’s total width, though Word may adjust rendering based on available space.

Attributes

Attribute Type Possible Values Description
(none) — — All column definitions are carried by w:gridCol child elements.

Examples

<!-- Three equal-width columns (1.5 inch each) -->
<w:tblGrid>
  <w:gridCol w:w="2160"/>
  <w:gridCol w:w="2160"/>
  <w:gridCol w:w="2160"/>
</w:tblGrid>
<!-- Four columns with varying widths (1.5", 1", 1", 0.5") -->
<w:tblGrid>
  <w:gridCol w:w="2160"/>
  <w:gridCol w:w="1440"/>
  <w:gridCol w:w="1440"/>
  <w:gridCol w:w="720"/>
</w:tblGrid>

Notes

  • Twip Conversion: 1440 twips = 1 inch = 25.4 mm. Divide widths by 1440 to convert to inches.
  • Grid Coordinates: The number of w:gridCol elements defines the logical column count. Every row must reference this grid.
  • Cell Spanning: A cell with w:gridSpan w:val="2" occupies 2 grid columns. Row gridSpan sum must equal total grid columns.
  • Column Immutability: Changing the grid structure requires updating all affected rows.
  • Width Calculation: Sum all w:gridCol widths to get logical table width.
  • AutoFit Mode: If w:tblLayout is autofit, rendered widths may differ from grid widths based on content.
  • Vertical Merge: Grid defines columns; w:vMerge (row merging) uses same grid coordinates.
  • Structural Consistency: Every row’s total w:gridSpan must equal the grid column count.
  • Round-Trip Stability: Preserve original grid widths when reading/writing to maintain layout.
  • Compatibility: Table grid structure is stable across Office versions.