a:r (Text Run)

Description

a:r is the DrawingML text run element that represents a contiguous sequence of text characters with uniform formatting. It is defined in ECMA-376 Part 1 §20.1.2.3.3 and is the fundamental building block for styled text in DrawingML documents.

Unlike elements or XML nodes, a text run in DrawingML is semantically equivalent to a “span” or “text fragment” in HTML — it groups consecutive characters that share a single set of formatting attributes (font, color, size, bold, italic, underline, etc.). Whenever the formatting changes within a paragraph, a new run must be created.

Text Run Purpose

The purpose of a:r is to:

1. Encapsulate Formatted Text — Bind text content (a:t) with its formatting rules (a:rPr) into a single, indivisible unit.
2. Enable Mixed Formatting — Allow paragraphs to contain text with varying styles without creating new logical paragraphs.
3. Separate Content from Presentation — Keep text (a:t) separate from its visual properties (a:rPr).
4. Support Language and Direction — Attach language codes (ISO 639) and text direction (left-to-right, right-to-left) to text segments.

Run Properties (a:rPr)

The optional a:rPr child element specifies character-level formatting:

• Typography: Font family, size, weight (bold), slant (italic), underline, strikethrough
• Color and Effects: Fill (solid, gradient, pattern), outline, shadow, glow, reflection, soft edge
• Advanced Styling: Superscript/subscript, capitalization (small caps, uppercase), spacing, rotation
• Language and Localization: Language code, East Asian/Complex Script font substitution

If a:rPr is omitted, the run inherits formatting from the paragraph properties (a:pPr) or the master/theme default.

Text Content (a:t)

The required a:t child element contains the actual Unicode text string. Each run contains exactly one a:t element. If a run has no text (empty a:t), it is effectively invisible but may carry end-of-run properties for the next run.

Run Precedence

Formatting is applied in this precedence order (highest to lowest):

1. Run properties (a:rPr) — Most specific
2. Paragraph properties (a:pPr) — Intermediate
3. Master/Theme defaults — Least specific

Content Model

a:r
├─ a:rPr (0–1, optional)
│  ├─ a:latin | a:ea | a:cs (Font substitution)
│  ├─ a:solidFill | a:schemeClr (Color fill)
│  ├─ a:ln (Outline)
│  ├─ a:effectLst (Effects: shadow, glow, reflection, etc.)
│  └─ ... (30+ child elements for full formatting)
└─ a:t (1, required) — Text content (string)

Attributes

Run Properties Reference

The a:rPr element (child of a:r) controls these character-level properties:

Examples

Plain Text Run (No Explicit Properties)

<a:r>
  <a:t>Simple text with inherited formatting</a:t>
</a:r>

var run = new Run(
  new Text("Simple text with inherited formatting"));

Bold and Italic Runs

<a:p>
  <a:pPr lvl="0"/>
  <a:r>
    <a:rPr sz="2400" b="1" lang="en-US"/>
    <a:t>Bold text</a:t>
  </a:r>
  <a:r>
    <a:rPr sz="2400" lang="en-US"/>
    <a:t> and </a:t>
  </a:r>
  <a:r>
    <a:rPr sz="2400" i="1" lang="en-US"/>
    <a:t>italic text</a:t>
  </a:r>
</a:p>

var para = new Paragraph(
  new ParagraphProperties { Level = 0 },
  new Run(
    new RunProperties { FontSize = 2400, Bold = true, Language = "en-US" },
    new Text("Bold text")),
  new Run(
    new RunProperties { FontSize = 2400, Language = "en-US" },
    new Text(" and ")),
  new Run(
    new RunProperties { FontSize = 2400, Italic = true, Language = "en-US" },
    new Text("italic text")));

Colored Text Run with Solid Fill

<a:r>
  <a:rPr sz="2400" lang="en-US">
    <a:solidFill>
      <a:srgbClr val="FF0000"/>
    </a:solidFill>
  </a:rPr>
  <a:t>Red text</a:t>
</a:r>

var run = new Run(
  new RunProperties { FontSize = 2400, Language = "en-US" }
    .Append(new SolidFill(new RgbColorModelHex { Val = "FF0000" })),
  new Text("Red text"));

Text with Hyperlink-Style Formatting (Blue + Underline)

<a:r>
  <a:rPr sz="2400" u="sng" lang="en-US">
    <a:solidFill>
      <a:srgbClr val="0563C1"/>
    </a:solidFill>
  </a:rPr>
  <a:t>Hyperlink-styled text</a:t>
</a:r>

var run = new Run(
  new RunProperties 
  { 
    FontSize = 2400, 
    Underline = TextUnderlineValues.Single,
    Language = "en-US"
  }.Append(new SolidFill(new RgbColorModelHex { Val = "0563C1" })),
  new Text("Hyperlink-styled text"));

Superscript and Subscript

<a:p>
  <a:pPr lvl="0"/>
  <a:r>
    <a:rPr sz="2400" lang="en-US"/>
    <a:t>E=mc</a:t>
  </a:r>
  <a:r>
    <a:rPr sz="1400" baseline="35000" lang="en-US"/>
    <a:t>2</a:t>
  </a:r>
  <a:r>
    <a:rPr sz="2400" lang="en-US"/>
    <a:t> and H</a:t>
  </a:r>
  <a:r>
    <a:rPr sz="1400" baseline="-25000" lang="en-US"/>
    <a:t>2</a:t>
  </a:r>
  <a:r>
    <a:rPr sz="2400" lang="en-US"/>
    <a:t>O</a:t>
  </a:r>
</a:p>

