guideExport to Word

The export to Word feature lets you generate a .docx file directly from the editor.

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.

If this feature is used without authentication, the resulting document will be watermarked.

# Demo

The demo below lets you generate a Word file based on the editor’s content. Edit the document, then click the export to Word toolbar button Export to Word to save the content as a Word file.

The Flavorful Tuscany Meetup

Welcome letter

Dear Guest,

We are delighted to welcome you to the annual Flavorful Tuscany Meetup. We hope you will enjoy the program as well as your stay at the Bilancino Hotel.

Please find attached the full schedule of the event.

The annual Flavorful Tuscany meetups are always a culinary discovery. You get the best of Tuscan flavors during an intense one-day stay at one of the top hotels in the region. All the sessions are led by top chefs passionate about their profession. I would recommend saving the date in your calendar for this one!

Angelina Calvino, food journalist

Please arrive at the Bilancino Hotel reception desk at least half an hour earlier to ensure that the registration process goes as smoothly as possible.

We look forward to welcoming you to the event.

Victoria Valc signature

Victoria Valc, Event Manager at Bilancino Hotel

 

 

 

The Flavorful Tuscany Meetup Schedule

Saturday, July 14
9:30 AM - 11:30 AM

Americano vs. Brewed - “know your coffee” with: 

  • Giulia Orlanda
  • Stefano Garau
  • Giuseppe Russo
1:00 PM - 3:00 PM

Regional delicacies of Tuscany - live cooking 1

Incorporate the freshest ingredients 
with Rita Fresco

5:00 PM - 8:00 PM Tuscan vineyards at a glance - wine-tasting 
with Frederico Riscoli

1 Registration for the live cooking session is required as seats are limited.

 

This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.

If you have already tried the export to Word feature, help us develop it by sharing your feedback with this short survey. It only takes about 2 minutes, but will be invaluable for the development team. Thank you!

# How it works

The export to Microsoft Word feature collects the HTML generated with the editor.getData() method and the default editor content styles combined with the styles provided by you in the configuration. It then sends them to the CKEditor Cloud Services HTML to DOCX converter service. The service generates a Word file and returns it to the user’s browser so they can save it in the Word format on their disk.
You can read more about the converter and the plugin in a dedicated Feature spotlight blog post.

The generated .docx file may not be fully compatible with older versions of Word. At the time of writing this guide, the generated document was fully compatible with Word in Office 365.

The complementary pagination feature allows you to see where page breaks would be after you export the document to Word. Thanks to the live preview, the user can fine-tune the structure of the output document when editing it. The pagination feature also shows you the page count and lets you navigate between the document pages.

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

After you purchase a license, follow the steps below, as explained in the Export to Word quick start guide:

