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();

Paragraph with page break and mixed content

<w:p>
  <w:pPr>
    <w:pageBreakBefore/>
    <w:pStyle w:val="Heading2"/>
  </w:pPr>
  <w:r>
    <w:b/>
    <w:t>New Section</w:t>
  </w:r>
</w:p>

new Paragraph(
  new ParagraphProperties(
    new PageBreakBefore(),
    new ParagraphStyleId { Val = "Heading2" }),
  new Run(
    new RunProperties(new Bold()),
    new Text("New Section")));

Paragraph Content Model

Paragraph Mark Behavior

• Implicit Mark: Every <w:p> implicitly ends with a paragraph mark (non-printing glyph)
• Mark Formatting: Formatting for the mark lives in <w:pPr><w:rPr>, not in a separate <w:r>
• Trailing Whitespace: The mark carries default character properties for any trailing space/soft returns
• Copy/Paste: The mark copies with the paragraph; pasting paragraphs includes mark properties

RSID Attributes (Revision Tracking)

Notes

• Hierarchical constraint: 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.
• Property ordering: When w:pPr is present it must be the first child element; placing it after run content is invalid and violates the OOXML schema.
• Paragraph Mark Glyph: The invisible mark at paragraph end carries properties from w:pPr/w:rPr; users see it as ¶ in Word’s formatting view.
• Empty Paragraphs: A <w:p/> with no children is a valid empty paragraph, useful for spacing and blank lines.
• Runs vs. Properties: Properties apply to entire paragraph; runs apply character-level formatting inside runs.
• Unique IDs: w14:paraId and w14:textId must be unique within document for cross-reference stability during editing.
• Style Inheritance: If no w:pStyle specified, paragraph inherits from “Normal” style (typically defined in styles.xml).
• Bidirectional Text: Use w:bdo (bidirectional override) or w:dir (direction) for mixed LTR/RTL content (Arabic, Hebrew).
• Revision Tracking: RSID attributes allow Word to correlate edits across save sessions and user machines.
• Office Math: w:oMathPara is for block-level equations; w:oMath is inline (inside w:r).
• Revision tracking attributes: The rsid* attributes are round-trip attributes — a conforming producer may omit them, and a conforming consumer must not fail if they are absent. They track which editing session modified the paragraph.
• Section break behavior: 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 suppression: 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.
• Paragraph mark properties: The paragraph mark (implicit last character) carries formatting from w:pPr/w:rPr; this is where run properties for the mark itself live, separate from run properties in w:r children.
• Empty paragraphs: An empty <w:p/> (or <w:p><w:pPr>.../></w:p>) is valid and represents a blank line or spacing element; they are essential for layout and should not be removed when processing documents.
• Style inheritance: Paragraph-level properties can be applied via style (w:pStyle) or direct properties in w:pPr; direct properties override style properties.
• Content ordering: Paragraphs in the body flow sequentially; each paragraph is independent, but their w:pPr properties (especially spacing) can create visual grouping.
• Table cell requirements: Every table cell (w:tc) must end with at least one w:p; paragraphs cannot be omitted from cell content even if the cell appears visually empty.
• Field codes in paragraphs: Complex fields are constructed using w:fldChar (begin/separate/end) with w:instrText; simple fields use w:fldSimple with the w:instr attribute.