---
title: "Lists"
canonical_url: "https://www.nutrient.io/guides/document-authoring/editing-content/lists/"
md_url: "https://www.nutrient.io/guides/document-authoring/editing-content/lists.md"
last_updated: "2026-07-08T00:00:00.000Z"
description: "Create, update, and read bullet and numbered lists in Document Authoring by applying list formatting to paragraphs, setting nesting levels, clearing lists, and inspecting list state."
---

# Work with lists

Document Authoring stores list state as a paragraph property. Each paragraph is a bullet item, a numbered item, or not a list item.

Inside a [transaction](https://www.nutrient.io/guides/document-authoring/editing-content/programmatic-editing.md), you can:

- Apply list formatting to a range of paragraphs with [`setParagraphList()`](https://www.nutrient.io/api/document-authoring/types/programmatic/blocklevelcontainer/#setparagraphlist).

- Copy list formatting between paragraphs with [`applyParagraphListFrom()`](https://www.nutrient.io/api/document-authoring/types/programmatic/blocklevelcontainer/#applyparagraphlistfrom).

- Read a paragraph’s current list state with [`list()`](https://www.nutrient.io/api/document-authoring/types/programmatic/paragraph/#list).

Before you start, make sure the Document Authoring library is installed and running in your app. If you haven’t set it up yet, refer to the [getting started](https://www.nutrient.io/sdk/document-authoring/getting-started.md) guide.

The examples omit error handling. Add it before you use this code in production.

## Apply list formatting

Use [`setParagraphList()`](https://www.nutrient.io/api/document-authoring/types/programmatic/blocklevelcontainer/#setparagraphlist) to turn a contiguous range of paragraphs into a list. The range uses `{ index, count }` over the block-level content. This example creates three paragraphs and formats them as a bullet list:

```js

const currentDoc = editor.currentDocument();

await currentDoc.transaction(async ({ draft }) => {
  const content = draft.body().content();
  const start = content.blocklevels().length;

  content.addParagraph().asTextView().setText('Draft the announcement');
  content.addParagraph().asTextView().setText('Prepare the demo');
  content.addParagraph().asTextView().setText('Send the follow-up');

  content.setParagraphList({ index: start, count: 3 }, { kind: 'bullet' });

  return true;
});

```

Use `kind: 'numbered'` for a numbered list. Set `level` to nest items. Level `0` is the top level:

```js

content.setParagraphList({ index: start, count: 3 }, { kind: 'numbered', level: 1 });

```

## Remove list formatting

Pass `{ kind: 'none' }` to clear list formatting while keeping the paragraph text:

```js

content.setParagraphList({ index: start, count: 3 }, { kind: 'none' });

```

## Copy list formatting from another paragraph

Use [`applyParagraphListFrom()`](https://www.nutrient.io/api/document-authoring/types/programmatic/blocklevelcontainer/#applyparagraphlistfrom) to copy a source paragraph’s list formatting to a target range. Set `list: 'continue'` to continue the source numbering, or set `list: 'startNew'` to start a new list with the same format:

```js

await currentDoc.transaction(async ({ draft }) => {
  const content = draft.body().content();
  const sourceIndex = 0;

  content.applyParagraphListFrom(
    sourceIndex,
    { index: 1, count: 2 },
    { list: 'startNew' },
  );

  return true;
});

```

## Read list state

Use [`list()`](https://www.nutrient.io/api/document-authoring/types/programmatic/paragraph/#list) to check whether a paragraph is a list item:

```js

await currentDoc.transaction(async ({ draft }) => {
  for (const blockLevel of draft.body().content().blocklevels()) {
    if (blockLevel.type!== 'paragraph') continue;

    const list = blockLevel.list();

    if (!list) continue;                  // not a list item
    if ('unsupported' in list) continue;  // imported or custom format

    console.log(`${list.kind} list, level ${list.level}`);
  }

  return false;
});

```

The method returns one of these values:

- `null` when the paragraph isn’t a list item.

- `{ kind, level }` for a bullet or numbered item the API can classify.

- `{ unsupported: true, level }` for imported or custom list formats the API can’t safely classify.

## Learn more

**[Text and formatting](https://www.nutrient.io/guides/document-authoring/editing-content/text-and-formatting.md)**\
Apply character formatting to list text.

**[Programmatic editing](https://www.nutrient.io/guides/document-authoring/editing-content/programmatic-editing.md)**\
Learn how transactions work and how to use paragraph properties and the document model.
---

## Related pages

- [Use copy/paste and HTML interoperability](/guides/document-authoring/editing-content/copy-paste-and-html-interoperability.md)
- [Find and replace text](/guides/document-authoring/editing-content/find-and-replace.md)
- [Work with footnotes and endnotes](/guides/document-authoring/editing-content/footnotes-and-endnotes.md)
- [Edit documents programmatically](/guides/document-authoring/editing-content/programmatic-editing.md)
- [Work with images and shapes](/guides/document-authoring/editing-content/images-and-shapes.md)
- [Format text](/guides/document-authoring/editing-content/text-and-formatting.md)
- [Work with tables](/guides/document-authoring/editing-content/tables.md)