Image plugin

This plugin enables the user to insert an image into TinyMCE’s editable area. The plugin also adds a toolbar button and an Insert/edit image menu item under the Insert menu.

Basic setup

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_list: [
    { title: 'My image 1', value: 'https://www.example.com/my1.gif' },
    { title: 'My image 2', value: 'http://www.moxiecode.com/my2.gif' }
  ]
});

This is not drag-drop functionality and the user is required to enter the path to the image. Optionally the user can also enter the image description, dimensions, and whether image proportions should be constrained (selected via a checkbox). Some of these settings can be preset using the plugin’s configuration options.

SVGs (Scalable Vector Graphics) are not supported in TinyMCE to protect our users and their end-users. SVGs can be used to perform both client-side and server-side attacks.

Options

These configuration options affect the execution of the image plugin. Many of the settings here will disable dialog box features used to insert or edit images. A predefined list of images can also be provided to enable quick insertion of those images.

If you wish to align the image, you can also use the text align buttons while images are selected.

`a11y_advanced_options`

This option affects the functionality of:

The Accessibility Checker plugin (a11ychecker).
The Image plugin (image).
The Image Optimizer Powered by Uploadcare plugin (uploadcare).

Setting a11y_advanced_options to true:

Adds the Image is decorative option to the Insert/Edit Image dialog, allowing users to specify that an image is decorative and does not require alternative text for accessibility purposes.
Adds the Decorative image button to Image Optimizer’s Alt text context toolbar, allowing users to specify that an image is decorative and does not require alternative text for accessibility purposes.
Adds the Image is decorative option to the Accessibility Checker error dialog for images without alternative text or the role="presentation" attribute.

If a11ychecker_allow_decorative_images is not explicitly set, the value defined in a11y_advanced_options will be used.

Type: Boolean

Default value: false

Possible values: true, false

Example: using `a11y_advanced_options`

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

`file_picker_callback`

This hook can be used to add custom file picker to those dialogs that have it. Once you define file_picker_callback, small browse button will appear along the fields of supported file types (see file_picker_types). When user clicks the button, TinyMCE will automatically call the callback with three arguments:

callback - a callback to call, once you have hold of the file; it expects new value for the field as the first argument and optionally meta information for other fields in the dialog as the second one
value - current value of the affected field
meta - object containing values of other fields in the specified dialog (notice that meta.filetype contains the type of the field)

It should be noted, that we only provide a hook. It is up to you to implement specific functionality.

Type: Function

The following example demonstrates how you can use file_picker_callback API, but doesn’t pick any real files. Check the Interactive example for a more functional example.

Example: using `file_picker_callback`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  file_picker_callback: (callback, value, meta) => {
    // Provide file and text for the link dialog
    if (meta.filetype == 'file') {
      callback('mypage.html', { text: 'My text' });
    }

    // Provide image and alt text for the image dialog
    if (meta.filetype == 'image') {
      callback('myimage.jpg', { alt: 'My alt text' });
    }

    // Provide alternative source and posted for the media dialog
    if (meta.filetype == 'media') {
      callback('movie.mp4', { source2: 'alt.ogg', poster: 'image.jpg' });
    }
  }
});

Interactive example

TinyMCE
HTML
JS
Edit on CodePen

<textarea id="file-picker"></textarea>

