Working with Lists

Working with Lists

This guide shows how numbered and bulleted lists are represented and controlled in Aspose.Words FOSS for .NET. A List is a reusable list definition shared by every paragraph that uses it, ListFormat is how an individual paragraph refers to a list and its current level, and ListLevel holds the actual numbering or bullet formatting for one level of a list.

The List Object and ListCollection

List represents one list definition — the numbering rules a document can apply to many paragraphs. List.ListId identifies it, List.IsMultiLevel reports whether it defines more than one level, and List.ListLevels returns a ListLevelCollection holding one ListLevel per level the list defines. List.IsListStyleDefinition and IsListStyleReference distinguish a list that defines its own formatting from one that references formatting via a linked Style (available through List.Style). Every document’s lists are reached through Document.Lists, which returns a ListCollection: ListCollection.Add(listTemplate) creates a new list from one of Word’s predefined ListTemplate formats, Add(listStyle) creates one from a Style, AddSingleLevelList(listTemplate) creates a single-level variant, and AddCopy(srcList) duplicates an existing list — useful when you want paragraphs to have independent numbering (a fresh restart) rather than sharing the same counter. ListCollection.GetListByListId(listId) retrieves a specific list, and Count reports how many lists the document has.

Applying Lists to Paragraphs with ListFormat

ListFormat, reached from a paragraph’s formatting, controls what list a paragraph belongs to and at what level. ListFormat.List is the List the paragraph uses, and ListFormat.ListLevelNumber is the zero-based level within that list; IsListItem reports whether the paragraph is part of a list at all. ApplyBulletDefault() and ApplyNumberDefault() apply Word’s default bullet or numbered list formatting to a paragraph in one call, RemoveNumbers() removes list formatting, and ListIndent()/ListOutdent() move a paragraph deeper into or shallower out of the list’s levels — the same operations Word performs when pressing Tab or Shift+Tab at the start of a list paragraph.

List Levels and Numbering Style

ListLevel holds the formatting for one level of a list: NumberStyle (a NumberStyle enum value such as Arabic numerals or Roman numerals), NumberFormat (the format string combining the number with literal text, such as a period or parenthesis), StartAt (the starting number), and RestartAfterLevel (which higher level’s increment restarts this level’s counter). Alignment (a ListLevelAlignment value: Left, Center, Right) and TrailingCharacter (a ListTrailingCharacter value: Tab, Space, Nothing) control how the label is positioned and separated from the paragraph text, alongside TabPosition, NumberPosition, and TextPosition for precise layout. IsLegal forces legal-style numbering (always Arabic, regardless of NumberStyle), and LinkedStyle associates the level with a paragraph Style. For picture bullets, CreatePictureBullet() and DeletePictureBullet() manage an ImageData bullet image, and ListLevel.Font sets the formatting of the number or bullet character itself. ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) computes the actual label value at a given position in the numbering sequence.

List Labels and Predefined Templates

ListLabel describes the rendered label for a specific list item instance — LabelString is the literal text Word displays (such as “3.” or “•”), LabelValue is the underlying numeric value, and Font is the label’s formatting. ListTemplate is an enum of Word’s predefined list formats (bullet styles such as BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds, and numbered formats), used with ListCollection.Add(listTemplate) to start from a built-in format rather than building one property by property.

Tips and Best Practices

• Use ListCollection.AddCopy(srcList) when a new group of paragraphs needs list numbering that starts over independently, rather than reusing a List that’s already attached to other paragraphs.
• Prefer ListFormat.ApplyNumberDefault() / ApplyBulletDefault() for standard lists instead of manually configuring every ListLevel property.
• Check List.IsListStyleReference vs IsListStyleDefinition before modifying list formatting directly — a style-referencing list’s formatting may be controlled by its linked Style instead.
• Set RestartAfterLevel explicitly on nested lists rather than relying on default restart behavior when numbering must reset at specific outline levels.
• Use ListFormat.ListIndent()/ListOutdent() to move a paragraph between list levels instead of setting ListLevelNumber directly, since these methods keep the paragraph’s list formatting internally consistent.

Common Issues

FAQ

What’s the difference between List and ListFormat?

List is the reusable numbering/bullet definition shared across paragraphs; ListFormat is per-paragraph — it points at which List a specific paragraph uses and at which level, via ListFormat.List and ListLevelNumber.

How do I check whether a paragraph is part of a list?

Read ListFormat.IsListItem on the paragraph’s formatting; if true, ListFormat.List and ListLevelNumber describe which list and level it belongs to.

How do I make a new list start numbering from 1 independently of an existing list?

Use ListCollection.AddCopy(srcList) to create an independent copy of the list definition, then apply the copy to the new paragraphs — rather than reusing the original List, which would continue the same counter.

How do I create a bulleted or numbered list from scratch?

Use ListFormat.ApplyBulletDefault() or ApplyNumberDefault() for Word’s default formatting, or ListCollection.Add(listTemplate) with a ListTemplate value to start from one of Word’s predefined formats and customize the resulting List.ListLevels from there.

How do I control the number format, such as “1)” instead of “1.”?

Set ListLevel.NumberFormat on the relevant level to the desired format string, alongside NumberStyle for the numeral style itself.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation