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.
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 can create layouts that perfectly match your requirements, whether for specific print sizes, digital displays, or unique document formats.