> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/core/create/document-creation-api/lists.md).

# Lists

Use the doc creation API to create lists programmatically.

A `List` is a content node holding `ListItem` item labels like numbers, letters, or roman numerals. They are generated and renumbered automatically during pagination.

{% hint style="info" %}
**Info**

The list class is named `List` in most languages. Exceptions include `ListContainer` in PHP because list is a reserved word, `PTList` in Objective-C, and `PDFNet.List` in JavaScript.
{% endhint %}

## Simple list

`AddList` creates a list and `AddItem` appends an item. A `ListItem` is a content container in its own right, so its content is added as paragraphs.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
List list = doc.AddList();
list.SetNumberFormat(List.NumberFormat.e_decimal, ".", true);

list.AddItem().AddParagraph("Create a FlowDocument.");
list.AddItem().AddParagraph("Append content to it.");
list.AddItem().AddParagraph("Paginate it into a PDF.");
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
List list = doc.AddList();
list.SetNumberFormat(List::e_decimal, ".", true);

list.AddItem().AddParagraph("Create a FlowDocument.");
list.AddItem().AddParagraph("Append content to it.");
list.AddItem().AddParagraph("Paginate it into a PDF.");
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
list := doc.AddList()
list.SetNumberFormat(ListE_decimal, ".", true)

list.AddItem().AddParagraph("Create a FlowDocument.")
list.AddItem().AddParagraph("Append content to it.")
list.AddItem().AddParagraph("Paginate it into a PDF.")
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
List list = doc.addList();
list.setNumberFormat(List.ListItemNumberFormat.e_decimal, ".", true);

list.addItem().addParagraph("Create a FlowDocument.");
list.addItem().addParagraph("Append content to it.");
list.addItem().addParagraph("Paginate it into a PDF.");
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const list = await doc.addList();
list.setNumberFormat(PDFNet.List.NumberFormat.e_decimal, '.', true);

await (await list.addItem()).addParagraphWithText('Create a FlowDocument.');
await (await list.addItem()).addParagraphWithText('Append content to it.');
await (await list.addItem()).addParagraphWithText('Paginate it into a PDF.');
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTList* list = [doc AddList];
[list SetNumberFormatWithSuffix:e_ptlist_format_decimal suffix:@"." cascade:YES];

[[list AddItem] AddParagraphWithText:@"Create a FlowDocument."];
[[list AddItem] AddParagraphWithText:@"Append content to it."];
[[list AddItem] AddParagraphWithText:@"Paginate it into a PDF."];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$list = $doc->AddList();
$list->SetNumberFormat(ListContainer::e_decimal, ".", true);

$list->AddItem()->AddParagraph("Create a FlowDocument.");
$list->AddItem()->AddParagraph("Append content to it.");
$list->AddItem()->AddParagraph("Paginate it into a PDF.");
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
list = doc.AddList()
list.SetNumberFormat(List.e_decimal, ".", True)

list.AddItem().AddParagraph("Create a FlowDocument.")
list.AddItem().AddParagraph("Append content to it.")
list.AddItem().AddParagraph("Paginate it into a PDF.")
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
list = doc.AddList()
list.SetNumberFormat(List::E_decimal, ".", true)