# 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 { ExportWord } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportWord, /* ... */ ],
        toolbar: [ 'exportWord', '|', /* ... */ ],
        exportWord: {
            tokenUrl: 'https://example.com/cs-token-endpoint',
            fileName: 'my-file.docx',
            converterOptions: {
                format: 'A4', // Default value, you do not need to specify it explicitly for A4.
                margin_top: '20mm',
                margin_bottom: '20mm',
                margin_right: '12mm',
                margin_left: '12mm'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Configuration

For more technical details, check the plugin configuration API.

# Default configuration

This is the default configuration of the Word export feature for CKEditor 5.

{
    exportWord: {
        fileName: 'document.docx',
        converterUrl: 'https://docx-converter.cke-cs.com/v1/convert',
        stylesheets: [
            'EDITOR_STYLES'
        ],
        converterOptions: {
            format: 'A4',
            margin_top: '1in',
            margin_bottom: '1in',
            margin_right: '1in',
            margin_left: '1in',
            header: undefined,
            footer: undefined,
            comments: undefined,
            suggestions: undefined,
            orientation: 'portrait'
        },
        dataCallback: ( editor ) => editor.getData( { pagination: true } )
    }
}

# EDITOR_STYLES option

The EDITOR_STYLES value for the stylesheets configuration option is the default one, but it will not work with the new installation methods introduced in v42.0.0, which are currently shown as the default in the documentation. We have retained it for backward compatibility, but because the new setup loads stylesheets separately from the editor, it will not work with this string.

The rule of thumb is if you want the export to preserve the styles, always add the style sheets with the content styles of the editor. Their path depends on your application setup, for example:

{
    exportPdf: {
        stylesheets: [
            './ckeditor5-content.css'
            './styles.css'
        ],
        // ...
    }
}

In the snippet above, we assume both style sheets are available via the relative path on the client side. For example, some frameworks allow to place files in the public folder.

# Export to Word v2

Note: Export to Word uses by default the old version of the converter that will no longer receive updates. It is highly recommended to migrate to the latest version. For migrating from v1 to v2, for more details see migration guide. To use v2, you need to specify the version in the version property of the configuration. In the following months, V2 will become the default. Stay tuned!

{
    exportWord: {
        // ...
        version: 2, // by default is 1.
        converterOptions: {
            document: {
                size: 'A4',
                orientation: 'portrait',
                margins: {
                    top: '1in',
                    bottom: '1in',
                    right: '1in',
                    left: '1in'
                }
            },
            headers: undefined,
            footers: undefined,
            collaboration_features: undefined,
        },
        // ...
    }
}

# Plugin options

For some use cases the default configuration will suffice. As you can see in the example above, you can improve how your Word file will look by adjusting the Word export plugin configuration.

  • config.exportWord.stylesheets

    You can set the paths (relative or absolute URLs) to the style sheets that should be included during the HTML to DOCX conversion. Prior to the version 42.0.0 of the editor, if you wanted to extend editor’s default content styles, you had to pass a special 'EDITOR_STYLES' token before a path to your custom styling. This special string is only supported in legacy setup now (custom builds with webpack or DLLs).

    Note: The order of the paths matters. If you have custom elements or have overridden the default editor’s content styles, the paths to your file(s) should go after the editor styles. See the examples in the config.exportWord.stylesheets documentation.

  • config.exportWord.fileName

    Sets the name for the generated Word file (together with the extension). The default name is document.docx. You can see it called in the default configuration listing above.

    This option, however, also allows for using a callback to generate a dynamic file name. In the example below, the document’s title will be used as the file name of the generated .docx file.

    // Dynamic file name.
    const exportWordConfig = {
        fileName: () => {
            const articleTitle = document.querySelector( '#title' );
            return `${ articleTitle.value }.docx`;
        }
    }
    
  • config.exportWord.converterUrl

    By default, the Word export feature uses the CKEditor Cloud Services HTML to DOCX converter service to generate the Word files. You can use this option to provide the URL to an on-premises converter. Contact us if you need this feature.

  • config.exportWord.tokenUrl

    A token URL or a token request function. This field is optional and you should use it when you require a different tokenUrl for the export to Word feature. You can skip this option if you use the cloudServices configuration to provide the same tokenUrl. In most cases you will probably want to provide the token in cloudServices, as other plugins like Easy Image or real-time collaboration will use this token as well. In this guide, to explicitly show that this value is needed, we leave it inside the exportWord configuration.

  • config.exportWord.converterOptions

    The plugin allows you to provide a custom CKEditor Cloud Services HTML to DOCX converter configuration.

  • config.exportWord.dataCallback

    By default, the plugin uses editor.getData( { pagination: true } ) to gather the HTML sent to the conversion service. You can use this option to customize the editor’s data.

    When using the pagination feature, the pagination:true option inserts additional markers into the editor’s data. Thanks to that, the HTML to DOCX converter creates a Word document similar to what is displayed in the editor.

# HTML to Word converter features

# Styling a document

By default, the export to Word plugin takes editor content styles and sends them to the CKEditor Cloud Services HTML to DOCX Converter. You can also add custom styles by providing the paths to the external CSS files.

// More editor's configuration.
// ...
exportWord: {
    fileName: 'document.docx',
    converterUrl: 'https://docx-converter.cke-cs.com/v1/convert',
    stylesheets: [
        'path/to/editor-styles.css',
        'path/to/my-styles.css'
    ],
    // More configuration of the export to Word feature.
    // ...
}
// More editor's configuration.
// ...

# Supported CSS properties

The HTML to DOCX Converter supports proper CSS inheritance with a set of whitelisted properties. You can use them to style the document content.

You can apply CSS properties like:

  • color
  • background-color
  • font-size
  • font-family
  • text-align

to the following elements: h1, h2, h3, h4, h5, h6, p, span, td, th, strong, i, u, s, sub, sup, mark.

You can also position images using the float CSS property, supporting left, right, and none values.

You can use any CSS selector to style these elements, including classes, attributes, and the * selector.

# Setting the page format

Consistency is an important factor. To make sure that the editor content and the generated Word file look the same, you need to match their format settings. You can change your existing style sheet or use a new one, for example, format.css. By default, the CKEditor Cloud Services HTML to DOCX converter is set to A4 format, but you may change this setting in your configuration.

Assuming that you want to create a document in the US Letter format, with the standard margins (19mm for each side), here is the example code you can use:

import { ClassicEditor } from 'ckeditor5';
import { ExportWord } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportWord, /* ... */ ],
        toolbar: [ 'exportWord', '|', /* ... */ ],
        exportWord: {
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-document.docx',
            converterOptions: {
                // Document format settings with proper margins.
                format: 'Letter',
                margin_top: '19mm',
                margin_bottom: '19mm',
                margin_right: '19mm',
                margin_left: '19mm',
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

This example focuses only on preparing the editable to match the converter settings. Please keep in mind that as a result, the appearance of your editor may change. Depending on your editor type and implementation or even some inherited global styles like box-sizing, applying new padding values may change the size of the editor on your website.

For the purpose of this example, box-sizing: border-box was implemented to make sure that the editor’s width will not change.

Here is the example for V2 API.

// ...
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ...
        exportWord: {
            // ...
            version: 2,
            converterOptions: {
                document: {
                    size: 'Letter',
                    margins: {
                        top: '19mm',
                        bottom: '19mm',
                        right: '19mm',
                        left: '19mm'
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Now set the corresponding editor styles:

/* format.css */

/* Styles for the editable. */
.ck.ck-content.ck-editor__editable {
    /* US Letter size. */
    width: 215.9mm;
    /* Padding is your document's margin. */
    padding: 19mm;
    /* You don't want to change the size of the editor by applying the new padding values. */
    box-sizing: border-box;
    /* ... */
}

With these settings, the content in the generated Word file should have the same US Letter format layout as it has in the editor.

The converter lets you set the document’s header and footer similarly to Microsoft Word or Google Docs.

// Let's keep the CSS string as a variable to avoid unnecessary string duplication.
const templateCSS = '.styled { color: #4b22aa; text-align: center; }'

const converterOptions = {
    header: [
        // Header template for all headers (without the `type` property).
        { html: '<p class="styled">Default header content</p>', css: templateCSS },
        // Header template only for the first page of the document.
        { html: '<p class="styled">First document page header content</p>', css: templateCSS, type: 'first' },
        // Header template for every even page of the document.
        { html: '<p class="styled">Every even page header content</p>', css: templateCSS, type: 'even' },
        // Header template for every odd page of the document.
        { html: '<p class="styled">Every odd page header content</p>', css: templateCSS, type: 'odd' }
    ],
    footer: [
        // Footer template for all footers (without the `type` property).
        { html: '<p class="styled">Default footer content</p>', css: templateCSS },
        // Footer template only for the first page of the document.
        { html: '<p class="styled">First document page footer content</p>', css: templateCSS, type: 'first' },
        // Footer template for every even page of the document.
        { html: '<p class="styled">Every even page footer content</p>', css: templateCSS, type: 'even' },
        // Footer template for every odd page of the document.
        { html: '<p class="styled">Every odd page footer content</p>', css: templateCSS, type: 'odd' }
    ],
}

As you can see, the header and footer options take an array of objects that define templates for the particular type of page. If you want to have consistent templates no matter the page, you can define only the default headers/footers template (Note: This setting misses the type property on purpose).

Regarding CSS, you can style the header and footer using the same supported properties as used for styling the whole document.

For more details, refer to the CKEditor Cloud Services HTML to DOCX converter’s documentation.

Let’s discover what it looks like in V2 API.

const templateCSS = '.styled { color: #4b22aa; text-align: center; }'

const converterOptions = {
    headers: {
        // Header template for all headers.
        default : {
            html: '<p class="styled">Default header content</p>',
            css: templateCSS
        },
        // Header template only for the first page of the document.
        first: {
            html: '<p class="styled">First document page header content</p>',
            css: templateCSS
        },
        // Header template for every even page of the document.
        even: {
            html: '<p class="styled">Every even page header content</p>',
            css: templateCSS
        },
        // Header template for every odd page of the document.
        odd: {
            html: '<p class="styled">Every odd page header content</p>',
            css: templateCSS
        }
    },
    footers: {
        // Footer template for all footers.
        default: {
            html: '<p class="styled">Default footer content</p>',
            css: templateCSS
        },
        // Footer template only for the first page of the document.
        first: {
            html: '<p class="styled">First document page footer content</p>',
            css: templateCSS
        },
        // Footer template for every even page of the document.
        even: {
            html: '<p class="styled">Every even page footer content</p>',
            css: templateCSS
        },
        // Footer template for every odd page of the document.
        odd: {
            html: '<p class="styled">Every odd page footer content</p>',
            css: templateCSS
        }
    },
}

It is not an array anymore. There are only the headers and footers objects which contain other objects where the key is a type of your header/footer.

# Setting the base URL

To enable proper resolution of relative URLs for images and links, you need to pass the base_url option:

const conversionOptions = {
    base_url: 'https://ckeditor.com'
};

For an editor’s content like the one below:

<p><a href="/">Our company homepage</a></p>
<p><img src="/logo.svg" alt="Our logo"></p>

this option will result in resolving these URLs into their absolute forms:

  • / will become https://ckeditor.com,
  • /logo.svg will become https://ckeditor.com/logo.svg.

# Comments and suggestions

When your editor has collaboration features (like comments and track changes) enabled, the export to Word feature will take care of setting the configuration needed by the CKEditor Cloud Services HTML to DOCX converter. But if for some reason you need to pass your own data, you can do this via the REST API converter options.

Note: Currently formatting suggestions are not supported. Only insertions and deletions will work correctly with the CKEditor Cloud Services HTML to DOCX converter.

# Other

  • By default, the generated Word file is encoded with UTF-8.

# Known issues

Not all CKEditor 5 plugins and features are compatible with export to Word at the moment. Feel free to contact us if you are interested in any of these features specifically. Here is a list of known issues:

# Unsupported plugins

  • Media embed – Embedded media will not be included in the exported document.
  • MathType – Supported partially. The plugin parses the data but not the formatting, losing some of the math operators and not reproducing a usable equation in the effecting file.

# Unsupported features

  • Inline and block formatting suggestions – Such suggestions are not included in the exported document.
  • Comments applied to whole widgets (like tables) – Such comments are not included in the exported document.
  • The complementary pagination feature provides live preview of the document’s page breaks, ensuring the output document looks correct.
  • If you would like to export your content to a portable, universal format, using the export to PDF feature will allow you to generate PDF files out of your editor-created content.

# Common API

The ExportWord plugin registers:

  • The 'exportWord' button.

  • The 'exportWord' command implemented by ExportWordCommand.

    You can execute the command using the editor.execute() method. However, if you want to use the command directly (not via the toolbar button), you need to specify the the options or gather them from the configuration. Otherwise, the command will not execute properly.

    The example code to use the command directly should look like this:

    // Start generating a Word file based on the editor content and the plugin configuration.
    const config = editor.config.get( 'exportWord' );
    editor.execute( 'exportWord', config );