a:p (Paragraph)

Description

a:p is the fundamental block-level container for text within a DrawingML text body. It is defined in ECMA-376 Part 1 §20.1.2.2.6 and represents a logical paragraph in presentations, charts, shapes, and other DrawingML-enabled documents.

Unlike WordprocessingML where paragraphs are structural units of body text, DrawingML paragraphs are layout containers within constrained spaces (slide shapes, chart labels, SmartArt). Each paragraph is independent and self-contained, with its own formatting, bullet/numbering, alignment, and spacing rules.

A text body (a:txBody) comprises one or more paragraphs. Consumers render each paragraph sequentially, applying text wrapping based on the shape’s dimensions and text anchor properties. Paragraph properties (a:pPr) control high-level formatting: alignment, indentation, spacing, bullet characteristics, and hierarchy level. Individual text runs (a:r) within the paragraph inherit or override run-level properties via a:rPr.

Paragraph Structure

The content model for a:p follows this sequence:

1. Paragraph properties (a:pPr, optional, 0–1) — Must appear first if present. Controls paragraph-wide formatting.
2. Run-level content (repeating) — Any combination of:
   • Text runs (a:r) — Text with run properties
   • Line breaks (a:br) — Soft line break (not end-of-paragraph)
   • Line-end properties (a:endParaRPr, 0–1) — Formatting for the paragraph mark itself

Paragraph Mark and End-of-Paragraph

Every a:p ends with an implicit paragraph mark (not visible, but carries formatting). The a:endParaRPr child element specifies the formatting of that mark. If a:endParaRPr is omitted, the paragraph mark inherits formatting from the last run, or from paragraph properties if no runs exist.

Hierarchy and Nesting

Paragraphs support outline hierarchy via the lvl attribute in a:pPr (level 0 = main, level 1 = first indent, etc.). This enables multi-level bullet lists, outlines, and nested content without explicit nesting of elements.

Attributes

Child Elements

Examples

Minimal Paragraph

<a:p>
  <a:r>
    <a:t>Simple text</a:t>
  </a:r>
</a:p>

var paragraph = new Paragraph(
  new Run(
    new Text("Simple text")));

Paragraph with Properties (centered, Heading level)

<a:p>
  <a:pPr algn="ctr" lvl="0">
    <a:spcBef>
      <a:spcPts val="600"/>
    </a:spcBef>
    <a:spcAft>
      <a:spcPts val="400"/>
    </a:spcAft>
  </a:pPr>
  <a:r>
    <a:rPr sz="4400" b="1" lang="en-US"/>
    <a:t>Slide Title</a:t>
  </a:r>
</a:p>

var paragraph = new Paragraph(
  new ParagraphProperties
  {
    Alignment = TextAlignmentTypeValues.Center,
    Level = 0,
    SpaceBefore = new SpaceBefore { Val = 600 },
    SpaceAfter = new SpaceAfter { Val = 400 }
  },
  new Run(
    new RunProperties { FontSize = 4400, Bold = true, Language = "en-US" },
    new Text("Slide Title")));

Bulleted Paragraph with Multiple Runs

<a:p>
  <a:pPr lvl="0">
    <a:buFont typeface="Wingdings" pitchFamily="2" charset="2"/>
    <a:buChar char="•"/>
  </a:pPr>
  <a:r>
    <a:rPr lang="en-US"/>
    <a:t>First key point: </a:t>
  </a:r>
  <a:r>
    <a:rPr lang="en-US" i="1"/>
    <a:t>emphasized detail</a:t>
  </a:r>
</a:p>

var paragraph = new Paragraph(
  new ParagraphProperties(
    new BulletFont { Typeface = "Wingdings" },
    new BulletChar { Char = "•" }
  ) { Level = 0 },
  new Run(
    new RunProperties { Language = "en-US" },
    new Text("First key point: ")),
  new Run(
    new RunProperties { Language = "en-US", Italic = true },
    new Text("emphasized detail")));

Paragraph with Line Breaks

<a:p>
  <a:pPr lvl="0"/>
  <a:r>
    <a:t>Line 1</a:t>
  </a:r>
  <a:br/>
  <a:r>
    <a:t>Line 2</a:t>
  </a:r>
</a:p>

var paragraph = new Paragraph(
  new ParagraphProperties { Level = 0 },
  new Run(new Text("Line 1")),
  new LineBreak(),
  new Run(new Text("Line 2")));

Paragraph with End-of-Paragraph Formatting

