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

  /** Show the white fade gradient behind the edit-overlay toolbars (header, footer,
   *  footnotes, endnotes). Set to false for a flat, gradient-free toolbar. Default: true. */
  toolbarGradient?: boolean

  /** 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.
   *
   *  Accepts a static `Extensions` array, OR a callback that receives a
   *  `HeaderFooterExtensionsContext` per subtype (default / first / odd / even ×
   *  header / footer) and returns the extensions for that sub-editor. Use the
   *  callback form to attach `Collaboration` against the auto-computed Y field
   *  for each subtype. See Adding collaboration to Pages.
   *
   *  Defaults to ConvertKit; mirror your main editor's stack to keep schemas aligned. */
  headerFooterExtensions?: Extensions | ((ctx: HeaderFooterExtensionsContext) => 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 }

  /** Word-like footnotes. Disabled unless `enabled` is true. See Footnotes. */
  footnotes?: {
    /** Master switch. Default: false. */
    enabled?: boolean

    /** Extensions for the footnotes editor. Static array, or a callback that
     *  receives collaboration context (Y field + Y.Doc) for the footnotes
     *  editor. Defaults to ConvertKit. */
    extensions?: Extensions | ((ctx: FootnotesExtensionsContext) => Extensions)

    /** Seed footnote content keyed by note id (matches the DOCX import shape).
     *  Non-collaborative documents only. */
    initialContent?: Record<string, JSONContent>

    /** Render the Word-style separator rule above the footnotes area. Default: true. */
    separator?: boolean

    /** Maximum fraction of the page content height the footnotes area may
     *  occupy before clipping. Default: 0.5. */
    maxHeightRatio?: number

    /** Whether double-clicking the footnotes area opens the editor. Default: true. */
    editable?: boolean

    /** Accent color for footnote markers and the footnotes editor.
     *  Defaults to the `accentColor` value. */
    accentColor?: string
  }

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

  /** Word-like endnotes, collected at the end of the document. Disabled unless
   *  `enabled` is true. See Endnotes. */
  endnotes?: {
    /** Master switch. Default: false. */
    enabled?: boolean

    /** Extensions for the endnotes editor. Static array, or a callback that
     *  receives collaboration context (Y field + Y.Doc) for the endnotes
     *  editor. Defaults to ConvertKit. */
    extensions?: Extensions | ((ctx: EndnotesExtensionsContext) => Extensions)

    /** Seed endnote content keyed by note id (matches the DOCX import shape).
     *  Non-collaborative documents only. */
    initialContent?: Record<string, JSONContent>

    /** Render the Word-style separator rule above the endnotes list. Default: true. */
    separator?: boolean

    /** Whether double-clicking the endnotes list opens the editor. Default: true. */
    editable?: boolean

    /** Accent color for endnote markers and the endnotes editor.
     *  Defaults to the `accentColor` value. */
    accentColor?: string
  }

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

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')