Important changes to Tiny Cloud pricing > Find out more

Image & file options

These settings affect TinyMCE's image and file handling capabilities.

Contribute to this page

automatic_uploads

Enable or disable automatic upload of images represented by data URLs or blob URIs. Such images get generated, for example, as a result of image manipulation through Image Tools plugin, or after image is drag-n-dropped onto the editor from the desktop.

Warning: Note that, this option will do nothing if images_upload_url is not specified.

Type: Boolean

Default Value: true

Possible Values: true, false

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

block_unsupported_drop

Note: This feature is only available for TinyMCE 5.4 and later.

When the block_unsupported_drop option is set to true, the editor blocks unsupported images and files from being dropped into the editor. If the block_unsupported_drop option is set to false, dropping an unsupported file into the editor will cause the browser to navigate away from the page containing the editor.

Type: Boolean

Default Value: true

Possible Values: true, false

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

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 TinyMCE 5) 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'});
    }
  }
});

Live Example

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'
});

images_dataimg_filter

Important: This option was deprecated with the release of TinyMCE 5.3. images_dataimg_filter may be removed in a future release of TinyMCE.

The images_dataimg_filter option is used to filter <img> elements before they are passed to image_upload_handler or images_upload_url. If the callback function provided returns false for an image, the image will not be uploaded.

Type: JavaScript Function

Example
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  images_upload_url: 'postAcceptor.php',
  images_dataimg_filter: function(img) {
    return !img.hasAttribute('internal-blob');  // blocks the upload of <img> elements with the attribute "internal-blob".
  }
});

Note: The images_dataimg_filter option can also be used to specify a filter predicate function for disabling the logic that converts base64 images into blobs while within the editor. Tiny discourages using images_dataimg_filter for this purpose.

images_reuse_filename

By default TinyMCE will generate unique filename for each uploaded file (for details refer to Upload Images). Sometimes this might have undesirable side-effects. For example, ,when automatic_uploads is enabled, every manipulation on the image done with Image Tools plugin, results in file upload and each time under a different filename, despite the fact that the image stays the same.

Setting images_reuse_filename to true tells TinyMCE to use the actual filename of the image, instead of generating a new one each time. Take into account that src attribute of the corresponding <img> tag gets replaced with whatever filename you send back from the server (see images_upload_url). It can be the same filename or something else, but the next time that filename is used for the upload.

Type: Boolean

Default Value: false

Possible Values: true, false

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

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_url: 'postAcceptor.php',
  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_url: 'postAcceptor.php',
  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 four arguments:

  • blobInfo
  • A success callback
  • A failure callback
  • A progress callback that takes a value between 1 and 100

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: To replace the <img> 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, 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 < 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);
  }
});

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'
});

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.