Customize list numbering and bullets for DOCX export

@tiptap-pro/extension-export-docx accepts an optional registry of numbering format definitions (multilevel marker style, marker text, alignment, indent, and font) selected per-list via an attribute on the outermost <ol> or <ul>. Lists with a matching id export with the corresponding definition; lists without one keep the default ladder for their kind.

A format whose levels use baseStyle: 'bullet' describes a glyph ladder instead of a counter, so the same registry also carries decorative bullets. See Bullet ladders.

The feature is opt-in. Consumers who don't supply numberingFormats see no behavior change.

What's provided

A picker UI for end users isn't part of these packages; that's an application concern and depends on your component library.

Quick start

import { Editor } from '@tiptap/core'
import { ConvertKit, type NumberingFormatDefinition } from '@tiptap-pro/extension-convert-kit'
import { ExportDocx, LevelFormat } from '@tiptap-pro/extension-export-docx'

// 1. Define your registry: one source of truth, used on both sides below.
const MY_FORMATS: NumberingFormatDefinition[] = [
  {
    id: 'decimal-paren',
    levels: [
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1)' },
      { baseStyle: LevelFormat.LOWER_LETTER, textTemplate: '%2)' },
      { baseStyle: LevelFormat.LOWER_ROMAN, textTemplate: '%3)' },
    ],
  },
  {
    id: 'outline',
    levels: [
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1.' },
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1.%2.' },
      { baseStyle: LevelFormat.DECIMAL, textTemplate: '%1.%2.%3.' },
    ],
  },
]

// 2. Opt in via ConvertKit. Passing `formats` generates the editor-preview CSS
//    and injects it for you; register ExportDocx with the same registry so the
//    .docx carries the matching definitions.
const editor = new Editor({
  extensions: [
    ConvertKit.configure({
      // Off by default so consumers without custom numbering keep a clean
      // orderedList schema. Pass an options object (or `true`) to opt in.
      orderedListNumbering: { formats: MY_FORMATS },
    }),
    ExportDocx.configure({
      numberingFormats: MY_FORMATS,
      onCompleteExport: (blob) => {
        /* download blob */
      },
    }),
  ],
})

// 3. Start a numbered list in the chosen format at the current selection
//    (or, when already in a list, change its format with setOrderedListNumberingFormat).
editor.chain().focus().toggleOrderedListWithFormat('outline').run()

Prefer to manage the stylesheet yourself? Omit formats and inject the CSS from generateNumberingFormatCss instead. The two paths produce the same markers.

Enabling ordered list numbering

OrderedListNumbering ships with @tiptap-pro/extension-convert-kit but is off by default, to keep the orderedList schema clean for consumers that don't use custom numbering. Opt in via ConvertKit:

ConvertKit.configure({ orderedListNumbering: true })

Pass an options object instead of true to configure three things:

ConvertKit.configure({
  orderedListNumbering: {
    // The format id new ordered lists start with. Defaults to `null` (plain `1. 2. 3.`).
    defaultFormat: 'outline',
    // The same, for new bullet lists.
    defaultBulletFormat: 'arrows',
    // The same definitions you pass to ExportDocx. When provided, the
    // editor-preview CSS is generated from them and injected automatically,
    // so on-screen markers match the export with no extra wiring.
    formats: MY_FORMATS,
  },
})

Passing formats here is the equivalent of calling generateNumberingFormatCss and injecting the result yourself: choose whichever fits your setup.

Applying a format

The setOrderedListNumberingFormat(id) command sets the numberingFormat attribute on the outermost ordered list ancestor of the current selection. Pass null to clear it (the list then exports as plain 1. 2. 3.).

editor.chain().focus().setOrderedListNumberingFormat('decimal-paren').run()
editor.chain().focus().setOrderedListNumberingFormat(null).run()

The command returns false when the selection isn't inside an ordered list, and also when a list of another kind stands between the selection and that ordered list, because such a list ends the ladder. To ask whether this command will reach a list, use editor.can().setOrderedListNumberingFormat(null) rather than editor.isActive('orderedList'): the two disagree in exactly that case, and only can() matches what the command will do.

Starting a new list in a format

setOrderedListNumberingFormat only targets a list the selection is already inside. To start a numbered list in a chosen format from a non-list selection, use toggleOrderedListWithFormat(format?). It creates the ordered list and applies the format in one call, which is the natural action for a "pick a format to start a numbered list" toolbar button:

