Import from Word
The import from Word feature allows you to easily import .docx
(Word document files) or .dotx
(Word template files) into CKEditor 5 WYSIWYG editor, retaining formatting and rich media, as well as comments and tracked changes (requires comments and track changes features).
The feature sends the selected Word file to the CKEditor Cloud Services DOCX to HTML converter service. The service returns an HTML code generated from the uploaded file and then inserts it into the editor content in place of the document selection.
Please note that while there exists the pagination plugin, it cannot be used to reflect the original pages division in content imported from Word. It is an export-only feature.
This is a premium feature and you need a subscription to use it. You can purchase it here for your open source CKEditor implementation. Contact us if:
- CKEditor commercial license is needed for your application.
- You need on-premises (self-hosted) version of the service.
- You have other licensing questions.
You can also sign up for the CKEditor Premium Features 30-day free trial.
Note that some formatting or content may be stripped if you do not enable related CKEditor 5 plugins.
Read more in the Automatic content filtering section below.
# Demo
The demo below allows you to import a Word file into the editor. To test the feature, you can download the sample Word document and import it into CKEditor 5 below. Click the “Import from Word” toolbar button to send the selected Word file to the CKEditor Cloud Services DOCX to HTML converter service. After a short while you should see that the Word file content has been inserted into the editor.
This demo only presents a limited set of features. Visit the full-featured editor example to see more in action.
# Importing styles
CKEditor 5 supports two strategies for importing styles from Word:
- Using styles defined in CKEditor 5.
- Using styles defined in Word.
The decision as to which approach to use is strongly related to your use case. The ability to choose whether to retain or to drop native Word styles gives great flexibility and the ability to tailor the service to your specific needs.
# Using styles defined in CKEditor
The import from Word feature is pre-configured to preserve styles defined in the CKEditor 5’s implementation or applied directly by the end-user. It means, it will retain the basic text styling (like bold or italics), headings, images, tables, and the overall document structure, but will allow the editor to apply styles used by CKEditor 5 to the imported content for more general formatting, like font family, font size, paragraph spacing, etc. if not set. This way the file content is simply imported into the editor and does not differ visually from the already existing content. This is mostly useful, e.g. when the formatting needs to follow corporate guidelines or brandbook. With that approach, import keeps semantically close formatting to existing content.
# Using styles defined in Microsoft Word
The converter was designed with an option to enable importing the whole Word document styling, if needed. By this, we mean that the default content formatting that can be set for the whole document is all included in the import and preserved as much as possible (within the support of CKEditor 5 feature plugins). Word applies styles in a specific way, and the user may choose to retain those. To make the converter work this way, the default_styles
option should be set to true
. This is most useful when the user just needs to edit a Word document in their browser and when cross-platform interoperability needs to be available. We can call it the full Word editing experience. However, an integrator still can decide upon which styles will be indeed preserved by a proper CKEditor 5 configuration.
# Paste from Word vs import from Word
The paste from Word feature allows you to paste content from Microsoft Word into your CKEditor 5 WYSIWYG editor and maintain the original structure and formatting. After creating a document in Microsoft Word you can simply copy it to CKEditor 5 and retain basic text styling, heading levels, links, lists, tables and images on condition, that these features are supported by the installed CKEditor 5 plugins (e.g. if font colors are not explicitly turned on in the editor instance, they will be dropped). This operation is fast and easy, but can only be done “by hand”.
The import from Word, however, is much more advanced. First of all, it can be automated and does not need the presence of CKEditor 5 editor, nor the human supervision to convert files. These can be fed into the service and converted automatically, becoming a part of a larger process.
While the paste from Word feature can only retain the formatting currently supported by the editor instance, this limitation does not concern the Import from Word service. You can read more about the differences and specific supported features in the dedicated comparison guide.
# Related features
- The paste from Word feature allows you to paste content from Microsoft Word and maintain the original structure and formatting.
- The export to Word feature allows you to generate editable
.docx
files out of your editor-created content. - The export to PDF feature allows you to generate portable PDF files out of your editor-created content.
# Automatic content filtering
Due to the CKEditor 5 custom data model, only content which is handled by the editor plugins will be preserved. This guarantees that the output provided by CKEditor 5 will be clean and semantic.
However, this also means that you may need to enable some additional plugins in your rich-text editor to prevent stripping content or formatting (e.g. font family and font size features to handle font formatting).
If you struggle to keep some formatting that is not handled by dedicated plugins, you can try using the general HTML support feature with all HTML features enabled.
# base64
images and Content Security Policy
If the import from Word plugin is used without custom uploaders, then Content Security Policy may prevent base64
images from being imported due to security concerns. It will then result in an error in console similar to this one:
Refused to connect to `data:image/jpeg:base64,/xxxxx utills.js:43 xxxxx` because it violates the documents Content Security Policy.
In such a case, you should try using a ready-made upload solution like CKBox or Easy Image. You can also consider changing the CSP directive.
# Comments and tracked changes
Import from Word feature supports Word files with comments and tracked changes, and they will be imported as long as your CKEditor 5 build includes the comments and track changes features.
All comments and suggestions imported from a Word file will use author name same as in the Word file and will also include a special label informing that a given item comes from an external source.
If your CKEditor 5 build does not include track changes feature, the content will be imported as if all tracked changes were accepted (same as “No Markup” displayed mode).
# Before you start
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.
You can try import from Word in preview mode without a valid license. It will only import part of the document, and the rest of the content will be replaced with a lorem ipsum text placeholder.
After you purchase a license, follow the steps below, as explained in the Import from Word quick start guide:
- Log into the CKEditor Ecosystem customer dashboard.
- Create the token endpoint needed for authorization.
The import from Word feature requires the document lists feature to work. Be sure to install it before you start.
# Installation
To add the import from Word feature to your editor, first install the @ckeditor/ckeditor5-import-word
package:
npm install --save @ckeditor/ckeditor5-import-word
Then, add the ImportWord
plugin to your plugin list and configure it; also, add the toolbar button:
import ImportWord from '@ckeditor/ckeditor5-import-word/src/importword';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, ... ],
toolbar: [ 'importWord', ... ], // Depending on your preference.
importWord: {
// Feature configuration.
}
} )
.then( ... )
.catch( ... );
Read more about installing plugins.
# Configuration
The feature can be configured via the config.importWord
object.
# Providing the token URL
The import from Word feature requires the token endpoint URL configured in the config.importWord.tokenUrl
key. If not explicitly provided, the token URL from config.cloudServices.tokenUrl
is used instead. If both are provided, the token URL defined in config.importWord.tokenUrl
takes precedence over the config.cloudServices.tokenUrl
.
import ImportWord from '@ckeditor/ckeditor5-import-word/src/importword';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, ... ],
toolbar: [ 'importWord', ... ],
importWord: {
tokenUrl: 'https://example.com/cs-token-endpoint'
}
} )
.then( ... )
.catch( ... );
# Configuring the converter service URL
If the cloud service is hosted in your own environment you should configure the converter service URL via the config.importWord.converterUrl
option:
import ImportWord from '@ckeditor/ckeditor5-import-word/src/importword';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, ... ],
toolbar: [ 'importWord', ... ],
importWord: {
converterUrl: 'https://example.com/converter'
}
} )
.then( ... )
.catch( ... );
# Default styles
By default the converter service will convert styles explicitly applied to the content. You can modify this behaviour by passing the config.importWord.defaultStyles
option:
import ImportWord from '@ckeditor/ckeditor5-import-word/src/importword';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, ... ],
toolbar: [ 'importWord', ... ],
importWord: {
defaultStyles: true
}
} )
.then( ... )
.catch( ... );
# Comments styles
If the imported document contains comments, only their basic styles will be kept by default. However, you can modify this behavior by passing the config.importWord.commentsStyles
option:
import ImportWord from '@ckeditor/ckeditor5-import-word/src/importword';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, ... ],
toolbar: [ 'importWord', ... ],
importWord: {
commentsStyles: 'none'
}
} )
.then( ... )
.catch( ... );
This configuration option can take the following values:
'basic'
– Only basic styles are kept (bold, italic, underline, strikethrough and links).'none'
– Comment text is imported without any styling.'full'
– All styles are preserved (not recommended).
# Common API
The ImportWord
plugin registers:
- The
'importWord'
UI button component that opens the native file browser to let you import a Word file directly from your disk. - The
'importWord'
command implemented by theImportWordCommand
that accepts the file to import.
# The dataInsert
event
The dataInsert
event is fired by ImportWordCommand
. It allows for modifying the HTML content before it is inserted to the editor.
editor.commands.get( 'importWord' ).on( 'dataInsert', ( event, data ) => {
// The `data.html` property contains the HTML returned by the converter service.
// Updating its value modifies the content that will be inserted to the editor.
data.html = '<p>An example paragraph.</p>';
} );
Also, you can prevent the event from further processing, and stop the import, by calling the event.stop()
function.
editor.commands.get( 'importWord' ).on( 'dataInsert', ( event, data ) => {
// Example: do not insert the HTML if it contains a table.
if ( data.html.includes( '<table' ) ) {
event.stop();
}
} );
We recommend using the official CKEditor 5 inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
# Collaboration features integration
Import from word automatically integrates with the comments and track changes features, if these features are properly enabled and configured in your editor build.
When collaboration features are enabled, the data
parameter in the dataInsert
event may include the comment_threads
and suggestions
fields, which will hold data from the imported Word file.
# Known limitations
- The document lists feature must be enabled to properly handle lists items.
- CKEditor 5 does not support lists with skipped intermediate levels.
- Due to lists merging in CKEditor 5, custom starting values are sometimes discarded by the editor.
- CKEditor 5 may overwrite some table borders with its built-in styles.
- Document headers and footers are not supported yet.
- For track changes and comments, check the feature comparison guide for current development.
- The feature does not support
.doc
files.
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.