Pages extension API reference
interface PagesOptions {
/**
* Page format that determines page size and margins.
* Can be a built-in format name or a custom page format object.
* Built-in formats: A4, A3, A5, Letter, Legal, Tabloid
* @default 'A4'
*/
pageFormat: 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'Tabloid' | PageFormat
/**
* Height of the page header in pixels.
* @default 50
*/
headerHeight?: number
/**
* Height of the page footer in pixels.
* @default 50
*/
footerHeight?: number
/**
* Gap between pages in pixels.
* @default 50
*/
pageGap?: number
/**
* Header content for every page. Can be a string (with tokens) or a function.
* @default ''
*/
header?: string | ((page: number, total: number) => string)
/**
* Footer content for every page. Can be a string (with tokens) or a function.
* @default '
*/
footer?: string | ((page: number, total: number) => string)
/**
* Background color for the page break area.
* @default undefined
*/
pageBreakBackground?: string
/**
* Callback function called when the page format changes.
* Receives the new page format as an argument.
* @default () => {}
*/
onPageFormatChange?: (pageFormat: PageFormat) => void
}
interface PageFormat {
name: string
width: number // Width in pixels
height: number // Height in pixels
margins: {
top: number // Margin in pixels
right: number // Margin in pixels
bottom: number // Margin in pixels
left: number // Margin in pixels
}
}
Option | Type / Values | Default | Description |
---|---|---|---|
pageFormat | string | PageFormat | 'A4' | Built-in format name or custom page format object |
headerHeight | number (px) | 50 | Header height in pixels |
footerHeight | number (px) | 50 | Footer height in pixels |
pageGap | number (px) | 50 | Gap between pages in pixels |
header | string | fn | '' | Header content; string (supports {page} /{total} ) or (pageNumber, totalPages) => string |
footer | string | fn | '{page}' | Footer content; string (supports {page} /{total} ) or (pageNumber, totalPages) => string |
pageBreakBackground | string (CSS color) | undefined | Background color for page breaks |
onPageFormatChange | fn | () => {} | Callback when page format changes; receives new PageFormat |
Example usage
Basic configuration with built-in format
import { Pages } from '@tiptap-pro/extension-pages'
const editor = new Editor({
extensions: [
Pages.configure({
pageFormat: 'A4',
headerHeight: 60,
footerHeight: 40,
pageGap: 40,
header: 'My Project',
footer: (page, total) => `Page ${page} of ${total}`,
pageBreakBackground: '#f8f8f8',
}),
],
})
Custom page format configuration
import { Pages } from '@tiptap-pro/extension-pages'
const editor = new Editor({
extensions: [
Pages.configure({
pageFormat: {
name: 'Custom Format',
width: 600,
height: 800,
margins: {
top: 40,
right: 30,
bottom: 40,
left: 30,
},
},
header: 'Custom Document',
footer: '{page} / {total}',
onPageFormatChange: (pageFormat) => {
console.log('Page format changed:', pageFormat.name)
// Save user preference, update UI, etc.
},
}),
],
})
Available commands
The Pages extension provides the following commands:
Command | Parameters | Description |
---|---|---|
setPageFormat | pageFormat: PageFormat | Changes the page format programmatically |
Command usage
// Change to built-in format
editor.commands.setPageFormat('Letter')
// Change to custom format
editor.commands.setPageFormat({
id: 'wide-page-format',
width: 1000, // px
height: 700, // px
margins: { top: 20, right: 20, bottom: 20, left: 20 } // px
})
Note
The header
and footer
options accept either a string (with tokens {page}
and {total}
) or a function (page, total) => string
for dynamic content.