OOXML.org

w:tc (Table Cell)

Contains the content and formatting properties for a single table cell.

Parent elements

Child elements

Description

w:tc is a table cell containing one or more block-level elements (paragraphs and/or nested tables). It is defined in ECMA-376 Part 1 §17.4.66.

Every w:tc must contain at least one w:p as its last child. Cell properties are specified in an optional leading w:tcPr element. Cells span multiple columns via w:gridSpan in w:tcPr, and merge vertically via w:vMerge.

Attributes

Attribute Type Possible Values Description
(none) — — Properties are expressed via the w:tcPr child element.

Child Elements

Child Purpose Order
w:tcPr Cell-level properties (width, borders, shading, merging, etc.) First (optional)
w:p or w:tbl Block-level content (paragraphs and/or nested tables) Second onward
w:p Must appear last (required, even if empty) Final child

Cell Property Reference

Property Purpose Example
w:tcW Cell width (in twips or percent) <w:tcW w:w="2000" w:type="dxa"/>
w:gridSpan Column spanning <w:gridSpan w:val="2"/>
w:vMerge Vertical merge <w:vMerge/> (restart) or <w:vMerge w:val="continue"/>
w:shd Cell background color <w:shd w:fill="D3D3D3"/>
w:tcBorders Cell borders <w:tcBorders>...</w:tcBorders>

Examples

Simple cell with text

<w:tc>
  <w:tcPr>
    <w:tcW w:w="2500" w:type="dxa"/>
  </w:tcPr>
  <w:p>
    <w:r><w:t>Cell content</w:t></w:r>
  </w:p>
</w:tc>

Cell spanning two columns with shading

<w:tc>
  <w:tcPr>
    <w:tcW w:w="5000" w:type="dxa"/>
    <w:gridSpan w:val="2"/>
    <w:shd w:fill="E8E8E8"/>
  </w:tcPr>
  <w:p>
    <w:pPr><w:jc w:val="center"/></w:pPr>
    <w:r><w:t>Spans 2 columns</w:t></w:r>
  </w:p>
</w:tc>

Cell with vertical merge (continuation)

<w:tc>
  <w:tcPr>
    <w:vMerge w:val="continue"/>
  </w:tcPr>
  <w:p>
    <w:r><w:t></w:t></w:r>
  </w:p>
</w:tc>

Cell containing nested table and text

<w:tc>
  <w:tcPr><w:tcW w:w="2500" w:type="dxa"/></w:tcPr>
  <w:p>
    <w:r><w:t>Above table:</w:t></w:r>
  </w:p>
  <w:tbl>
    <w:tblGrid><w:gridCol w:w="1250"/><w:gridCol w:w="1250"/></w:tblGrid>
    <w:tr>
      <w:tc><w:p><w:r><w:t>N1</w:t></w:r></w:p></w:tc>
      <w:tc><w:p><w:r><w:t>N2</w:t></w:r></w:p></w:tc>
    </w:tr>
  </w:tbl>
  <w:p>
    <w:r><w:t>Below table</w:t></w:r>
  </w:p>
</w:tc>

Cell Properties Reference

Property Purpose Example
w:tcW Cell width (twips, percent, or auto) <w:tcW w:w="2500" w:type="dxa"/>
w:gridSpan Horizontal span (merges columns) <w:gridSpan w:val="2"/> (spans 2 grid columns)
w:vMerge Vertical merge (spans rows) <w:vMerge/> (start) or <w:vMerge w:val="continue"/> (continuation)
w:tcMar Cell margins/padding <w:tcMar><w:top/><w:left/><w:bottom/><w:right/></w:tcMar>
w:shd Cell background color <w:shd w:fill="D3D3D3"/>
w:tcBorders Cell borders (overrides table borders) <w:tcBorders><w:top/><w:left/><w:bottom/><w:right/></w:tcBorders>
w:vAlign Vertical alignment (top/center/bottom) <w:vAlign w:val="center"/>
w:tcFitText Fit text to cell (shrink font if needed) <w:tcFitText/>

Vertical Alignment

Value Behavior
top Content aligns to top of cell (default)
center Content centers vertically
bottom Content aligns to bottom of cell

Cell Spanning and Merging

Scenario Approach Notes
Horizontal (multi-column) w:gridSpan w:val="N" Cell occupies N grid columns; reduces cell count in row
Vertical (multi-row) w:vMerge (start/continue) First cell in span: <w:vMerge/>, subsequent cells: <w:vMerge w:val="continue"/>
Combined Both gridSpan and vMerge Cell can span both horizontally and vertically simultaneously

Notes

  • Mandatory final paragraph: Every w:tc must end with at least one w:p (paragraph), even if the cell contains only a table. This is a ECMA-376 requirement for spec compliance.
  • Cell width types: Cell width can be absolute (twips/dxa), percentage (pct), or auto; width is constrained by table width and column definitions.
  • Vertical merge restart: Use <w:vMerge/> (no w:val attribute) to start a vertical merge block; cells below use <w:vMerge w:val="continue"/>.
  • Grid Span Impact: When a cell uses w:gridSpan w:val="2", it occupies 2 logical grid columns; the next cell in the row moves to column 3 (not column 2).
  • Cell Margins Override: w:tcMar in cell properties overrides table-level w:tblCellMar; allows per-cell padding adjustments.
  • Borders Override: w:tcBorders in cell properties overrides table-level w:tblBorders; allows custom per-cell border styling.
  • Empty Cells: A cell must contain at least one <w:p> even if empty; never leave a cell with no paragraph.
  • Nested Tables: Tables inside cells inherit no properties from the parent table; define complete table properties for nested tables.
  • Text Fitting: Use w:tcFitText to automatically shrink font if text doesn’t fit; useful for fixed-size cells.
  • Accessibility: Ensure header cells use w:shd contrast and semantic markup; use row/column headers for table navigation.
  • Vertical merge content: Continuation cells in a vertical merge still must contain at least one w:p, but the paragraph is typically empty or hidden from view.
  • Column spanning vs. vertical merge: w:gridSpan spans horizontally across columns; w:vMerge merges cells vertically across rows; they are independent operations.
  • Cell properties override: Cell-level properties in w:tcPr always override table-level properties in w:tblPr; this allows fine-grained control per cell.
  • Nested table content: When a cell contains a nested table, the table structure is complete (including w:tblGrid, w:tblPr, w:tr); the paragraph requirement still applies.
  • Cell margins: Cell padding/margins are controlled via w:tblPr/w:tblCellMar (table-level default) or w:tcPr/w:tcMar (cell-level override).
  • Borders and shading: Individual cell borders and background colors override table-level borders; this allows striped or highlighted rows/columns.
  • Accessibility: Ensure cells contain meaningful content and are structured logically; avoid completely empty cells in data tables as they confuse screen readers.