TipTap Pagination Plus

tiptap-pagination-plus extension that adds pagination support to your editor with table handling capabilities.

Demo

https://romikmakavana.me/tiptap-pagination/

Documentation

https://romikmakavana.me/tiptap

Installation

This package supports both TipTap v2 and TipTap v3. Choose the appropriate installation command based on your TipTap version:

For TipTap v3 (Recommended)

# Install latest version (defaults to TipTap v3)
npm install tiptap-pagination-plus

# Or explicitly install the tiptap-v3 tag
npm install tiptap-pagination-plus@tiptap-v3

For TipTap v2

npm install tiptap-pagination-plus@tiptap-v2

Note: Both versions are maintained and updated with each release. The latest tag (default) points to the TipTap v3 compatible version.

Usage

Basic Setup

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { 
  PaginationPlus,
  PAGE_SIZES
} from 'tiptap-pagination-plus'

const editor = new Editor({
  extensions: [
    StarterKit,
    PaginationPlus.configure({
      pageHeight: 800,        // Height of each page in pixels
      pageWidth: 789,         // Width of each page in pixels
      pageGap: 50,            // Gap between pages in pixels
      pageGapBorderSize: 1,   // Border size for page gaps
      pageGapBorderColor: "#e5e5e5", // Border color for page gaps
      pageBreakBackground: "#ffffff",  // Background color for page gaps
      footerRight: "Made with ❤️ by Romik",  // Custom HTML content to display in the footer right side
      footerLeft: "<p><strong>Contact Me :</strong><br>[email protected]</p>",         // Custom HTML content to display in the footer left side
      headerRight: "Page {page}",        // Custom HTML content to display in the header right side
      headerLeft: "<h1>Tiptap Pagination Plus</h1><p>by Romik Makavana</p>",         // Custom HTML content to display in the header left side
      marginTop: 20,          // Top margin for pages
      marginBottom: 20,       // Bottom margin for pages
      marginLeft: 50,         // Left margin for pages
      marginRight: 50,        // Right margin for pages
      contentMarginTop: 10,   // Top margin for content within pages
      contentMarginBottom: 10, // Bottom margin for content within pages
      // Optional: Per-page header/footer customization
      customHeader: {
        2: { headerLeft: "Page 2 Header", headerRight: "Page {page}" }
      },
      customFooter: {
        3: { footerLeft: "Page 3 Footer", footerRight: "Page {page}" }
      },
      // Optional: Click callbacks
      onHeaderClick: ({ event, pageNumber }) => {
        console.log(`Header clicked on page ${pageNumber}`)
      },
      onFooterClick: ({ event, pageNumber }) => {
        console.log(`Footer clicked on page ${pageNumber}`)
      },
    }),
  ],
})

// Example: Using predefined page sizes
editor.chain().focus().updatePageSize(PAGE_SIZES.A4).run()

// Example: Dynamic updates
editor.chain().focus()
  .updatePageHeight(1000)
  .updatePageWidth(600)
  .updateMargins({ top: 30, bottom: 30, left: 60, right: 60 })
  .updateHeaderContent('Document Title', 'Page {page}')
  .updateFooterContent('Confidential', 'Page {page} of {total}')
  .run()

Per-Page Header/Footer Customization

You can define different headers and footers for specific pages:

PaginationPlus.configure({
  // Default header/footer for all pages
  headerLeft: "Default Header",
  headerRight: "Page {page}",
  footerLeft: "Default Footer",
  footerRight: "Page {page}",
  
  // Custom header for page 2
  customHeader: {
    2: {
      headerLeft: "Chapter 2",
      headerRight: "Page {page}"
    }
  },
  
  // Custom footer for page 3
  customFooter: {
    3: {
      footerLeft: "Special Footer",
      footerRight: "Page {page}"
    }
  },
  
  // Handle header/footer clicks
  onHeaderClick: ({ event, pageNumber }) => {
    console.log(`Header clicked on page ${pageNumber}`)
    // Your custom logic here
  },
  onFooterClick: ({ event, pageNumber }) => {
    console.log(`Footer clicked on page ${pageNumber}`)
    // Your custom logic here
  }
})

Table Pagination

Key points for table pagination:

