The TinyMCE Web Component integration

TinyMCE Web Component quick start guide

The Official TinyMCE Web Component integrates TinyMCE into Web Component projects. This procedure creates a HTML page containing a TinyMCE editor based on our Basic example.

Procedure

To add a TinyMCE editor to a web page using the TinyMCE Web Component:

  1. Add the DOCTYPE element to the target page, such as:

    <!DOCTYPE html>

    The DOCTYPE declaration is required for the editor to function correctly.

  2. Add the following meta elements to the head of page:

    <head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>

    The second meta element is required for the editor to function correctly on mobile devices. For information on the viewport meta element, see: MDN Web Docs - Using the viewport meta tag to control layout on mobile browsers.

  3. Add a script element sourcing the TinyMCE Web Component (tinymce-webcomponent.js), such as:

    <script src="https://cdn.jsdelivr.net/npm/@tinymce/tinymce-webcomponent@1/dist/tinymce-webcomponent.min.js"></script>

    The tinymce-webcomponent can also be sourced from npmjs.

  4. (optional) Add a script element sourcing TinyMCE, such as:

    <script src="/path/to/tinymce.min.js"></script>

    If a script element sourcing TinyMCE is not provided, the TinyMCE Web Component will load TinyMCE from the Tiny Cloud. For information on the available options for sourcing TinyMCE, see: Loading TinyMCE.

  5. Add a tinymce-editor element where the editor should appear.

    <tinymce-editor></tinymce-editor>

    The default TinyMCE editor will load at this location if the page is opened in a web browser.

Example: Adding the TinyMCE Web Component to a HTML page

The following example shows the TinyMCE Web Component in a HTML page, with:

  • Various TinyMCE configuration options set using attributes.

  • TinyMCE sourced from the Tiny Cloud.

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<p>Welcome to the TinyMCE Web Component example!</p> 
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>

    <!--
      Adding the `tinymce-editor` element with various options set as attributes.
    -->
    <tinymce-editor
      api-key="no-api-key"
      height="500"
      menubar="false"
      plugins="advlist autolink lists link image charmap print preview anchor
      searchreplace visualblocks code fullscreen
      insertdatetime media table paste code help wordcount"
      toolbar="undo redo | formatselect | bold italic backcolor |
      alignleft aligncenter alignright alignjustify |
      bullist numlist outdent indent | removeformat | help"
      content_style="body
      {
        font-family:Helvetica,Arial,sans-serif;
        font-size:14px
      }"
      >

      <!-- Adding some initial editor content -->
      &lt;p&gt;Welcome to the TinyMCE Web Component example!&lt;/p&gt;

    </tinymce-editor>

    <!--
      Sourcing the `tinymce-webcomponent` from jsDelivr,
      which sources TinyMCE from the Tiny Cloud.
    -->
    <script src="https://cdn.jsdelivr.net/npm/@tinymce/tinymce-webcomponent@1/dist/tinymce-webcomponent.min.js"></script>

  </body>
</html>
/*

No Javascript is required for this configuration.

*/

TinyMCE Web Component technical reference

Covered in this section:

Use a cloud version of the TinyMCE Web Component integration

To use a cloud version of Web Component, the integration is accessible from JSDelivr.

For example:

<script src="https://cdn.jsdelivr.net/npm/@tinymce/tinymce-webcomponent@1/dist/tinymce-webcomponent.min.js"></script>

Installing the TinyMCE Web Component integration

To add the TinyMCE Web Component integration to a JavaScript project, on command line or command prompt, run the following:

  • NPM users:

    npm i --save @tinymce/tinymce-webcomponent

  • Yarn users:

    yarn add @tinymce/tinymce-webcomponent

Loading TinyMCE

The integration requires both the TinyMCE Web Component (tinymce-webcomponent.min.js) and TinyMCE (tinymce.min.js).

If TinyMCE is not available for TinyMCE Web Component, the latest version of TinyMCE will be automatically loaded from the Tiny Cloud.

To use TinyMCE Web Component with a self-hosted copy of TinyMCE, ensure that the self-hosted copy of TinyMCE can be loaded in the same location as the TinyMCE Web Component (such as the same web page).

To use TinyMCE from the Tiny Cloud, add the api-key attribute to the tinymce-editor element with an API from Tiny Account.

Configuring the editor

The editor is configured by setting attributes on the tinymce-editor custom element. All attributes may be represented as strings, however some attributes will accept boolean or number inputs. Where an array, object, or function is a valid input; examples have been provided.

Setting the initial content

To set the initial editor content, add encoded HTML to the tinymce-editor element as content, such as:

<tinymce-editor>
  <p>This will be the initial content of the editor.</p>
</tinymce-editor>

The editor will load the text content in the tinymce-editor element as the initial HTML.

The HTML must be encoded as text to prevent injected javascript from running, which may have an unintended impact on the surrounding document.

Loading plugins

To add plugins and extend the functionality of the editor, add a string of plugin identifiers using the plugins attribute, such as:

<tinymce-editor plugins="advlist autolink link image lists charmap print preview"></tinymce-editor>

For a list of available plugins, see: Add plugins to TinyMCE.

Setting the editor width

To set the width of the editor (content area and user interface), use the width attribute. For example:

Setting a pixel-based editor width
<tinymce-editor width="300"></tinymce-editor>
Setting a CSS unit based editor width
<tinymce-editor width="50%"></tinymce-editor>

Setting the editor height

To set the height of the editor (content area and user interface), use the height attribute. For example:

Setting a pixel-based editor height
<tinymce-editor height="300"></tinymce-editor>
Setting a CSS unit based height
<tinymce-editor height="15em"></tinymce-editor>

Setting the toolbar

To set the editor toolbar buttons, use the toolbar attribute. For example:

<tinymce-editor toolbar="undo redo | styleselect | bold italic | alignleft aligncenter alignright alignjustify | outdent indent"></tinymce-editor>

The toolbar attribute accepts a space-separated string of toolbar buttons with pipe characters (|) for grouping buttons. For a list of available toolbar buttons, see: Toolbar Buttons Available for TinyMCE.

Disabling the toolbar

To disable the toolbar, set the toolbar attribute to "false". For example:

<tinymce-editor toolbar="false"></tinymce-editor>

Setting the toolbar mode

To control the behavior of the toolbar, set the toolbar_mode attribute. For example:

<tinymce-editor toolbar_mode="floating"></tinymce-editor>

For information on the available toolbar modes, see: User interface options - toolbar_mode.

Setting the menu bar

To set the menus shown on the editor menu bar, add the menubar attribute. For example:

<tinymce-editor menubar="file edit insert view format table tools help"></tinymce-editor>

To disable or remove the menu bar, set the menubar attribute to "false". For example:

<tinymce-editor menubar="false"></tinymce-editor>

To change the menu items shown in the menus, or define custom menus, set the menu configuration option using the config attribute.

For information on:

Setting context menu

To change the context menu sections that can be shown in the editor context menu, use the contextmenu attribute. Such as:

<tinymce-editor plugins="link image table" contextmenu="link image table"></tinymce-editor>

To disable the context menu, set the contextmenu attribute to "false". For example:

<tinymce-editor contextmenu="false"></tinymce-editor>

For a list of available context menu sections, see: Available context menu sections. For information on context menus, see: User interface options - contextmenu.

Setting the quick-insert toolbar

The quick-insert toolbar is shown when a new line is added, providing buttons for inserting objects such as tables and images.

To add a quick-insert toolbar, add "quickbars" to the plugins attribute. To change the quick-insert toolbar, set the quickbars_insert_toolbar attribute, such as:

<tinymce-editor plugins="quickbars hr pagebreak" quickbars_insert_toolbar="quickimage quicktable quicklink | hr pagebreak"></tinymce-editor>

The quickbars_insert_toolbar attribute accepts a space-separated string of toolbar buttons with pipe characters (|) for grouping buttons. For a list of available toolbar buttons, see: Toolbar Buttons Available for TinyMCE.