tinymce.init({
  selector: 'textarea#file-picker',
  plugins: 'image code',
  toolbar: 'undo redo | link image | code',
  /* enable title field in the Image dialog*/
  image_title: true,
  /* enable automatic uploads of images represented by blob or data URIs*/
  automatic_uploads: true,
  /*
    URL of our upload handler (for more details check: https://www.tiny.cloud/docs/configure/file-image-upload/#images_upload_url)
    images_upload_url: 'postAcceptor.php',
    here we add custom filepicker only to Image dialog
  */
  file_picker_types: 'image',
  /* and here's our custom image picker*/
  file_picker_callback: (cb, value, meta) => {
    const input = document.createElement('input');
    input.setAttribute('type', 'file');
    input.setAttribute('accept', 'image/*');

    input.addEventListener('change', (e) => {
      const file = e.target.files[0];

      const reader = new FileReader();
      reader.addEventListener('load', () => {
        /*
          Note: Now we need to register the blob in TinyMCEs image blob
          registry. In the next release this part hopefully won't be
          necessary, as we are looking to handle it internally.
        */
        const id = 'blobid' + (new Date()).getTime();
        const blobCache =  tinymce.activeEditor.editorUpload.blobCache;
        const base64 = reader.result.split(',')[1];
        const blobInfo = blobCache.create(id, file, base64);
        blobCache.add(blobInfo);

        /* call the callback and populate the Title field with the file name */
        cb(blobInfo.blobUri(), { title: file.name });
      });
      reader.readAsDataURL(file);
    });

    input.click();
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});

`file_picker_types`

This option enables you to specify what types of file pickers you need by a space or comma separated list of type names. There are currently three valid types: file, image and media.

Type: String

Possible values: 'file', 'image', 'media'

Example: using `file_picker_types`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  file_picker_types: 'file image media'
});

`image_caption`

This option lets users enable captions for images. When this option is enabled the image dialog will have an extra checkbox called "Caption". When a user checks the checkbox the image will get wrapped in an HTML5 figure element with a figcaption inside it. The user will then be able to type caption content inside the editor.

Type: Boolean

Default value: false

Possible values: true, false

Example: using `image_caption`

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

Below is an example of the HTML created when a user selects the caption checkbox.

<figure class="image">
<img src="url" alt="" />
<figcaption>Caption</figcaption>
</figure>

Note that the figure element needs some custom CSS added to render properly. The following is what is used in the internal content.css within TinyMCE, and can be overridden with your own custom content_css stylesheet.

figure.image {
  display: inline-block;
  border: 1px solid gray;
  margin: 0 2px 0 1px;
  background: #f5f2f0;
}

figure.align-left {
  float: left;
}

figure.align-right {
  float: right;
}

figure.image img {
  margin: 8px 8px 0 8px;
}

figure.image figcaption {
  margin: 6px 8px 6px 8px;
  text-align: center;
}

`image_list`

This option lets you specify a predefined list of sources for images. image_list takes the form of an array containing items to add to a list with a corresponding image. Each item has a title and a value.

Type: false, String, Function or Array

Default value: false

Example: using `image_list`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_list: [
    { title: 'Cat', value: 'cat.png' },
    { title: 'Dog', value: 'dog.jpg' }
  ]
});

Example of a nested list of images

To create a nested list, replace value with menu to add the top level of the list, then provide an array of items.

For example:

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_list: [
    { title: 'Cat', value: 'cat.png' },
    { title: 'Dogs',
      menu: [
        { title: 'Alaskan Husky', value: 'husky.jpg' },
        { title: 'Dingo', value: 'dingo.png' },
        { title: 'Swedish Lapphund', value: 'swedish_lapphund.gif' }
      ]
    }
  ]
});

Example of an external script that returns an JSON array of images

You can also configure a URL with JSON data. The format of that list is the same as above.

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_list: '/mylist.php'
});

Example of a custom async function

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_list: (success) => {
    success([
      { title: 'Dog', value: 'mydog.jpg' },
      { title: 'Cat', value: 'mycat.gif' }
    ]);
  }
});

`image_advtab`

This option adds an "Advanced" tab to the image dialog allowing you to add custom styles, spacing and borders to images.

Type: Boolean

Default value: false

Possible values: true, false

Example: using `image_advtab`

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

`image_class_list`

This option lets you specify a predefined list of classes to add to an image. It takes the form of an array with items to set classes on links.

Type: Array

Example: using `image_class_list`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_class_list: [
    { title: 'None', value: '' },
    { title: 'No border', value: 'img_no_border' },
    { title: 'Green border', value: 'img_green_border' },
    { title: 'Blue border', value: 'img_blue_border' },
    { title: 'Red border', value: 'img_red_border' }
  ]
});

Example of a nested list of image classes

To create a nested list, replace value with menu to add the top level of the list, then provide an array of items.

For example:

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_class_list: [
    { title: 'None', value: '' },
    { title: 'No border', value: 'img_no_border' },
    { title: 'Borders',
      menu: [
        { title: 'Green border', value: 'img_green_border' },
        { title: 'Blue border', value: 'img_blue_border' },
        { title: 'Red border', value: 'img_red_border' }
      ]
    }
  ]
});

