OOXML.org

w:tbl (Table)

Container for a table consisting of table properties, a table grid definition, and one or more table rows.

Parent elements

Child elements

Description

w:tbl is the root element for a table in a WordprocessingML document body. It is defined in ECMA-376 Part 1 §17.4.38.

A table contains an optional set of table-level properties (w:tblPr), a table grid definition (w:tblGrid), and one or more rows (w:tr). Tables can be nested inside table cells to arbitrary depth.

Attributes

Attribute Type Possible Values Description
(none) — — All table properties are expressed via child elements.

Child Elements

Child Purpose Order
w:tblPr Table-level properties (style, width, borders, etc.) First (optional)
w:tblGrid Column definitions specifying logical grid width Second (required)
w:tr (repeatable) Table rows containing cells Third onward

Examples

Simple two-column table

<w:tbl>
  <w:tblPr>
    <w:tblW w:w="5000" w:type="pct"/>
  </w:tblPr>
  <w:tblGrid>
    <w:gridCol w:w="2500"/>
    <w:gridCol w:w="2500"/>
  </w:tblGrid>
  <w:tr>
    <w:tc><w:p><w:r><w:t>Cell A</w:t></w:r></w:p></w:tc>
    <w:tc><w:p><w:r><w:t>Cell B</w:t></w:r></w:p></w:tc>
  </w:tr>
  <w:tr>
    <w:tc><w:p><w:r><w:t>Cell C</w:t></w:r></w:p></w:tc>
    <w:tc><w:p><w:r><w:t>Cell D</w:t></w:r></w:p></w:tc>
  </w:tr>
</w:tbl>

Table with nested table

<w:tbl>
  <w:tblPr><w:tblW w:w="5000" w:type="pct"/></w:tblPr>
  <w:tblGrid><w:gridCol w:w="2500"/><w:gridCol w:w="2500"/></w:tblGrid>
  <w:tr>
    <w:tc>
      <w:p><w:r><w:t>Cell with nested table:</w:t></w:r></w:p>
      <w:tbl>
        <w:tblGrid><w:gridCol w:w="2500"/><w:gridCol w:w="2500"/></w:tblGrid>
        <w:tr>
          <w:tc><w:p><w:r><w:t>Nested 1</w:t></w:r></w:p></w:tc>
          <w:tc><w:p><w:r><w:t>Nested 2</w:t></w:r></w:p></w:tc>
        </w:tr>
      </w:tbl>
    </w:tc>
    <w:tc><w:p><w:r><w:t>Regular cell</w:t></w:r></w:p></w:tc>
  </w:tr>
</w:tbl>

Table Structure Components

Component Purpose Required Details
w:tblPr Table-level properties No Style, width, alignment, borders, margins, conditional formatting
w:tblGrid Logical grid definition Yes Defines column count and logical widths (reference only)
w:tr Table rows Yes One or more rows; each row contains cells for each grid column
w:tc Table cells Required per row Must map 1:1 to grid columns (use gridSpan for multi-column cells)

Grid and Column Spanning

Concept Definition Impact
Grid Column Count Number of <w:gridCol> elements in w:tblGrid Defines maximum logical columns; row structure must respect this
Grid Span <w:gridSpan w:val="N"/> in cell properties Cell occupies N grid columns; subsequent cells shift accordingly
Cell Count Requirement Row must have enough cells to span all grid columns 5-column grid requires 5 cells, OR 2 cells with gridSpan values summing to 5

Table Model

<w:tbl>
  <w:tblPr>...</w:tblPr>           <!-- Table formatting -->
  <w:tblGrid>                       <!-- Define logical columns -->
    <w:gridCol/>                    <!-- Column 1 -->
    <w:gridCol/>                    <!-- Column 2 -->
  </w:tblGrid>
  <w:tr>                            <!-- Row 1 -->
    <w:trPr>...</w:trPr>           <!-- Row properties (height, header) -->
    <w:tc>...</w:tc>               <!-- Column 1 cell -->
    <w:tc>...</w:tc>               <!-- Column 2 cell -->
  </w:tr>
  <w:tr>                            <!-- Row 2 -->
    <w:tc>...</w:tc>               <!-- Column 1 cell -->
    <w:tc>...</w:tc>               <!-- Column 2 cell -->
  </w:tr>
</w:tbl>

Notes

  • Child element order: ECMA-376 specifies strict ordering: w:tblPr (optional), w:tblGrid (required), then w:tr elements (one or more).
  • Grid definition purpose: The w:tblGrid defines the logical grid columns; actual cell width is determined by w:tcPr/w:tcW in each cell.
  • Minimum table size: A table must contain at least one row (w:tr), and each row must contain at least one cell (w:tc).
  • Cell paragraph requirement: Every w:tc must end with at least one w:p (paragraph); cells cannot be empty or contain only tables.
  • Nested tables: Tables can be nested arbitrarily deep inside cells; nesting inside w:tc is valid, but w:tbl cannot be a direct child of w:p or w:body.
  • Row spanning and merging: Column spanning is controlled by w:gridSpan in w:tcPr; vertical merging is controlled by w:vMerge in w:tcPr.
  • Table-level properties override: Properties in w:tblPr apply to the entire table; cell-level properties (w:tcPr) take precedence for specific cells.
  • Performance: Very large tables (>100 rows) can impact rendering and file size; consider breaking into multiple tables if needed.
  • Width types: Table width can be percentage (pct), absolute twips (dxa), or auto; width is advisory and may be adjusted based on content.
  • Table placement: Tables are block-level elements and can only appear as direct children of w:body, w:tc, w:hdr, w:ftr, or other block containers; not inside w:p.
  • Accessibility: Include table title/description (in w:tblPr) and proper header row marking (w:tblHeader) for semantic markup.