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:

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

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

Usage with Pages

When both PageBreak and Pages are registered, PageBreak automatically operates in Pages mode:

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Pages } from '@tiptap-pro/extension-pages'
import { PageBreak } from '@tiptap-pro/extension-pagebreak'

const editor = new Editor({
  extensions: [StarterKit, 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

If you use StarterKit's HardBreak extension (which also binds Mod-Enter), place PageBreak after StarterKit 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.

PreviouslyPage gap & background

Next upLimitations