---
title: "Image & file options"
description: "These settings affect TinyMCE's image and file handling capabilities."
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/file-image-upload/"
md_url: "https://www.tiny.cloud/docs/tinymce/5/file-image-upload/index.md"
version: "5"
last_updated: "2024-04-09T10:06:54Z"
tokens: 3181
---
Important This page documents TinyMCE 5. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/file-image-upload/).
# Image & file options

## `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](../editimage/) plugin, or after image is drag-n-dropped onto the editor from the desktop.

> **Note:** This option will do nothing if `images_upload_url` is not specified.
**Type:** `Boolean`

**Default Value:** `true`

**Possible Values:** `true`, `false`

### Example: Using `automatic_uploads`

```js
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: Using `block_unsupported_drop`

```js
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`](/docs-4x/configure/file-image-upload/#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](../image/#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`

> **Note:** The following example demonstrates how you can use `file_picker_callback` API, but doesn’t pick any real files. Check [Basic Local File Picker](../file-picker/) demo for a more functional example.

### Example: Using `file_picker_callback`

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

### Interactive example

**Example**

```js
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: function (cb, value, meta) {
    var input = document.createElement('input');
    input.setAttribute('type', 'file');
    input.setAttribute('accept', 'image/*');

    /*
      Note: In modern browsers input[type="file"] is functional without
      even adding it to the DOM, but that might not be the case in some older
      or quirky browsers like IE, so you might want to add it to the DOM
      just in case, and visually hide it. And do not forget do remove it
      once you do not need it anymore.
    */

    input.onchange = function () {
      var file = this.files[0];

      var reader = new FileReader();
      reader.onload = function () {
        /*
          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.
        */
        var id = 'blobid' + (new Date()).getTime();
        var blobCache =  tinymce.activeEditor.editorUpload.blobCache;
        var base64 = reader.result.split(',')[1];
        var 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:14px }'
});
```

## `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`

```js
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` will be removed in TinyMCE 6.0.
The **images_dataimg_filter** option is used to filter `<img>` elements before they are passed to [`image_upload_handler`](#images_upload_handler) or [`images_upload_url`](#images_upload_url). If the callback function provided returns `false` for an image, the image will not be uploaded.

**Type:** `JavaScript Function`

### Example: Using `images_dataimg_filter`

```js
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_file_types`

> **Note:** This feature is only available for TinyMCE 5.6 and later.
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](../image/) dialog.
- Which image file formats are recognized and placed in an `img` element by the [Paste](../paste/) and [PowerPaste](../introduction-to-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](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types).

### Example: Using `images_file_types`

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

## `images_reuse_filename`

By default TinyMCE will generate unique filename for each uploaded file (for details refer to [Upload Images](../upload-images/#imageuploaderrequirements)). Sometimes this might have undesirable side-effects. For example, when `automatic_uploads` is enabled, every manipulation on the image done with [Image Tools](../editimage/) 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](#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: Using `images_reuse_filename`

```js
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`](#images_upload_url) page.

**Type:** `String`

### Example: Using `images_upload_base_path`

```js
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`](#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`s](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials).

**Type:** `Boolean`

**Default Value:** `false`

**Possible Values:** `true`, `false`

### Example: Using `images_upload_credentials`

```js
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 that takes an error message and an optional object containing:

  - `remove` - Removes the image from the document, defaults to `false`
- 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: Using `images_upload_handler`

```js
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);
};

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:

```json
{ "location": "folder/sub-folder/new-location.png" }
```
Be sure to check out a demo implementation of the server-side upload handler [here](../php-upload-handler/) (written in PHP).

**Type:** `String`

### Example: Using `images_upload_url`

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