How to Work with Lists in .NET

Step 1: Apply a List to a Paragraph

Use ListFormat.ApplyBulletDefault() or ApplyNumberDefault() on a paragraph’s formatting to apply Word’s default bullet or numbered list in one call — this is the quickest way to apply a standard list. For a specific predefined format instead of the default, call Document.Lists (a ListCollection) .Add(listTemplate) with a ListTemplate value such as BulletDisk, BulletSquare, NumberArabicDot, or NumberUppercaseRomanDot to create a List from one of Word’s built-in formats, or AddSingleLevelList(listTemplate) for a single-level variant. Once a paragraph has list formatting, ListFormat.IsListItem reports true, and ListFormat.List/ListLevelNumber identify which list and level it uses.

Step 2: Give a New Group of Paragraphs Independent Numbering

Paragraphs whose ListFormat.List points at the same shared List object continue the same counter. When a new group of paragraphs needs numbering that restarts from 1 independently, call ListCollection.AddCopy(srcList) to duplicate an existing list definition, then apply the copy to the new paragraphs instead of reusing the original. ListCollection.GetListByListId(listId) retrieves a specific list by its ListId when you need to look one up rather than create one, and Count reports how many lists the document currently has.

Step 3: Move a Paragraph Between List Levels

Use ListFormat.ListIndent() to move a paragraph one level deeper into its list, and ListOutdent() to move it one level shallower — the same operations Word performs for Tab and Shift+Tab at the start of a list paragraph. Prefer these methods over setting ListLevelNumber directly, since they keep the paragraph’s list formatting internally consistent. Call RemoveNumbers() to strip list formatting from a paragraph entirely.

Step 4: Customize a List Level’s Numbering Format

Reach a specific level through List.ListLevels (a ListLevelCollection), then set ListLevel.NumberStyle (a NumberStyle value such as Arabic, UppercaseRoman, LowercaseLetter, or Bullet) and NumberFormat — the format string combining the number with literal text such as a period or parenthesis — together, since a mismatched pair produces unexpected rendering. StartAt sets the level’s starting number, and RestartAfterLevel controls which higher level’s increment restarts this level’s counter — set it explicitly on nested lists rather than relying on default restart behavior. Alignment (Left, Center, Right) and TrailingCharacter (Tab, Space, Nothing) control label position and the separator between the label and the paragraph text, alongside TabPosition, NumberPosition, and TextPosition for precise layout. IsLegal forces legal-style numbering (always Arabic) regardless of NumberStyle.

Step 5: Add a Picture Bullet to a List Level

Call ListLevel.CreatePictureBullet() on the target level to create a picture-bullet definition, then supply the bullet’s ImageData before removing any existing text-bullet formatting on the same level. Call DeletePictureBullet() to remove a picture bullet and revert to text-based bullet formatting.

Step 6: Inspect a List Item’s Rendered Label

ListLabel describes the label actually rendered for one list item instance, reached from the item’s paragraph formatting. LabelString is the literal text Word displays — such as “3.” or “•” — LabelValue is the underlying numeric value, and Font is the label’s own formatting, independent of the paragraph text’s formatting. For computing a label’s value at an arbitrary position in the sequence without rendering the whole list, call ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat).