Lists
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— bundlesBulletList,OrderedList,ListItem, andListKeymap. - 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 | Not supported | Supported (requires TaskList extension) | Not supported |
Import
Import lists using the editor extension or the REST API. 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, OrderedList, ListItem, and ListKeymap extensions are registered by ConvertKit. 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. Task lists require the separate TaskList and TaskItem extensions.
Export
Export lists using the editor extension or the REST API. 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
The editor supports task lists (taskList and taskItem nodes) with a checked attribute. However, task lists are not part of the DOCX conversion pipeline. They cannot be imported from DOCX, and they are not included in DOCX export output.
If your editor uses task lists, they will function correctly for editing but will not round-trip through DOCX conversion.