Tiptap Docs

Pages

Available in Team planBeta

Tiptap Pages is a paginated editing layer for Tiptap. It adds page boundaries, page formats, headers, footers, page breaks, and zoom on top of any Tiptap editor — so your reader can author a report, a letter, a contract, or a book the way they would in a word processor.

Pro package

Pages is a Pro package included with Tiptap subscriptions. Before installation, set up access to Tiptap's private NPM registry.

What this does

  • Paginated layout — content flows across visual pages of a chosen format (A4, Letter, custom).
  • Page formats and margins — built-in formats with sensible defaults, plus full control via custom format objects.
  • Headers and footers — static text, HTML strings, or Tiptap JSON; with {page} and {total} placeholders; and with separate slots for first page or odd/even pages, mirroring Word.
  • Edit-in-place — double-click a header or footer to open a fully featured Tiptap editor in the overlay.
  • Zoom — visual zoom in [0.25, 4] that does not affect document content or export.
  • Page breaks — insert explicit breaks via the PageBreak extension, or let Pages handle automatic breaks.

What you install with it

Pages does not ship a node and mark schema. To use it you also install:

  • @tiptap-pro/extension-convert-kit — the canonical editor kit for Conversion and Pages workflows. ConvertKit registers a DOCX-aware schema (paragraphs, headings, lists, images, marks).
  • @tiptap-pro/extension-pages-tablekit — pagination-safe tables. Required, because ConvertKit's bundled tables are not designed to paginate.
npm install @tiptap-pro/extension-convert-kit \
            @tiptap-pro/extension-pages-tablekit \
            @tiptap-pro/extension-pages
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',
      header: 'My document',
      footer: 'Page {page} of {total}',
    }),
  ],
})

See the install guide for the full walkthrough.

What works

  • Built-in page formats: A4, A3, A5, Letter, Legal, Tabloid; plus custom formats with arbitrary dimensions and margins.
  • Header and footer content as plain text, HTML, or Tiptap JSON, with {page} / {total} placeholders.
  • Different headers and footers for the first page and for odd/even pages, like Word.
  • Live editing of headers and footers in dedicated overlays. They participate in collaboration alongside the main document — see Adding collaboration to Pages.
  • Programmatic control: open or close a header/footer editor for a specific page, react to page format changes, react to zoom changes.
  • Lock or unlock header/footer editing per overlay, at config-time or runtime via editableHeader / editableFooter options and setHeaderEditable / setFooterEditable commands.
  • Pagination-safe tables via PagesTableKit. Tables shrink proportionally to fit the page, exact-height rows clip, declared widths are preserved.
  • Round-trip with Tiptap Conversion: imported DOCX headers and footers are auto-applied; exported DOCX, PDF, ODT, EPUB carry headers, footers, and pagination through.

What won't work

These are real, documented limits — not bugs. If your workflow depends on any of them, treat the constraint as a design boundary.

  • Non-splittable blocks larger than a page cause an infinite layout loop. This is the single most important limitation to know about before adopting Pages. Table rows, figures, positioned containers, and most other Block Formatting Context (BFC) elements cannot be split across pages — the layout can only move the whole block to the next page. If the block is taller than the page itself, it can't fit there either, and the layout keeps trying to move it forward and never stabilises. The result is an unresponsive editor. This is a hard limit of the current approach to splitting content between pages, not a near-term roadmap item. See Limitations for the full treatment, including how to detect and prevent it. The table-specific case lives in PagesTableKit's Known issues.
  • No per-page styling, no page templates. Every page uses the same layout and visual styling.
  • No browser-print integration. Use the Conversion extensions and REST endpoints for print-ready output.

What to expect

  • Beta surface. Pages is in active development. Pin exact package versions if you depend on it; minor versions may introduce breaking changes.
  • Pixel values are CSS pixels. All dimensions in the API correspond to standard browser CSS pixels (one inch is 96 px). The cmToPixels and inchToPixels utilities round-trip cleanly so you can author in real-world units.
  • Edit-in-place that participates in collaboration. Double-clicking a header or footer opens a full Tiptap editor, and that editor is part of the same collaborative session as the main document.

What not to expect

  • Pages is not a full editor by itself — it's a layout overlay. Pair it with ConvertKit for the document schema and TableKit from extension-pages-tablekit for tables.
  • Pages does not implement DOCX import or export by itself. It's a rendering target. For round-trip with files, pair it with the Conversion extensions: import via extension-import-docx, export via extension-export-docx, extension-export-pdf, etc.
  • Pages does not own table rendering for paginated content. Use PagesTableKit, not the open-source @tiptap/extension-table or ConvertKit's built-in tables.

Pair with Conversion

The two products were built to work together:

Next upInstall