`image_description`

This options allows you disable the image description input field in the image dialog.

Type: Boolean

Default value: true

Possible values: true, false

Example: using `image_description`

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

`image_dimensions`

This options allows you disable the image dimensions input field in the image dialog.

Type: Boolean

Default value: true

Possible values: true, false

Example: using `image_dimensions`

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

`image_prepend_url`

This option allows you to specify a URL prefix that will be applied to images when appropriate.

Type: String

Example: using `image_prepend_url`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_prepend_url: 'https://www.example.com/images/'
});

`image_title`

This options allows you enable the image title input field in the image dialog.

Type: Boolean

Default value: false

Possible values: true, false

Example: using `image_title`

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

`image_uploadtab`

This option adds an "Upload" tab to the image dialog allowing you to upload local images, when the images_upload_url is also configured.

Type: Boolean

Default value: true

Possible values: true, false

Example: using `image_uploadtab`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  image_uploadtab: 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'
});

`images_upload_base_path`

This option lets you specify a basepath to prepend to URLs returned from the configured images_upload_url page.

Type: String

Example: using `images_upload_base_path`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  images_upload_url: 'postAcceptor.php',
  images_upload_base_path: '/some/basepath'
});

`images_upload_credentials`

The images_upload_credentials option specifies whether calls to the configured images_upload_url should pass along credentials (such as cookies, authorization headers, or TLS client certificates) for cross-domain uploads. When set to true, credentials will be sent to the upload handler, similar to the withCredentials property of XMLHttpRequest.

Type: Boolean

Default value: false

Possible values: true, false

Example: using `images_upload_credentials`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  images_upload_url: 'postAcceptor.php',
  images_upload_credentials: true
});

`images_upload_handler`

This option allows you to specify a function that is used to replace TinyMCE’s default JavaScript upload handler function with custom logic.

The upload handler function takes two arguments:

blobInfo
A progress callback that takes a value between 1 and 100.

and returns a Promise that will resolve with the uploaded image URL or reject with an error. The error can be either a string or an object containing the following properties:

message - The error message to display in the UI.
remove - A flag to remove the image from the document, defaults to false if not set.

When this option is not set, TinyMCE utilizes an XMLHttpRequest to upload images one at a time to the server and resolves the Promise with the JSON location property for the remote image returned by the server.

Type: Function

Example: using `images_upload_handler`

const example_image_upload_handler = (blobInfo, progress) => new Promise((resolve, reject) => {
  const xhr = new XMLHttpRequest();
  xhr.withCredentials = false;
  xhr.open('POST', 'postAcceptor.php');

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

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

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

    const json = JSON.parse(xhr.responseText);

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

    resolve(json.location);
  };

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

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

  xhr.send(formData);
});

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  images_upload_handler: example_image_upload_handler
});

`images_upload_url`

This option lets you specify a URL for the server-side upload handler. Upload will get triggered whenever you call editor.uploadImages() or - automatically, if automatic_uploads option is enabled. Upload handler should return a new location for the uploaded file in the following format:

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

Be sure to checkout a demo implementation of the server-side upload handler here (written in PHP).

Type: String

Example: using `images_upload_url`

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  images_upload_url: 'postAcceptor.php'
});

`object_resizing`

This options allows you to turn on/off the resizing handles on images, tables or media objects. This option is enabled by default and allows you to resize table and images. You can also specify a CSS3 selector of what you want to enable resizing on.

Disable all resizing of images/tables

Type: Boolean, String

Default value: true

Possible values: true, false, or a valid CSS selector

The default value for this option is different for mobile devices. For information on the default mobile option, see: TinyMCE Mobile — Configuration options with mobile defaults.

Example: disable object resizing

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

Enable resizing on images only

Type: Boolean, String

Default value: true

Possible values: true, false, img

Example: enable object resizing for images

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  object_resizing: 'img'
});

`resize_img_proportional`

When a user resizes an image in the editor, this option controls whether image is resized proportionally or freely. If set to:

