Important changes to Tiny Cloud pricing > Find out more

Image plugin

Insert an image into TinyMCE.

Contribute to this page

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.

Type: String

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

Note that 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.

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.

file_picker_callback

This hook can be used to add custom file picker to those dialogs that have it. Internally we support this in Image, Media and Link dialogs. This replaces the file_browser_callback (removed in version 5.0) option. The new file_picker_callback provides a way to update values of other fields in the dialog.

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: JavaScript Function

The following example demonstrates how you can use file_picker_callback API, but doesn’t pick any real files. Check Basic Local File Picker demo for a more functional example.

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

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
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
tinymce.init({
  selector: "textarea",  // change this value according to your HTML
  plugins: "image",
  menubar: "insert",
  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. This is what we use 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: String

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

Example of JSON URL with 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",
  menubar: "insert",
  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",
  menubar: "insert",
  toolbar: "image",
    image_list: function(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
tinymce.init({
  selector: "textarea",  // change this value according to your HTML
  plugins: "image",
  menubar: "insert",
  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: String

Example
tinymce.init({
  selector: "textarea",  // change this value according to your HTML
  plugins: "image",
  menubar: "insert",
  toolbar: "image",
  image_class_list: [
    {title: 'None', value: ''},
    {title: 'Dog', value: 'dog'},
    {title: 'Cat', value: 'cat'}
  ]
});

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

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

images_upload_credentials

The images_upload_credentials option lets you specify if calls to the configured images_upload_url should pass along credentials like cookies etc. cross domain.

Type: Boolean

Default Value: false

Possible Values: true, false

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

images_upload_handler

The images_upload_handler 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 three arguments: blobInfo, a success callback, and a failure callback. When this option is not set, TinyMCE utilizes an XMLHttpRequest to upload images one at a time to the server and calls the success callback with the location of the remote image.

Note: Please note that when using this option, no other image uploader options are necessary. Additionally, if you would like TinyMCE to replace the <image> tag’s src attribute with the remote location, please use the success callback defined in the images_upload_handler function with the returned JSON object’s location property.

Type: JavaScript Function

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  images_upload_handler: function (blobInfo, success, failure) {
    var xhr, formData;

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

    xhr.onload = function() {
      var json;

      if (xhr.status != 200) {
        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);
    };

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

    xhr.send(formData);
  }
});

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

typeahead_urls

This option allows disable the type ahead url field feature.

Type: Boolean

Default Value: true

Possible Values: true, false

Example
tinymce.init({
  selector: 'textarea',
  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'
  }}
]

Can't find what you're looking for? Let us know.

Except as otherwise noted, the content of this page is licensed under the Creative Commons BY-NC-SA 3.0 License, and code samples are licensed under the Apache 2.0 License.