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

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

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:

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

# 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

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.

# Installation

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

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