---
title: "PageBreak node"
description: "Learn how to use the PageBreak extension to insert explicit page breaks in your Tiptap editor, with or without the Pages extension."
canonical_url: "https://tiptap.dev/docs/pages/core-concepts/page-break-node"
---

# PageBreak node

Learn how to use the PageBreak extension to insert explicit page breaks in your Tiptap editor, with or without the Pages extension.

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](https://tiptap.dev/docs/pages/getting-started/overview.md) is present.

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

## 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

```bash
npm install @tiptap-pro/extension-pagebreak
```

## Basic usage

Use PageBreak as a standalone extension for a visual page break indicator. Pair it with [ConvertKit](https://tiptap.dev/docs/conversion/import/docx/convertkit.md) for the editor schema:

```ts
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](https://tiptap.dev/docs/pages/getting-started/install.md) — ConvertKit + TableKit + Pages — and add PageBreak alongside:

```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'
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](https://tiptap.dev/docs/pages/guides/pagekit-usage.md). To disable it, pass `pagebreak: false`:

```js
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

```js
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.

```js
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](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md) 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](https://tiptap.dev/docs/conversion/export/docx/page-breaks.md) for setup details.