list.AddItem().AddParagraph("Create a FlowDocument.")
list.AddItem().AddParagraph("Append content to it.")
list.AddItem().AddParagraph("Paginate it into a PDF.")
```

{% endcode %}
{% endtab %}
{% endtabs %}

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2F0uEejbLeqKCpEyRM6IJu%2Flist_simple.png?alt=media&amp;token=92b66ede-8fef-4258-b0b1-4fc094d21286" alt="Example of a list with numbers."><figcaption></figcaption></figure>

## Number formats

`SetNumberFormat` selects the label style. The three-argument overload also sets the suffix printed after the label and whether the format cascades to nested lists.

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2FXYBsHEKZBLjP171J5RKw%2Flist_number_formats.png?alt=media&amp;token=89aa2b6d-d417-45dd-b936-879143a04b5d" alt="Examples of number formatting like roman numerals."><figcaption></figcaption></figure>

Number formatting options include:

<table data-search="false"><thead><tr><th>Value</th><th>Labels</th></tr></thead><tbody><tr><td><code>e_none</code></td><td>(no label - an unordered list)</td></tr><tr><td><code>e_decimal</code></td><td>1, 2, 3</td></tr><tr><td><code>e_decimal_zero</code></td><td>01, 02, 03</td></tr><tr><td><code>e_lower_roman</code></td><td>i, ii, iii</td></tr><tr><td><code>e_upper_roman</code></td><td>I, II, III</td></tr><tr><td><code>e_lower_letter</code></td><td>a, b, c</td></tr><tr><td><code>e_upper_letter</code></td><td>A, B, C</td></tr><tr><td><code>e_ordinal</code></td><td>1st, 2nd, 3rd</td></tr><tr><td><code>e_ordinal_text</code></td><td>First, Second, Third</td></tr><tr><td><code>e_cardinal_text</code></td><td>One, Two, Three</td></tr><tr><td><code>e_chinese_counting</code></td><td>Chinese counting numerals</td></tr><tr><td><code>e_chinese_counting_thousand</code></td><td>Chinese counting numerals, thousands</td></tr></tbody></table>

Use `SetStartIndex` to begin numbering somewhere other than 1.

## Nest lists

A `ListItem` can contain a nested `List` through its own `AddList`. Nested lists are indented automatically and can use their own number format.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
List list = doc.AddList();
list.SetNumberFormat(List.NumberFormat.e_decimal, ".", true);
list.GetLabelStyle().SetBold(true);

list.AddItem().AddParagraph("Revenue grew in every region.");

ListItem risks = list.AddItem();
risks.AddParagraph("Risks for the Q4 forecast:");

List riskList = risks.AddList();
riskList.SetNumberFormat(List.NumberFormat.e_lower_letter, ")", true);
riskList.AddItem().AddParagraph("Currency fluctuations.");
riskList.AddItem().AddParagraph("Longer sales cycles.");

list.AddItem().AddParagraph("Hiring continues as planned.");
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
List list = doc.AddList();
list.SetNumberFormat(List::e_decimal, ".", true);
list.GetLabelStyle().SetBold(true);

list.AddItem().AddParagraph("Revenue grew in every region.");

ListItem risks = list.AddItem();
risks.AddParagraph("Risks for the Q4 forecast:");

List risk_list = risks.AddList();
risk_list.SetNumberFormat(List::e_lower_letter, ")", true);
risk_list.AddItem().AddParagraph("Currency fluctuations.");
risk_list.AddItem().AddParagraph("Longer sales cycles.");

list.AddItem().AddParagraph("Hiring continues as planned.");
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
list := doc.AddList()
list.SetNumberFormat(ListE_decimal, ".", true)
list.GetLabelStyle().SetBold(true)

list.AddItem().AddParagraph("Revenue grew in every region.")

risks := list.AddItem()
risks.AddParagraph("Risks for the Q4 forecast:")

riskList := risks.AddList()
riskList.SetNumberFormat(ListE_lower_letter, ")", true)
riskList.AddItem().AddParagraph("Currency fluctuations.")
riskList.AddItem().AddParagraph("Longer sales cycles.")

list.AddItem().AddParagraph("Hiring continues as planned.")
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
List list = doc.addList();
list.setNumberFormat(List.ListItemNumberFormat.e_decimal, ".", true);
list.getLabelStyle().setBold(true);

list.addItem().addParagraph("Revenue grew in every region.");

ListItem risks = list.addItem();
risks.addParagraph("Risks for the Q4 forecast:");

List riskList = risks.addList();
riskList.setNumberFormat(List.ListItemNumberFormat.e_lower_letter, ")", true);
riskList.addItem().addParagraph("Currency fluctuations.");
riskList.addItem().addParagraph("Longer sales cycles.");

list.addItem().addParagraph("Hiring continues as planned.");
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const list = await doc.addList();
list.setNumberFormat(PDFNet.List.NumberFormat.e_decimal, '.', true);
(await list.getLabelStyle()).setBold(true);

await (await list.addItem()).addParagraphWithText('Revenue grew in every region.');

const risks = await list.addItem();
await risks.addParagraphWithText('Risks for the Q4 forecast:');

const riskList = await risks.addList();
riskList.setNumberFormat(PDFNet.List.NumberFormat.e_lower_letter, ')', true);
await (await riskList.addItem()).addParagraphWithText('Currency fluctuations.');
await (await riskList.addItem()).addParagraphWithText('Longer sales cycles.');

await (await list.addItem()).addParagraphWithText('Hiring continues as planned.');
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTList* list = [doc AddList];
[list SetNumberFormatWithSuffix:e_ptlist_format_decimal suffix:@"." cascade:YES];
[[list GetLabelStyle] SetBold:YES];

[[list AddItem] AddParagraphWithText:@"Revenue grew in every region."];

PTListItem* risks = [list AddItem];
[risks AddParagraphWithText:@"Risks for the Q4 forecast:"];

PTList* risk_list = [risks AddList];
[risk_list SetNumberFormatWithSuffix:e_ptlist_format_lower_letter suffix:@")" cascade:YES];
[[risk_list AddItem] AddParagraphWithText:@"Currency fluctuations."];
[[risk_list AddItem] AddParagraphWithText:@"Longer sales cycles."];

[[list AddItem] AddParagraphWithText:@"Hiring continues as planned."];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$list = $doc->AddList();
$list->SetNumberFormat(ListContainer::e_decimal, ".", true);
$list->GetLabelStyle()->SetBold(true);

$list->AddItem()->AddParagraph("Revenue grew in every region.");

$risks = $list->AddItem();
$risks->AddParagraph("Risks for the Q4 forecast:");

$risk_list = $risks->AddList();
$risk_list->SetNumberFormat(ListContainer::e_lower_letter, ")", true);
$risk_list->AddItem()->AddParagraph("Currency fluctuations.");
$risk_list->AddItem()->AddParagraph("Longer sales cycles.");

$list->AddItem()->AddParagraph("Hiring continues as planned.");
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
list = doc.AddList()
list.SetNumberFormat(List.e_decimal, ".", True)
list.GetLabelStyle().SetBold(True)

list.AddItem().AddParagraph("Revenue grew in every region.")

risks = list.AddItem()
risks.AddParagraph("Risks for the Q4 forecast:")

risk_list = risks.AddList()
risk_list.SetNumberFormat(List.e_lower_letter, ")", True)
risk_list.AddItem().AddParagraph("Currency fluctuations.")
risk_list.AddItem().AddParagraph("Longer sales cycles.")

list.AddItem().AddParagraph("Hiring continues as planned.")
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
list = doc.AddList()
list.SetNumberFormat(List::E_decimal, ".", true)
list.GetLabelStyle().SetBold(true)

list.AddItem().AddParagraph("Revenue grew in every region.")

risks = list.AddItem()
risks.AddParagraph("Risks for the Q4 forecast:")

risk_list = risks.AddList()
risk_list.SetNumberFormat(List::E_lower_letter, ")", true)
risk_list.AddItem().AddParagraph("Currency fluctuations.")
risk_list.AddItem().AddParagraph("Longer sales cycles.")

list.AddItem().AddParagraph("Hiring continues as planned.")
```