To disable the quick-insert toolbar, set the quickbars_insert_toolbar attribute to "false". For example:

<tinymce-editor plugins="quickbars" quickbars_insert_toolbar="false"></tinymce-editor>

Setting the quick-selection toolbar

The quick-selection toolbar is shown when text is selected, providing formatting buttons such as: bold, italic, and link.

To add a quick-selection toolbar, add "quickbars" to the plugins attribute. To change the quick-selection toolbar, set the quickbars_selection_toolbar attribute, such as:

<tinymce-editor plugins="quickbars" quickbars_selection_toolbar="bold italic | formatselect | quicklink blockquote"></tinymce-editor>

The quickbars_selection_toolbar attribute accepts a space-separated string of toolbar buttons with pipe characters (|) for grouping buttons. For a list of available toolbar buttons, see: Toolbar Buttons Available for TinyMCE.

To disable the quick-selection toolbar, set the quickbars_selection_toolbar attribute to "false". For example:

<tinymce-editor plugins="quickbars" quickbars_selection_toolbar="false"></tinymce-editor>

Setting content stylesheets

To set the CSS for the content area of the editor, use the content_css attribute.

For example, to use one of the TinyMCE CSS configurations:

<tinymce-editor content_css="writer"></tinymce-editor>

To use a custom CSS file, provide a relative or abolute path to the css file, such as:

<tinymce-editor content_css="path/to/mycontent.css"></tinymce-editor>

Tiny recommends using:

  • The content_style option to apply a small set of CSS styles.

  • The content_css option for applying large or complex CSS configurations.

For information on the content_css option, see: Content appearance options - content_css.

Setting content styling

To apply a small set of CSS styles to the editor, use the content_style attribute. For example:

<tinymce-editor content_style="div { margin: 10px; border: 5px solid red; padding: 3px; }"></tinymce-editor>

Tiny recommends using:

  • The content_style option to apply a small set of CSS styles.

  • The content_css option for applying large or complex CSS configurations.

For information on the content_style option, see: Content appearance options - content_style.

Setting PowerPaste’s word import method

This setting only applies if the PowerPaste plugin (powerpaste) is enabled.

To control how content pasted from Microsoft Word is filtered, use the powerpaste_word_import attribute. For example:

<tinymce-editor powerpaste_word_import="merge"></tinymce-editor>

For information on the powerpaste_word_import option, including supported values, see: The PowerPaste plugin - powerpaste_word_import.

Setting PowerPaste’s html import method

This setting only applies if the PowerPaste plugin (powerpaste) is enabled.

To control how content pasted from sources other than Microsoft Word is filtered, use the powerpaste_html_import attribute. For example:

<tinymce-editor powerpaste_html_import="prompt"></tinymce-editor>

For information on the powerpaste_html_import option, including supported values, see: The PowerPaste plugin - powerpaste_html_import.

Setting PowerPaste to allow local images

This setting only applies if the PowerPaste plugin (powerpaste) is enabled.

To prevent Base64 encoded images with a data URI from being pasted into the editor, set powerpaste_allow_local_images to "false". For example:

<tinymce-editor powerpaste_allow_local_images="false"></tinymce-editor>

For information on the powerpaste_allow_local_images option, including supported values, see: The PowerPaste plugin - powerpaste_allow_local_images.

Showing resize handles

The resize attribute gives you the ability to disable the resize handle or set it to resize the editor both horizontal and vertically. By default the editor will resize vertically (resize="true").

To remove the resize handle and disable resizing of the editor, set the resize attribute to "false". Such as:

<tinymce-editor resize="false"></tinymce-editor>

To allow the user to resize the editor both horizontally and vertically, set the resize attribute to "both". For example:

<tinymce-editor resize="both"></tinymce-editor>

For information on the resize option, see: User interface options - resize.

Setting the editor setup function

To execute a javascript callback before the editor instance is rendered, use the setup attribute. For example:

