---
title: "Image plugin"
description: "Insert an image into TinyMCE."
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/image/"
md_url: "https://www.tiny.cloud/docs/tinymce/5/image/index.md"
version: "5"
last_updated: "2024-04-16T01:50:26Z"
tokens: 5016
---
Important This page documents TinyMCE 5. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/image/).
# 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

```js
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.example.com/my1.gif'},
    {title: 'My image 2', value: 'http://www.moxiecode.com/my2.gif'}
  ]
});
```

> **Note:** 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.

> **Note:** 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`).

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 **Image is decorative** option to the *Accessibility Checker error* dialog for images without alternative text or the `role="presentation"` attribute.

> **Important:** When `a11y_advanced_options` is set to `true`, [`a11ychecker_allow_decorative_images`](../a11ychecker/#a11ychecker_allow_decorative_images) will default to `true`.
**Type:** `Boolean`

**Default Value:** `false`

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

#### Example: Using `a11y_advanced_options`

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

### `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](#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'
});
```

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

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

```html
<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`](../content-appearance/#content_css) stylesheet.

```css
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: Using `image_list`

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

#### Example of a nested list of images

> **Note:** This feature is only available for TinyMCE 5.5 and later.
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:

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  menubar: 'insert',
  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.

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

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

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

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  menubar: 'insert',
  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

> **Note:** This feature is only available for TinyMCE 5.5 and later.
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:

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  menubar: 'insert',
  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`

```js
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 to disable the image dimensions input field in the image dialog.

**Type:** `Boolean`

**Default Value:** `true`

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

#### Example: Using `image_dimensions`

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

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

### `image_title`

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

**Type:** `Boolean`

**Default Value:** `false`

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

#### Example: Using `image_title`

```js
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`](../file-image-upload/#images_upload_url) is also configured.

**Type:** `Boolean`

**Default Value:** `true`

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

#### Example: Using `image_uploadtab`

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

### `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](#) 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_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'
});
```

## `typeahead_urls`

This option allows disabling the type ahead url field feature.

**Type:** `Boolean`

**Default Value:** `true`

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

### Example: Using `typeahead_urls`

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

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