OOXML.org

w:t (Text Content)

Contains the literal character data of a run. Use xml:space='preserve' when leading or trailing spaces are significant.

Parent elements

Description

w:t holds the literal text content of a run. It is defined in ECMA-376 Part 1 §17.3.3.31.

By default, XML parsers strip leading and trailing whitespace from element content. To preserve spaces at the start or end of the text node, set the standard XML attribute xml:space="preserve". This is important when the text is part of a word boundary that spans multiple runs.

Attributes

Attribute Type Possible Values Description
xml:space XML standard preserve (keep leading/trailing spaces) or default (XML default — spaces may be collapsed). Controls whitespace handling for the text content.

Examples

Plain text

<w:t>Hello</w:t>

Text with preserved leading space

<w:t xml:space="preserve"> world</w:t>

Whitespace Handling Examples

Scenario XML Behavior
Text with leading space (needs preserve) <w:t xml:space="preserve"> text</w:t> Space is kept
Text without leading space <w:t>text</w:t> No special attribute needed
Multiple internal spaces <w:t>hello world</w:t> Internal spaces always preserved
Trailing space (needs preserve) <w:t xml:space="preserve">text </w:t> Space is kept
Whitespace-only content <w:t xml:space="preserve"> </w:t> Three spaces (not collapsed)

Text Run Examples

Use Case XML Notes
Simple word <w:r><w:t>hello</w:t></w:r> No preserve needed (internal)
Word boundary prefix <w:r><w:t xml:space="preserve"> </w:t></w:r> Leading space forces preserve
Sentence split across runs <w:r><w:t>Hello</w:t></w:r><w:r><w:t xml:space="preserve"> </w:t></w:r><w:r><w:t>World</w:t></w:r> Middle space must have preserve
Tab character <w:r><w:tab/></w:r> OR <w:r><w:t>&#9;</w:t></w:r> Use w:tab element preferably
Soft return <w:r><w:br/></w:r> Don’t put actual newline in w:t
Multiple spaces in formula <w:r><w:t xml:space="preserve"> = A1 + B1 </w:t></w:r> Preserve for alignment

Notes

  • Whitespace preservation critical: Always use xml:space="preserve" when the text begins or ends with a space character; otherwise the space will be lost during XML parsing and the word boundary will be corrupted.
  • Scope limitation: w:t can only appear inside w:r (Text Run); it must not span run or paragraph boundaries.
  • Multiple runs for punctuation: If a space or punctuation follows formatted text, place it in a separate w:t with xml:space="preserve" to ensure consistent formatting.
  • Empty text elements: An empty <w:t></w:t> is valid but unusual; typically used in field construction or template placeholders.
  • Special character escaping: Text content does not use entity references for special characters (e.g., use &, not &amp; in source; XML parser handles encoding).
  • Line breaks within runs: Use w:br or w:tab for line/tab characters, not literal newlines in text content.
  • Text concatenation: When multiple w:t elements appear in the same w:r, their content is concatenated with no separator; spacing must be explicit.
  • Non-breaking spaces: Use &#xA0; (Unicode non-breaking space) in text for spaces that should not wrap, but be mindful that some tools may normalize these.
  • Unicode normalization: Different tools may normalize Unicode text differently (NFD vs NFC); the spec doesn’t mandate a specific form.
  • Accessibility: Screen readers depend on text nodes; empty or hidden text may confuse accessibility tools; provide alt text for images via attributes.
  • Performance: Very long text nodes (>5,000 characters) can impact rendering performance; consider splitting across multiple runs if acceptable.
  • Field codes and variables: In field codes, text within w:t is literal and not computed; use field machinery for dynamic content.
  • Bidirectional text: Bidirectional text (RTL languages) uses w:t same as LTR; use w:dir or w:bdo for explicit directionality.