Bullets and Numbering

Bullets and Numbering requires an understanding of Sections and Paragraphs.

docx is quite flexible in its bullets and numbering system, allowing the user great freedom in how bullets and numbers are to be styled and displayed. E.g., numbers can be shown using Arabic numerals, roman numerals, or even ordinal words ("one", "two", "three", ...). The format also supports re-using bullets/numbering styles throughout the document, so that different lists using the same style need not redefine them.

Configuration

Numbering is configured by adding config into Document:

new Document({
    numbering: {
        config: [...]
    }
})

Each config entry includes the following properties:

. Each level includes the following properties:

Property	Type	Notes	Possible Values
reference	`string`	Required	A unique `string`
levels	`ILevelOptions[]`	Required	a series of levels which form a sequence starting at 0 indicating the top-level list look and increasing from there to describe the sublists, then sub-sublists, etc

Level Options

Levels define the numbering definition itself, what it looks like, the indention, the alignment and the style. The reason why it is an array is because it allows the ability to create sub-lists. A sub list will have a different configuration because you may want the sub-list to have a different indentation or different bullet.

Property	Type	Notes	Possible Values
level	`number`	Required	The list level this definition is for. `0` is for the root level, `1` is for a sub list, `2` is for a sub-sub-list etc.
format	`LevelFormat`	Optional	`DECIMAL`, `UPPER_ROMAN`, `LOWER_ROMAN`, `UPPER_LETTER`, `LOWER_LETTER`, `ORDINAL`, `CARDINAL_TEXT`, `ORDINAL_TEXT`, `HEX`, `CHICAGO`, `IDEOGRAPH__DIGITAL`, `JAPANESE_COUNTING`, `AIUEO`, `IROHA`, `DECIMAL_FULL_WIDTH`, `DECIMAL_HALF_WIDTH`, `JAPANESE_LEGAL`, `JAPANESE_DIGITAL_TEN_THOUSAND`, `DECIMAL_ENCLOSED_CIRCLE`, `DECIMAL_FULL_WIDTH2`, `AIUEO_FULL_WIDTH`, `IROHA_FULL_WIDTH`, `DECIMAL_ZERO`, `BULLET`, `GANADA`, `CHOSUNG`, `DECIMAL_ENCLOSED_FULLSTOP`, `DECIMAL_ENCLOSED_PARENTHESES`, `DECIMAL_ENCLOSED_CIRCLE_CHINESE`, `IDEOGRAPH_ENCLOSED_CIRCLE`, `IDEOGRAPH_TRADITIONAL`, `IDEOGRAPH_ZODIAC`, `IDEOGRAPH_ZODIAC_TRADITIONAL`, `TAIWANESE_COUNTING`, `IDEOGRAPH_LEGAL_TRADITIONAL`, `TAIWANESE_COUNTING_THOUSAND`, `TAIWANESE_DIGITAL`, `CHINESE_COUNTING`, `CHINESE_LEGAL_SIMPLIFIED`, `CHINESE_COUNTING_THOUSAND`, `KOREAN_DIGITAL`, `KOREAN_COUNTING`, `KOREAN_LEGAL`, `KOREAN_DIGITAL2`, `VIETNAMESE_COUNTING`, `RUSSIAN_LOWER`, `RUSSIAN_UPPER`, `NONE`, `NUMBER_IN_DASH`, `HEBREW1`, `HEBREW2`, `ARABIC_ALPHA`, `ARABIC_ABJAD`, `HINDI_VOWELS`, `HINDI_CONSONANTS`, `HINDI_NUMBERS`, `HINDI_COUNTING`, `THAI_LETTERS`, `THAI_NUMBERS`, `THAI_COUNTING`, `BAHT_TEXT`, `DOLLAR_TEXT`, `CUSTOM`
text	`string`	Optional	A unique `string` to describe the shape of the bullet
alignment	`string`	Required	`START`, `CENTER`, `END`, `BOTH`, `MEDIUM_KASHIDA`, `DISTRIBUTE`, `NUM_TAB`, `HIGH_KASHIDA`, `LOW_KASHIDA`, `THAI_DISTRIBUTE`, `LEFT`, `RIGHT`, `JUSTIFIED`
style	`string`	Optional	Sections

Using ordered lists in `docx`

Add a numbering section to the Document to numbering style, define your levels. Use LevelFormat.UPPER_ROMAN for the format in levels:

const doc = new Document({
    ...
    numbering: {
        config: [
            {
                reference: "my-numbering",
                levels: [
                    {
                        level: 0,
                        format: LevelFormat.UPPER_ROMAN,
                        text: "%1",
                        alignment: AlignmentType.START,
                        style: {
                            paragraph: {
                                indent: { left: 2880, hanging: 2420 },
                            },
                        },
                    },
                    ...
                ],
            },
        ],
    },
    ...
});

And then on a Paragraph, we can add use the numbering created:

new Paragraph({
    text: "Hey you!",
    numbering: {
        reference: "my-numbering",
        level: 0,
    },
}),

Numbering options

Along with reference and level, the numbering object supports an optional instance property:

Property	Type	Notes
reference	`string`	The numbering style reference, must match a defined config
level	`number`	The list level (0 = top-level, 1 = sub-list, etc.)
instance	`number`	(Optional) Identifies the instance of the list. Lists with the same `instance` (or none) continue numbering across paragraphs. A new `instance` value restarts numbering from `1`.

Example:

new Paragraph({
    text: "First list item",
    numbering: { reference: "my-numbering", level: 0, instance: 1 },
});

new Paragraph({
    text: "Second list item",
    numbering: { reference: "my-numbering", level: 0, instance: 1 },
});

new Paragraph({
    text: "New list, starts again at 1",
    numbering: { reference: "my-numbering", level: 0, instance: 2 },
});

Un-ordered lists / Bullet points

Add a numbering section to the Document to numbering style, define your levels. Use LevelFormat.BULLET for the format in levels:

const doc = new Document({
    ...
    numbering: {
        config: [
            {
                reference: "my-bullet-points",
                levels: [
                    {
                        level: 0,
                        format: LevelFormat.BULLET,
                        text: "\u1F60",
                        alignment: AlignmentType.LEFT,
                        style: {
                            paragraph: {
                                indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.25) },
                            },
                        },
                    },
                ],
            },
        ],
    },
    ...
});

And then on a Paragraph, we can add use the numbering created:

new Paragraph({
    text: "Hey you!",
    numbering: {
        reference: "my-bullet-points",
        level: 0,
    },
}),

Disabling numbering inherited from paragraph style

If the numbering is set on a paragraph style, you may wish to disable it for a specific paragraph:

const doc = new Document({
    ...
    numbering: {
        config: [
            {
                reference: "my-bullet-points",
                levels: [
                    {
                        level: 0,
                        format: LevelFormat.BULLET,
                        text: "\u1F60",
                        alignment: AlignmentType.LEFT,
                        style: {
                            paragraph: {
                                indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.25) },
                            },
                        },
                    },
                ],
            },
        ],
    },
    styles: {
        paragraphStyles: [
            {
                id: 'bullet',
                name: 'Bullet',
                basedOn: 'Normal',
                next: 'Normal',
                run: {},
                paragraph: {
                    numbering: {
                        reference: 'my-bullet-points',
                        level: 0,
                    },
                },
            },
        ],
    },
    ...
});

new Paragraph({
    text: "No bullet points!",
    style: "Bullet",
    numbering: false,
}),

Full Example

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/3-numbering-and-bullet-points.ts