Page format

The pageFormat option controls the size and margins of each page in your document. This helps your content look consistent and professional, especially when printing or exporting.

Built-in formats

Name	Dimensions (cm)	Dimensions (px @ 96dpi)	Margins (cm: top, right, bottom, left)
`A4`	21.0 × 29.7	794 × 1123	2.5, 2.0, 2.5, 2.0
`A3`	29.7 × 42.0	1123 × 1587	2.5, 2.0, 2.5, 2.0
`A5`	14.8 × 21.0	559 × 794	2.0, 1.5, 2.0, 1.5
`Letter`	21.59 × 27.94	816 × 1063	2.54, 2.54, 2.54, 2.54
`Legal`	21.59 × 35.56	816 × 1346	2.54, 2.54, 2.54, 2.54
`Tabloid`	27.94 × 43.18	1063 × 1634	2.54, 2.54, 2.54, 2.54

Each format comes with sensible default margins and sizes. These are not user-configurable yet.

Using built-in formats

Pages.configure({
  pageFormat: 'Letter',
})

Using constants for built-in formats

You can also import the built-in page format constants for better autocompletion and type safety:

import { PAGE_FORMATS } from '@tiptap-pro/extension-pages'

Pages.configure({
  pageFormat: PAGE_FORMATS.Letter,
})

This is equivalent to using the string literal:

Pages.configure({
  pageFormat: 'Letter',
})

Use whichever approach you prefer.

Custom page formats

You can define custom page formats by providing a page format object with your desired dimensions and margins:

Pages.configure({
  pageFormat: {
    id: 'custom-page-format',
    width: cmToPixels(22.94),
    height: cmToPixels(35.18),
    margins: {
      top: cmToPixels(2.54),
      right: cmToPixels(2.54),
      bottom: cmToPixels(2.54),
      left: cmToPixels(2.54),
    },
  },
})

Tip

In this example, we use the cmToPixels utility to define our page dimensions and margins in centimeters, making it easy to work with familiar print measurements. Learn more about cmToPixels in the utility reference.

Page margins

Page margins can be customized by using a custom page format. Built-in formats come with fixed margins, but you can create your own format with custom margins:

Pages.configure({
  pageFormat: {
    id: 'custom-layout',
    width: 794,   // px
    height: 1123, // px
    margins: {
      top: 60,    // px
      right: 40,  // px
      bottom: 60, // px
      left: 40,   // px
    },
  },
})

Changing page format programmatically

Use the setPageFormat command to change the page format after the editor is initialized:

// Switch to a built-in format
editor.commands.setPageFormat('A4')

// Switch to a custom format
editor.commands.setPageFormat({
  id: 'custom-wide-page-format',
  width: cmToPixels(27.94),
  height: cmToPixels(43.18),
  margins: {
    top: cmToPixels(2.54),
    right: cmToPixels(2.54),
    bottom: cmToPixels(2.54),
    left: cmToPixels(2.54),
  },
})

Listening to page format changes

Use the onPageFormatChange callback to react when the page format is changed:

Pages.configure({
  pageFormat: 'A4',
  onPageFormatChange: (pageFormat) => {
    console.log('Page format changed to:', pageFormat)
    // Update your UI, save the preference, etc.
  },
})

Flexibility

With custom page formats, you have full control over both page dimensions and margins to create the exact layout you need.