# Lists

DsWord provides 21 built-in templates to create lists in a Word document. Learn how to work with lists to format and arrange text in an organized way.

## Content

Lists can be used to format and arrange text in an organized way. The appearance of lists can be customized by defining numbered, bulleted, and multilevel lists.
DsWord provides 21 built-in list templates to create lists in a document using the [ListTemplate](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.ListTemplate.html) class. This class represents a list template that defines the format of list including the type of bullet or numbering style applied to the list. The [Add](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.ListTemplateCollection.Add.html) method of the [ListTemplateCollection](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.ListTemplateCollection.html) class allows you to define and add list template to the collection of list templates in a document. The list templates are applied to a sequence of paragraphs to convert them to a list, where each paragraph serves as the list item. DsWord allows you to apply list formatting to the paragraphs using properties of the [ListFormat](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.ListFormat.html) class. It also provides [ListLevel](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.ListLevel.html) class which represents single list level for bulleted or numbered list. In addition, you can use [BuiltInListTemplateId](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.BuiltInListTemplateId.html) enumeration to use predefined list templates and [NumberStyle](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.NumberStyle.html) enumeration to specify the number style for a list.
![Nested list in a Word document](https://cdn.mescius.io/document-site-files/images/d623c730-bceb-4e85-a6b2-a3dbe84720b2/images/list.png)

## Create List

To create list in a Word document:

1. Add a paragraph using the Add method.
2. Access the list templates collection using [ListTemplates](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.DocumentBase.ListTemplates.html) property of the **DocumentBase** class.
3. Add a sequence of paragraphs which will serve as the list items using **Add** method of the **ListTemplateCollection** class.
4. Add paragraph part of the list using **Add** method of the paragraph collection for each item in the list.
5. Apply list template to all the paragraphs by using [ListFormat](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.Paragraph.ListFormat.html) property of the **Paragraph** class.

    ```csharp
    //Define a ListTemplate for level 1 list items:
    ListTemplate myListTemplate = doc.ListTemplates.Add(
            BuiltInListTemplateId.BulletDefault, "myListTemplate");
    
    //Define list templates for level 2 list items
    ListTemplate mySubList1Template = doc.ListTemplates.Add(
            BuiltInListTemplateId.NumberUppercaseRomanDot, "mySubList1Template");
    ListTemplate mySubList2Template = doc.ListTemplates.Add(
            BuiltInListTemplateId.NumberUppercaseRomanDot, "mySubList2Template");
    ListTemplate mySubList3Template = doc.ListTemplates.Add(
            BuiltInListTemplateId.NumberUppercaseRomanDot, "mySubList3Template");
    
    ParagraphCollection pars = doc.Body.Sections.First.GetRange().Paragraphs;
    pars.Add("The list of bullets:");
    
    //Add list items using Paragraph and set their list template and level number:
    Paragraph p1 = pars.Add("Bullet item 1");
    p1.ListFormat.Template = myListTemplate;
    p1.ListFormat.LevelNumber = 1;
    Paragraph p1s1 = pars.Add("Numbered item 1: Nested item 1");
    p1s1.ListFormat.Template = mySubList1Template;
    p1s1.ListFormat.LevelNumber = 2;
    
    Paragraph p2 = pars.Add("Bullet item 2");
    p2.ListFormat.Template = myListTemplate;
    p2.ListFormat.LevelNumber = 1;
    Paragraph p2s1 = pars.Add("Numbered item 2: Nested item 1");
    p2s1.ListFormat.Template = mySubList2Template;
    p2s1.ListFormat.LevelNumber = 2;
    Paragraph p2s2 = pars.Add("Numbered item 2: Nested item 2");
    p2s2.ListFormat.Template = mySubList2Template;
    p2s2.ListFormat.LevelNumber = 2;
    
    Paragraph p3 = pars.Add("Bullet item 3");
    p3.ListFormat.Template = myListTemplate;
    p3.ListFormat.LevelNumber = 1;
    Paragraph p3s1 = pars.Add("Numbered item 3: Nested item 1");
    p3s1.ListFormat.Template = mySubList3Template;
    p3s1.ListFormat.LevelNumber = 2;
    
    //Save the document
    doc.Save("CreateList.docx");
    ```

## Modify List

To modify a list:

1. Access the list templates collection using **ListTemplates** property of the **DocumentBase** class.
2. Add a paragraph to the list using the **Add** method. This adds another item in the list.
3. Apply list template to all the paragraph using **ListFormat** property of the **Paragraph** class.
4. Set the list level for the new paragraph, if required. For example, set the level number to 2, so that it appears as a nested item in the list.

    ```csharp
    doc.Load("List.docx");
    
    //Access the list template collection
    ListTemplate myListTemplate = doc.ListTemplates["myListTemplate"];
    
    //Add a paragraph to the list
    Paragraph p4=doc.Body.Sections.First.GetRange().Paragraphs.Add("Bullet item 4");
    p4.ListFormat.Template = myListTemplate;
    
    //Set the bullet level
    p4.ListFormat.LevelNumber = 2;
    
    //Save the document
    doc.Save("ModifyList.docx");
    ```

## Delete List

To delete a list, remove list formatting from the last paragraph of the document using [ClearFormatting](/document-solutions/dot-net-word-api/api/online/DS.Documents.Word/GrapeCity.Documents.Word.ListFormat.ClearFormatting.html) method of the ListFormat class.

```csharp
doc.Load("List.docx");

//Access the list template collection
ListTemplate myListTemplate = doc.ListTemplates["myListTemplate"];

//Remove list formatting from all the paragraphs serving as the list items
for (int p = 1; p < doc.Body.Paragraphs.Count; p++)
    doc.Body.Paragraphs[p].ListFormat.ClearFormatting();

//Save the document
doc.Save("DeleteList.docx");
```

## Restart List

You can also restart a list by using the **RestartList** method of **Paragraph** class. The method provides an optional **startNumberingValue** parameter which defines the new numerical value to be used as the restart value in the list. If the list is alphabetical, this numerical value defines the index of the letter in the alphabet to be used as the restart value in the list. For example, if the numerical value is 8:

* A numbered list will restart from 8
* An alphabetical list will restart from 'h' (8th letter)

If **startNumberingValue** parameter is null, the list will restart from the first number or first letter, whichever is applicable.
The screenshot below shows a document (List.docx) that contains a multi-level list, and the same document after being updated using the following code:
![Restart aplhabetical list in GcWord](https://cdn.mescius.io/document-site-files/images/d623c730-bceb-4e85-a6b2-a3dbe84720b2/images/restart_list_alphabet.png)

```csharp
var doc = new GcWordDocument();
//Load document containing list
doc.Load("List.docx");
//Restart 5th paragraph of the list and switch its list element to 8th alphabet letter (h)
doc.Body.Paragraphs[4].RestartList(8);

//Save the document
doc.Save("RestartList.docx");
```

> !type=note
> **Note:** The following behavior in DsWord differs from MS Word:
>
> * DsWord allows you to restart last items of lists unlike MS Word.
> * DsWord does not allow you to restart single-level lists as multilevel-lists unlike MS Word.

For more information on how to implement lists using DsWord, see [DsWord sample browser](https://developer.mescius.com/documents-api-word/demos/basics/content/bullets/code-cs).