w:numPr (Numbering Properties)
Specifies that the paragraph belongs to a list, referencing a numbering definition and level.
Description
w:numPr is the numbering properties container within w:pPr, linking a paragraph to a list definition and specifying its list level. It is defined in ECMA-376 Part 1 §17.3.1.19.
It contains two child elements: w:ilvl (the zero-based level index) and w:numId (the ID of the w:num instance). Setting w:numId to 0 removes any list formatting from the paragraph.
Attributes
| Attribute | Type | Possible Values | Description |
|---|---|---|---|
| (none) | — | — | Properties are expressed via w:ilvl and w:numId child elements. |
Child Elements
| Child | Attributes | Purpose |
|---|---|---|
w:ilvl |
w:val (0-8 for outline levels) |
Zero-based list level index (0 = top level, 1 = nested, etc.). |
w:numId |
w:val (positive integer or 0) |
ID of the w:num instance from numbering.xml; 0 = remove list formatting. |
Examples
Top-Level List Item (Level 0)
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/> <!-- Top level -->
<w:numId w:val="1"/> <!-- List instance 1 -->
</w:numPr>
</w:pPr>
<w:r><w:t>First item</w:t></w:r>new ParagraphProperties(
new NumberingProperties(
new NumberingLevelReference { Val = 0 },
new NumberingId { Val = 1 })),
new Run(new Text("First item"));Nested List Item (Level 1)
<w:pPr>
<w:numPr>
<w:ilvl w:val="1"/> <!-- Nested level -->
<w:numId w:val="1"/> <!-- Same list instance -->
</w:numPr>
</w:pPr>
<w:r><w:t>Nested item</w:t></w:r>new ParagraphProperties(
new NumberingProperties(
new NumberingLevelReference { Val = 1 }, // Level 1 (nested)
new NumberingId { Val = 1 })), // Same list
new Run(new Text("Nested item"));Remove List Formatting (numId = 0)
<!-- Return to normal paragraph (not a list item) -->
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/>
<w:numId w:val="0"/> <!-- 0 = no list formatting -->
</w:numPr>
</w:pPr>
<w:r><w:t>Regular paragraph after list</w:t></w:r>new ParagraphProperties(
new NumberingProperties(
new NumberingLevelReference { Val = 0 },
new NumberingId { Val = 0 })), // 0 removes list
new Run(new Text("Regular paragraph after list"));Numbering Hierarchy
| Level | Indent | Typical Format | Use |
|---|---|---|---|
| 0 | 0” | 1, 2, 3… | Top-level items |
| 1 | 0.5” | a, b, c… | First nested level |
| 2 | 1” | i, ii, iii… | Second nested level |
| 3 | 1.5” | A, B, C… | Third nested level |
| 4+ | 2”+ | Various | Deep nesting (uncommon) |
Numbering Context
Single List: All paragraphs with w:numId="1" belong to the same logical list, regardless of levels:
1. First item (ilvl=0)
a. Nested 1a (ilvl=1)
b. Nested 1b (ilvl=1)
2. Second item (ilvl=0)
a. Nested 2a (ilvl=1)
Multiple Lists: Different w:numId values create separate list instances:
1. First list item
2. Second first list item
A. Second list item (different numId)
B. Second second list item