Page breaks

Page breaks are the only page-structure element that fully round-trips between DOCX and the editor. The import creates pageBreak nodes, and the export writes them back as DOCX page breaks.

What you need

• Extensions: @tiptap-pro/extension-pagebreak (not in StarterKit)
• Optional: Pages extension for paginated layout where page breaks push content to the next visual page

Support overview

Import

Import page breaks using the editor extension or the REST API. Both produce identical output.

The import detects <w:br w:type="page"/> elements in the DOCX and produces pageBreak nodes. When a page break appears in a paragraph alongside text content, the text is emitted as a paragraph first, followed by a separate pageBreak node. Standalone page breaks (paragraphs containing only a page break) produce a single pageBreak node.

Soft page breaks (<w:lastRenderedPageBreak/>) are layout hints from Word's renderer and are not imported. Only explicit page breaks are converted.

{
  "type": "pageBreak"
}

Editor rendering

The PageBreak extension renders page break nodes in the editor. The behavior depends on whether the Pages extension is also installed:

Without Pages: The page break renders as a visual dashed divider with a centered "Page break" label. It serves as a visual hint only, with no paginated layout.

With Pages: The page break fills the remaining space on the current page, pushing subsequent content to the next page. This mirrors Word's behavior.

For full configuration details, see the PageBreak node guide.

Export

Export page breaks using the editor extension or the REST API. Both handle page breaks identically.

Each pageBreak node is exported as a DOCX paragraph containing <w:br w:type="page"/>. No additional configuration is needed.

What round-trips

Page breaks round-trip correctly when the PageBreak extension is installed. The import produces pageBreak nodes, the editor preserves them, and the export writes them back to DOCX.