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

Pages uses standard CSS pixels — one inch is 96 pixels — so the dimensions below match what your browser will render. The Pages extension preserves fractional pixel values internally to avoid cumulative layout drift; the integers shown here are rounded for readability.

Each built-in format ships with default margins and sizes. To customize them, define your own format object — see Custom page formats below.

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),
    },
  },
})

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.
  },
})