// From a paragraph: create an ordered list and set its format.
editor.chain().focus().toggleOrderedListWithFormat('outline').run()

// Omit the format to start a list in the configured `defaultFormat`.
editor.chain().focus().toggleOrderedListWithFormat().run()

When the selection is already inside an ordered list the command toggles the list off, mirroring toggleOrderedList. Chaining toggleOrderedList().setOrderedListNumberingFormat(format) reaches the same end state; the single command is simply more convenient and also handles the toggle-off case.

Omitting the argument is not the same as passing null. Omit it and the new list takes the configured defaultFormat; pass null and it takes no format at all.

The two commands answer editor.can() about different things, so a toolbar needs both. toggleOrderedListWithFormat answers the same way its plain toggle does, which is true from an ordinary paragraph because it can create the list; disable a "start a list in this format" button on that. setOrderedListNumberingFormat answers whether a list is already there to change, which is false from that same paragraph. Use the setter's answer to pick which command to run, not to disable the button:

// One "apply this format" button, doing the right thing in both places.
if (editor.can().setOrderedListNumberingFormat(null)) {
  editor.chain().focus().setOrderedListNumberingFormat(id).run()
} else {
  editor.chain().focus().toggleOrderedListWithFormat(id).run()
}

Bullet lists

Bullet lists have the same pair, targeting the outermost bulletList ancestor:

editor.chain().focus().setBulletListNumberingFormat('arrows').run()
editor.chain().focus().toggleBulletListWithFormat('arrows').run()

Everything above holds for the bullet pair, with defaultBulletFormat in place of defaultFormat. setBulletListNumberingFormat returns false in four positions: outside any list, inside an ordered list, inside a checklist, and inside a bullet list reached only by crossing one of those two. A task list is not a bullet list, so it ends the ladder the same way an ordered list does. Branch on editor.can().setBulletListNumberingFormat(null), which is false in all four, the same way the ordered pair does above.

toggleBulletListWithFormat has the same reach as its ordered twin: from inside a checklist it converts the whole checklist into a plain bullet list, losing the checkboxes.

Adding formats after the editor is running

formats is read once, when the editor is created. A registry that only exists later, the usual case being the one a DOCX import reconstructs from the file, goes in with registerNumberingFormats(formats). The command merges by id and refreshes the injected preview stylesheet, so lists already in the document pick up their markers straight away:

editor.commands.registerNumberingFormats(formatsFromTheImport)

Merging by id means repeating the call is safe: re-registering an id replaces that entry rather than adding a second one, so importing the same file twice leaves one definition behind. An id you configured in formats is replaced the same way, which lets an imported document override a house format of the same name.

The full registry, your configured formats plus everything registered since, is on the extension's storage. Hand it to the exporter to close the round trip:

ExportDocx.configure({ numberingFormats: editor.storage.orderedListNumbering.numberingFormats })

The ImportDocx extension calls registerNumberingFormats for you when orderedListNumbering is on, so an imported document renders its own markers without any wiring. Call it yourself when you load content some other way.

Reading the active format

To reflect the active format in a toolbar, read it from the extension's storage, which stays in sync as the selection and document change:

const activeOrdered = editor.storage.orderedListNumbering.activeNumberingFormat
const activeBullet = editor.storage.orderedListNumbering.activeBulletNumberingFormat
// a format id, or `null` when the selection is not inside a list of that kind

Each field answers what its own command would target, so only one is set at a time: inside a bullet list nested in an ordered one, the bullet field reports that list and the ordered field reads null.

NumberingFormatDefinition

interface NumberingFormatDefinition {
  id: string
  levels: NumberingLevelDefinition[]
}

NumberingLevelDefinition

interface NumberingLevelDefinition {
  baseStyle: NumberingBaseStyle
  textTemplate: string
  startAt?: number
  alignment?: 'left' | 'center' | 'right'
  numberIndent?: number | string
  textIndent?: number | string
  markerFont?: NumberingMarkerFont
  suffix?: 'tab' | 'space' | 'nothing'
  isLegalNumbering?: boolean
  linkedStyle?: string
}

ConvertKit's types use plain string literals so the package does not pull in docx. The fields are structurally compatible with ExportDocx's stricter (docx-typed) version, so passing LevelFormat.DECIMAL from @tiptap-pro/extension-export-docx works the same as passing the string 'decimal'.

NumberingMarkerFont