<script>
  function setupEditor(editor) {
    editor.on('click', function () {
      console.log('Editor was clicked');
    });
  }
</script>
<tinymce-editor setup="setupEditor"></tinymce-editor>

For information on the setup option, see: Integration and setup options - setup.

Setting the editor skin

To apply a custom skin to the editor, use the skin attribute. For example:

<tinymce-editor skin="borderless"></tinymce-editor>

For information on:

Setting the images upload URL

To specify the location of a server-side upload handler, use the images_upload_url attribute. For example:

<tinymce-editor images_upload_url="postAcceptor.php"></tinymce-editor>

The upload handler should return the location of the uploaded file in the following format:

{ "location": "folder/sub-folder/new-location.png" }

For information on using the images_upload_url, see: Image & file options - images_upload_url.

Setting the images upload handler

To specify custom image upload handler callback function, use the images_upload_handler attribute.

<script>
function example_image_upload_handler (blobInfo, success, failure, progress) {
  var xhr, formData;

  xhr = new XMLHttpRequest();
  xhr.withCredentials = false;
  xhr.open('POST', 'postAcceptor.php');

  xhr.upload.onprogress = function (e) {
    progress(e.loaded / e.total * 100);
  };

  xhr.onload = function() {
    var json;

    if (xhr.status === 403) {
      failure('HTTP Error: ' + xhr.status, { remove: true });
      return;
    }

    if (xhr.status < 200 || xhr.status >= 300) {
      failure('HTTP Error: ' + xhr.status);
      return;
    }

    json = JSON.parse(xhr.responseText);

    if (!json || typeof json.location != 'string') {
      failure('Invalid JSON: ' + xhr.responseText);
      return;
    }

    success(json.location);
  };

  xhr.onerror = function () {
    failure('Image upload failed due to a XHR Transport error. Code: ' + xhr.status);
  };

  formData = new FormData();
  formData.append('file', blobInfo.blob(), blobInfo.filename());

  xhr.send(formData);
};

</script>
<tinymce-editor images_upload_handler="example_image_upload_handler"></tinymce-editor>

For information on using the images_upload_handler option, see: Image & file options - images_upload_handler.

Setting the images upload base path

To specify the basepath to prepend to URLs returned from the configured images_upload_url script, use the images_upload_base_path attribute. For example:

<tinymce-editor images_upload_url="postAcceptor.php" images_upload_base_path="/some/basepath"></tinymce-editor>

For information on using the images_upload_base_path option, see: Image & file options - images_upload_base_path.

Setting the images upload to have credentials

To receive credentials (such as cookies, authorization headers, or TLS client certificates) for cross-domain image uploads, set the images_upload_credentials attribute to "true".

<tinymce-editor images_upload_url="postAcceptor.php" images_upload_credentials="true"></tinymce-editor>

For information on using the images_upload_credentials option, see: Image & file options - images_upload_credentials.

Setting the images upload to reuse filenames

To force the editor to use the same filename for a given image, regardless of the number of times it is uploaded within a given instance, set the images_reuse_filename attribute to "true".

<tinymce-editor images_upload_url="postAcceptor.php" images_reuse_filename="true"></tinymce-editor>

For information on using the images_reuse_filename option, see: Image & file options - images_reuse_filename.

Setting the icon pack

To apply a bundled set of custom or premium icons to the editor, use the icons attribute. For example:

<tinymce-editor icons="material"></tinymce-editor>

Use this attribute if the icon pack is bundled with TinyMCE (including custom icon packs). If the icon pack is hosted on a web site, use the icons_url attribute.

For information on:

Setting the icon pack URL

To apply a hosted set of custom or premium icons to the editor, use the icons_url attribute. For example:

<tinymce-editor icons_url="https://www.example.com/icons/material/icons.js"></tinymce-editor>

Use this attribute if the icon pack is hosted on a web site. If the icon pack is bundled with TinyMCE (including custom icon packs), use the icons attribute.

For information on:

Setting additional configuration options

