---
title: "Custom page layouts in DOCX"
description: "Learn how to customize your DOCX (Word) page and margin sizes using the Export extension."
canonical_url: "https://tiptap.dev/docs/conversion/export/docx/page-layout"
---

# Custom page layouts in DOCX

Learn how to customize your DOCX (Word) page and margin sizes using the Export extension.

- **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start
  plan](https://cloud.tiptap.dev/v2/billing) in your account.
- **2. Install from private registry**

  To install this frontend extension, authenticate to Tiptap's private npm registry by following
  the [setup guide](https://tiptap.dev/docs/guides/pro-extensions.md).

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.

> **Interactive demo:** [ExportDocxCustomPageSize](https://embed-pro.tiptap.dev/preview/Extensions/ExportDocxCustomPageSize)

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

```js
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"`               |
| `header` | `PositiveUniversalMeasure` | Distance from the top edge of the page to the top of the header. Should be less than `top` so the header sits above body content.          | Word default `"1.25cm"` |
| `footer` | `PositiveUniversalMeasure` | Distance from the bottom edge of the page to the bottom of the footer. Should be less than `bottom` so the footer sits below body content. | Word default `"1.25cm"` |

> **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:**
>
> 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.

```js
ExportDocx.configure({
  onCompleteExport: (result) => {
    // Handle the exported file
  },
  pageMargins: {
    top: '2cm',
    bottom: '2cm',
    left: '1.5cm',
    right: '1.5cm',
    // Distance from the page edge to the header/footer
    header: '1cm',
    footer: '1cm',
  },
})
```

### Header and footer offsets

The `header` and `footer` properties on `pageMargins` control how far the running header and footer sit from the top and bottom edges of the page. They map directly to Word's "Header from top" and "Footer from bottom" settings under Page Setup → Layout.

For the header to render above the body, `header` should be smaller than `top`. The same relationship applies to `footer` and `bottom`. When omitted, Word applies its default of `1.25cm` (≈0.5in).

```js
ExportDocx.configure({
  onCompleteExport: (result) => {
    // Handle the exported file
  },
  pageMargins: {
    top: '2.5cm',
    bottom: '2.5cm',
    left: '2cm',
    right: '2cm',
    // Header sits 1cm from the top of the page (above the 2.5cm top margin)
    header: '1cm',
    // Footer sits 1cm from the bottom of the page (below the 2.5cm bottom margin)
    footer: '1cm',
  },
})
```

> **Auto-derived from the Pages extension:**
>
> When the [Pages extension](https://tiptap.dev/docs/editor/extensions/functionality/pages.md) is configured alongside
> `ExportDocx`, the `header` and `footer` offsets are automatically derived from the Pages storage
> values `headerTopMargin` and `footerBottomMargin`. Values you pass to `pageMargins` always take
> precedence — set `header` or `footer` explicitly to override the auto-derived values.

## Page background color

Use the `pageColor` option to set a background color for every page in the exported document.

### Accepted formats

| Format        | Example                                                   |
| ------------- | --------------------------------------------------------- |
| Hex (6-digit) | `"#ff0000"`, `"FF0000"`                                   |
| Hex (3-digit) | `"#f00"`                                                  |
| `rgb()`       | `"rgb(255, 0, 0)"`                                        |
| `rgba()`      | `"rgba(255, 0, 0, 0.5)"`                                  |
| Named color   | Common CSS named colors (`"red"`, `"blue"`, `"green"`, …) |

Pass `"transparent"` or leave `pageColor` undefined to omit the page color.

```js
ExportDocx.configure({
  onCompleteExport: (result) => {
    // Handle the exported file
  },
  pageColor: '#fff8dc', // cornsilk-style cream page
})
```

> **Word does not print page backgrounds by default:**
>
> In Word, the page background is shown on screen but is **not** included when printing or exporting
> to PDF. To make it visible in printed output or PDF exports, the reader must enable **File →
> Options → Display → Print background colors and images** in Word.

## Complete example

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

```js
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',
      },
      // Page background color
      pageColor: '#fff8dc',
    }),
    // 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:

```js
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:

```js
// 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',
  },
  pageColor: 'gray', // overrides the configured page color for this export
})
```

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