Pagination overview
The pagination feature is a dedicated decoupled editor plugin which allows you to see where page breaks would be after the document is exported to PDF or to Word. It also respects page breaks inserted by the user with the page break feature.
In addition to this, the pagination feature shows you the page numbering as well as the total number of pages in the document. It also introduces a dedicated toolbar that allows you to easily go to the next or previous page of the document or jump straight to a particular page.
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.
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.
Please note that the pagination plugin cannot be used to reflect the original pages 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.
# Demo
The demo below allows you to see the page break lines that would match page boundaries when the document is exported to a PDF or a DOCX file. Use the pagination feature toolbar buttons to navigate back
and forth between pages.Please note, that, 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 only presents a limited set of features. Visit the full-featured editor example to see more in action.
# 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.
# Before you start
# Pagination license
This is an additionally payable feature. Contact us to receive an offer tailored to your needs. If you already have a valid license, please log into your user dashboard to access the feature settings.
You can also sign up for the CKEditor Premium Features 30-day free trial to test the feature.
If you have more than one license for CKEditor premium features (Comments, Track changes, Revision history, or Pagination), you may use any key of those in your CKEditor configuration to activate all of the features.
Since the introduction of single key for all premium features (Comments, Track changes, Revision history, or Pagination), the one key can be used to activate any and all of the features.
After you purchase a license, follow the steps below to obtain important information needed during the configuration phase.
# Log in to the CKEditor Ecosystem dashboard
Log in to the CKEditor Ecosystem dashboard. You will receive a confirmation email and will be asked to create a password for your account. Keep it safe. Navigate to “Your products > CKEditor”.
From the list of available subscriptions in the dashboard choose the Pagination subscription and press the “Manage” link.
On the next page you will see the subscription parameters overview together with the management area.
# Access the license key
Once you enter the management console for pagination, you have access to the license key needed to run the feature. This key is necessary to activate the feature during installation. Do not share it with anyone.
# 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/src/pagination';
DecoupledEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Pagination, ... ],
toolbar: [
'previousPage',
'nextPage',
'pageNavigation', '|',
...
],
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, please check the plugin configuration API.
The configuration is the key to allow 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. Note that 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 the 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 to go straight to a particular page number.
import Pagination from '@ckeditor/ckeditor5-pagination/src/pagination';
DecoupledEditor
.create( document.querySelector( '#editor' ), {
plugins: [ Pagination, ... ],
toolbar: [
'previousPage',
'nextPage',
'pageNavigation', '|',
...
]
} )
.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 really important to match the content styles with the ones that are 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 and 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 stylesheets sent to the service
While preparing the stylesheets that will be sent 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 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 as of 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' )
.
# 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 concerning 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.