<a:p>
  <a:pPr lvl="0"/>
  <a:r>
    <a:rPr lang="en-US" sz="2400"/>
    <a:t>Main text content</a:t>
  </a:r>
  <a:endParaRPr lang="en-US" sz="2400"/>
</a:p>

var paragraph = new Paragraph(
  new ParagraphProperties { Level = 0 },
  new Run(
    new RunProperties { Language = "en-US", FontSize = 2400 },
    new Text("Main text content")),
  new EndParagraphRunProperties { Language = "en-US", FontSize = 2400 });

Nested Hierarchy (Multi-level outline)

<a:txBody>
  <a:bodyPr/>
  <a:lstStyle/>
  <a:p>
    <a:pPr lvl="0">
      <a:buChar char="•"/>
    </a:pPr>
    <a:r><a:t>Main point</a:t></a:r>
  </a:p>
  <a:p>
    <a:pPr lvl="1">
      <a:buChar char="◦"/>
    </a:pPr>
    <a:r><a:t>Sub-point</a:t></a:r>
  </a:p>
  <a:p>
    <a:pPr lvl="0">
      <a:buChar char="•"/>
    </a:pPr>
    <a:r><a:t>Another main point</a:t></a:r>
  </a:p>
</a:txBody>

var textBody = new TextBody();
textBody.Append(new BodyProperties());
textBody.Append(new ListStyle());

textBody.Append(new Paragraph(
  new ParagraphProperties(new BulletChar { Char = "•" }) { Level = 0 },
  new Run(new Text("Main point"))));

textBody.Append(new Paragraph(
  new ParagraphProperties(new BulletChar { Char = "◦" }) { Level = 1 },
  new Run(new Text("Sub-point"))));

textBody.Append(new Paragraph(
  new ParagraphProperties(new BulletChar { Char = "•" }) { Level = 0 },
  new Run(new Text("Another main point"))));

Paragraph Alignment Values

Paragraph Hierarchy Levels

Spacing Units

DrawingML spacing is measured in:

• EMU (English Metric Units) in attributes like spcBef@val, spcAft@val
• Points via child elements (a:spcPts)
• Percentage via a:spcPct for proportional spacing

Common Formatting Patterns

Empty Paragraph (Blank Line)

<a:p/>

Paragraph with Font Fallback Chain

<a:p>
  <a:endParaRPr lang="en-US" sz="2400">
    <a:latin typeface="Calibri"/>
    <a:ea typeface="Microsoft YaHei"/>
    <a:cs typeface="Arial"/>
  </a:endParaRPr>
</a:p>

Paragraph with Hanging Indent

<a:p>
  <a:pPr marL="500" indent="-300"/>
  <a:r><a:t>Bullet text with hanging indent</a:t></a:r>
</a:p>

Notes

Element Relationships

• Parent a:bodyPr (Indirect): Paragraph sits inside a:txBody, which directly contains a:bodyPr. This relationship controls text anchor, margins, auto-fit behavior, and 3D rotation for the entire text body.
• Child a:pPr (Optional): Paragraph properties are optional (0–1 occurrences). If present, must be the first child. Contains all paragraph-level formatting.
• Child a:r (Required for text): At least one text run should exist to display content. Multiple runs allow mixed formatting within a paragraph.
• Child a:br (Optional): Soft line breaks within paragraphs. Do not create new logical paragraphs.
• Child a:endParaRPr (Optional): Formatting for the paragraph mark itself (typically font properties).

General Notes

• Required Element: At least one a:p must exist in any a:txBody.
• No Attributes: The a:p element itself carries no attributes; use a:pPr for all formatting.
• Run Inheritance: Formatting in a:r overrides a:pPr settings; use a:endParaRPr for paragraph mark formatting.
• Levels: The lvl attribute in a:pPr controls outline hierarchy without nesting elements, enabling bullet/numbering levels.
• Line Breaks: a:br creates soft line breaks within paragraphs; they do not create new logical paragraphs.
• Empty Paragraphs: A paragraph with no a:r children (and no a:br) is valid and renders as a blank line.
• Text Wrapping: Paragraph text wraps within the shape’s bounds; overflow may be truncated or overflowed depending on a:bodyPr/a:spAutoFit.
• Theme Integration: Paragraph and run properties inherit from the master slide’s theme when not explicitly set.
• Compatibility: DrawingML paragraphs render consistently across Word, PowerPoint, Excel, and other Office applications supporting PresentationML/SpreadsheetML.