w:pPr (Paragraph Properties)

Container for all formatting properties applied to a paragraph.

Parent elements

Child elements

Description

w:pPr is the paragraph properties container, grouping all formatting properties for a w:p element. It is defined in ECMA-376 Part 1 §17.3.1.26.

When w:pPr appears inside a w:style element, it defines the default paragraph properties for that style. When inside w:lvl, it defines properties for a particular list level. The w:pPr element acts as the control center for all block-level formatting, including indentation, spacing, borders, shading, alignment, and outline level.

Unlike inline formatting (handled by w:rPr), paragraph properties apply to the entire paragraph and take effect from the paragraph mark. The ordering of child elements matters for schema validation; properties should follow the ECMA-376 specification order.

Attributes

Attribute	Type	Possible Values	Description
(none)	—	—	All paragraph properties are expressed via child elements; `w:pPr` itself has no attributes.

Child Elements by Category

Style & Formatting

Alignment & Indentation

Spacing

Numbering & Outline

Page & Line Control

Character Formatting

Sections

Examples

Basic paragraph with heading style and center alignment

<w:p>
  <w:pPr>
    <w:pStyle w:val="Heading1"/>
    <w:jc w:val="center"/>
  </w:pPr>
  <w:r><w:t>Chapter Title</w:t></w:r>
</w:p>

var para = new Paragraph(
  new ParagraphProperties(
    new ParagraphStyleId { Val = "Heading1" },
    new Justification { Val = JustificationValues.Center }),
  new Run(new Text("Chapter Title")));

Complex paragraph: styled, indented, spaced, with shading

<w:p>
  <w:pPr>
    <w:pStyle w:val="BodyText"/>
    <w:jc w:val="left"/>
    <w:ind w:left="720" w:right="360" w:firstLine="720"/>
    <w:spacing w:before="120" w:after="120" w:line="360" w:lineRule="auto"/>
    <w:shd w:fill="E8F4F8"/>
    <w:pBdr>
      <w:top w:val="single" w:sz="12" w:space="1" w:color="0070C0"/>
    </w:pBdr>
  </w:pPr>
  <w:r>
    <w:rPr><w:b/></w:rPr>
    <w:t>Important note:</w:t>
  </w:r>
  <w:r><w:t> This paragraph has multiple formatting properties applied.</w:t></w:r>
</w:p>

var para = new Paragraph(
  new ParagraphProperties(
    new ParagraphStyleId { Val = "BodyText" },
    new Justification { Val = JustificationValues.Left },
    new Indentation { Left = "720", Right = "360", FirstLine = "720" },
    new SpacingBetweenLines { Before = "120", After = "120", Line = "360", LineRule = LineSpacingRuleValues.Auto },
    new Shading { Val = ShadingPatternValues.Clear, Fill = "E8F4F8" },
    new ParagraphBorders(
      new TopBorder { Val = BorderValues.Single, Sz = 12, Space = 1, Color = "0070C0" })),
  new Run(new RunProperties(new Bold()), new Text("Important note:")),
  new Run(new Text(" This paragraph has multiple formatting properties applied.")));

Bulleted list item with paragraph properties

<w:p>
  <w:pPr>
    <w:pStyle w:val="ListBullet"/>
    <w:numPr>
      <w:ilvl w:val="0"/>
      <w:numId w:val="1"/>
    </w:numPr>
    <w:ind w:left="720" w:hanging="360"/>
    <w:spacing w:after="0"/>
  </w:pPr>
  <w:r><w:t>First bullet point</w:t></w:r>
</w:p>

var para = new Paragraph(
  new ParagraphProperties(
    new ParagraphStyleId { Val = "ListBullet" },
    new NumberingProperties(
      new NumberingLevelReference { Val = 0 },
      new NumberingId { Val = 1 }),
    new Indentation { Left = "720", Hanging = "360" },
    new SpacingBetweenLines { After = "0" }),
  new Run(new Text("First bullet point")));

Notes

Child element order: ECMA-376 specifies a strict order for w:pPr children. When building programmatically, the OpenXml SDK enforces this order automatically.
Style inheritance: When a paragraph applies a style via w:pStyle, the paragraph properties defined in the style are inherited. Direct properties in w:pPr override the style’s properties.
Paragraph mark properties: The w:rPr child (if present) defines the formatting of the paragraph mark itself, which affects certain behaviors like line spacing calculations.
Toggle properties: Elements like w:keepNext, w:keepLines, w:pageBreakBefore are on/off flags; their presence means true, absence means false.
Measurement units: All distance attributes use twentieths of a point (twips); 1 inch = 1440 twips, 1 cm ≈ 567 twips.
Performance: Complex paragraph properties with many borders, shading, and nested formatting can impact document rendering performance when applied to thousands of paragraphs.

<w:p>
  <w:pPr>
    <w:pStyle w:val="Heading1"/>
    <w:jc w:val="center"/>
  </w:pPr>
  <w:r><w:t>Chapter Title</w:t></w:r>
</w:p>

new Paragraph(
  new ParagraphProperties(
    new ParagraphStyleId { Val = "Heading1" },
    new Justification { Val = JustificationValues.Center },
    new SpacingBetweenLines { Before = "240", After = "120" }),
  new Run(new Text("Title Text")));