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

# Custom page layouts in DOC

Learn how to customize your DOC page and margin sizes using the Export DOC 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 DOC Export extension 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.

> **Consider using DOCX instead:**
>
> The DOC format is a legacy format from Microsoft Word 97-2003. For modern use, we recommend
> exporting to [DOCX](https://tiptap.dev/docs/conversion/export/docx/page-layout.md) instead. Use DOC only when compatibility
> with older systems requires it.

## Page size configuration

Use the `pageSize` option to define custom page dimensions for your exported DOC 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 units:

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

### Configuration options

| Property | Type     | Description                                                                                          | Default    |
| -------- | -------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `width`  | `string` | The width of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px).  | `"21cm"`   |
| `height` | `string` | The height of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px). | `"29.7cm"` |

```js
import { ExportDoc } from '@tiptap-pro/extension-export-doc'

ExportDoc.configure({
  token: 'YOUR_TOKEN',
  appId: 'YOUR_APP_ID',
  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, top and bottom margins can accept negative values.

### Configuration options

| Property | Type     | Description                                                                                                                                  | Default    |
| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `top`    | `string` | The top margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px).                             | `"1cm"`    |
| `bottom` | `string` | The bottom margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px).                          | `"1cm"`    |
| `left`   | `string` | The left margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px).                                    | `"1cm"`    |
| `right`  | `string` | The right margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px).                                   | `"1cm"`    |
| `header` | `string` | Distance from the top edge of the page to the top of the header. Should be smaller than `top`. Must be a positive number with unit.          | `"1.25cm"` |
| `footer` | `string` | Distance from the bottom edge of the page to the bottom of the footer. Should be smaller than `bottom`. Must be a positive number with unit. | `"1.25cm"` |

```js
import { ExportDoc } from '@tiptap-pro/extension-export-doc'

ExportDoc.configure({
  token: 'YOUR_TOKEN',
  appId: 'YOUR_APP_ID',
  pageMargins: {
    top: '2cm',
    bottom: '2cm',
    left: '1.5cm',
    right: '1.5cm',
    // Distance from the page edge to the header/footer
    header: '1cm',
    footer: '1cm',
  },
})
```

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

> **Convert service requirement:**
>
> End-to-end support for `pageMargins.header` and `pageMargins.footer` requires the Tiptap convert
> service to be on a version that accepts these fields and ships an updated
> `@tiptap-pro/extension-export-docx`. On older convert service versions the values are ignored and
> Word's defaults are used.

## Page background color

Use the `pageColor` option to set a background color for every page of the exported DOC.

### Accepted formats

| Format        | Example                                                   |
| ------------- | --------------------------------------------------------- |
| Hex (6-digit) | `"#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
ExportDoc.configure({
  token: 'YOUR_TOKEN',
  appId: 'YOUR_APP_ID',
  pageColor: '#fff8dc',
})
```

> **Word does not print page backgrounds by default:**
>
> In Microsoft 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 DOC Export extension:

```js
import { ExportDoc } from '@tiptap-pro/extension-export-doc'

const editor = new Editor({
  extensions: [
    // Other extensions...
    ExportDoc.configure({
      token: 'YOUR_TOKEN',
      appId: 'YOUR_APP_ID',
      // 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...
  ],
})

// Export with custom layout
editor
  .chain()
  .exportDoc({
    onCompleteExport(result) {
      const url = URL.createObjectURL(result)
      const a = document.createElement('a')

      a.href = url
      a.download = 'custom-layout.doc'
      a.click()

      URL.revokeObjectURL(url)
    },
  })
  .run()
```

## Common page sizes

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

| Format      | Width    | Height   |
| ----------- | -------- | -------- |
| **A4**      | `21cm`   | `29.7cm` |
| **A5**      | `14.8cm` | `21cm`   |
| **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
ExportDoc.configure({
  token: 'YOUR_TOKEN',
  appId: 'YOUR_APP_ID',
  // 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.