w:r (Text Run)

Description

w:r is a run — the fundamental unit of formatted text in a paragraph. It is defined in ECMA-376 Part 1 §17.3.2.25.

A run groups one or more consecutive characters that share the same set of run properties (w:rPr). A paragraph may contain any number of runs. Each run can hold text (w:t), special characters (w:br, w:tab, w:sym), and inline objects (w:drawing, w:fldChar).

Runs are the lowest-level block of content in the paragraph model; they do not span paragraph boundaries.

Attributes

w:r has no attributes of its own. Content and formatting are specified through its child elements.

Examples

Plain text run

<w:r>
  <w:t>Hello, World!</w:t>
</w:r>

new Run(new Text("Hello, World!"));

Bold, 14pt run

<w:r>
  <w:rPr>
    <w:b/>
    <w:sz w:val="28"/>
  </w:rPr>
  <w:t>Important!</w:t>
</w:r>

new Run(
  new RunProperties(
    new Bold(),
    new FontSize { Val = "28" }),
  new Text("Important!"));

Complex formatted run with multiple properties

<w:r>
  <w:rPr>
    <w:b/>
    <w:i/>
    <w:color w:val="0070C0"/>
    <w:sz w:val="24"/>
    <w:highlight w:val="yellow"/>
  </w:rPr>
  <w:t xml:space="preserve">Emphasized </w:t>
</w:r>

new Run(
  new RunProperties(
    new Bold(),
    new Italic(),
    new Color { Val = "0070C0" },
    new FontSize { Val = "24" },
    new Highlight { Val = HighlightColorValues.Yellow }),
  new Text(" Emphasized ") { Space = SpaceProcessingModeValues.Preserve });

Run with special characters and drawing

<w:r>
  <w:rPr>
    <w:b/>
  </w:rPr>
  <w:t>Text with: </w:t>
</w:r>
<w:r>
  <w:br/>  <!-- Line break -->
</w:r>
<w:r>
  <w:tab/>  <!-- Tab character -->
</w:r>
<w:r>
  <w:drawing>
    <!-- Inline image or shape -->
  </w:drawing>
</w:r>

// Text run
new Run(new RunProperties(new Bold()),
  new Text("Text with: "))
// Line break run
new Run(new Break())
// Tab run
new Run(new TabChar())
// Drawing (image) run
new Run(new Drawing(...))

Run Content Model

Key Characteristics

• Minimum Formatting Unit: Runs are the smallest block of consistently formatted text.
• Homogeneous Properties: All text in a run shares identical character formatting.
• Paragraph-Scoped: Runs cannot span paragraph boundaries; they must be children of w:p or similar container.
• Sequential: Multiple runs in a paragraph are rendered sequentially without gaps.
• Content Flexibility: Single run can mix text, whitespace, line breaks, tabs, symbols, and embedded objects.
• No Direct Style: Runs don’t directly reference styles; formatting comes from w:rPr child element.
• Inheritance: If no w:rPr specified, run inherits formatting from parent paragraph’s style.

Run with Tab and Line Break

<w:r>
  <w:rPr><w:b/></w:rPr>
  <w:t>Column 1</w:t>
</w:r>
<w:r><w:tab/></w:r>
<w:r><w:t>Column 2</w:t></w:r>
<w:r><w:br/></w:r>
<w:r><w:t>Next line</w:t></w:r>

new Run(new RunProperties(new Bold()), new Text("Column 1")),
new Run(new TabChar()),
new Run(new Text("Column 2")),
new Run(new Break()),
new Run(new Text("Next line"));

Font Size Reference

Notes

• Runs vs. paragraphs: Runs never span paragraph boundaries; formatting changes require a new run. Multiple runs in a paragraph render sequentially.
• Empty runs: A run with no text content (<w:r></w:r>) is valid but unusual; it typically contains only properties or special elements.
• Run content: A single w:r can contain multiple w:t elements, but all text in the run shares the same w:rPr properties.
• Hyperlinks: Runs inside w:hyperlink gain hyperlink behavior; the run itself does not carry the link target.
• Change tracking: Deleted text uses w:delText instead of w:t; w:ins and w:del wrap runs to mark insertions and deletions.
• Field codes: Runs with w:instrText and w:fldChar implement fields such as mail merge, tables of contents, and dates. A field uses begin, instruction, and end markers rather than a plain text string.
• Whitespace: Use xml:space="preserve" on w:t to keep leading or trailing whitespace; XML parsers otherwise strip it.
• Special characters: Use w:tab, w:br, and w:sym for tabs, line breaks, and symbol-font characters rather than literal text characters.
• Text direction: Complex scripts such as Arabic and Hebrew use bCs, iCs, and szCs variants in w:rPr for bidirectional text handling.
• Inline objects: Use w:drawing for images, shapes, and charts; anchored or inline positioning is determined by shape properties.
• Property inheritance: Without w:rPr, a run inherits formatting from paragraph mark properties (w:pPr/w:rPr) or its applied style.
• Performance: Excessive small runs can affect rendering speed; split very long runs (over 10,000 characters) when doing so improves processing.
• Accessibility: Provide meaningful text and alternative text for drawings; avoid runs containing only formatting or whitespace without descriptive context.