---
title: "Page breaks"
description: "How page breaks are handled across the DOCX conversion pipeline, including import, editor rendering, and export."
canonical_url: "https://tiptap.dev/docs/conversion/content-types/page-layout/page-breaks"
---

# Page breaks

How page breaks are handled across the DOCX conversion pipeline, including import, editor rendering, and export.

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](https://tiptap.dev/docs/pages/getting-started/overview.md) for paginated layout where page breaks push content to the next visual page

## Support overview

|             | Import    | Editor                                   | Export    |
| ----------- | --------- | ---------------------------------------- | --------- |
| Page breaks | Supported | Supported (requires PageBreak extension) | Supported |

## Import

Import page breaks using the [editor extension](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md) or the [REST API](https://tiptap.dev/docs/conversion/import/docx/rest-api.md). 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.

```json
{
  "type": "pageBreak"
}
```

> **PageBreak extension required:**
>
> The `pageBreak` node type is not part of StarterKit. Without the [PageBreak extension](https://tiptap.dev/docs/pages/core-concepts/page-break-node.md), imported page break nodes require a [custom extension](https://tiptap.dev/docs/editor/extensions/custom-extensions/extend-existing.md) to render. See the [invalid schema guide](https://tiptap.dev/docs/guides/invalid-schema.md) for strategies.

## Editor rendering

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

## Export

Export page breaks using the [editor extension](https://tiptap.dev/docs/conversion/export/docx/editor-extension.md) or the [REST API](https://tiptap.dev/docs/conversion/export/docx/rest-api.md). 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.