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:
ConvertKitbundlesBulletList,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 | Supported, opt-in | Supported (ConvertKit) | 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. TaskList and TaskItem are registered by ConvertKit too, so checkbox lists render without extra setup.
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
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 for which checkbox shapes are recognised, how to style them, and what happens to a numbered list that holds checkboxes.