Customize ordered list numbering 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>. Lists with a matching id export with the corresponding definition; lists without one export as plain 1. 2. 3..

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 two things:

ConvertKit.configure({
  orderedListNumbering: {
    // The format id new ordered lists start with. Defaults to `null` (plain `1. 2. 3.`).
    defaultFormat: 'outline',
    // 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.

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.

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

const activeFormatId = editor.storage.orderedListNumbering.activeNumberingFormat
// a format id, or `null` when the selection is not inside an ordered list

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
}

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.

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

Schema convention — outermost only

The numberingFormat attribute belongs on the outermost <ol> only. One definition declares all nesting levels for the entire multilevel list. OrderedListNumbering enforces this on parse — pasted HTML with data-numbering-format on a nested <ol> has the attribute stripped.

All nesting levels under one outermost <ol> 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:

generateNumberingFormatCss(formats, options?)

Returns the CSS text — 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. 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.

Resolution rules

• A matched id renders every level of that multilevel list — including all nested <ol>s — using the corresponding definition.
• An unmatched id (typo, missing attribute, empty numberingFormats) renders as plain 1. 2. 3. numbering.
• Sibling multilevel lists referencing the same format restart independently — each starts at its own startAt.

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.