• Tables will automatically split across pages when they exceed the page height
• To split table across pages, you have to use these extensions
• List : TablePlus, TableRowPlus, TableCellPlus, TableHeaderPlus

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | pageHeight | number | 800 | Height of each page in pixels | | pageWidth | number | 789 | Width of each page in pixels | | pageGap | number | 50 | Gap between pages in pixels | | pageGapBorderSize | number | 1 | Border size for page gaps | | pageGapBorderColor | string | "#e5e5e5" | Border color for page gaps | | pageBreakBackground | string | "#ffffff" | Background color for page gaps | | footerRight | string | "{page}" | Custom HTML content to display in the footer right side (supports multiline and rich text) | | footerLeft | string | "" | Custom HTML content to display in the footer left side (supports multiline and rich text) | | headerRight | string | "" | Custom HTML content to display in the header right side (supports multiline and rich text) | | headerLeft | string | "" | Custom HTML content to display in the header left side (supports multiline and rich text) | | marginTop | number | 20 | Top margin for pages | | marginBottom | number | 20 | Bottom margin for pages | | marginLeft | number | 50 | Left margin for pages | | marginRight | number | 50 | Right margin for pages | | contentMarginTop | number | 10 | Top margin for content within pages | | contentMarginBottom | number | 10 | Bottom margin for content within pages | | customHeader | Record<number, { headerLeft: string, headerRight: string }> | {} | Custom headers for specific pages (page number as key) | | customFooter | Record<number, { footerLeft: string, footerRight: string }> | {} | Custom footers for specific pages (page number as key) | | onHeaderClick | (params: { event: MouseEvent, pageNumber: number }) => void | undefined | Callback function when header is clicked | | onFooterClick | (params: { event: MouseEvent, pageNumber: number }) => void | undefined | Callback function when footer is clicked |

Commands

The PaginationPlus extension provides several commands to dynamically update pagination settings:

| Command | Parameters | Description | |---------|------------|-------------| | updatePageBreakBackground | color: string | Update the background color of page gaps | | updatePageSize | size: PageSize | Update page dimensions and margins using predefined page sizes | | updatePageHeight | height: number | Update the height of pages in pixels | | updatePageWidth | width: number | Update the width of pages in pixels | | updatePageGap | gap: number | Update the gap between pages in pixels | | updateMargins | margins: { top: number, bottom: number, left: number, right: number } | Update page margins | | updateContentMargins | margins: { top: number, bottom: number } | Update content margins within pages | | updateHeaderContent | left: string, right: string, pageNumber?: number | Update header HTML content for left and right sides. If pageNumber is provided, updates header for that specific page only | | updateFooterContent | left: string, right: string, pageNumber?: number | Update footer HTML content for left and right sides. If pageNumber is provided, updates footer for that specific page only |

Using Commands

// Update page background color
editor.chain().focus().updatePageBreakBackground('#f0f0f0').run()

// Update page size using predefined sizes
import { PAGE_SIZES } from 'tiptap-pagination-plus'
editor.chain().focus().updatePageSize(PAGE_SIZES.A4).run()

// Update individual page dimensions
editor.chain().focus().updatePageHeight(1000).run()
editor.chain().focus().updatePageWidth(600).run()

// Update margins
editor.chain().focus().updateMargins({ 
  top: 30, 
  bottom: 30, 
  left: 60, 
  right: 60 
}).run()

// Update header and footer content (supports HTML, multiline, and rich text)
editor.chain().focus().updateHeaderContent('Document Title', 'Page {page}').run()
editor.chain().focus().updateFooterContent('Confidential', 'Page {page} of {total}').run()

// Update header/footer for specific page
editor.chain().focus().updateHeaderContent('Page 2 Title', 'Page {page}', 2).run()
editor.chain().focus().updateFooterContent('Page 3 Footer', 'Page {page}', 3).run()

// Example with HTML content in headers/footers
editor.chain().focus()
  .updateHeaderContent(
    '<strong>Company Name</strong><br><small>Department</small>', 
    '<span style="color: blue;">Page {page}</span>'
  )
  .updateFooterContent(
    '<em>Confidential</em>', 
    'Page {page}'
  )
  .run()

Predefined Page Sizes

The extension includes predefined page sizes that can be used with the updatePageSize command:

import { PAGE_SIZES } from 'tiptap-pagination-plus'

// Available page sizes:
PAGE_SIZES.A4      // A4 size (794x1123px)
PAGE_SIZES.A3      // A3 size (1123x1591px) 
PAGE_SIZES.A5      // A5 size (419x794px)
PAGE_SIZES.LETTER  // Letter size (818x1060px)
PAGE_SIZES.LEGAL   // Legal size (818x1404px)
PAGE_SIZES.TABLOID // Tabloid size (1060x1635px)

Features

• Automatic page breaks based on content height
• Page numbers in the footer
• Custom header/footer HTML content support with multiline and rich text
• Per-page header/footer customization - Define different headers and footers for specific pages
• Header/footer click callbacks - Handle user interactions with headers and footers
• Use {page} variable to display current page number in header/footer text
• Header and footer heights are automatically calculated based on content
• Table pagination with header preservation
• Responsive design
• Automatic page height calculation
• Support for nested content

License

MIT