---
title: "Pages"
description: "Turn your Tiptap editor into a paginated, document-style layout with headers, footers, page formats, and zoom."
canonical_url: "https://tiptap.dev/docs/pages/getting-started/overview"
---

# Pages

Turn your Tiptap editor into a paginated, document-style layout with headers, footers, page formats, and zoom.

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.

> **Interactive demo:** [Pages](https://embed-pro.tiptap.dev/preview/Extensions/Pages)

> **Pro package:**
>
> Pages is a Pro package included with [Tiptap subscriptions](https://tiptap.dev/pricing). Before
> installation, set up [access to Tiptap's private NPM registry](https://tiptap.dev/docs/guides/pro-extensions.md).

## 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](https://tiptap.dev/docs/pages/core-concepts/page-break-node.md), 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.

```bash
npm install @tiptap-pro/extension-convert-kit \
            @tiptap-pro/extension-pages-tablekit \
            @tiptap-pro/extension-pages
```

```ts
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](https://tiptap.dev/docs/pages/getting-started/install.md) 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](https://tiptap.dev/docs/pages/guides/collaboration-with-pages.md).
- 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](https://tiptap.dev/docs/pages/guides/pages-tablekit.md). 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](https://tiptap.dev/docs/pages/core-concepts/limitations.md#oversized-non-splittable-blocks-cause-an-infinite-layout-loop) for the full treatment, including how to detect and prevent it. The table-specific case lives in [PagesTableKit's Known issues](https://tiptap.dev/docs/pages/guides/pages-tablekit.md#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](https://tiptap.dev/docs/conversion/getting-started/overview.md) 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](https://tiptap.dev/docs/conversion/getting-started/overview.md) 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](https://tiptap.dev/docs/pages/guides/pages-tablekit.md), not the open-source `@tiptap/extension-table` or ConvertKit's built-in tables.

## Pair with Conversion

The two products were built to work together:

- [Conversion overview](https://tiptap.dev/docs/conversion/getting-started/overview.md) — the import/export pipeline.
- [Import DOCX](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md) — bring Word documents into your paginated editor (headers and footers auto-apply).
- [Export DOCX](https://tiptap.dev/docs/conversion/export/docx/editor-extension.md) — export paginated content with headers and footers preserved.
- [Export PDF](https://tiptap.dev/docs/conversion/export/pdf/editor-extension.md) — render the paginated layout to a PDF.
- [From zero to print-ready](https://tiptap.dev/docs/pages/guides/zero-to-print-ready.md) — full end-to-end walkthrough.

## Related

- [Install](https://tiptap.dev/docs/pages/getting-started/install.md)
- [API reference](https://tiptap.dev/docs/pages/core-concepts/options.md)
- [Page format](https://tiptap.dev/docs/pages/core-concepts/page-format.md) · [Page header and footer](https://tiptap.dev/docs/pages/core-concepts/page-header-footer.md) · [Page gap](https://tiptap.dev/docs/pages/core-concepts/page-gap.md) · [Zoom](https://tiptap.dev/docs/pages/core-concepts/zoom.md)
- [PagesTableKit](https://tiptap.dev/docs/pages/guides/pages-tablekit.md) · [PageKit](https://tiptap.dev/docs/pages/guides/pagekit-usage.md)
- [Limitations](https://tiptap.dev/docs/pages/core-concepts/limitations.md)