Export custom styles to .docx

When exporting to DOCX, you can define custom styles that will be applied to the exported document. This is useful when you want to have a consistent look and feel across your documents.

// Import the ExportDocx extension
import { ExportDocx } from '@tiptap-pro/extension-export-docx'

const editor = new Editor({
  extensions: [
    // Other extensions ...
    ExportDocx.configure({
      onCompleteExport: (result: string | Buffer<ArrayBufferLike> | Blob | Stream) => {}, // required
      styleOverrides: { // Style overrides
        paragraphStyles: [
          // Heading 1 style override
          {
            id: 'Heading1',
            name: 'Heading 1',
            basedOn: 'Normal',
            next: 'Normal',
            quickFormat: true,
            run: {
              font: 'Aptos',
              size: pointsToHalfPoints(16),
              bold: true,
              color: 'FF0000',
            },
            paragraph: {
              spacing: {
                before: pointsToTwips(12),
                after: pointsToTwips(6),
                line: lineHeightToDocx(1.15),
              },
            },
          },
        ]
      }
    }),
    // Other extensions ...
  ],
  // Other editor settings ...
})

In the example above ☝️ we are exporting a document with a custom Heading 1 style. The style is based on the Normal style, has a red color, and uses the Aptos font. The spacing before the paragraph is set to 12pt, and 6pt after it. The line height is set to 1.15.

You can also create custom styling for other elements like Heading 2, Heading 3, List Bullet, List Number, etc. The paragraphStyles array accepts an array of objects with the following properties:

Paragraph style object

A paragraphStyle object accepts the following properties:

Property	Type	Description
`id`	`string`	Unique identifier for the style.
`name`	`string`	Display name of the style.
`basedOn`	`string`	The base style (e.g., `Normal`) that this style builds upon.
`next`	`string`	The style to apply to the following paragraph.
`quickFormat`	`boolean`	If `true`, the style appears in the quick format menu.
`run`	`object`	Defines text formatting (font, size, color, bold, etc.).
`paragraph`	`object`	Defines paragraph formatting (spacing, alignment, borders, etc.).

Run style properties

The run object from a paragraphStyle accepts the following properties:

