Import from Word

The import from Word feature lets you easily 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).

# 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.

# 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.

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.

# Importing styles

CKEditor 5 supports two strategies for importing styles from Word:

1. Using styles defined in CKEditor 5.
2. 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.

# 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

You can try the import from Word feature 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.

# 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';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ImportWord, /* ... */ ],
        toolbar: [ 'importWord', /* ... */ ], // Depending on your preference.
        importWord: {
            // Import from Word configuration.
            // ...
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 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';

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';

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.formatting object:

import { ImportWord } from '@ckeditor/ckeditor5-import-word';

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 modify this behavior by passing the config.importWord.formatting.comments option:

import { ImportWord } from '@ckeditor/ckeditor5-import-word';

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

• 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.

# 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.

# 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 the ImportWordCommand 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();
    }
} );

# 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.