Options for the PowerPaste plugin

Options

paste_as_text

This option enables you to set the default state of the Paste as text menu item under the Edit menu dropdown. It’s disabled by default.

Type: Boolean

Default value: false

Possible values: true, false

Example: using paste_as_text

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  toolbar: 'paste',
  paste_as_text: true
});

paste_merge_formats

This option enables the merge format feature when pasting content. This merges identical text format elements to reduce the number of HTML elements produced. For example: <b>abc <b>bold</b> 123</b> becomes <b>abc bold 123</b> since the inner format is redundant. This option is enabled by default but can be disabled if retaining nested or identical format elements is important.

Type: Boolean

Default value: true

Possible values: true, false

Example: using paste_merge_formats

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  toolbar: 'paste',
  paste_merge_formats: false
});

paste_tab_spaces

This option controls how many spaces are used to represent a tab character in HTML when pasting plain text content. By default, when tab characters are pasted they will be converted into 4 sequential space characters.

Type: Number

Default value: 4

Example: using paste_tab_spaces

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  toolbar: 'paste',
  paste_tab_spaces: 2
});

powerpaste_word_import

This option controls how content pasted from Microsoft Word is filtered.

Type: String or Function

Default value: 'prompt'

Possible values: 'clean', merge, prompt or a Function

What the supported string-based values do:

Value Behavior

clean

Preserves the structure of the content such as headings, tables, and lists.

Removes inline styles and classes.

This results in simple content that uses the site’s CSS stylesheet while retaining the semantic structure of the original document.

merge

Preserves the inline formatting and structure of the original document.

Removes invalid and proprietary styles, tags and attributes.

This ensures the HTML is valid while more closely matching the original document formatting.

prompt

Prompts the user to choose between the clean and merge options after attempting to paste HTML content.

Alternatively, this option can take an asynchronous function that returns a Promise which will resolve with the string clean or merge. This allows the paste mode to be dynamically set each time a user pastes relevant content. It can be used, for example, to replicate the prompt dialog with a custom dialog.

When using the Windows operating system, copying and pasting content from Microsoft Word 2013 (or later) in "Protected View" will result in plain, unformatted text. This is due to how Protected View interacts with the clipboard.

Example: powerpaste_word_import using an asynchronous function

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  powerpaste_word_import: () => new Promise((resolve) => {
    // use a native confirm dialog to prompt the user to choose between clean and merge
    if (confirm('Would you like to keep formatting?')) {
      resolve('merge');
    } else {
      resolve('clean');
    }
  })
});

powerpaste_googledocs_import

This option controls how content pasted from Google Docs is filtered.

Type: String or Function

Default value: 'prompt'

Possible values: 'clean', merge, prompt or a Function

What the supported string-based values do:

Value Behavior

clean

Preserves the structure of the content such as headings, tables, and lists.

Removes inline styles and classes.

This results in simple content that uses the site’s CSS stylesheet while retaining the semantic structure of the original document.

merge

Preserves the inline formatting and structure of the original document.

Removes invalid and proprietary styles, tags and attributes.

This ensures the HTML is valid while more closely matching the original document formatting.

prompt

Prompts the user to choose between the clean and merge options after attempting to paste HTML content.

Alternatively, this option can take an asynchronous function that returns a Promise which will resolve with the string clean or merge. This allows the paste mode to be dynamically set each time a user pastes relevant content. It can be used, for example, to replicate the prompt dialog with a custom dialog.

Example: powerpaste_googledocs_import using an asynchronous function

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  powerpaste_googledocs_imports: () => new Promise((resolve) => {
    // use a native confirm dialog to prompt the user to choose between clean and merge
    if (confirm('Would you like to keep formatting?')) {
      resolve('merge');
    } else {
      resolve('clean');
    }
  })
});

powerpaste_html_import

This option controls how content pasted from sources other than Microsoft Word and Google Docs are filtered.

Type: String

Default value: 'clean'

Possible values: 'clean', merge, prompt

What the supported string-based values do:

Value Behavior

clean

Preserves the structure of the content such as headings, tables, and lists.

Removes inline styles and classes.

This results in simple content that uses the site’s CSS stylesheet while retaining the semantic structure of the original document.

merge

Preserves the inline formatting and structure of the original document.

Removes invalid and proprietary styles, tags and attributes.

This ensures the HTML is valid while more closely matching the original document formatting.

prompt

Prompts the user to choose between the clean and merge options after attempting to paste HTML content.
Pasting from a TinyMCE instance to a TinyMCE instance

Content copied or cut from a TinyMCE instance and then pasted into a TinyMCE instance (eg, copyied or cut from one part of a TinyMCE document and pasted into another place within the same document) is not processed by powerpaste_html_import.

In this circumstance, whatever is copied or cut is exactly what is pasted.

example: using powerpaste_html_import to require a prompt when pasting html

tinymce.init({
  selector: 'textarea',  // change this value according to your html
  plugins: 'powerpaste',
  powerpaste_html_import: 'prompt',
});

This option enables or disables the automatic linking of text that resembles URLs in pasted content.

Type: Boolean

Default value: true

Possible values: true, false

Setting the powerpaste_autolink_urls option to false overrides the auto-linking behavior of the smart_paste option.

Example: Disable auto-linking of URLs

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  powerpaste_autolink_urls: false,
});

powerpaste_allow_local_images

When set to true, Base64 encoded images using a data URI in the copied content will not be removed after pasting.

Type: Boolean

Default value: true

Possible values: true, false

If you configure PowerPaste to allow local images, you can have TinyMCE automatically upload Base64 encoded images for conversion back to a standard image as described on the image upload documentation.

