Pagination overview
The pagination feature is a dedicated decoupled editor plugin that lets you see where page breaks will be after the document is exported to PDF or to Word. The feature respects page breaks inserted by the user with the page break feature.
This is a premium feature and you need a license for it on top of your CKEditor 5 commercial license. Contact us to receive an offer tailored to your needs.
You can also sign up for the CKEditor Premium Features 30-day free trial to test the feature.
# 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.As of now, the Pagination feature demo does not work properly in the Firefox and Safari browsers. Refer to the browser compatibility section for further details.
This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.
# 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 and export to Word 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 blog post.
The pagination plugin cannot be used to reflect the original page division in content imported from Word. This is an export-only feature.
This feature is dedicated for use with the decoupled editor only. If used with different types of editor builds, 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 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 guide for details.
For the export plugins, you will need a special token endpoint. To get it, log into your CKEditor Ecosystem Dashboard account and follow the guide on creating a token URL. 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
To add the pagination feature to your editor, install the @ckeditor/ckeditor5-pagination
package:
npm install --save @ckeditor/ckeditor5-pagination
Then add the Pagination
plugin to your plugin list and configure it; remember the license key:
import { Pagination } from '@ckeditor/ckeditor5-pagination';
DecoupledEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Pagination, /* ... */ ],
toolbar: [
'previousPage',
'nextPage',
'pageNavigation', '|',
// More toolbar items.
// ...
],
pagination: {
// A4
pageWidth: '21cm',
pageHeight: '29.7cm',
pageMargins: {
top: '20mm',
bottom: '20mm',
right: '12mm',
left: '12mm'
}
},
licenseKey: 'your-license-key'
} )
.then( /* ... */ )
.catch( /* ... */ );
Read more about installing plugins.
# Configuration
For more technical details, check the plugin configuration API.
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 or the export to Word configuration. The structure of both configurations is different.
# Example configuration
{
pagination: {
// A4
pageWidth: '21cm',
pageHeight: '29.7cm',
pageMargins: {
top: '20mm',
bottom: '20mm',
left: '12mm',
right: '12mm'
}
},
licenseKey: 'your-license-key'
}
# 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
,config.pagination.pageHeight
The page dimensions.
-
The page margins.
-
config.pagination.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
.
# Pagination toolbar
CKEditor 5 pagination feature provides a few toolbar items that can be added to your editor toolbar configuration. They are all optional – the pagination feature does not need them to show you the document page division.
The pagination toolbar buttons make the document navigation easier, though:
- The
'nextPage'
button allows you to go to the next document page. - The
'previousPage'
button allows you to go to the previous document page. - The
'pageNavigation'
toolbar item shows you the total page count and allows you to go straight to a particular page number.
import { Pagination } from '@ckeditor/ckeditor5-pagination';
DecoupledEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Pagination, /* ... */ ],
toolbar: [
'previousPage',
'nextPage',
'pageNavigation', '|',
// More toolbar items.
// ...
]
} )
.then( /* ... */ )
.catch( /* ... */ );
# Troubleshooting
The pagination feature computes where the page breaks would be in the local browser, but the export to PDF or export to Word 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), 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 or export to Word features.
.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:
@media print { body { margin: 0 !important; } }
-
Override the default browser behavior of breaking the tables:
.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.
DecoupledEditor
.create( initialData, config )
.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();
} )
.catch( err => {
console.error( err );
} );
# Known issues
# 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:
# 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
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 allows you to manually insert a page break into your document.
- The export to Word feature will allow you to generate editable
.docx
files out of your editor-created content. - The export to PDF feature will allow you to generate portable PDF files out of your editor-created content.
# Common API
The Pagination
plugin registers:
-
The
'pageNavigation'
toolbar item. -
The
'nextPage'
and'previousPage'
buttons. -
The
'pagination'
option for thegetData()
method:const data = editor.getData( { pagination: true } );
This option enables downcast conversion of the calculated page breaks.
- At the beginning of the element:
<p style="page-break-before:always;" data-pagination-page="4"> ... </p>
- Inside the text:
<p> ... <span style="page-break-before:always;" data-pagination-page="8"></span> ... </p>
- At the beginning of the element:
If you have any further comments or suggestions about this feature, we will be happy if you contact us and share them!
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.