{% endcode %}
{% endtab %}
{% endtabs %}

<figure><img src="https://3779731113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fziw3GiL98Xfj63F3He8h%2Fuploads%2FZBIHFPOYKszW6h6w8fZs%2Flist_nested.png?alt=media&amp;token=abe9904a-0359-408c-88b5-e6f7a2089b6c" alt="Example of nested numbering."><figcaption></figcaption></figure>

## Style labels

`GetLabelStyle` returns a `TextStyledElement` that applies to the generated labels only, leaving item text untouched. This is how you make numbers bold or colored without affecting the content. Item text is styled as usual, through the paragraph inside the item.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
TextStyledElement labels = list.GetLabelStyle();
labels.SetBold(true);
labels.SetTextColor(0, 51, 102);

Paragraph itemText = list.AddItem().AddParagraph("An emphasized item.");
itemText.GetTextStyledElement().SetItalic(true);
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
TextStyledElement labels = list.GetLabelStyle();
labels.SetBold(true);
labels.SetTextColor(0, 51, 102);

Paragraph item_text = list.AddItem().AddParagraph("An emphasized item.");
item_text.GetTextStyledElement().SetItalic(true);
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
labels := list.GetLabelStyle()
labels.SetBold(true)
labels.SetTextColor(0, 51, 102)

