Custom page layouts in DOCX

Available in Start planBeta

The DOCX Export extension now supports custom page sizes and margins, allowing you to create documents with precise layouts that match your requirements. Whether you need A5 pages, custom paper sizes, or specific margin configurations, you can configure these settings directly in the extension.

Page size configuration

Use the pageSize option to define custom page dimensions for your exported DOCX files. The page size configuration accepts width and height values with various measurement units.

Supported units

All page size and margin measurements support the following universal units:

Unit	Description
`cm`	Centimeters (default)
`in`	Inches
`pt`	Points
`pc`	Picas
`mm`	Millimeters
`px`	Pixels

Configuration options

Property	Type	Description	Default
`width`	`PositiveUniversalMeasure`	The width of the page. Must be positive	`"21.0cm"` (A4 width)
`height`	`PositiveUniversalMeasure`	The height of the page. Must be positive	`"29.7cm"` (A4 height)

PositiveUniversalMeasure

A PositiveUniversalMeasure is a string representing a positive length with a unit, such as "21cm", "8.5in", "148mm", "595pt", "50pc", or "800px". Supported units include centimeters (cm), millimeters (mm), inches (in), points (pt), picas (pc), and pixels (px). The value must be greater than zero. If you provide a value without a unit, centimeters (cm) will be used by default.

ExportDocx.configure({
  onCompleteExport: (result) => {
    // Handle the exported file
  },
  pageSize: {
    width: '14.8cm',    // A5 width
    height: '21cm',     // A5 height
  },
})

Page margins configuration

The pageMargins option allows you to set custom margins for all sides of your document pages. Unlike page sizes, margins can accept negative values if needed.

Configuration options

Property	Type	Description	Default
`top`	`UniversalMeasure`	Top margin of the page. Can be negative.	`"1.0cm"`
`bottom`	`UniversalMeasure`	Bottom margin of the page. Can be negative.	`"1.0cm"`
`left`	`PositiveUniversalMeasure`	Left margin of the page. Must be positive.	`"1.0cm"`
`right`	`PositiveUniversalMeasure`	Right margin of the page. Must be positive.	`"1.0cm"`

UniversalMeasure

A UniversalMeasure is a string representing a length with a unit, such as "21cm", "8.5in", "148mm", "595pt", "50pc", or "800px". Supported units include centimeters (cm), millimeters (mm), inches (in), points (pt), picas (pc), and pixels (px). The value can be positive or negative. If you provide a value without a unit, centimeters (cm) will be used by default.

PositiveUniversalMeasure

ExportDocx.configure({
  onCompleteExport: (result) => {
    // Handle the exported file
  },
  pageMargins: {
    top: '2cm',
    bottom: '2cm', 
    left: '1.5cm',
    right: '1.5cm',
  },
})

Complete example

Here's a complete example showing how to configure custom page layouts with the DOCX Export extension:

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

const editor = new Editor({
  extensions: [
    // Other extensions...
    ExportDocx.configure({
      onCompleteExport: result => {
        // Create and download the DOCX file
        const blob = new Blob([result], {
          type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
        })
        const url = URL.createObjectURL(blob)
        const a = document.createElement('a')
        
        a.href = url
        a.download = 'custom-layout.docx'
        a.click()
        URL.revokeObjectURL(url)
      },
      // A5 page size
      pageSize: {
        width: '14.8cm',
        height: '21cm',
      },
      // Custom margins
      pageMargins: {
        top: '2cm',
        bottom: '2cm',
        left: '2cm',
        right: '2cm',
      },
    }),
    // Other extensions...
  ],
})

Common page sizes

Here are some common page sizes you can use as reference:

Format	Width	Height
A4	`21.0cm`	`29.7cm`
A5	`14.8cm`	`21.0cm`
Letter	`8.5in`	`11in`
Legal	`8.5in`	`14in`
Tabloid	`11in`	`17in`

Different measurement units

You can mix and match different units based on your preference:

ExportDocx.configure({
  onCompleteExport: (result) => {
    // Handle the exported file
  },
  // US Letter size in inches
  pageSize: {
    width: '8.5in',
    height: '11in',
  },
  // Margins in different units
  pageMargins: {
    top: '0.75in',    // Inches
    bottom: '72pt',   // Points (1 inch = 72 points)
    left: '2cm',      // Centimeters
    right: '20mm',    // Millimeters
  },
})

Unit consistency

While you can mix different units, it's generally recommended to use consistent units throughout your configuration for better maintainability and clarity.

Runtime configuration

You can also override page layout settings when calling the export command directly:

// Export with different page layout settings
editor.commands.exportDocx({
  onCompleteExport: (result) => {
    // Handle the exported file
  },
  pageSize: {
    width: '11in',    // Tabloid width
    height: '17in',   // Tabloid height
  },
  pageMargins: {
    top: '0.5in',
    bottom: '0.5in',
    left: '0.75in',
    right: '0.75in',
  },
})

This allows you to create different export configurations for different use cases without reconfiguring the entire extension.