w:tabs (Tab Stops)

Description

w:tabs is a container for one or more tab stop definitions that control where tab characters (\t or U+0009) position the insertion point within a paragraph. It is defined in ECMA-376 Part 1 §17.3.1.34.

Each child w:tab element specifies a tab position (in twips from the left margin), an optional leader character (like dots or dashes), and an alignment type (left, right, center, decimal). Tabs are commonly used in tables of contents, forms, lists, and columnar layouts.

When the document is edited, pressing the Tab key will move to the next defined tab stop position or to the default tab interval (typically 0.5 inches) if no custom stops are defined.

Attributes

Child Elements

Tab Element Attributes

Examples

Simple left-aligned tab at 1.5 inches

<w:pPr>
  <w:tabs>
    <w:tab w:val="left" w:pos="2160"/>
  </w:tabs>
</w:pPr>
<w:r><w:t>Name</w:t></w:r>
<w:r><w:tab/></w:r>
<w:r><w:t>John Doe</w:t></w:r>

var pPr = new ParagraphProperties(
  new Tabs(
    new TabStop { Val = TabStopValues.Left, Pos = 2160 }));
var para = new Paragraph(pPr,
  new Run(new Text("Name")),
  new Run(new TabChar()),  // Tab character
  new Run(new Text("John Doe")));

Multiple tabs with leaders (like table of contents)

<w:pPr>
  <w:tabs>
    <w:tab w:val="left" w:pos="1440"/>
    <w:tab w:val="right" w:pos="5040" w:leader="dot"/>
  </w:tabs>
</w:pPr>
<w:r><w:t>Chapter 1</w:t></w:r>
<w:r><w:tab/></w:r>
<w:r><w:tab/></w:r>
<w:r><w:t>1</w:t></w:r>
<!-- Result: "Chapter 1" left-aligned, then dots, then page number right-aligned -->

var pPr = new ParagraphProperties(
  new Tabs(
    new TabStop { Val = TabStopValues.Left, Pos = 1440 },
    new TabStop { Val = TabStopValues.Right, Pos = 5040, Leader = TabStopLeaderCharValues.Dot }));
var para = new Paragraph(pPr,
  new Run(new Text("Chapter 1")),
  new Run(new TabChar()),
  new Run(new TabChar()),
  new Run(new Text("1")));

Decimal-aligned tab (for numbers)

<w:pPr>
  <w:tabs>
    <w:tab w:val="decimal" w:pos="2160"/>
  </w:tabs>
</w:pPr>
<w:r><w:t>Price</w:t></w:r>
<w:r><w:tab/></w:r>
<w:r><w:t>$99.99</w:t></w:r>
<!-- Decimal point aligns at tab stop position 2160 -->

var pPr = new ParagraphProperties(
  new Tabs(
    new TabStop { Val = TabStopValues.Decimal, Pos = 2160 }));
var para = new Paragraph(pPr,
  new Run(new Text("Price")),
  new Run(new TabChar()),
  new Run(new Text("$99.99")));

Tab Leaders Reference

Tab Alignment Reference

Common Tab Stop Positions (Twips)

Advanced Tab Stop Scenario

Form with multiple columns:

<w:pPr>
  <w:tabs>
    <w:tab w:val="left" w:pos="1440"/>         <!-- Column 1 at 1" -->
    <w:tab w:val="left" w:pos="3600"/>         <!-- Column 2 at 2.5" -->
    <w:tab w:val="right" w:pos="7200"/>        <!-- Column 3 right-aligned at 5" -->
  </w:tabs>
</w:pPr>
<w:r><w:t>Field 1</w:t></w:r>
<w:r><w:tab/></w:r>
<w:r><w:t>Field 2</w:t></w:r>
<w:r><w:tab/></w:r>
<w:r><w:t>Field 3</w:t></w:r>

<w:r><w:t>USD 1234.56</w:t></w:r>
<w:r><w:tab/></w:r>
<w:r><w:t>1234.56</w:t></w:r>
<!-- Decimal points align at 2160 twips -->

var pPr = new ParagraphProperties(
  new Tabs(
    new TabStop { Val = TabStopValues.Decimal, Pos = 2160 }));
var para = new Paragraph(pPr,
  new Run(new Text("USD 1234.56")),
  new Run(new TabChar()),
  new Run(new Text("1234.56")));

Tab Stop Alignment Values

Tab Position Conversion Reference

Leader Character Options

Notes

• Default intervals: When no custom tabs are defined, Word uses default stops, typically every 0.5 inches.
• Tab character: Represent tabs in XML with <w:tab/> run elements, not literal tab characters or whitespace; the character corresponds to U+0009.
• Position units: All w:pos values are in twips (1/20 point); 1440 twips = 1 inch and 1 twip is approximately 0.05 mm.
• Position origin: Positions are measured from the left margin, including paragraph indentation; indentation does not shift tab positions.
• Multiple stops and performance: Up to 63 stops can be defined per paragraph, but 10-15 is a practical maximum; excessive stops may affect rendering.
• Inheritance: Tab stops are defined at paragraph level and apply to its runs.
• Leader characters: w:leader controls repeated filler characters between text and the tab position; none means no filler.
• Alignment and locale: Decimal alignment uses the first period or comma in the text; format numbers for the target locale. RTL text reverses positioning conceptually while the XML remains unchanged.
• Rendered width: Actual tab width depends on font and content; use alignment values to keep columns consistent.
• Accessibility: Tabs should represent logical columns; complex tab layouts can confuse screen readers, so use semantic markup or lists when appropriate.
• Forms: Tab stops work for simple forms; use tables for complex layouts.
• Compatibility: Tab stops render consistently across Office versions and systems.