---
title: "Lists"
description: "How bullet lists, ordered lists, nested lists, and task lists convert between DOCX and Tiptap."
canonical_url: "https://tiptap.dev/docs/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. Numbering format and start values from DOCX are not preserved during import.

## What you need

- **Extensions:** [`ConvertKit`](https://tiptap.dev/docs/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)                                                                         | Partial       |
| Numbering format (a/A/i/I/1) | Read internally to classify ordered vs bullet, then discarded | The OrderedList extension's `type` attr accepts these values, but the importer does not set it | Not preserved |
| Start number                 | Not extracted from `w:start` in DOCX numbering                | The OrderedList extension's `start` attr is supported, but the importer does not set it        | Not preserved |
| Nested lists                 | Supported                                                     | Supported                                                                                      | Supported     |
| Task lists                   | Supported, opt-in                                             | Supported (ConvertKit)                                                                         | Supported     |

## Import

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

The conversion service groups all consecutive DOCX list paragraphs into list structures, regardless of their numbering ID. The indentation level (`ilvl`) controls nesting. The importer reads the `numFmt` value only to classify each paragraph as a bullet or ordered list item. Bullet-style numbering produces `bulletList` nodes. Decimal, letter, and roman numbering all produce `orderedList` nodes with no further differentiation: a list authored as `A, B, C` in Word and a list authored as `1, 2, 3` arrive at the editor as identical `orderedList` nodes with no attributes. The Tiptap OrderedList extension's `type` attribute (which would render `<ol type="a">`) is never populated from the import side. To preserve a custom numbering style end-to-end today, set the `type` attribute on the editor side after the content is loaded.

The `w:start` value from DOCX numbering definitions is not parsed, so start numbers are not imported.

## Editor rendering

The [`BulletList`](https://tiptap.dev/docs/editor/extensions/nodes/bullet-list.md), [`OrderedList`](https://tiptap.dev/docs/editor/extensions/nodes/ordered-list.md), [`ListItem`](https://tiptap.dev/docs/editor/extensions/nodes/list-item.md), and `ListKeymap` extensions are registered by [`ConvertKit`](https://tiptap.dev/docs/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">`), but the DOCX importer does not set these attributes.

Nesting works through the `listItem` content model, which allows block content including other lists inside list items. [`TaskList`](https://tiptap.dev/docs/editor/extensions/nodes/task-list.md) and [`TaskItem`](https://tiptap.dev/docs/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.dev/docs/conversion/export/docx/editor-extension.md) or the [REST API](https://tiptap.dev/docs/conversion/export/docx/rest-api.md). Both handle lists identically.

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.

> **Numbering format and start values are not exported:**
>
> The export converter does not read the `type` or `start` attributes from ordered list nodes. All
> ordered lists export as default decimal numbering (1, 2, 3) regardless of the format set in the
> editor. A list with `type: "a"` and `start: 5` in the editor will export as a standard 1, 2, 3
> list in Word.

## 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.dev/docs/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.