Word Lists

With lists you can easily create content that's organized hierarchically.

GemBox.Document supports creating 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 shows how you can create simple bulleted and numbered list styles and how to create list items with different levels.

Word document with bulleted and numbered lists
Screenshot of Word file with list styles
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 the Define new bullets, numbers, and multilevel lists article. GemBox.Document enables you to specify the desired format and indentation for each list level individually, by using ListLevelFormat objects from the ListStyle.

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

Word document with custom numbered lists
Screenshot of Word file with customized list
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 the ListLevelFormat.AssociatedParagraphStyle property and assign your list's first level to the Heading 1 style, second level to the Heading 2 style, and so on. By using such styling you can assign just the Paragraph.ParagraphFormat.Style to the required Paragraph element, without having to set the Paragraph.ListFormat.Style as well.

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

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

Want more?

Next example GitHub

Check the next example or select an example from the menu. You can also download our examples from the GitHub.


Like it?

Download Buy

If you want to try the GemBox.Document yourself, you can download the free version. It delivers the same performance and set of features as the professional version, but with some operations limited. To remove the limitation, you need to purchase a license.