Word Lists

With lists you can easily create a content that's organized in a hierarchical way.

GemBox.Document supports creating a multi-level lists that are bulleted, pictured, numbered and/or alphabetized and you can format them up to 9 levels (from level 0 to level 8) using ListStyle.ListLevelFormats.

List items are Paragraph elements that have ListStyle applied to them. Typically by incrementing or decrementing the list item's level you increase or decrease its indentation and thus promote or demote that list item in its hierarchy.

The following example demonstrates how you can create simple bulleted and numbered list styles and how to create list items with different levels.

Screenshot of Word file with list styles
Word document with bulleted and numbered lists
using GemBox.Document;

class Program
{
    static void Main()
    {
        // If using Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        var document = new DocumentModel();

        var section = new Section(document);
        document.Sections.Add(section);

        var blocks = section.Blocks;

        // Create bullet list style.
        ListStyle bulletList = new ListStyle(ListTemplateType.Bullet);
        bulletList.ListLevelFormats[0].ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = true;
        bulletList.ListLevelFormats[0].CharacterFormat.FontColor = Color.Red;

        // Create bullet list items.
        blocks.Add(new Paragraph(document, "First item.")
        {
            ListFormat = { Style = bulletList }
        });
        blocks.Add(new Paragraph(document, "Second item.")
        {
            ListFormat = { Style = bulletList }
        });
        blocks.Add(new Paragraph(document, "Third item.")
        {
            ListFormat = { Style = bulletList }
        });

        blocks.Add(new Paragraph(document));

        // Create number list style.
        var numberList = new ListStyle(ListTemplateType.NumberWithDot);

        // Create number list items.
        blocks.Add(new Paragraph(document, "First item.")
        {
            ListFormat = { Style = numberList }
        });
        blocks.Add(new Paragraph(document, "Sub item 1. a.")
        {
            ListFormat = { Style = numberList, ListLevelNumber = 1 }
        });
        blocks.Add(new Paragraph(document, "Item below sub item 1. a.")
        {
            ListFormat = { Style = numberList, ListLevelNumber = 2 }
        });
        blocks.Add(new Paragraph(document, "Sub item 1. b.")
        {
            ListFormat = { Style = numberList, ListLevelNumber = 1 }
        });
        blocks.Add(new Paragraph(document, "Second item.")
        {
            ListFormat = { Style = numberList }
        });

        document.Save("Lists.%OutputFileType%");
    }
}
Imports GemBox.Document

Module Program

    Sub Main()

        ' If using Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim document As New DocumentModel()

        Dim section As New Section(document)
        document.Sections.Add(section)

        Dim blocks = section.Blocks

        ' Create bullet list style.
        Dim bulletList As New ListStyle(ListTemplateType.Bullet)
        bulletList.ListLevelFormats(0).ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = True
        bulletList.ListLevelFormats(0).CharacterFormat.FontColor = Color.Red

        ' Create bullet list items.
        blocks.Add(New Paragraph(document, "First item.") With
        {
            .ListFormat = New ListFormat() With {.Style = bulletList}
        })
        blocks.Add(New Paragraph(document, "Second item.") With
        {
            .ListFormat = New ListFormat() With {.Style = bulletList}
        })
        blocks.Add(New Paragraph(document, "Third item.") With
        {
            .ListFormat = New ListFormat() With {.Style = bulletList}
        })

        blocks.Add(New Paragraph(document))

        ' Create number list style.
        Dim numberList As New ListStyle(ListTemplateType.NumberWithDot)

        ' Create number list items.
        blocks.Add(New Paragraph(document, "First item.") With
        {
            .ListFormat = New ListFormat() With {.Style = numberList}
        })
        blocks.Add(New Paragraph(document, "Sub item 1. a.") With
        {
            .ListFormat = New ListFormat() With {.Style = numberList, .ListLevelNumber = 1}
        })
        blocks.Add(New Paragraph(document, "Item below sub item 1. a.") With
        {
            .ListFormat = New ListFormat() With {.Style = numberList, .ListLevelNumber = 2}
        })
        blocks.Add(New Paragraph(document, "Sub item 1. b.") With
        {
            .ListFormat = New ListFormat() With {.Style = numberList, .ListLevelNumber = 1}
        })
        blocks.Add(New Paragraph(document, "Second item.") With
        {
            .ListFormat = New ListFormat() With {.Style = numberList}
        })

        document.Save("Lists.%OutputFileType%")

    End Sub
