Lists

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 bundles BulletList, OrderedList, ListItem, and ListKeymap.
• Configuration: None required. Nesting works out of the box at all pipeline stages.

Support overview

Import

Import lists using the editor extension or the REST API. 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 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, 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">). 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.

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 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.
• 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 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.

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.