Word styles

Word documents use a style system where every paragraph and text run references a named style. The conversion pipeline resolves known paragraph style names to their Tiptap equivalents and falls back to plain paragraphs for everything else. The basedOn inheritance chain is used only for resolving run-level formatting.

Style resolution on import works identically via both the editor extension and REST API. For export, both paths support styleOverrides for customizing document-level style definitions. The extension additionally supports element overrides for per-element control that the REST API does not accept.

Recognized paragraph styles

The import service recognizes these paragraph style names (matched case-insensitively). When a paragraph's canonical style name matches one of them, it is converted to the corresponding Tiptap node:

Style inheritance

Word styles can inherit from other styles, similar to class inheritance. A custom style "Company Heading" might be based on "Heading 2", which is based on "Normal". This creates a chain of parent styles.

When importing, the converter walks this chain to collect text formatting (font, size, bold, italic, color) from each ancestor. However, the chain is not used to determine what type of node a paragraph becomes. Node type is based only on the paragraph's own style name matching a known pattern (the heading regex or "Quote").

This means a paragraph styled "Company Heading" becomes a plain paragraph node, even though it inherits heading formatting from "Heading 2". For the converter to produce a heading, the style name itself must match the heading pattern (e.g., "Heading 2").

Character styles

Word also supports character styles applied to individual text runs. The import does not preserve character style names. Instead, the resolved formatting (bold, italic, color, font size, etc.) is already reflected in the run's CSS properties at parse time and gets mapped to Tiptap marks.

This means a run styled "Strong" that resolves to bold produces a bold mark because the formatting includes font-weight: bold. The style name "Strong" itself is discarded.

Custom character styles with non-standard formatting (small caps, letter spacing, text effects) will lose that formatting if the renderer does not handle it.

Editor

There is no style extension in Tiptap. The editor does not have a concept of Word paragraph or character styles. Each content type has its own extension (Heading, Blockquote, CodeBlock, Paragraph), and formatting is handled through marks.

To bring the document's named-style typography (the visual definitions of Heading 1, Normal, Quote, etc.) into the editor as cascading CSS rather than per-node attributes, use the experimental CSS injection feature. It extracts the style catalog and either injects it as a scoped <style> tag or hands it to you as a cssStyles object. The 16 selectors and 11 properties it covers (typography only; no per-side borders, no letter spacing) are documented on that page.

Export

Each Tiptap node type maps to a fixed Word style:

Custom styles from the original document are not round-tripped. A paragraph imported from a "Legal Disclaimer" style will export as "Normal".

Default export style definitions

Customizing export styles

Override any default style or add new ones using styleOverrides. Your overrides are deep-merged with the defaults: matching id values merge recursively, new id values are appended.

ExportDocx.configure({
  styleOverrides: {
    paragraphStyles: [
      {
        id: 'Normal',
        name: 'Normal',
        run: {
          font: 'Calibri',
          size: 24,        // half-points (24 = 12pt)
        },
        paragraph: {
          spacing: {
            after: 200,    // twips (200 = 10pt)
            line: 276,     // 240ths of a line (276 = 1.15)
          },
        },
      },
    ],
  },
})