w:tab (Tab Character)

Inserts a tab character at the current position within a run, advancing to the next tab stop.

Parent elements

Description

w:tab inserts a tab character at the current position in the run. It is defined in ECMA-376 Part 1 §17.3.3.32.

The tab stop it aligns to is determined by the w:tabs paragraph property of the containing paragraph, or by the document’s default tab stop (w:defaultTabStop in w:settings). w:tab is an empty element with no attributes.

Attributes

Attribute	Type	Possible Values	Description
(none)	—	—	`w:tab` is an empty element; the tab stop is resolved from the paragraph’s `w:tabs` list or the document default.

Examples

<w:r>
  <w:tab/>
</w:r>
<w:r>
  <w:t>Content after tab</w:t>
</w:r>

new Run(new TabChar()),
new Run(new Text("Content after tab"));

<!-- Multiple tabs in a row -->
<w:r>
  <w:t>Column1</w:t>
</w:r>
<w:r>
  <w:tab/>
</w:r>
<w:r>
  <w:t>Column2</w:t>
</w:r>
<w:r>
  <w:tab/>
</w:r>
<w:r>
  <w:t>Column3</w:t>
</w:r>

<!-- Tab with decimal alignment (for numbers) -->
<w:p>
  <w:pPr>
    <w:tabs>
      <w:tab w:val="decimal" w:pos="2880" w:leader="dot"/>  <!-- 2 inches, decimal-aligned -->
    </w:tabs>
  </w:pPr>
  <w:r><w:t>Price</w:t></w:r>
  <w:r><w:tab/></w:r>
  <w:r><w:t>$19.99</w:t></w:r>
</w:p>

// Multiple tabs
new Run(new Text("Column1")),
new Run(new TabChar()),
new Run(new Text("Column2")),
new Run(new TabChar()),
new Run(new Text("Column3")),

// Tab with paragraph properties
new Paragraph(
  new ParagraphProperties(
    new Tabs(
      new TabStop { Val = TabStopValues.Decimal, Pos = 2880, Leader = TabStopLeaderCharValues.Dot })),
  new Run(new Text("Price")),
  new Run(new TabChar()),
  new Run(new Text("$19.99")));

<!-- Tab with formatting (color) -->
<w:p>
  <w:pPr>
    <w:tabs>
      <w:tab w:val="left" w:pos="1440"/>  <!-- 1 inch -->
    </w:tabs>
  </w:pPr>
  <w:r>
    <w:t>Before Tab</w:t>
  </w:r>
  <w:r>
    <w:rPr><w:color w:val="FF0000"/></w:rPr>
    <w:tab/>  <!-- Tab inherits red color -->
  </w:r>
  <w:r>
    <w:t>After Tab</w:t>
  </w:r>
</w:p>

new Paragraph(
  new ParagraphProperties(
    new Tabs(new TabStop { Val = TabStopValues.Left, Pos = 1440 })),
  new Run(new Text("Before Tab")),
  new Run(
    new RunProperties(new Color { Val = "FF0000" }),
    new TabChar()),  // Tab inherits red color
  new Run(new Text("After Tab")));

Tab Stop Configuration

Type	Purpose	Behavior
`left` (default)	Left-aligned tab	Text after tab aligns to left edge of stop position
`center`	Center-aligned tab	Text centers at the stop position
`right`	Right-aligned tab	Text aligns to right edge of stop position
`decimal`	Decimal-aligned tab	Decimal point (.) aligns at stop position; useful for numbers
`bar`	Vertical bar	Inserts a vertical bar at the stop position (not typically used)

Tab Stop Positioning

Unit	Value	Equivalent	Typical Use
Twips (dxa)	1440	1 inch	Precise positioning
0.5 inch	720	0.5”	Common column spacing
1 inch	1440	1”	Standard margins
2 inches	2880	2”	Wide column

Tab Leaders (Dot/Dash Fill)

Value	Display	Use Case
`none` (default)	Empty space	Standard alignment
`dot`	…	Table of contents, dot leaders
`hyphen`	—	List separators
`underscore`	___	Form fields, underlines
`heavy`	▔▔▔	Thick visual separator

Notes

Tab resolution: The tab stop the cursor aligns to is determined by the nearest w:tab entry in the containing paragraph’s w:tabs property, or by the document default (w:defaultTabStop in settings.xml).
Empty element: w:tab has no child elements or attributes; it is an empty element placeholder.
Inheritance: The tab character inherits text properties (color, font, bold) from the containing run’s w:rPr.
Formatting alternative: Use w:tab instead of literal tab characters (U+0009) in w:t for proper XML and semantic intent.
Multiple tabs: Multiple consecutive w:tab elements align to successive tab stops in the paragraph’s w:tabs list.
Default tab spacing: If no w:tabs are defined, Word uses default tab stops (typically 0.5 inches); this can be overridden via w:defaultTabStop.
Table alignment: While w:tab can be used for manual column alignment, use w:tbl (tables) for proper data alignment and nesting.
Column alignment: Decimal-aligned tabs are particularly useful for numeric data; align numbers by their decimal points.
Accessibility: Tab characters should reflect logical document structure; avoid using tabs for visual layout instead of semantic markup.
Performance: Overuse of tabs in large documents has minimal impact; tables are preferable for complex multi-column layouts.
RTL text: Tab stops are oriented according to paragraph direction (LTR vs RTL); position values remain absolute regardless of direction.