powerpaste_block_drop

Due to browser limitations, it is not possible to filter content that is dragged and dropped into the editor. When powerpaste_block_drop is set to true dragging and dropping content into the editor will be disabled. This prevents the unfiltered content from being introduced. Copy and paste is still enabled.

Type: Boolean

Default value: false

Possible values: true, false

Example: using powerpaste_block_drop

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  powerpaste_block_drop: false
});

powerpaste_clean_filtered_inline_elements

This option allows for configuration of PowerPaste’s "clean" paste filters for inline elements. These filters are run when powerpaste_word_import or powerpaste_html_import are set to "clean"; or when a user clicks the "Remove formatting" button on the paste prompt dialog.

The list of inline elements that should be removed on paste can be specified by setting powerpaste_clean_filtered_inline_elements to a comma-separated string of inline element tag names.

Type: A comma-separated string or Array

Default value: []

Example: powerpaste_clean_filtered_inline_elements

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  powerpaste_word_import: 'clean', // optional
  powerpaste_html_import: 'clean', // optional
  powerpaste_clean_filtered_inline_elements: 'strong, em, b, i, u, strike, sup, sub, font'
});

powerpaste_keep_unsupported_src

Due to browser limitations, PowerPaste is not able to support all image types supported by Microsoft Word and Microsoft Excel. When powerpaste_keep_unsupported_src is set to true, PowerPaste will store the original src of unsupported images in a data-image-src attribute on the pasted image element. This enables developers to add further image support via post-processing.

For example, browsers do not allow PowerPaste to access the file system. If your application has access to the file system, setting powerpaste_keep_unsupported_src to true may allow you to replace unsupported images during post-processing using the original file paths.

Type: Boolean

Default value: false

Possible values: true, false

Example: using powerpaste_keep_unsupported_src

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  powerpaste_keep_unsupported_src: true
});

smart_paste

The smart_paste function will:

  • Detect text that resembles a URL and change the text to a hyperlink.

  • Detect text that resembles the URL for an image and will try to replace the text with the image.

To disable the smart_paste functionality, set smart_paste to false. To configure which image file types are recognised, see Image & file options - images_file_types.

Type: Boolean

Default value: true

Possible values: true, false

Setting the powerpaste_autolink_urls option to false overrides the auto-linking feature of the smart_paste option.

Example: using smart_paste

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'powerpaste',
  toolbar: 'paste',
  smart_paste: false
});

images_file_types

This option configures which image file formats are accepted by the editor. Changing this option will adjust the following editor behaviour:

  • Which image file formats are allowed to be uploaded in the Image dialog.

  • Which image file formats are recognized and placed in an img element by the core paste and PowerPaste smart_paste functionality.

Type: String

Default value: 'jpeg,jpg,jpe,jfi,jif,jfif,png,gif,bmp,webp'

Possible values: A list of valid web image file extensions. For a list of possible values see: MDN Web Docs - Image file type and format guide.

Example: using images_file_types

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  images_file_types: 'jpg,svg,webp'
});

Advanced Options

Pre-filtering and post-filtering callbacks

Developers can add custom filtering before and after PowerPaste's filters are run using the pre-filtering and post-filtering callbacks. These can be added as init options or at runtime using event listeners.

These callbacks are also triggered by the core paste functionality, but when triggered by PowerPaste they are passed more data.

paste_preprocess

This option allows you to run custom filtering on the content from the clipboard before it is run through PowerPaste’s filters. The callback is passed two arguments: the PowerPaste plugin instance and an object containing event data. This object contains:

  • Standard paste event data.

  • content - A string containing the content to be pasted.

  • mode - A string indicating whether PowerPaste is in clean, merge, or auto mode.

  • source - A string indicating which kind of filtering PowerPaste will run based on the source of the content. This will return html, msoffice, googledocs, image, imagedrop, plaintext, text, or invalid.

The mode 'auto' is used when the content source does not have formatting to "clean" or "merge". For example, when pasting an image with no text or markup content.

Type: Function

Example TinyMCE configuration:

const yourCustomFilter = (content) => {
  // Implement your custom filtering and return the filtered content
  return content;
};

tinymce.init({
  selector: 'textarea',
  plugins: 'powerpaste',
  paste_preprocess: (pluginApi, data) => {
    console.log(data.content, data.mode, data.source);
    // Apply custom filtering by mutating data.content
    // For example:
    const content = data.content;
    const newContent = yourCustomFilter(content);
    data.content = newContent;
  }
});

paste_postprocess

This option allows you to run custom filtering on the pasted content after it is run through PowerPaste’s filters. The callback is passed two arguments: the PowerPaste plugin instance and an object containing event data. This object contains:

  • Standard paste event data.

  • node - A DOM node containing the DOM structure of the filtered paste content.

  • mode - A string indicating whether PowerPaste is in clean, merge, or auto mode.

  • source - A string indicating which kind of filtering PowerPaste will run based on the source of the content. This will return html, msoffice, googledocs, image, imagedrop, plaintext, text, or invalid.

The mode 'auto' is used when the content source does not have formatting to "clean" or "merge". For example, when pasting an image with no text or markup content.

Type: Function

Example TinyMCE configuration:

tinymce.init({
  selector: 'textarea',
  plugins: 'powerpaste',
  paste_postprocess: (pluginApi, data) => {
    console.log(data.node, data.mode, data.source);
    // Apply custom filtering by mutating data.node
    const additionalNode = document.createElement('div');
    additionalNode.innerHTML = '<p>This will go before the pasted content.</p>';
    data.node.insertBefore(additionalNode, data.node.firstElementChild);
  }
});