Property	Type	Description
`font`	`string`	Font family for the text.
`size`	`number`	Font size in half-points (e.g., 16 points = 32).
`bold`	`boolean`	Set to `true` to make the text bold.
`italics`	`boolean`	Set to `true` for italic text.
`color`	`string`	Text color in hex format (e.g., `FF0000` for red. No # necessary).
`kern`	`number`	Adjusts the spacing between characters in points.
`effect`		Special text effects that can be applied.
`emphasisMark`	`string`	Emphasis marks that appear above or below text. (like `dot`)
`smallCaps`	`boolean`	Set to `true` to display text in small capitals.
`allCaps`	`boolean`	Set to `true` to display text in all uppercase.
`strike`	`boolean`	Set to `true` to apply a single strikethrough.
`doubleStrike`	`boolean`	Set to `true` to apply a double strikethrough.
`subScript`	`boolean`	Set to `true` for subscript text.
`superScript`	`boolean`	Set to `true` for superscript text.
`highlight`		Highlight color (predefined values).
`characterSpacing`	`number`	Adjusts spacing between characters in TWIPs (…we know, TWIPs right?
`shading`	`object`	Applies background shading to the text.
`shading` → `type`	`ShadingType`	The shading type (`clear`, `solid`, `horizontalStripe`, etc.).
`shading` → `fill`	`string`	The shading fill color in hex format (e.g., `FF0000` for red).
`shading` → `color`	`string`	The shading color in hex format (e.g., `FF0000` for red).
`scale`	`number`	Adjusts the width of the text (as a percentage).
`underline`	`object`	Underline style, specify properties like `color` and `type` or and empty object for a simple underline.
`underline` → `color`	`string`	Underline color in hex format (e.g., `FF0000` for red. No # necessary).
`underline` → `type`	`UnderlineType`	The underline type (`single`, `double` or `thick`)

For more advanced styling options and detailed usage you can refer to the IRunStylePropertiesOptions type exposed from our package, or refer to the docx documentation.

Paragraph style properties

The paragraph object from a paragraphStyle accepts the following properties:

Property	Type	Description
`spacing`	`object`	Controls spacing: properties like `before`, `after`, and `line`.
`alignment`	`string`	Sets paragraph alignment (`left`, `center`, `right`, or `justify`).
`border`	`object`	Defines borders around the paragraph (top, bottom, left, right).
`shading`	`object`	Applies background shading to the paragraph.
`indent`	`object`	Specifies indentation (first line, hanging, left, right).
`contextualSpacing`	`boolean`	If `true`, reduces spacing between paragraphs of the same style.
`keepNext`	`boolean`	Keeps this paragraph on the same page as the next.
`keepLines`	`boolean`	Keeps all lines of the paragraph together on the same page.
`outlineLevel`	`number`	Sets the outline level for document organization (typically 1–9).
`thematicBreak`	`number`	Adds a horizontal line break when set to `true`.
`rightTabStop`	`number`	Sets the position of the right tab stop in twips.
`leftTabStop`	`number`	Sets the position of the left tab stop in twips.
`numbering`	`object`	Controls numbering settings (e.g., reference, level, custom formatting).
`numbering` → `reference`	`string`	The numbering style reference ID.
`numbering` → `level`	`number`	The level in the numbering hierarchy (0-based).
`spacing`	`object`	Controls the spacing of the paragraph.
`spacing` → `before`	`number`	Space before the paragraph.
`spacing` → `after`	`number`	Space after the paragraph.
`spacing` → `line`	`number`	Line spacing within the paragraph.
`spacing` → `lineRule`	`LineRuleType`	Defines how the line spacing is calculated.

For more advanced styling options and detailed usage you can refer to the IParagraphStylePropertiesOptions type exposed from our package, or refer to the docx documentation.

Tiptap's export default styles

Tiptap offers a sensible default styling for the exported document, but you can override these styles by providing your own custom styles. This allows you to create a consistent look and feel across your documents.

{
  paragraphStyles: [
    // Normal style (default for most paragraphs)
    {
      id: 'Normal',
      name: 'Normal',
      run: {
        font: 'Aptos',
        size: pointsToHalfPoints(11),
      },
      paragraph: {
        spacing: {
          before: 0,
          after: pointsToTwips(10),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // List Paragraph style (used for bullets and numbering)
    {
      id: 'ListParagraph',
      name: 'List Paragraph',
      basedOn: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos',
        size: pointsToHalfPoints(11),
      },
      paragraph: {
        spacing: {
          before: 0,
          after: pointsToTwips(2),
          line: lineHeightToDocx(1),
        },
      },
    },
    // Heading 1 style
    {
      id: 'Heading1',
      name: 'Heading 1',
      basedOn: 'Normal',
      next: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos Light',
        size: pointsToHalfPoints(16),
        bold: true,
        color: '2E74B5',
      },
      paragraph: {
        spacing: {
          before: pointsToTwips(12),
          after: pointsToTwips(6),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Heading 2 style
    {
      id: 'Heading2',
      name: 'Heading 2',
      basedOn: 'Normal',
      next: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos Light',
        size: pointsToHalfPoints(14),
        bold: true,
        color: '2E74B5',
      },
      paragraph: {
        spacing: {
          before: pointsToTwips(12),
          after: pointsToTwips(6),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Heading 3 style
    {
      id: 'Heading3',
      name: 'Heading 3',
      basedOn: 'Normal',
      next: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos',
        size: pointsToHalfPoints(13),
        bold: true,
        color: '2E74B5',
      },
      paragraph: {
        spacing: {
          before: pointsToTwips(12),
          after: pointsToTwips(6),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Heading 4 style
    {
      id: 'Heading4',
      name: 'Heading 4',
      basedOn: 'Normal',
      next: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos',
        size: pointsToHalfPoints(12),
        bold: true,
        color: '2E74B5',
      },
      paragraph: {
        spacing: {
          before: pointsToTwips(12),
          after: pointsToTwips(6),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Heading 5 style
    {
      id: 'Heading5',
      name: 'Heading 5',
      basedOn: 'Normal',
      next: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos',
        size: pointsToHalfPoints(11),
        bold: true,
        color: '2E74B5',
      },
      paragraph: {
        spacing: {
          before: pointsToTwips(12),
          after: pointsToTwips(6),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Title style
    {
      id: 'Title',
      name: 'Title',
      basedOn: 'Normal',
      next: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos Light',
        size: pointsToHalfPoints(22),
        bold: true,
        color: '000000',
      },
      paragraph: {
        alignment: AlignmentType.CENTER,
        spacing: {
          before: 0,
          after: 0,
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Subtitle style
    {
      id: 'Subtitle',
      name: 'Subtitle',
      basedOn: 'Normal',
      next: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos Light',
        size: pointsToHalfPoints(16),
        italics: true,
        color: '666666',
      },
      paragraph: {
        alignment: AlignmentType.CENTER,
        spacing: {
          before: 0,
          after: 0,
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Quote style (typically for indented, italic text)
    {
      id: 'Quote',
      name: 'Quote',
      basedOn: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos',
        italics: true,
      },
      paragraph: {
        alignment: AlignmentType.CENTER,
        spacing: {
          before: pointsToTwips(10),
          after: pointsToTwips(10),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // Intense Quote style (more pronounced indentation)
    {
      id: 'IntenseQuote',
      name: 'Intense Quote',
      basedOn: 'Normal',
      quickFormat: true,
      run: {
        font: 'Aptos',
        italics: true,
        color: '444444',
      },
      paragraph: {
        alignment: AlignmentType.CENTER,
        spacing: {
          before: pointsToTwips(10),
          after: pointsToTwips(10),
          line: lineHeightToDocx(1.15),
        },
      },
    },
    // No Spacing style (no extra space before or after paragraphs)
    {
      id: 'NoSpacing',
      name: 'No Spacing',
      basedOn: 'Normal',
      quickFormat: true,
      paragraph: {
        spacing: {
          before: 0,
          after: 0,
          line: lineHeightToDocx(1),
        },
      },
    },
    // Hyperlink style
    {
      id: 'Hyperlink',
      name: 'Hyperlink',
      basedOn: 'Normal',
      run: {
        color: '0563C1',
        underline: {
          type: 'single',
        },
      },
    },
  ],
}