w:tblBorders (Table Borders)

Defines border styles for the outside edges and inside rules of the table.

Parent elements

w:tblPr

Description

w:tblBorders specifies the border settings applied to all outside edges and inside grid lines of an entire table. It is defined in ECMA-376 Part 1 §17.4.39.

Each child element (w:top, w:bottom, w:left, w:right, w:insideH, w:insideV) defines the border for one logical position: perimeter edges (top, bottom, left, right) control the table boundary, while insideH and insideV control the horizontal and vertical gridlines within the table. Individual cell borders defined in w:tcBorders or paragraph-level w:pBdr can override these table-level defaults using precedence rules (explicit cell borders override table defaults).

The table border model establishes a consistent appearance but allows exceptions at the cell level, enabling designs like alternating row styles or highlighted header rows without redefining borders on every cell.

Attributes

Attribute	Type	Possible Values	Description
(none)	—	—	All borders are specified via child border elements (`w:top`, `w:bottom`, `w:left`, `w:right`, `w:insideH`, `w:insideV`).

Each border child element supports:

Child attribute	Type	Possible Values	Description
`w:val`	`ST_Border`	`single`, `double`, `thick`, `dotted`, `dashed`, `dashDot`, `dashDotDot`, `triple`, `thinThickSmallGap`, `nil`, `none`, etc.	Border style. `nil` removes any border (stronger than `none`).
`w:sz`	`ST_EighthPointMeasure`	Positive integer in eighths-of-a-point (e.g. `4` = 0.5 pt, `8` = 1 pt)	Border thickness.
`w:space`	`ST_PointMeasure`	Integer in points	Space between border and content.
`w:color`	`ST_HexColorAuto`	6-digit hex RGB or `auto`	Border colour.

Examples

<!-- Basic table with uniform borders -->
<w:tblBorders>
  <w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/>
  <w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/>
  <w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/>
  <w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/>
  <w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto"/>
  <w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto"/>
</w:tblBorders>

var border = () => new BorderType { Val = BorderValues.Single, Size = 4, Space = 0, Color = "auto" };
new TableBorders(
  new TopBorder(border()),
  new LeftBorder(border()),
  new BottomBorder(border()),
  new RightBorder(border()),
  new InsideHorizontalBorder(border()),
  new InsideVerticalBorder(border()));

<!-- Table with no inner grid lines, only outer border -->
<w:tblBorders>
  <w:top w:val="double" w:sz="8" w:space="0" w:color="0070C0"/>
  <w:left w:val="double" w:sz="8" w:space="0" w:color="0070C0"/>
  <w:bottom w:val="double" w:sz="8" w:space="0" w:color="0070C0"/>
  <w:right w:val="double" w:sz="8" w:space="0" w:color="0070C0"/>
  <w:insideH w:val="nil"/>
  <w:insideV w:val="nil"/>
</w:tblBorders>

new TableBorders(
  new TopBorder { Val = BorderValues.Double, Size = 8, Space = 0, Color = "0070C0" },
  new LeftBorder { Val = BorderValues.Double, Size = 8, Space = 0, Color = "0070C0" },
  new BottomBorder { Val = BorderValues.Double, Size = 8, Space = 0, Color = "0070C0" },
  new RightBorder { Val = BorderValues.Double, Size = 8, Space = 0, Color = "0070C0" },
  new InsideHorizontalBorder { Val = BorderValues.Nil },
  new InsideVerticalBorder { Val = BorderValues.Nil });

Notes

Border Precedence: Table-level borders form the baseline; w:tcBorders and w:pBdr (paragraph borders) can override at the cell/paragraph level. Explicit cell borders always win over table borders.
Size Conversion: Border w:sz is measured in eighths-of-a-point; convert to points by dividing by 8 (e.g., sz="24" = 3 points).
Grid Lines: insideH (horizontal) and insideV (vertical) control the visible gridlines between cells; omit these for a borderless table interior.
Nil vs. None: w:val="nil" completely removes a border (overrides style inheritance), while w:val="none" is a style value that renders as no visible border but may be overridden.
Color Specification: Use 6-digit hex RGB (e.g., 0070C0) for consistency across applications; color="auto" resolves to the default foreground color.
Empty tblBorders Element: An empty <w:tblBorders/> inherits all border settings from the table style; explicitly set w:val="nil" on edges to remove them.
Cell Merging & Borders: Merged cells (w:vMerge, w:gridSpan) still respect w:tcBorders; merged cell boundaries follow cell-level, not table-level, border rules.
Performance Consideration: Large tables with many individually-specified cell borders should consider using table styles instead to reduce XML bloat.
RTL Tables: The perimeter borders (top, bottom, left, right) apply consistently regardless of text direction; for truly RTL-aware table layouts, adjust cell-level w:tcBorders.
Compatibility: All border styles (single, double, dotted, etc.) are stable across Office versions; custom patterns should be avoided for cross-platform compatibility.