End Module

In Word documents you can easily customize the list items appearance, as shown in Define new bullets, numbers, and multilevel lists article. GemBox.Document enables specifying the desired format and indentation for each list level individually, by using ListLevelFormat objects from the ListStyle.

The following example demonstrates how you can create a customized multi-level numbered list.

Screenshot of Word file with customized list
Word document with custom numbered lists
using System.Linq;
using GemBox.Document;

class Program
{
    static void Main()
    {
        // If using Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        int listItemsCount = %NumberOfListItems%;

        var document = new DocumentModel();

        var section = new Section(document);
        document.Sections.Add(section);

        // Create number list style.
        var numberList = new ListStyle(ListTemplateType.NumberWithDot);

        // Customize list level formats.
        for (int level = 0; level < numberList.ListLevelFormats.Count; level++)
        {
            ListLevelFormat levelFormat = numberList.ListLevelFormats[level];

            levelFormat.ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = true;
            levelFormat.Alignment = HorizontalAlignment.Left;
            levelFormat.NumberStyle = NumberStyle.Decimal;

            levelFormat.NumberPosition = 18 * level;
            levelFormat.NumberFormat = string.Concat(Enumerable.Range(1, level + 1).Select(i => $"%{i}."));
        }

        // Create number list items.
        for (int i = 0; i < listItemsCount; i++)
        {
            var paragraph = new Paragraph(document, "Lorem ipsum");

            paragraph.ListFormat.Style = numberList;
            paragraph.ListFormat.ListLevelNumber = i % 9;

            section.Blocks.Add(paragraph);
        }

        document.Save("CustomizedList.%OutputFileType%");
    }
}
Imports System.Linq
Imports GemBox.Document

Module Program

    Sub Main()

        ' If using Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim listItemsCount As Integer = %NumberOfListItems%
        
        Dim document As New DocumentModel()

        Dim section As New Section(document)
        document.Sections.Add(section)

        ' Create number list style.
        Dim numberList As New ListStyle(ListTemplateType.NumberWithDot)

        ' Customize list level formats.
        For level = 0 To numberList.ListLevelFormats.Count - 1

            Dim levelFormat As ListLevelFormat = numberList.ListLevelFormats(level)

            levelFormat.ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = True
            levelFormat.Alignment = HorizontalAlignment.Left
            levelFormat.NumberStyle = NumberStyle.Decimal

            levelFormat.NumberPosition = 18 * level
            levelFormat.NumberFormat = String.Concat(Enumerable.Range(1, level + 1).Select(Function(i) $"%{i}."))

        Next

        ' Create number list items.
        For i = 0 To listItemsCount - 1

            Dim paragraph As New Paragraph(document, "Lorem ipsum")

            paragraph.ListFormat.Style = numberList
            paragraph.ListFormat.ListLevelNumber = i Mod 9

            section.Blocks.Add(paragraph)

        Next

        document.Save("CustomizedList.%OutputFileType%")

    End Sub
End Module

Often you'll want to combine your list with some ParagraphStyle, for instance when creating numbered headings.

To do this, you can use ListLevelFormat.AssociatedParagraphStyle property and assign your list's first level to "Heading 1" style, second level to "Heading 2" style, etc. By using such styling you can assign just the Paragraph.ParagraphFormat.Style on the required Paragraph element, without having to set the Paragraph.ListFormat.Style as well.

In Word files, list items are automatically numbered, the Paragraph elements don't contain the information about their number, they only contain a reference to the ListStyle which they're using.

GemBox.Document calculates the list numbers when exporting the document to format like PDF or XPS. Also, GemBox.Document provides a CalculateListItems method after which you can find out any list item's level numbers through Paragraph.ListItem.Numbers or retrieve the list item's numerical representation through Paragraph.ListItem.Inlines.

Check next example or download examples from GitHub.