w:pgBorders (Page Borders)

Specifies borders drawn around each page in a section, with control over which sides display a border and their offset from the page or text edges.

Parent elements

w:sectPr

Child elements

Description

w:pgBorders defines decorative borders around the pages of a section. Unlike paragraph borders (w:pBdr), page borders are drawn at the page margin level and can extend to the edge of the page.

It is defined in ECMA-376 Part 1 §17.6.10.

Attributes

Attribute	Type	Possible Values	Description
`w:zOrder`	`ST_PageBorderZOrder`	`front`, `back`	Whether the border is drawn in front of or behind page content.
`w:display`	`ST_PageBorderDisplay`	`allPages`, `firstPage`, `notFirstPage`	Which pages in the section display the border.
`w:offsetFrom`	`ST_PageBorderOffset`	`page`, `text`	Whether border distances are measured from the page edge or from the text margins.

Child Elements

Each side is represented by its own child element (w:top, w:left, w:bottom, w:right) with the following attributes:

Attribute	Description
`w:val`	Border style (`ST_Border`): `single`, `double`, `dashSmallGap`, `apples`, etc. (including art borders).
`w:color`	Six-digit hex RGB or `auto`.
`w:sz`	Width in eighths of a point.
`w:space`	Distance from text/page edge in points.

Examples

<!-- Full black single-line border around page edge -->
<w:sectPr>
  <w:pgBorders w:offsetFrom="page">
    <w:top    w:val="single" w:color="000000" w:sz="24" w:space="24"/>
    <w:left   w:val="single" w:color="000000" w:sz="24" w:space="24"/>
    <w:bottom w:val="single" w:color="000000" w:sz="24" w:space="24"/>
    <w:right  w:val="single" w:color="000000" w:sz="24" w:space="24"/>
  </w:pgBorders>
</w:sectPr>

new SectionProperties(
  new PageBorders(
    new TopBorder    { Val = BorderValues.Single, Color = "000000", Size = 24U, Space = 24U },
    new LeftBorder   { Val = BorderValues.Single, Color = "000000", Size = 24U, Space = 24U },
    new BottomBorder { Val = BorderValues.Single, Color = "000000", Size = 24U, Space = 24U },
    new RightBorder  { Val = BorderValues.Single, Color = "000000", Size = 24U, Space = 24U }
  )
  { OffsetFrom = PageBorderOffsetValues.Page }
);

<!-- Top and bottom decorative borders only, offset from text margins -->
<w:pgBorders w:offsetFrom="text" w:display="allPages" w:zOrder="front">
  <w:top    w:val="wavy" w:color="4472C4" w:sz="12" w:space="12"/>
  <w:bottom w:val="wavy" w:color="4472C4" w:sz="12" w:space="12"/>
</w:pgBorders>

new PageBorders(
  new TopBorder    { Val = BorderValues.Wavy, Color = "4472C4", Size = 12U, Space = 12U },
  new BottomBorder { Val = BorderValues.Wavy, Color = "4472C4", Size = 12U, Space = 12U }
)
{
  OffsetFrom = PageBorderOffsetValues.Text,
  Display = PageBorderDisplayValues.AllPages,
  ZOrder = PageBorderZOrderValues.Front
};

Notes

Offset Reference: w:offsetFrom="page" measures from page edge; w:offsetFrom="text" from text margins.
Size Unit: Border w:sz in eighths-of-a-point; sz=”24” = 3 points.
Space Unit: w:space in points when offsetFrom=”page”; twentieths-of-a-point when offsetFrom=”text”.
Display Options: allPages (all), firstPage (first only), notFirstPage (all except first).
Z-Order: front places border over page content; back places behind.
Partial Borders: Omit any w:top, w:left, w:bottom, w:right child to exclude that side.
Art Borders: Special art border types (apples, babyPacifier, etc.) may not render consistently across apps.
Color Specification: 6-digit hex RGB or “auto” for default color.
Section-Level: Borders apply to entire section; different sections can have different borders.
Compatibility: Basic border styles (single, double, dotted, dashed) render consistently; art borders may vary.