true — When users resize an image, the image will be resized proportionally (both dimensions of the image are resized by the same percentage of length). Users can freely resize images by holding the Shift key while resizing.
false — When users resize an image, the image can be resized freely. Users can proportionally resize images by holding the Shift key while resizing.

Type: Boolean

Default value: true

Possible values: true, false

Example: using `resize_img_proportional`

To disable proportional image resizing:

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

`typeahead_urls`

This option controls whether the typeahead url field feature should be enabled or disabled.

Type: Boolean

Default value: true

Possible values: true, false

Example: using `typeahead_urls`

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

Q: Where are the advanced image options?

Use the Style Formats option instead, which is much more powerful.

style_formats: [
  {
    title: 'Image Left',
    selector: 'img',
    styles: {
      float: 'left',
      margin: '0 10px 0 10px'
    }
  },
  {
    title: 'Image Right',
    selector: 'img',
    styles: {
      float: 'right',
      margin: '0 10px 0 10px'
    }
  }
]

The Image plugin provides the following toolbar buttons:

Toolbar button identifier Description

Toolbar button identifier	Description
`image`	Creates/Edits images within the editor.

image

Creates/Edits images within the editor.

These toolbar buttons can be added to the editor using:

The toolbar configuration option.
The quickbars_insert_toolbar configuration option.
Custom Context toolbars.

The Image plugin provides the following menu items:

Menu item identifier Default Menu Location Description

Menu item identifier	Default Menu Location	Description
`image`	Insert	Opens the image dialog.

image

Insert

Opens the image dialog.

These menu items can be added to the editor using:

The menu configuration option.
The contextmenu configuration option.
Custom Menu toolbar buttons.

Commands

The Image plugin provides the following TinyMCE command.

Command	Description
mceImage	Opens the insert/edit image dialog.

Command

Description

mceImage

Opens the insert/edit image dialog.

Example

tinymce.activeEditor.execCommand('mceImage');

Image plugin

Basic setup

Options

a11y_advanced_options

Example: using a11y_advanced_options

file_picker_callback

Example: using file_picker_callback

Interactive example

file_picker_types

Example: using file_picker_types

image_caption

Example: using image_caption

image_list

Example: using image_list

Example of a nested list of images

Example of an external script that returns an JSON array of images

Example of a custom async function

image_advtab

Example: using image_advtab

image_class_list

Example: using image_class_list

Example of a nested list of image classes

image_description

Example: using image_description

image_dimensions

Example: using image_dimensions

image_prepend_url

Example: using image_prepend_url

image_title

Example: using image_title

image_uploadtab

Example: using image_uploadtab

images_file_types

Example: using images_file_types

images_upload_base_path

Example: using images_upload_base_path

images_upload_credentials

Example: using images_upload_credentials

images_upload_handler

Example: using images_upload_handler

images_upload_url

Example: using images_upload_url

object_resizing

Disable all resizing of images/tables

Example: disable object resizing

Enable resizing on images only

Example: enable object resizing for images

resize_img_proportional

Example: using resize_img_proportional

typeahead_urls

Example: using typeahead_urls

Q: Where are the advanced image options?

Toolbar buttons

Menu items

Commands

`a11y_advanced_options`

Example: using `a11y_advanced_options`

`file_picker_callback`

Example: using `file_picker_callback`

`file_picker_types`

Example: using `file_picker_types`

`image_caption`

Example: using `image_caption`

`image_list`

Example: using `image_list`

`image_advtab`

Example: using `image_advtab`

`image_class_list`

Example: using `image_class_list`

`image_description`

Example: using `image_description`

`image_dimensions`

Example: using `image_dimensions`

`image_prepend_url`

Example: using `image_prepend_url`

`image_title`

Example: using `image_title`

`image_uploadtab`

Example: using `image_uploadtab`

`images_file_types`

Example: using `images_file_types`

`images_upload_base_path`

Example: using `images_upload_base_path`

`images_upload_credentials`

Example: using `images_upload_credentials`

`images_upload_handler`

Example: using `images_upload_handler`

`images_upload_url`

Example: using `images_upload_url`

`object_resizing`

`resize_img_proportional`

Example: using `resize_img_proportional`

`typeahead_urls`

Example: using `typeahead_urls`