Import from Word
The import from Word feature lets you import .docx
(Word document) or .dotx
(Word template) files into the editor. The process preserves formatting and rich media as well as comments and tracked changes (if these features are enabled).
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 import a Word file into the editor. To test the feature, download the sample Word document. Use the import from Word toolbar button and select the downloaded file. The file’s content will appear in the editor.
This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.
# Additional feature information
The import from Word feature sends the selected Word file to the CKEditor Cloud Services DOCX to HTML converter service. The service returns HTML code generated from the uploaded file and then inserts it into the editor content in place of the document selection.
The editor may strip some formatting or content if you do not enable related CKEditor 5 plugins.
Read more in the Automatic content filtering section below.
Even though CKEditor 5 offers a dedicated pagination plugin, it cannot be used to reflect the original page division in content imported from Word. This is an export-only feature.
# 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 you great flexibility. It also allows you 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. This means that it will retain basic text styling (like bold or italics), headings, images, tables, and the overall document structure. At the same time, it 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 you import the file content into the editor and it does not differ visually from the already existing content. This is useful when the formatting needs to follow corporate guidelines or a brand book. With that approach, import keeps semantically close formatting to the existing content.
# Using styles defined in Microsoft Word
The converter has an option to enable importing the entire Word document styling. In this approach, the Word default content formatting 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, you should set the default_styles
option 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. You can call it the “complete Word editing experience.” However, an integrator can still decide which styles to preserve by a proper CKEditor 5 configuration.
# Paste from Office vs import from Word
The paste from Office 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 copy it to CKEditor 5 and retain basic text styling, heading levels, links, lists, tables, and images if these features are supported by the installed CKEditor 5 plugins. For example, 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 manually.
Import from Word, however, is much more advanced. First of all, you can automate it and it does not need the presence of CKEditor 5 editor or human supervision to convert files. You can feed the files into the service and convert them automatically, as part of a larger process.
While the paste from Office feature can only retain the formatting 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.
# Automatic content filtering
Due to the CKEditor 5 custom data model, the editor will only preserve content handled by its plugins. 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 (for example, the 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. Consult the list of properties that need to have GHS enabled to be imported into the content.
# base64
images and Content Security Policy
If you use the import from Word plugin without custom uploaders, Content Security Policy (CSP) may prevent base64
images from being imported due to security concerns. This will result in an error in the console like 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
The import from Word feature supports Word files with comments and tracked changes. They will be imported as long as your CKEditor 5 preset includes the comments and track changes features.
All comments and suggestions imported from a Word file will use the same author’s name as in the Word file. They will also include a special label informing that a given item comes from an external source.
Read more about the integration between the import from Word and the comments feature in the Comments walkthrough guide.
If your CKEditor 5 preset does not include the 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 a premium feature and you need a license for it. If you do not have one yet, contact us.
You can also sign up for the CKEditor Premium Features 30-day free trial to test the feature.
You can try the import from Word feature in preview mode without a valid license. It will import a part of the document, and replace the rest of the content 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 General HTML Support plugin to work. Be sure to install it before you start.
# Installation
⚠️ New import paths
Starting with version 42.0.0, we changed the format of import paths. This guide uses the new, shorter format. Refer to the Packages in the legacy setup guide if you use an older version of CKEditor 5.
After installing the editor, add the feature to your plugin list and toolbar configuration:
import { ClassicEditor } from 'ckeditor5';
import { ImportWord } from 'ckeditor5-premium-features';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, /* ... */ ],
toolbar: [ 'importWord', /* ... */ ], // Depending on your preference.
importWord: {
// Import from Word configuration.
// ...
}
} )
.then( /* ... */ )
.catch( /* ... */ );
# Configuration
You can configure the feature 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 { ClassicEditor } from 'ckeditor5';
import { ImportWord } from 'ckeditor5-premium-features';
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 service is hosted in your own environment, you should configure the converter service URL via the config.importWord.converterUrl
option:
import { ClassicEditor } from 'ckeditor5';
import { ImportWord } from 'ckeditor5-premium-features';
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 change this behavior by passing the config.importWord.formatting
object:
import { ClassicEditor } from 'ckeditor5';
import { ImportWord } from 'ckeditor5-premium-features';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, /* ... */ ],
toolbar: [ 'importWord', /* ... */ ],
importWord: {
formatting: {
resets: 'none',
defaults: 'none',
styles: 'inline'
}
}
} )
.then( /* ... */ )
.catch( /* ... */ );
# Comments styles
If the imported document contains comments, only their basic styles will be kept by default. However, you can change this behavior by passing the config.importWord.formatting.comments
option:
import { ClassicEditor } from 'ckeditor5';
import { ImportWord } from 'ckeditor5-premium-features';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ ImportWord, /* ... */ ],
toolbar: [ 'importWord', /* ... */ ],
importWord: {
formatting: {
comments: '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).
# Known limitations
- 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.
# Related features
- The paste from Word feature allows you to paste content from Microsoft Word and keep 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.
# 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 inserting it into 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 into 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 enabled and configured in your editor setup.
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.
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.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.