interface NumberingMarkerFont {
  font?: string | { name: string }
  size?: number | string
  bold?: boolean
  italics?: boolean
  color?: string
  underline?: unknown
}

Mirrors the subset of docx IRunOptions that generateNumberingFormatCss understands. Additional fields you pass through to ExportDocx are ignored by the preview but still survive into the .docx.

The textTemplate grammar

• %1 through %9 reference the counter at the 1-indexed nesting depth. So %1 is always "the counter at the outermost level", regardless of which level the textTemplate belongs to.
• All other characters render literally.
• Stray % followed by a non-digit (e.g. "50%") is preserved.
• A %N pointing at a level that counts nothing, a 'bullet' or 'none' level, draws nothing.

To make each level display its own counter, use ascending %N per level. To make a level include parent counters (legal-style outlines), chain them: '%1.%2.' at level 1 renders '1.1.'.

Bullet ladders

Word draws a bullet from the glyph in w:lvlText, so an arrow, diamond or star is something the document carries rather than something the reader's Word decides. A format whose levels use baseStyle: 'bullet' describes that ladder, and a bulletList selects it through the same numberingFormat attribute:

numberingFormats: [
  {
    id: 'arrows',
    levels: [
      { baseStyle: 'bullet', textTemplate: '➔' },
      { baseStyle: 'bullet', textTemplate: '◆' },
    ],
  },
]
// { type: 'bulletList', attrs: { numberingFormat: 'arrows' }, content: [...] }

On a 'bullet' level, textTemplate is the glyph itself and markerFont.font names the font to draw it in, which is what a Word symbol-font bullet needs. Everything else on the level works the same way it does for a counter, indents included. Only the exact value bullet marks a level this way; every other baseStyle stays a counter level.

A bullet level counts nothing, so a %N pointing at one draws nothing. 'Item %1:' on a bullet level renders Item :, in Word and in the preview alike. 'none' behaves the same way, and isLegalNumbering does not change it: legal numbering redraws a counter in arabic, but it cannot give a level a counter it does not have.

A format is not tied to a list kind. It applies to whichever list names it, the way a Word numId points at a definition whatever the list looks like, so a glyph ladder on an <ol> draws glyphs and a counter ladder on a <ul> counts. generateNumberingFormatCss selects the attribute on ul and ol alike, so the preview and the export agree either way.

A list nested inside another of the same kind takes the outer list's ladder at its own depth, so one multilevel list keeps one definition.

Task lists

A task list renders as a ul, but it is not a level of a bullet ladder. A checklist keeps its checkboxes, and a bullet list nested inside one keeps its own numberingFormat.

A checklist also ends the chain, exactly as a list of the other kind does. The commands and the active… storage fields stop there, so a bullet list reached only through a checklist is outermost again and carries its own format.

Schema convention: outermost of its own kind

The numberingFormat attribute belongs on the outermost list of each kind. One definition declares all nesting levels for that entire multilevel list. OrderedListNumbering enforces this on parse: pasted HTML with data-numbering-format on an <ol> nested in another <ol>, or on a <ul> nested in another <ul>, has the attribute stripped.

A list of the other kind starts a ladder of its own, and it also ends the chain: a <ul> reached through an <ol> is outermost again, so it keeps a format of its own even when a further <ul> encloses the whole thing. The commands and the active… storage fields stop at that boundary too, so each targets the list the export and the preview actually draw.

All nesting levels under one outermost list share a single counter scope, and sub-levels restart when the parent advances, exactly as Word does.

Cycling rule

levels.length defines the cycle period. When a list nests deeper than levels.length - 1, depth N reuses levels[N % levels.length] for both DOCX export and the editor preview CSS. Supply nine levels to cover Word's full nesting depth without cycling; supply fewer when the deeper levels can naturally repeat the shallower entries.

Defaults match Word's standard

When numberIndent / textIndent are omitted, the exporter and the CSS helper both emit Word's standard multilevel-list defaults:

Marker alignment

alignment says where the marker sits in relation to numberIndent, the position its level gives it. Word justifies the marker against that single point, and the editor preview does the same.

Body text sits at textIndent whichever you pick, so a right-aligned marker leaves a wider gap between itself and the text than a left-aligned marker of the same width. Under 'left' and 'center', a marker wider than that gap pushes the body text of its own item further right; a right-aligned marker grows into the space before numberIndent instead and never moves the text. Either way only that one item's text moves: a list nested inside the item still starts at the position its own level gives it.

