---
title: "Lists"
description: "How bullet lists, ordered lists, nested lists, and task lists convert between DOCX and Tiptap."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/conversion/content-types/text-and-formatting/lists"
---

# Lists

How bullet lists, ordered lists, nested lists, and task lists convert between DOCX and Tiptap.

Bullet lists and ordered lists convert between DOCX and Tiptap with nesting preserved. The import keeps a list together the way Word numbers it, and reads the numbering format and start number of each ordered list.

## What you need

- **Extensions:** [`ConvertKit`](https://tiptap-docs.lin52025i.qzz.io/conversion/import/docx/convertkit.md) bundles `BulletList`, `OrderedList`, `ListItem`, and `ListKeymap`.
- **Configuration:** None required. Nesting works out of the box at all pipeline stages.

## Support overview

|                              | Import                                                                    | Editor                                                                                                              | Export                                             |
| ---------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Bullet lists                 | Supported                                                                 | Supported (ConvertKit)                                                                                              | Supported                                          |
| Ordered lists                | Supported                                                                 | Supported (ConvertKit)                                                                                              | Supported                                          |
| Numbering format (a/A/i/I/1) | Imported as `numberingFormat`, plus `type` for letters and roman numerals | Drawn by `OrderedListNumbering` (off by default). The OrderedList extension's `type` attr also accepts these values | Editor extension only, from the registered formats |
| Start number                 | Imported as `start` when the list does not start at 1                     | The OrderedList extension's `start` attr is supported                                                               | Editor extension only                              |
| Nested lists                 | Supported                                                                 | Supported                                                                                                           | Supported                                          |
| Task lists                   | Supported, opt-in                                                         | Supported (ConvertKit)                                                                                              | Supported                                          |

## Import

Import lists using the [editor extension](https://tiptap-docs.lin52025i.qzz.io/conversion/import/docx/editor-extension.md) or the [REST API](https://tiptap-docs.lin52025i.qzz.io/conversion/import/docx/rest-api.md). Both produce identical output.

The conversion service builds one list from consecutive list paragraphs that Word numbers as one list:

- Paragraphs on the same numbering ID (`numId`).
- Paragraphs on different numbering IDs whose definitions share an `nsid` and the same levels. A numbering ID that restarts the count with `w:startOverride` starts a new list.
- Empty paragraphs between items of one ordered list. Word keeps counting across them, so they do not end the list. Each one stays inside the item before it, which keeps the blank line.

A paragraph with text between list items, such as a heading, ends the list, and so does an empty paragraph in a bullet or task list. The indentation level (`ilvl`) controls nesting.

Bullet-style numbering produces `bulletList` nodes, and decimal, letter and roman numbering produce `orderedList` nodes. The outermost list of each gets a `numberingFormat` that [`OrderedListNumbering`](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/ordered-list-numbering.md) draws, and the response lists those formats in `numberingFormats`. An ordered list also gets `type` (`a`, `A`, `i` or `I`) for letter and roman numbering, and `start` when its first level does not start at 1.

The editor keeps `numberingFormat` only when `OrderedListNumbering` is on, for example with `ConvertKit.configure({ orderedListNumbering: true })`. With the default ConvertKit setup, the editor drops the attribute when it loads the content and keeps `type` and `start`. The REST response carries all three either way.

## Editor rendering

The [`BulletList`](https://tiptap-docs.lin52025i.qzz.io/editor/extensions/nodes/bullet-list.md), [`OrderedList`](https://tiptap-docs.lin52025i.qzz.io/editor/extensions/nodes/ordered-list.md), [`ListItem`](https://tiptap-docs.lin52025i.qzz.io/editor/extensions/nodes/list-item.md), and `ListKeymap` extensions are registered by [`ConvertKit`](https://tiptap-docs.lin52025i.qzz.io/conversion/import/docx/convertkit.md). No separate installation is needed.

Lists render using standard HTML elements: `<ul>` for bullet lists, `<ol>` for ordered lists, and `<li>` for list items. If `start` and `type` attributes are set on an `orderedList` node, the editor renders them as HTML attributes (e.g., `<ol start="5" type="a">`). With `OrderedListNumbering` on, the list's numbering format draws the markers instead and counts from the format's own start number.

The editor draws a format's markers only after the format is registered. `ImportDocx` registers the imported formats for you when `OrderedListNumbering` is on. After a REST import, pass the response's `numberingFormats` to `editor.commands.registerNumberingFormats()`, as shown in [Adding formats after the editor is running](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/ordered-list-numbering.md#adding-formats-after-the-editor-is-running).

Nesting works through the `listItem` content model, which allows block content including other lists inside list items. [`TaskList`](https://tiptap-docs.lin52025i.qzz.io/editor/extensions/nodes/task-list.md) and [`TaskItem`](https://tiptap-docs.lin52025i.qzz.io/editor/extensions/nodes/task-item.md) are registered by `ConvertKit` too, so checkbox lists render without extra setup.

## Export

Export lists using the [editor extension](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/editor-extension.md) or the [REST API](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/rest-api.md). Both export bullet, ordered, nested and task lists. Only the editor extension keeps numbering formats and start numbers.

Bullet lists and ordered lists both export to DOCX with correct structure. Nesting is preserved by incrementing the DOCX indentation level recursively. Each ordered list instance receives a unique numbering ID so multiple lists in the same document number independently. Lists with a `linkedStyle` format are the exception, see below.

The editor extension numbers an ordered list the way the editor shows it, with one exception:

- A list with a `numberingFormat` exports with that format. The extension reads the formats registered in the editor, from `@tiptap-pro/extension-export-docx` 0.34.0. See [Ordered list numbering](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/ordered-list-numbering.md).
- A list without a `numberingFormat` starts at its `start` number, from version 0.34.6. A list with a format counts from the format's own start number, as the editor does.
- The `type` attribute is not exported. A list with `type: "a"` and no `numberingFormat` exports as 1, 2, 3.
- The exception: a format with a [`linkedStyle`](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/ordered-list-numbering.md#numberingleveldefinition) level is one list for the whole document in Word. Its lists continue each other in the DOCX, while the editor restarts each one. Check the exported numbers when you use `linkedStyle`.

> **The REST API exports ordered lists as 1, 2, 3:**
>
> The `/v2/convert/export/docx` endpoint does not read `numberingFormat`, `type` or `start`. Every
> ordered list exports with decimal numbers that start at 1.

## Task lists

Word checkbox lists convert to `taskList` and `taskItem` nodes, with the ticked state preserved both ways. Import is opt-in and the editor extension turns it on for you when your schema can render the nodes.

See [Task lists](https://tiptap-docs.lin52025i.qzz.io/conversion/content-types/text-and-formatting/task-lists.md) for which checkbox shapes are recognised, how to style them, and what happens to a numbered list that holds checkboxes.