Import from Word plugin

This plugin is only available as a paid add-on to a TinyMCE subscription.

The Import from Word plugin lets you import .docx (Word document) or .dotx (Word template) files into the editor. The process preserves formatting and rich media.

Interactive example

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="importword">
  <h1 style="font-size: 1.5em; color: black; margin-top: 0; text-align: left;">Import from MS Word</h2>
  <ol style="padding-left: 20px; margin: 10px 0;">
      <li style="margin-bottom: 10px;">Click the <strong>Import from Word</strong> button in the toolbar or select <strong>File &gt; Import from Word</strong> in the menu.</li>
      <li style="margin-bottom: 10px;">Select the DOCX file to upload.</li>
      <li style="margin-bottom: 10px;">Edit the imported content however you wish.</li>
  </ol>
  <p style="font-size: 0.9em; color: #555; text-align: left; margin-top: 15px;">Learn more about <strong>Import from Word</strong> and our other document converters (<a href="https://tiny.cloud/tinymce/features/export-word/" style="color: #0066cc; text-decoration: none; border-bottom: 1px dotted #0066cc;">Export to Word</a> and <a href="https://tiny.cloud/tinymce/features/export-pdf" style="color: #0066cc; text-decoration: none; border-bottom: 1px dotted #0066cc;">Export to PDF</a>) at <a href="https://tiny.cloud" style="color: #0066cc; text-decoration: none; border-bottom: 1px dotted #0066cc;">https://tiny.cloud</a>.</p>
</textarea>
tinymce.init({
  selector: 'textarea#importword',
  height: '800px',
  plugins: [
    "importword", "advlist", "anchor", "autolink", "charmap", "code", "fullscreen",
    "help", "image", "insertdatetime", "link", "lists", "media",
    "preview", "searchreplace", "table", "visualblocks",
],
toolbar: "undo redo | importword | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image",
});

Basic setup using the Tiny Cloud service

To add the Import from Word plugin to the editor, add importword to the plugins option in the editor configuration.

For example:

tinymce.init({
  selector: 'textarea',
  plugins: 'importword',
  toolbar: 'importword',
// Below option is only required when using the cloud-based Import from Word plugin from Tiny.Cloud.
// Avoid setting it up during the trial period.
  importword_token_provider: () => { // required when using the Import from Word plugin with Tiny Cloud.
    return fetch('http://localhost:3000/jwt', { // specify your token endpoint
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
    }).then(response => response.json());
  },
});

For more infomation on the importword_token_provider option, see importword_token_provider.

The Import from Word plugin requires JWT authentication when using the Tiny Cloud service.

  • Configure the importword_token_provider option to specify the endpoint for retrieving a valid JWT token.

For more information on how to set up JWT authentication with Import from Word, see examples:

Trial period behavior:

  • The Import from Word plugin runs in evaluation mode and adds a watermark to exported content.

  • The importword_token_provider option is "not required" during the trial period.

  • If the trial period "expires" or the plugin lacks the necessary entitlement, it becomes non-functional.

  • Attempting to use JWT authentication during the trial will result in an error.

Basic setup using the self-hosted service

To use the self-hosted version of the Import from Word plugin, you need to set the importword_service_url option to the URL of the service.

Example:
tinymce.init({
  selector: 'textarea',
  plugins: 'importword',
  toolbar: 'importword',
  importword_service_url: 'http://localhost:8080/' // Update with the URL of the service you are using such  as 'http://myserver.com/'
});

The importword_service_url option automatically appends /v2/convert/docx-html to the URL provided, so only the base URL is required. For example, if the service is hosted at http://localhost:8080/v2/convert/docx-html, the importword_service_url option should be set to http://localhost:8080/. When using in production, ensure that the importword_service_url is updated to the production URL such as https://myserver.com/.

Options

The following configuration options affect the behavior of the Import from Word plugin.

importword_service_url

The importword_service_url option sets the URL endpoint for the DOCX-to-HTML conversion service.

This option is required when configuring the Import from Word plugin for on-premise setups. If you require access to this feature, please contact us. For detailed instructions on deploying the Import from Word service server-side component using Docker, refer to the on-premises documentation.

When using a custom host, set the importword_service_url option in your TinyMCE configuration to match your host. For example, if your custom host is mycustomhost.com, set the URL to https://mycustomhost.com/.

Type: String

Example: Setting up importword_service_url

tinymce.init({
  selector: 'textarea',
  plugins: 'importword',
  toolbar: 'importword',
  importword_service_url: '<service-URL>' // required for On-premise setups only
});

  • If the importword_service_url option is not configured, a console.error will display: The Import from Word plugin requires the importword_service_url to be configured.

  • If the URL provided is invalid, a console.error will display: The value provided in importword_service_url is not a valid URL.

importword_token_provider

The importword_token_provider option enables integration with a token-based authentication service for importing Word documents. It provides a mechanism to fetch an authentication token from a specified endpoint. This ensures that the import process can securely communicate with the server.

Type: Function

Default value: undefined

Return data: Token object

Example: using importword_token_provider

tinymce.init({
  selector: 'textarea',
  plugins: 'importword',
  toolbar: 'importword',
  importword_token_provider: () => { // required when using the Import from Word plugin with Tiny Cloud.
    return fetch('http://localhost:3000/jwt', { // specify your token endpoint
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
    }).then(response => response.json());
  },
});

Data structure for the JWT token

The object containing the valid encoded token must match the following structure:

{
  token: "<encoded JWT string>"
}
Field Type Required? Description

token

string

required

A Base64-encoded JSON Web Token (JWT) used for authentication and authorization.

importword_converter_options

Type: String

As of TinyMCE 7.5.0, the default value of the importword_converter_options setting has been updated to the following:
Default value:
importword_converter_options: {
  formatting: {
    styles: 'inline',
    resets: 'inline',
    defaults: 'inline',
  }
}

The importword_converter_options setting allows you to customize the behavior of the Import from Word plugin when converting Word documents to HTML.

Example: using importword_converter_options
tinymce.init({
  selector: 'textarea',
  plugins: 'importword',
  toolbar: 'importword',
  importword_service_url: '<service_URL>', // required if using On-premises service
  importword_converter_options: {
    formatting: {
      resets: 'inline',
      defaults: 'inline',
      styles: 'none',
    }
  }
});
For more information on the available converter options, refer to the Import from Word API documentation.

Toolbar buttons

The Import from Word plugin provides the following toolbar buttons:

Toolbar button identifier Description

importword

Opens the import dialog so the user can select a specific .docx or .dotx file.

These toolbar buttons can be added to the editor using:

The Import from Word plugin provides the following menu items:

Menu item identifier Default Menu Location Description

importword

File

Opens the import dialog so the user can select a specific .docx or .dotx file.

These menu items can be added to the editor using:

Commands

The Import from Word plugin provides the following TinyMCE commands.

Command Description

ImportWord

Opens a file picker, that allows content from either a .docx or .dotx file to be imported into the editor.
Example
document.querySelector('button').addEventListener('click',
  () => tinymce.activeEditor.execCommand('ImportWord')
);
The ImportWord command cannot be directly invoked through a script at the top level or from the browser console. Instead, it necessitates a specific user action within the user interface, such as clicking a toolbar button. To ensure correct execution, the command should be called within the scope of an event handler tied to a specific user interaction, as shown in the example.

API Reference

Explore the comprehensive API documentation for the Import from Word Premium plugin at Import from Word API Reference Documentation.