Pages extension API reference

import type { Extensions, JSONContent } from '@tiptap/core'

type PagesHeaderFooter = string | JSONContent

type BuiltInPageFormat = 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'Tabloid'

interface CustomPageFormat {
  id: string
  width: number // pixels
  height: number // pixels
  margins: {
    top: number
    right: number
    bottom: number
    left: number
  }
}

type PageFormat = BuiltInPageFormat | CustomPageFormat

interface PagesOptions {
  /** Built-in format name or custom page format object. Default: 'A4'. */
  pageFormat: PageFormat

  /** Initial zoom level. Clamped to [0.25, 4]. Default: 1. */
  zoom?: number

  /** Default header content. Accepts a plain string, an HTML string, or Tiptap JSONContent.
   *  Supports `{page}` and `{total}` placeholders. Default: ''. */
  header: string | JSONContent

  /** Default footer content. Same shape as `header`. Default: ''. */
  footer: string | JSONContent

  /** Distance from the page top to where the header content starts (pixels).
   *  Defaults to 50% of the page top margin. */
  headerTopMargin?: number

  /** Distance from the footer content bottom to the page bottom (pixels).
   *  Defaults to 50% of the page bottom margin. */
  footerBottomMargin?: number

  /** Visual gap between pages (pixels). Default: 50. */
  pageGap?: number

  /** CSS color shown in the area between pages. Default: '#ffffff'. */
  pageGapBackground?: string

  /** Accent color applied to both header and footer editor overlays. Default: '#6366f1'. */
  accentColor?: string

  /** Accent color for the header overlay only. Defaults to the `accentColor` value. */
  headerAccentColor?: string

  /** Accent color for the footer overlay only. Defaults to the `accentColor` value. */
  footerAccentColor?: string

  /** Enable a different header and footer for the first page (Word's "Different First Page").
   *  Default: false. */
  differentFirstPage?: boolean

  /** First-page header content. Default: ''. */
  headerFirstPage?: PagesHeaderFooter

  /** First-page footer content. Default: ''. */
  footerFirstPage?: PagesHeaderFooter

  /** Enable different headers and footers on odd vs. even pages (Word's "Different Odd & Even Pages").
   *  Default: false. */
  differentOddEven?: boolean

  /** Odd-pages header content. Default: ''. */
  headerOdd?: PagesHeaderFooter

  /** Even-pages header content. Default: ''. */
  headerEven?: PagesHeaderFooter

  /** Odd-pages footer content. Default: ''. */
  footerOdd?: PagesHeaderFooter

  /** Even-pages footer content. Default: ''. */
  footerEven?: PagesHeaderFooter

  /** Whether double-clicking the header opens the inline editor overlay.
   *  When false, the overlay cannot be opened by users or by `openHeaderEditor`.
   *  Default: true. */
  editableHeader?: boolean

  /** Whether double-clicking the footer opens the inline editor overlay.
   *  When false, the overlay cannot be opened by users or by `openFooterEditor`.
   *  Default: true. */
  editableFooter?: boolean

  /** Enable a different first-page footer independently of `differentFirstPage`.
   *  Set automatically when `setDifferentFirstPage(true)` is called. */
  differentFirstPageFooter?: boolean

  /** Enable different odd/even footers independently of `differentOddEven`.
   *  Set automatically when `setDifferentOddEven(true)` is called. */
  differentOddEvenFooter?: boolean

  /** Extensions registered on the inner header/footer editors.
   *  Defaults to StarterKit; mirror your main editor's stack to keep schemas aligned. */
  headerFooterExtensions?: Extensions

  /** Called when `setPageFormat()` succeeds, or when configure() applies a new format. */
  onPageFormatChange?: (pageFormat: PageFormat) => void

  /** Called when `setZoom()` changes the zoom level. */
  onZoomChange?: (zoom: number) => void

  /** Optional — return true to keep the active header or footer editor open when the user
   *  double-clicks outside it. Applies to both. */
  onDblClickHeaderFooterPreventClose?: (event: MouseEvent) => boolean

  /** Like `onDblClickHeaderFooterPreventClose`, but only for the header overlay.
   *  Takes priority over the fallback when both are set. */
  onDblClickHeaderPreventClose?: (event: MouseEvent) => boolean

  /** Like `onDblClickHeaderFooterPreventClose`, but only for the footer overlay.
   *  Takes priority over the fallback when both are set. */
  onDblClickFooterPreventClose?: (event: MouseEvent) => boolean

  /** Rename the built-in `{page}` / `{total}` placeholder tokens, or pass
   *  `false` to disable substitution entirely. Default: undefined (use built-ins as-is). */
  placeholders?: false | { page?: string; total?: string }
}

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'
import { Pages } from '@tiptap-pro/extension-pages'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      pageFormat: 'A4',
      pageGap: 40,
      header: 'My Project',
      footer: 'Page {page} of {total}',
      pageGapBackground: '#f8f8f8',
    }),
  ],
})

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

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),
    },
  },
  onPageFormatChange: (pageFormat) => {
    console.log('Page format changed:', pageFormat.id)
  },
})

// Switch later
editor.commands.setPageFormat('Letter')