PageBreak node

The PageBreak extension (@tiptap-pro/extension-pagebreak) adds a block-level atom node for inserting explicit page breaks into your document. It works in two modes depending on whether the Pages extension is present.

Two modes of operation

Standard mode (without Pages)

When used without the Pages extension, PageBreak renders as a visual dashed horizontal rule with a centered label. This provides a clear visual indicator of where a page break occurs, useful for content that will eventually be printed or exported.

Pages mode (with Pages)

When the Pages extension is detected, PageBreak automatically switches behavior. Instead of a visual divider, it renders an invisible filler element that expands to fill the remaining height of the current page, pushing all subsequent content to the next page. This mimics Microsoft Word's page break behavior.

Automatic detection

PageBreak detects the Pages extension automatically; no extra configuration is needed. Just register both extensions and the correct mode is applied.

Install

npm install @tiptap-pro/extension-pagebreak

Basic usage

Use PageBreak as a standalone extension for a visual page break indicator. Pair it with ConvertKit for the editor schema:

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { PageBreak } from '@tiptap-pro/extension-pagebreak'

const editor = new Editor({
  extensions: [ConvertKit, PageBreak],
})

Usage with Pages

When both PageBreak and Pages are registered, PageBreak automatically operates in Pages mode. Use the standard Pages stack — ConvertKit + TableKit + Pages — and add PageBreak alongside:

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'
import { PageBreak }  from '@tiptap-pro/extension-pagebreak'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({ pageFormat: 'A4' }),
    PageBreak,
  ],
})

Usage via PageKit

PageBreak is included by default when using PageKit. To disable it, pass pagebreak: false:

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

PageKit.configure({
  pages: { pageFormat: 'A4' },
  pagebreak: false, // Disable PageBreak
})

Options

Option	Type	Default	Description
`label`	`string`	`'Page break'`	Label text rendered inside the page break visual hint (standard mode only)
`nextNodeType`	`string`	`'paragraph'`	Node type inserted after a page break when placed at the end of the document
`HTMLAttributes`	`Record<string, unknown>`	`{}`	Custom HTML attributes applied to the page break node

Example configuration

PageBreak.configure({
  label: 'New page',
  nextNodeType: 'heading',
})

Commands

insertPageBreak

Inserts a page break at the current selection. After insertion, the cursor is placed in the node that follows the break.

editor.commands.insertPageBreak()

// Or in a chain
editor.chain().focus().insertPageBreak().run()

Keyboard shortcuts

Shortcut	Command
`Mod-Enter`	Insert a page break

This matches the Microsoft Word convention for inserting page breaks.

Shortcut priority

ConvertKit's bundled HardBreak extension also binds Mod-Enter. Register PageBreak after ConvertKit in your extensions array so the PageBreak shortcut takes priority.

DOCX compatibility

The Tiptap conversion service emits pageBreak nodes when importing .docx files that contain page breaks. These map directly to this extension's node type, so imported documents preserve their page break positions.

When exporting, page breaks are converted to <w:br w:type="page"/> in the DOCX output, producing standard Word page breaks. See the DOCX export page breaks guide for setup details.

PreviouslyZoom

Next upLimitations