# Pagination overview
The pagination feature is a dedicated [decoupled editor](../../examples/builds/document-editor.md) plugin that lets you see where page breaks will be after the document is [exported to PDF](../converters/export-pdf.md). The feature respects page breaks inserted by the user with the [page break feature](../page-break.md).
> **Unlock this feature with the Custom Plan**
>
> Try this feature for **free during your trial** — no credit card required.\
> After the trial, it’s available as a premium add-on in the [CKEditor Custom Plan](https://ckeditor.com/pricing/).
>
> [Sign up for a free trial ](https://portal.ckeditor.com/checkout?plan=free)[Contact sales](https://ckeditor.com/contact-sales/)
## Demo
The demo below lets you see page break lines. They show you the location of page breaks in an exported PDF or DOCX file. Use the pagination feature toolbar buttons to navigate back and forth between pages.
> **Note**
>
> As of now, the Pagination feature demo does not work properly in the Firefox and Safari browsers. Refer to the [browser compatibility section](#browser-compatibility) for further details.
## Additional feature information
In addition to page breaks, the pagination feature shows you page numbers and the total number of pages in the document. The feature also introduces a dedicated toolbar that lets you easily go to the next or previous page of the document or jump straight to a particular page.
The pagination feature is complementary to the [export to PDF](../converters/export-pdf.md) and [export to Word](../converters/export-word.md) features of CKEditor 5, ensuring the proper output every time. Combined with other CKEditor 5 features, these plugins allow for advanced editing and document creation implementations. This kind of practical application is shown in the [How to create ready-to-print documents with CKEditor 5 pagination feature](https://ckeditor.com/blog/How-to-create-ready-to-print-documents-with-page-structure-in-WYSIWYG-editor---CKEditor-5-pagination-feature/) blog post.
The pagination plugin cannot be used to reflect the original page division in content [imported from Word](../converters/import-word/import-word.md). This is an export-only feature.
> **Note**
>
> This feature is dedicated for use with the [decoupled editor](../../examples/builds/document-editor.md) type only. If used with different types of editors, it may result in certain issues, for example, incorrect rendering of the toolbar. If you need support for the pagination feature in other editor types, feel free to [contact us](https://ckeditor.com/contact/) and inquire.
## Before you start
To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](../../getting-started/licensing/license-key-and-activation.md) guide for details.
For the export plugins, you will need a special [token endpoint](https://ckeditor.com/docs/cs/latest/guides/security/token-endpoint.html). To get it, log into your CKEditor Ecosystem Dashboard account and [follow the guide on creating a token URL](https://ckeditor.com/docs/trial/latest/guides/export-to-pdf/quick-start.html#account-dashboard). When export features are used without this token, all generated documents will contain a watermark at the bottom of every page.
After obtaining all the credentials needed, create a custom editor and configure it.
## Installation
After [installing the editor](../../getting-started/installation/cloud/quick-start.md), add the feature to your plugin list and toolbar configuration:
**NPM**
```js
import { DecoupledEditor } from 'ckeditor5';
import { Pagination } from 'ckeditor5-premium-features';
DecoupledEditor
.create( {
root: {
element: document.querySelector( '#editor' )
},
licenseKey: '',
plugins: [ Pagination, /* ... */ ],
toolbar: [
'previousPage',
'nextPage',
'pageNavigation',
'|',
// More toolbar items.
],
pagination: {
// Configuration.
}
} )
.then( /* ... */ )
.catch( /* ... */ );
```
**CDN**
```js
const { DecoupledEditor } = CKEDITOR;
const { Pagination } = CKEDITOR_PREMIUM_FEATURES;
DecoupledEditor
.create( {
root: {
element: document.querySelector( '#editor' )
},
licenseKey: '',
plugins: [ Pagination, /* ... */ ],
toolbar: [
'previousPage',
'nextPage',
'pageNavigation',
'|',
// More toolbar items.
],
pagination: {
// Configuration.
}
} )
.then( /* ... */ )
.catch( /* ... */ );
```
## Configuration
> **Note**
>
> For more technical details, check the [plugin configuration API](../../api/module_pagination_pagination-PaginationConfig.md).
The configuration is crucial for allowing the pagination feature to measure where the page breaks would be. These configuration values must match the [export to PDF](../../api/module_export-pdf_exportpdf-ExportPdfConfig.md) or the [export to Word](../../api/module_export-word_exportword-ExportWordConfig.md) configuration. The structure of both configurations is different.
### Example configuration
```js
{
pagination: {
// A4
pageWidth: '21cm',
pageHeight: '29.7cm',
pageMargins: {
top: '20mm',
bottom: '20mm',
left: '12mm',
right: '12mm'
}
}
}
```
### Plugin options
The plugin options tell the pagination feature what the format of the page and the page margins are. There is also an additional configuration option that allows you to enable pagination in all browsers, including the officially unsupported ones.
* **[`config.pagination.pageWidth`](../../api/module_pagination_pagination-PaginationConfig.md#member-pageWidth)**, **[`config.pagination.pageHeight`](../../api/module_pagination_pagination-PaginationConfig.md#member-pageHeight)**
The page dimensions.
* **[`config.pagination.pageMargins`](../../api/module_pagination_pagination-PaginationConfig.md#member-pageMargins)**
The page margins.
* **[`config.pagination.enableOnUnsupportedBrowsers`](../../api/module_pagination_pagination-PaginationConfig.md#member-enableOnUnsupportedBrowsers)**
The pagination feature is by default enabled only in browsers that are using the Blink engine (Chrome, Chromium, newer Edge, newer Opera). This behavior can be modified by setting this configuration option to `true`.
## Troubleshooting
The pagination feature computes where the page breaks would be in the local browser, but the [export to PDF](../converters/export-pdf.md) or [export to Word](../converters/export-word.md) features are handled by dedicated HTML to PDF and DOCX converter services of CKEditor Cloud Services. Because of this, it is important to match the content styles with those sent to the backend service. Even a minor difference in the margin, padding, font size, etc. setting may lead to inconsistencies between the content in the editor and the generated PDF or Word file. Because of this, the local browser could calculate page breaks in incorrect places.
### Editor content styling
For example, if you are using [decoupled editor (document editor)](../../api/module_editor-decoupled_decouplededitor-DecoupledEditor.md), you need to make sure that the editor styles match precisely the configuration options that you provided to the feature and to the [export to PDF](../converters/export-pdf.md) or [export to Word](../converters/export-word.md) features.
```css
.ck.ck-editor__editable_inline {
/* A4 size */
width: calc( 210mm + 2px ); /* Expand the width by 2px because of the border and "box-sizing: border-box". */
height: auto;
padding: 20mm 12mm;
box-sizing: border-box;
border: 1px solid hsl( 0, 0%, 88% );
background: hsl( 0, 0%, 100% );
box-shadow: 0 2px 8px hsla( 0, 0%, 0%, .08 );
margin: 40px auto;
overflow: hidden;
}
```
Note the calculation of the width of the element.
### The style sheets sent to the service
While preparing the style sheets to send to the export to PDF or export to Word service, you should:
* Make sure that the styling of all elements is exact.
* Reset the default page margins:
```css
@media print {
body {
margin: 0 !important;
}
}
```
* Override the default browser behavior of breaking the tables:
```css
.ck-content .table thead {
display: table-row-group;
}
.ck-content .table tr {
break-inside: avoid;
break-after: auto;
}
```
### CKEditor 5 initialization
If you want to create the editor detached and attach it to the DOM tree later, remember to call `editor.ui.update();` after the editor is attached.
```js
DecoupledEditor
.create( {
...config,
root: {
initialData
}
} )
.then( editor => {
const editorContainer = document.querySelector( '#editor-container' );
const toolbarContainer = document.querySelector( '#toolbar-container' );
toolbarContainer.appendChild( editor.ui.view.toolbar.element );
editorContainer.appendChild( editor.ui.view.editable.element );
editor.ui.update();
} );
```
## Known issues
### Automatic page breaks in Export to Word
Browser engines and Microsoft Word differ significantly. Because of that, the automatic prediction of page breaks in [Export to Word](../converters/export-word.md#how-it-works) is problematic and error-prone. Therefore, pagination in the Export to Word should be based solely on [page breaks](../page-break.md). We strongly recommend reviewing your document’s structure before exporting and manually applying the page breaks to maintain the preferred structure. You can also use [Export to PDF](../converters/export-pdf.md), where predicting page breaks is more straightforward and works more consistently.
### Unsupported plugins
Not all CKEditor 5 plugins and features are compatible with pagination and export to PDF or Word at the moment. Refer to the documentation of the export features to learn more:
* [Export to PDF – known issues](../converters/export-pdf.md#known-issues)
* [Export to Word – known issues](../converters/export-word.md#known-issues)
* [Document title](../title.md) – cause conflicts
### Browser compatibility
Currently, the pagination feature works best with the following web browsers:
* Chrome
* Chromium
* latest Edge
* latest Opera
The pagination plugin does not work in Firefox yet. There are also some glitches in Safari. To prevent users from seeing potentially invalid pagination, the plugin disables itself after detecting these unsupported browsers.
If you want to enable the pagination feature in an unsupported browser, you can set the [`config.pagination.enableOnUnsupportedBrowsers`](../../api/module_pagination_pagination-PaginationConfig.md#member-enableOnUnsupportedBrowsers) configuration option to `true` or enable it at runtime by calling `editor.plugins.get( 'Pagination' ).clearForceDisabled( 'browserCheck' )`.
## Related features
Here are some useful CKEditor 5 features that you can use together with the pagination plugin for an all-around paged editing experience:
* The [page break feature](../page-break.md) allows you to manually insert a page break into your document.
* The [export to Word](../converters/export-word.md) feature will allow you to generate editable `.docx` files out of your editor-created content.
* The [export to PDF](../converters/export-pdf.md) feature will allow you to generate portable PDF files out of your editor-created content.
## Common API
The [`Pagination`](../../api/module_pagination_pagination-Pagination.md) plugin registers:
* The `'pageNavigation'` toolbar item.
* The `'nextPage'` and `'previousPage'` buttons.
* The `'pagination'` option for the [`getData()`](../../api/module_core_editor_editor-Editor.md#function-getData) method:
```js
const data = editor.getData( { pagination: true } );
```
This option enables downcast conversion of the calculated page breaks.
* At the beginning of the element:
```html
...
```
* Inside the text:
```html
... ...
```
> **Note**
>
> If you have any further comments or suggestions about this feature, we will be happy if you [contact us](https://ckeditor.com/contact/) and share them!
---
Full index of the CKEditor 5 documentation: [llms.txt](../../../llms.txt)