itemText := list.AddItem().AddParagraph("An emphasized item.")
itemText.GetTextStyledElement().SetItalic(true)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
TextStyledElement labels = list.getLabelStyle();
labels.setBold(true);
labels.setTextColor(0, 51, 102);

Paragraph itemText = list.addItem().addParagraph("An emphasized item.");
itemText.getTextStyledElement().setItalic(true);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const labels = await list.getLabelStyle();
labels.setBold(true);
labels.setTextColor(0, 51, 102);

const itemText = await (await list.addItem()).addParagraphWithText('An emphasized item.');
(await itemText.getTextStyledElement()).setItalic(true);
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTTextStyledElement* labels = [list GetLabelStyle];
[labels SetBold:YES];
[labels SetTextColor:0 green:51 blue:102];

PTParagraph* item_text = [[list AddItem] AddParagraphWithText:@"An emphasized item."];
[[item_text GetTextStyledElement] SetItalic:YES];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$labels = $list->GetLabelStyle();
$labels->SetBold(true);
$labels->SetTextColor(0, 51, 102);

$item_text = $list->AddItem()->AddParagraph("An emphasized item.");
$item_text->GetTextStyledElement()->SetItalic(true);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
labels = list.GetLabelStyle()
labels.SetBold(True)
labels.SetTextColor(0, 51, 102)

item_text = list.AddItem().AddParagraph("An emphasized item.")
item_text.GetTextStyledElement().SetItalic(True)
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
labels = list.GetLabelStyle()
labels.SetBold(true)
labels.SetTextColor(0, 51, 102)

item_text = list.AddItem().AddParagraph("An emphasized item.")
item_text.GetTextStyledElement().SetItalic(true)
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Continue a list

Adding non-list content between items normally ends the list, so a following `AddItem` starts fresh numbering. `ContinueList` marks the list as the logical continuation of the earlier one, so numbering carries on across the interruption.

{% tabs %}
{% tab title="C#" %}
{% code lineNumbers="true" %}

```csharp
List steps = doc.AddList();
steps.SetNumberFormat(List.NumberFormat.e_decimal, ".", true);
steps.AddItem().AddParagraph("Install the SDK.");
steps.AddItem().AddParagraph("Add your license key.");

doc.AddParagraph("Note: the license key is required before any other call.");

// Resume the same numbering after the interrupting paragraph.
steps.ContinueList();
steps.AddItem().AddParagraph("Build your first document.");
```

{% endcode %}
{% endtab %}

{% tab title="C++" %}
{% code lineNumbers="true" %}

```cpp
List steps = doc.AddList();
steps.SetNumberFormat(List::e_decimal, ".", true);
steps.AddItem().AddParagraph("Install the SDK.");
steps.AddItem().AddParagraph("Add your license key.");

doc.AddParagraph("Note: the license key is required before any other call.");

// Resume the same numbering after the interrupting paragraph.
steps.ContinueList();
steps.AddItem().AddParagraph("Build your first document.");
```