var para = new Paragraph(
  new ParagraphProperties { Level = 0 },
  new Run(new RunProperties { FontSize = 2400, Language = "en-US" }, new Text("E=mc")),
  new Run(new RunProperties { FontSize = 1400, Baseline = 35000, Language = "en-US" }, new Text("2")),
  new Run(new RunProperties { FontSize = 2400, Language = "en-US" }, new Text(" and H")),
  new Run(new RunProperties { FontSize = 1400, Baseline = -25000, Language = "en-US" }, new Text("2")),
  new Run(new RunProperties { FontSize = 2400, Language = "en-US" }, new Text("O")));

Strikethrough and Shadow Effects

<a:r>
  <a:rPr sz="2400" strike="sngStrike" lang="en-US">
    <a:effectLst>
      <a:outerShdw blurRad="50800" dist="38100" dir="2700000" algn="tl" rotWithShape="0">
        <a:srgbClr val="000000">
          <a:alpha val="100000"/>
        </a:srgbClr>
      </a:outerShdw>
    </a:effectLst>
  </a:rPr>
  <a:t>Struck-out shadowed text</a:t>
</a:r>

var effectLst = new EffectList();
var shadow = new OuterShadow 
{ 
  BlurRadius = 50800, 
  Distance = 38100, 
  Direction = 2700000, 
  Alignment = RectangleAlignmentValues.TopLeft
};
shadow.Append(new RgbColorModelHex { Val = "000000" }
  .Append(new Alpha { Val = 100000 }));
effectLst.Append(shadow);

var run = new Run(
  new RunProperties 
  { 
    FontSize = 2400, 
    Strike = TextStrikeValues.SingleStrike,
    Language = "en-US"
  }.Append(effectLst),
  new Text("Struck-out shadowed text"));

Multi-Language Text (Font Substitution)

<a:r>
  <a:rPr sz="2400" lang="en-US">
    <a:latin typeface="Calibri"/>
    <a:ea typeface="Microsoft YaHei"/>
    <a:cs typeface="Arial"/>
  </a:rPr>
  <a:t>English and 中文 and العربية text</a:t>
</a:r>

var rPr = new RunProperties { FontSize = 2400, Language = "en-US" };
rPr.Append(new LatinFont { Typeface = "Calibri" });
rPr.Append(new EastAsianFont { Typeface = "Microsoft YaHei" });
rPr.Append(new ComplexScriptFont { Typeface = "Arial" });

var run = new Run(rPr, new Text("English and 中文 and العربية text"));

Text Run Formatting Patterns

Run Size and Baseline Conversion

Font Substitution Hierarchy

When no explicit font is specified in a:rPr, or on a per-character basis, DrawingML uses this fallback order:

1. Explicit a:latin, a:ea, a:cs fonts in a:rPr
2. Paragraph-level fonts from a:pPr
3. Master slide theme fonts (majorFont/minorFont)
4. Presentation default theme
5. System font substitution (OS-specific fallback)

Fonts are mapped by character script:

• Latin (a:latin) — ASCII, Latin Extended, European scripts
• East Asian (a:ea) — CJK (Chinese, Japanese, Korean), Thai, Lao, Khmer
• Complex Script (a:cs) — Arabic, Hebrew, Devanagari, other RTL/complex scripts

Common Text Run Mistakes

❌ Empty Run

<a:r>
  <a:rPr sz="2400"/>
  <!-- No <a:t> element — missing text content! -->
</a:r>

✅ Correct Run

<a:r>
  <a:rPr sz="2400"/>
  <a:t>Text content</a:t>
</a:r>

❌ Misplaced Text Formatting

<a:p>
  <a:rPr b="1"/>  <!-- Wrong location! Properties belong in a:r, not a:p -->
  <a:r><a:t>Text</a:t></a:r>
</a:p>

✅ Correct Formatting Placement

<a:p>
  <a:pPr lvl="0"/>
  <a:r>
    <a:rPr b="1"/>  <!-- Correct: in a:r, not a:p -->
    <a:t>Text</a:t>
  </a:r>
</a:p>

Notes

Element Relationships

• Parent a:p: Text run is a direct child of paragraph. Multiple runs within a paragraph can have different formatting.
• Child a:rPr (Optional): Run properties are optional (0–1 occurrence). If present, must be the first child. Controls font, size, color, bold, italic, etc.
• Child a:t (Required for display): Text content element. A run with no a:t is valid but displays no text (useful for invisible bookmarks or hyperlink anchors).

General Notes

• Required in Paragraphs: To display text, at least one a:r must exist in a paragraph; empty paragraphs have no runs.
• Uniform Formatting: All text in a single run shares identical character formatting. Whenever formatting changes, create a new run.
• No Direct Text: The a:r element contains no text directly; use a:t child element to hold literal text.
• Null Runs: A run with no a:t child is valid but displays no text (used for bookmarks or hyperlinks with no visible text).
• Hyperlink Interaction: a:hyperlink is a sibling to a:r in a paragraph, not a child; links cannot wrap multiple runs automatically.
• Language Attribute: Always set lang (e.g., lang="en-US") for proper spellcheck, hyphenation, and proofing across documents.
• Font Size Units: Size is in hundredths of points (e.g., 2400 = 24pt, 1400 = 14pt). Fractional points are supported.
• Rendering: Text rendering respects the text anchor direction (a:bodyPr@anchor) and shape width/height; overflow handling depends on auto-fit settings (a:spAutoFit, a:noAutofit, a:normAutofit, a:shrinkTxtToFit).
• Compatibility: Text run structure mirrors WordML w:r and SpreadsheetML a:r, enabling text rendering consistency across Office applications.
• Performance: Many runs with subtle formatting changes can impact rendering performance; consolidate runs where possible.