w:tcPr (Table Cell Properties)

Container for formatting properties applied to a single table cell.

Parent elements

w:tc

Child elements

Description

w:tcPr is the table cell properties container, grouping all cell-level formatting. It is defined in ECMA-376 Part 1 §17.4.70.

Common children include w:tcW (cell width), w:gridSpan (column spanning), w:vMerge (vertical merging), w:tcBorders (cell borders), w:shd (background color), w:tcMar (cell margins), w:vAlign (vertical text alignment), and others. Cell-level properties override table-level properties defined in w:tblPr.

Cell properties control the appearance and behavior of individual cells within the table, including their size, borders, fill color, text alignment, and merge behavior.

Examples

<!-- Simple cell: width, light blue background, center alignment -->
<w:tcPr>
  <w:tcW w:w="2000" w:type="dxa"/>
  <w:shd w:fill="E8F4F8"/>
  <w:vAlign w:val="center"/>
</w:tcPr>

new TableCellProperties(
  new TableCellWidth { Width = "2000", Type = TableWidthUnitValues.Dxa },  // 1.4 inches
  new Shading { Fill = "E8F4F8" },  // Light blue
  new TableCellVerticalAlignment { Val = TableVerticalAlignmentValues.Center });

<!-- Spanning cell: 3 columns, double borders, custom margins -->
<w:tcPr>
  <w:tcW w:w="6000" w:type="dxa"/>
  <w:gridSpan w:val="3"/>
  <w:tcBorders>
    <w:top w:val="double" w:sz="24" w:color="0070C0"/>
    <w:bottom w:val="double" w:sz="24" w:color="0070C0"/>
  </w:tcBorders>
  <w:tcMar>
    <w:top w:w="100" w:type="dxa"/>
    <w:left w:w="100" w:type="dxa"/>
    <w:right w:w="100" w:type="dxa"/>
    <w:bottom w:w="100" w:type="dxa"/>
  </w:tcMar>
</w:tcPr>

new TableCellProperties(
  new TableCellWidth { Width = "6000", Type = TableWidthUnitValues.Dxa },
  new GridSpan { Val = 3 },  // Spans 3 grid columns
  new TableCellBorders(
    new TopBorder { Val = BorderValues.Double, Sz = 24U, Color = "0070C0" },
    new BottomBorder { Val = BorderValues.Double, Sz = 24U, Color = "0070C0" }),
  new TableCellMargin { Top = 100, Left = 100, Right = 100, Bottom = 100 });

Measurement Conversions

Width	Twips	Inches	mm
1 inch	1440	1.0	25.4
1.5 inches	2160	1.5	38.1
2 inches	2880	2.0	50.8
3 inches	4320	3.0	76.2

<w:vAlign w:val="center"/>
</w:tcPr>
<!-- Subsequent cell (continue merge) -->
<w:tcPr>
  <w:vMerge/>
</w:tcPr>

// First cell of vertical merge
var tcPr1 = new TableCellProperties(
  new TableCellWidth { Width = "1500", Type = TableWidthUnitValues.Dxa },
  new VerticalMerge { Val = MergedCellValues.Restart },
  new TableCellMargin(
    new TopMargin { Width = "100", Type = TableWidthUnitValues.Dxa },
    new LeftMargin { Width = "100", Type = TableWidthUnitValues.Dxa },
    new BottomMargin { Width = "100", Type = TableWidthUnitValues.Dxa },
    new RightMargin { Width = "100", Type = TableWidthUnitValues.Dxa }),
  new TableCellVerticalAlignment { Val = TableVerticalAlignmentValues.Center });

// Subsequent cell (continue merge)
var tcPr2 = new TableCellProperties(
  new VerticalMerge());  // No Val attribute = continue

Width Measurement Reference

Unit	Value	Example
Twips (dxa)	1440 = 1 inch	`<w:tcW w:w="2160" w:type="dxa"/>` = 1.5 inches
Percentage (pct)	5000 = 50%	`<w:tcW w:w="3333" w:type="pct"/>` = ~33%
Auto	0	`<w:tcW w:w="0" w:type="auto"/>` = auto-width

Vertical Alignment Options

Value	Position	Use Case
`top`	Top of cell	Default, most headers
`center`	Center of cell	Centered content, data cells
`bottom`	Bottom of cell	Footer rows

Notes

Cell overrides: Properties in w:tcPr override table-level w:tblPr properties, including borders and margins.
Grid spanning: w:gridSpan combines logical grid columns; actual column widths come from the table grid.
Vertical merging: Use w:vMerge with val="restart" to begin a merge; omit val to continue it in subsequent rows.
Width types and units: Widths can use dxa (twips), pct (fiftieths of a percent), auto, or nil. One inch is 1440 twips; one centimeter is approximately 567 twips.
Cell margins: Cell-level margins override w:tblCellMar and can provide different padding for header cells.
Borders: Cell borders override outer and inner table borders defined in w:tblBorders.
Background color: w:shd sets the cell fill; use six-digit hexadecimal RGB values.
Text alignment and direction: w:vAlign sets top, center, or bottom alignment. Use w:textDirection for vertical text, with common values lrTb and tbLr.
Compatibility: Cell properties render consistently across Office versions.