To configure any TinyMCE option that does not have a corresponding attribute, use the config attribute. For example:

<script>
  window.myConfig = {
    height: 500,
    template_selected_content_classes: 'selcontent',
    templates: [ {
      title: 'My Template', description: 'This is my template.',
      content: '<p>Hello, [.selcontent]#this statement will be replaced.#</p>'
    } ],
    spellchecker_dialog: true,
    spellchecker_ignore_list: ['Ephox', 'Moxiecode']
  };
</script>
<tinymce-editor
  config="myConfig"
  width="50%"
  toolbar="undo redo | bold italic | forecolor backcolor | template | alignleft aligncenter alignright alignjustify | bullist numlist | link | spellchecker"
  plugins="lists link noneditable searchreplace table template tinymcespellchecker wordcount">
</tinymce-editor>

Configuration options that have an attribute can also be passed to the config attribute.

Event binding

There are two methods to bind events for the TinyMCE Web Component.

  • The setup attribute, as described in Setting the editor setup function. For example:

    <script>
  function setupEditor(editor) {
    editor.on('click', function () {
      console.log('Editor was clicked');
    });
  }
</script>
<tinymce-editor setup="setupEditor"></tinymce-editor>

  • The on- attributes, such as the on-NodeChange attribute. For example:

    <script>
  function changeHandler(evt) {
    console.log('The ' + evt['type'] + ' event was fired.');
  }
</script>
<tinymce-editor on-Change="changeHandler"></tinymce-editor>

    If these attributes are later removed, the event will be automatically unbound. For the full list of supported on- attributes, see: Supported browser events and Supported TinyMCE events.

Supported browser events

Bind the following browser events using the corresponding TinyMCE Web Component attribute.

Browser event Attribute

BeforePaste

on-BeforePaste

Blur

on-Blur

Click

on-Click

ContextMenu

on-ContextMenu

Copy

on-Copy

Cut

on-Cut

Dblclick

on-Dblclick

Drag

on-Drag

DragDrop

on-DragDrop

DragEnd

on-DragEnd

DragGesture

on-DragGesture

DragOver

on-DragOver

Drop

on-Drop

Focus

on-Focus

FocusIn

on-FocusIn

FocusOut

on-FocusOut

KeyDown

on-KeyDown

KeyPress

on-KeyPress

KeyUp

on-KeyUp

MouseDown

on-MouseDown

MouseEnter

on-MouseEnter

MouseLeave

on-MouseLeave

MouseMove

on-MouseMove

MouseOut

on-MouseOut

MouseOver

on-MouseOver

MouseUp

on-MouseUp

Paste

on-Paste

SelectionChange

on-SelectionChange

Supported TinyMCE events

Bind the following TinyMCE events using the corresponding TinyMCE Web Component attribute.

TinyMCE event Attribute

Activate

on-Activate

AddUndo

on-AddUndo

BeforeAddUndo

on-BeforeAddUndo

BeforeExecCommand

on-BeforeExecCommand

BeforeGetContent

on-BeforeGetContent

BeforeRenderUI

on-BeforeRenderUI

BeforeSetContent

on-BeforeSetContent

Change

on-Change

ClearUndos

on-ClearUndos

Deactivate

on-Deactivate

Dirty

on-Dirty

ExecCommand

on-ExecCommand

GetContent

on-GetContent

Hide

on-Hide

Init

on-Init

LoadContent

on-LoadContent

NodeChange

on-NodeChange

PostProcess

on-PostProcess

PostRender

on-PostRender

PreProcess

on-PreProcess

ProgressState

on-ProgressState

Redo

on-Redo

Remove

on-Remove

Reset

on-Reset

SaveContent

on-SaveContent

SetAttrib

on-SetAttrib

ObjectResizeStart

on-ObjectResizeStart

ObjectResized

on-ObjectResized

ObjectSelected

on-ObjectSelected

SetContent

on-SetContent

Show

on-Show

Submit

on-Submit

Undo

on-Undo

VisualAid

on-VisualAid