w:p (Paragraph)

Description

w:p (paragraph) is the fundamental block-level container in a WordprocessingML document. Every piece of flowing body text lives inside a paragraph. The element is defined in ECMA-376 Part 1 §17.3.1.22 and maps to ISO/IEC 29500-1 §17.3.1.22.

The contents of a paragraph can be any combination of the following four kinds of content (in document order):

1. Paragraph properties (w:pPr) — exactly zero or one, always the first child when present. Controls alignment, indentation, spacing, numbering, style, and other paragraph-level formatting.
2. Annotations — bookmarks (w:bookmarkStart/w:bookmarkEnd), comment anchors, revision markup (w:ins, w:del), and permission ranges.
3. Custom markup — inline custom XML (w:customXml) and structured document tags (w:sdt).
4. Run-level content — text runs (w:r), hyperlinks (w:hyperlink), simple fields (w:fldSimple), bidirectional overrides (w:bdo/w:dir), Office Math (w:oMath/w:oMathPara), and subdocument anchors (w:subDoc).

Paragraph mark

Every w:p element implicitly ends with a paragraph mark — the non-printing glyph that Word stores as the last character. Run properties applied to that glyph are held in w:pPr/w:rPr (not in a separate w:r). Consumers must treat the paragraph mark as carrying the default character formatting for any trailing whitespace in the paragraph.

Empty paragraphs

A w:p element with no w:r children (and no other run-level content) is a valid, empty paragraph. Such paragraphs are used as paragraph separators and to carry blank lines, page breaks inserted via w:br, or section properties (w:sectPr inside w:pPr).

Paragraph identity and revision tracking

Each w:p carries up to five rsid* attributes that allow applications to correlate edits across save sessions. These are informational only; consumers are not required to preserve or honour them.

Attributes

Examples

Minimal paragraph

<w:p>
  <w:r>
    <w:t>Hello OOXML</w:t>
  </w:r>
</w:p>

new Paragraph(
  new Run(
    new Text("Hello OOXML")));

Paragraph with properties (centred, Heading 1 style)

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

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

Paragraph containing both a run and a simple field

<w:p>
  <w:r>
    <w:t xml:space="preserve">Prepared by: </w:t>
  </w:r>
  <w:fldSimple w:instr="AUTHOR">
    <w:r>
      <w:t>Jane Smith</w:t>
    </w:r>
  </w:fldSimple>
</w:p>

new Paragraph(
  new Run(new Text("Prepared by: ") { Space = SpaceProcessingModeValues.Preserve }),
  new SimpleField(
    new Run(new Text("Jane Smith"))) { Instruction = "AUTHOR" });

Empty paragraph (blank line)

<w:p/>

new Paragraph();

Notes

• w:p must appear as a direct child of w:body, w:tc, w:hdr, w:ftr, w:comment, w:footnote, w:endnote, w:sdtContent, w:docPartBody, or an inline w:customXml. It is not valid inside another w:p.
• When w:pPr is present it must be the first child element; placing it after run content is invalid.
• The rsid* attributes are round-trip attributes — a conforming producer may omit them, and a conforming consumer must not fail if they are absent.
• A paragraph that carries a w:sectPr inside its w:pPr acts as a section break paragraph. The section properties apply to the section that ends at this paragraph; the paragraph’s own text (if any) belongs to the new section.
• Spell-check and grammar-check suppression for an entire paragraph can be achieved via w:pPr/w:rPr/w:noProof (affects the paragraph mark) together with w:noProof on each constituent run.