{% endcode %}
{% endtab %}

{% tab title="Go" %}
{% code lineNumbers="true" %}

```go
steps := doc.AddList()
steps.SetNumberFormat(ListE_decimal, ".", true)
steps.AddItem().AddParagraph("Install the SDK.")
steps.AddItem().AddParagraph("Add your license key.")

doc.AddParagraph("Note: the license key is required before any other call.")

// Resume the same numbering after the interrupting paragraph.
steps.ContinueList()
steps.AddItem().AddParagraph("Build your first document.")
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
List steps = doc.addList();
steps.setNumberFormat(List.ListItemNumberFormat.e_decimal, ".", true);
steps.addItem().addParagraph("Install the SDK.");
steps.addItem().addParagraph("Add your license key.");

doc.addParagraph("Note: the license key is required before any other call.");

// Resume the same numbering after the interrupting paragraph.
steps.continueList();
steps.addItem().addParagraph("Build your first document.");
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const steps = await doc.addList();
steps.setNumberFormat(PDFNet.List.NumberFormat.e_decimal, '.', true);
await (await steps.addItem()).addParagraphWithText('Install the SDK.');
await (await steps.addItem()).addParagraphWithText('Add your license key.');

await doc.addParagraphWithText('Note: the license key is required before any other call.');

// Resume the same numbering after the interrupting paragraph.
steps.continueList();
await (await steps.addItem()).addParagraphWithText('Build your first document.');
```

{% endcode %}
{% endtab %}

{% tab title="Obj-C" %}
{% code lineNumbers="true" %}

```objectivec
PTList* steps = [doc AddList];
[steps SetNumberFormatWithSuffix:e_ptlist_format_decimal suffix:@"." cascade:YES];
[[steps AddItem] AddParagraphWithText:@"Install the SDK."];
[[steps AddItem] AddParagraphWithText:@"Add your license key."];

[doc AddParagraphWithText:@"Note: the license key is required before any other call."];

// Resume the same numbering after the interrupting paragraph.
[steps ContinueList];
[[steps AddItem] AddParagraphWithText:@"Build your first document."];
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code lineNumbers="true" %}

```php
$steps = $doc->AddList();
$steps->SetNumberFormat(ListContainer::e_decimal, ".", true);
$steps->AddItem()->AddParagraph("Install the SDK.");
$steps->AddItem()->AddParagraph("Add your license key.");

$doc->AddParagraph("Note: the license key is required before any other call.");

// Resume the same numbering after the interrupting paragraph.
$steps->ContinueList();
$steps->AddItem()->AddParagraph("Build your first document.");
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
steps = doc.AddList()
steps.SetNumberFormat(List.e_decimal, ".", True)
steps.AddItem().AddParagraph("Install the SDK.")
steps.AddItem().AddParagraph("Add your license key.")

doc.AddParagraph("Note: the license key is required before any other call.")

# Resume the same numbering after the interrupting paragraph.
steps.ContinueList()
steps.AddItem().AddParagraph("Build your first document.")
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}
{% code lineNumbers="true" %}

```ruby
steps = doc.AddList()
steps.SetNumberFormat(List::E_decimal, ".", true)
steps.AddItem().AddParagraph("Install the SDK.")
steps.AddItem().AddParagraph("Add your license key.")

doc.AddParagraph("Note: the license key is required before any other call.")

# Resume the same numbering after the interrupting paragraph.
steps.ContinueList()
steps.AddItem().AddParagraph("Build your first document.")
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Further Reading

* [Paragraphs and text](/core/create/document-creation-api/paragraphs-and-text.md) for styling the text inside list items.
* [Tables](/core/create/document-creation-api/tables.md) for tabular rather than sequential content.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/core/create/document-creation-api/lists.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.