// Roman numerals get wider as they count up. Right alignment keeps their
// periods in one column and the text in another.
levels: [{ baseStyle: LevelFormat.UPPER_ROMAN, textTemplate: '%1.', alignment: 'right' }]

A suffix of 'space' or 'nothing' drops the padded marker column, so under 'left' and 'center' the body text follows the marker directly instead of waiting for textIndent. Combined with 'right' the marker still ends at numberIndent, which leaves the body text starting there as well.

Indents on a single item

A level places every item that belongs to it, but a single item can sit somewhere else. When the paragraph inside a list item carries an indent attribute, that item's marker and body text both move to it and the level's textIndent no longer applies to that item. A negative firstLineIndent on the same paragraph sets that item's gap between marker and text, in place of the level's distance from numberIndent to textIndent. A heading inside a list item is read the same way.

// Sits further right than its level puts it, with a 24px gap for the marker.
{
  type: 'listItem',
  content: [
    {
      type: 'paragraph',
      attrs: { indent: 96, firstLineIndent: -24 },
      content: [{ type: 'text', text: 'Positioned by the item, not by the level' }],
    },
  ],
}

Imported documents rely on this. The import writes each list paragraph's own Word indent onto the paragraph node as indent and firstLineIndent (see ConvertKit), so the items land where the source document drew them rather than on the level's ladder.

Conditions and limits:

• It applies only to a list that names a format the editor knows about, whether from formats or from registerNumberingFormats. Without one nothing positions the item, so the paragraph keeps rendering the indent itself as padding-left and text-indent, exactly as a paragraph outside a list does. The same holds when orderedListNumbering is off.
• A task list is not part of a numbering ladder, so an item in a checklist keeps its indent on the paragraph.
• A positive firstLineIndent is an ordinary first-line indent rather than a marker gap. It stays on the paragraph and indents the first line of the item's text.
• indentRight is left alone. A list positions the left edge of its items, not the right.
• A list item holding more than one block takes its position from the first block. The later blocks line up with it and do not render an indent of their own.
• The attributes stay on the node, so ExportDocx writes the same indent back out and a DOCX round trip keeps it.
• The editor positions the item and clears the paragraph's own padding-left and text-indent with an inline style. A rule of your own on that paragraph needs !important to take the block back.

generateNumberingFormatCss(formats, options?)

Returns the CSS text, and you choose how to inject it (a <style> tag, a CSS-in-JS layer, a stylesheet served by your build pipeline, etc.). The function is pure and dependency-free, safe to call at boot or whenever your registry changes.

generateNumberingFormatCss(formats, {
  scope: '.tiptap.ProseMirror', // default
  maxDepth: 9, // default
})

The generated CSS positions each list marker and its body text to match the absolute positions Word renders, including the stair-step indents at every nesting depth. Its rules set the left margin and padding on the list and on each of its items, so a lower-specificity rule of your own on a ul, ol or li inside a formatted list loses to them; vertical spacing is left to you. If you need to override anything for theming (dark mode, RTL, font scaling), wrap the output in your own selector or scope and rely on the cascade.

List items need box-sizing: border-box. The item rules pair a percentage width with a padding, so without it an item sitting to the right of its level widens past the list's right edge. ConvertKit's CSS reset sets it inside .tiptap, which covers the default scope; add it yourself if you inject this CSS anywhere else.

Every format emits both ul[data-numbering-format="…"] and ol[data-numbering-format="…"] rules, because a format applies to whichever list names it. Each chain then steps to the next depth with > li > through its own element (ul:not([data-type="taskList"]) or ol), so a checklist keeps its checkboxes, and a ladder stops at a list of the other kind rather than reaching through it.

Resolution rules

• A matched id renders every level of that multilevel list (including all nested lists of the same kind) using the corresponding definition.
• An unmatched id (typo, missing attribute, empty numberingFormats) keeps the default ladder for that list kind: plain 1. 2. 3. for an ordered list, the built-in glyph ladder for a bullet list.
• Sibling multilevel lists referencing the same format restart independently, each starting at its own startAt. A format with a linkedStyle on any level is the exception: it is one list for the whole document, so its lists continue each other.

Known limitations

Word features the exporter intentionally does not model:

See also

• Editor extension overview: base ExportDocx configuration.
• Styles: styleOverrides for paragraph styles, headings, list-paragraph styles.
• REST API: server-side conversion endpoint.