---
title: "Media Optimizer (Image)"
description: "The Image feature of the Media Optimizer plugin allows you to optimize images in your content."
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/uploadcare-image/"
md_url: "https://www.tiny.cloud/docs/tinymce/latest/uploadcare-image/index.md"
version: "latest"
last_updated: "2026-03-31T06:30:06Z"
tokens: 5531
---
# Media Optimizer (Image)

> **Note:** This plugin is only available for [paid TinyMCE subscriptions](/pricing/).

## Overview

The **Image feature of the Media Optimizer plugin** offers a range of powerful features for image hosting, serving, and editing. These include responsive image delivery, automatic image format selection, automatic compression, and non-destructive image transformations and adjustments, all powered by [Uploadcare](https://uploadcare.com/).

## Key benefits

- Improve page loading speed and save on bandwidth by serving images in the optimal size, format, and compression based on the visitor’s browser and device.
- Ditch the image editor and adjust images right inside TinyMCE with non-destructive transformations and adjustments. Change your mind any time!
- Stay safe and compliant with secure uploads, built in malware protection, and unsafe content detection
- Enterprise-ready scalable cloud storage provided by Uploadcare, delivered through its lightning-fast global CDN, and compliant with SOC2 and GDPR standards.

## Interactive example

**Example**

```js
tinymce.init({
  selector: "textarea#uploadcare-image",
  plugins: [ "uploadcare", "code", "link", "preview", "lists" ],
  uploadcare_public_key: '<your-public-key>',
  uploadcare_filters: [
    { name: 'none' }, // No filter applied
    { name: 'adaris', amount: -100 }, // Adaris with inverted effect (amount -100), label defaults to 'adaris'
    { name: 'adaris', amount: -100, label: 'Vintage Fade' }, // Adaris with inverted effect (amount -100), label reads 'Vintage Fade'
    { name: 'adaris', amount: 0, label: 'Base' }, // Adaris with neutral effect (amount 0), label reads 'Base'
    { name: 'adaris', amount: 50, label: 'Light' }, // Adaris with light effect (amount 50), label reads 'Light'
    { name: 'adaris', amount: 100, label: 'Standard' }, // Adaris with standard effect (amount 100), label reads 'Standard'
    { name: 'adaris', amount: 200, label: 'Intense' }, // Adaris with intense effect (amount 200), label reads 'Intense'
    { name: 'zevcen', amount: 200, label: 'Glow Boost' }, // Zevcen with intense effect (amount 200), label reads 'Glow Boost'
    { name: 'galen', amount: 80, label: 'Soft Focus' }, // Galen with softening effect (amount 80), label reads 'Soft Focus'
    { name: 'carris', amount: 120, label: 'Sharp Contrast' }, // Carris with high contrast (amount 120), label reads 'Sharp Contrast'
    { name: 'ferand', amount: 60, label: 'Light Touch' }, // Ferand with light enhancement (amount 60), label reads 'Light Touch'
    { name: 'sorahel', amount: -50, label: 'Night Mood' } // Sorahel with darkened effect (amount -50), label reads 'Night Mood'
  ],
  a11y_advanced_options: true,
  toolbar: "undo redo | uploadcare | styles | bold italic underline | forecolor | bullist numlist| link | code preview",
  height: 700,	
  content_style: `
    body { max-width: 920px; margin: 1.5rem auto; padding: 0 2vw; }
    h1 { font-size: 1.5em; }
        h2 { font-size: 1.17em; }
    h1, h2, h3, h4, h5, h6 { font-weight: 500; margin: 0 0 0.75rem; }
    p + h1, p + h2, p + h3, p + h4, p + h5, p + h6 { margin-top: 2rem; }
    p { line-height: 1.6; margin: 0; } 
    p + p { margin-top: 1rem; }
    a { color: #2b70e3; }
    blockquote { color: #4e5c73; font-weight: 200; font-size: 1.3rem; margin: 1rem 2rem; padding: 0 0 0 1rem; border-left: 2px solid #2b70e3 !important; }
    figcaption {font-size: 0.875em;}
  `
  });
```

> **Warning:** **Plugin Compatibility Issues**
> 
> The [Media Optimizer Powered by Uploadcare](../uploadcare/) premium plugin cannot be configured together with the following plugins:
> 
> - [Image](../image/)
> - [Image Editing](../editimage/)
> **Recommended Solutions:**
> 
> For images:
> 
> - Configure either the [Image](../image/) and [Image Editing](../editimage/) plugins together, or
> - Configure the [Media Optimizer: Image](#) plugin as the sole image handler for all images.
> If all three plugins are enabled, editor notification: "Unable to initialize uploadcare due to the presence of incompatible plugins. Details are in the browser console." will be shown along with console error: "Unable to initialize uploadcare due to the presence of incompatible plugins: image, editimage".

## Basic setup

To add the Media Optimizer’s Image feature plugin to the editor, include `uploadcare` in the `plugins` option in the editor configuration.

Example
```js
tinymce.init({
  selector: 'textarea',
  plugins: 'uploadcare',
  toolbar: 'uploadcare',
  uploadcare_public_key: '<your-public-key>', // Required for Uploadcare integration
  // uploadcare_signed_upload_auth_provider: (_publicKey) => Promise.resolve({
  //   signature: 'sig',
  //   expire: 123
  // }), // Recommended option for secure uploads
});
```

> **Note:** For information on bundling this plugin with module bundlers, see [Bundling TinyMCE - Overview](../bundling-guide/).

> **Note:** The Media Optimizer’s Image feature plugin overrides the [Quickbar](../quickbars/) quickimage toolbar item. To ensure a better user experience and to avoid having two image buttons configure `quickbars_insert_toolbar` to omit the `quickimage` toolbar item.

## Image Operations

Below is an overview of the features provided by the Media Optimizer’s Image feature plugin for image optimization:

| Feature |  | Icon | Description |
| --- | --- | --- | --- |
| Upload |  | ![upload-from-device.svg](../_images/icons/upload-from-device.svg) | Upload images via drag-and-drop, file selection, or URL input |
| Upload from URL |  | ![upload-from-link.svg](../_images/icons/upload-from-link.svg) | Upload images from a URL |

Below is an overview of the image editing features provided by the Media Optimizer’s Image feature plugin:

| Feature | Operation | Icon | Description |
| --- | --- | --- | --- |
| Align |  | ![align-left.svg](../_images/icons/align-left.svg) | Provides alignment options for the image or element. |
|  | Align Left | ![align-left.svg](../_images/icons/align-left.svg) | Aligns the image to the left. |
|  | Align Centre | ![align-center.svg](../_images/icons/align-center.svg) | Centers the image. |
|  | Align Right | ![align-right.svg](../_images/icons/align-right.svg) | Aligns the image to the right. |
| Transform |  | ![transform-image.svg](../_images/icons/transform-image.svg) | Allows users to apply transformations to the image: |
|  | Rotate Left | ![rotate-left.svg](../_images/icons/rotate-left.svg) | Rotates the image counterclockwise (left). |
|  | Rotate Right | ![rotate-right.svg](../_images/icons/rotate-right.svg) | Rotates the image clockwise (right). |
|  | Flip Vertically | ![flip-vertically.svg](../_images/icons/flip-vertically.svg) | Flips the image vertically. |
|  | Flip Horizontally | ![flip-horizontally.svg](../_images/icons/flip-horizontally.svg) | Flips the image horizontally. |
|  | Resize | ![resize.svg](../_images/icons/resize.svg) | Changes the size of the image. |
| Adjust |  | ![adjustments.svg](../_images/icons/adjustments.svg) | Provides tools for adjusting image properties: |
|  | Brightness | ![brightness.svg](../_images/icons/brightness.svg) | Adjusts the image brightness. |
|  | Contrast | ![contrast.svg](../_images/icons/contrast.svg) | Adjusts the image contrast. |
|  | Exposure | ![exposure.svg](../_images/icons/exposure.svg) | Adjusts the image exposure. |
|  | Gamma | ![gamma.svg](../_images/icons/gamma.svg) | Adjusts the image gamma. |
|  | Vibrance | ![vibrance.svg](../_images/icons/vibrance.svg) | Adjusts the image vibrance. |
|  | Saturation | ![saturation.svg](../_images/icons/saturation.svg) | Adjusts the image saturation. |
|  | Warmth | ![warmth.svg](../_images/icons/warmth.svg) | Adjusts the image warmth. |
|  | Grayscale | ![grayscale.svg](../_images/icons/grayscale.svg) | Converts the image to grayscale. |
|  | Invert Colors | ![invert.svg](../_images/icons/invert.svg) | Inverts the image colors. |
|  | Sharpen | ![sharpen.svg](../_images/icons/sharpen.svg) | Sharpens the image. |
|  | Blur | ![blur.svg](../_images/icons/blur.svg) | Blurs the image. |
| Filters |  | ![auto-image-enhancement.svg](../_images/icons/auto-image-enhancement.svg) | Provides tools for applying filters to the image. |
| Alt Text |  | ![alt-text.svg](../_images/icons/alt-text.svg) | Adds alternative text to describe the image for accessibility purposes. |
|  | Decorative Image | ![image-decorative.svg](../_images/icons/image-decorative.svg) | Marks the image as decorative, indicating it doesn’t require alternative text for accessibility.   <br>This icon will only appear when the `a11y_advanced_options` configuration option is enabled. |
| Caption |  | ![caption.svg](../_images/icons/caption.svg) | Adds a caption below the image for additional context. |
| Revert |  | ![revert.svg](../_images/icons/revert-changes.svg) | Restores the image to its original state by undoing all edits. |

## Options

The following configuration options affect the behavior of the Media Optimizer’s Image feature plugin:

### `uploadcare_srcset_steps`

Specifies an array of numeric values representing the widths used to generate the `srcset` attribute for responsive images. This enables browsers to select the most suitable resolution based on the device’s display and network conditions.

Customize this array to include **only** the widths required for your application. Reducing the number of resolutions can improve processing speed, while adding specific sizes can accommodate unique layout needs.

**Type:** `Array`

**Default:** `[100, 200, 300, 500, 750, 1000, 1250, 1500, 2000, 2500, 3000]`

#### Example: Generated `srcset` Attribute with Custom Widths

When an image is uploaded, its original width is used to create a `srcset` attribute with downscaled images for the defined widths. For instance, if the image width is 780 pixels and `uploadcare_srcset_steps` is set to `[100, 200, 300, 500, 750]`, the resulting `srcset` will look like this:

Example: Responsive 780px Image with Custom Widths in `srcset`
```html
<img
  style="width: min(780px, 100%); aspect-ratio: 780 / 780;"
  src="https://ucarecdn.com/{image-uid}/-/preview/"
  sizes="(min-width: 780px) 780px, 100vw"
  srcset="
      https://ucarecdn.com/{image-uid}/-/resize/100x/ 100w,
      https://ucarecdn.com/{image-uid}/-/resize/200x/ 200w,
      https://ucarecdn.com/{image-uid}/-/resize/300x/ 300w,
      https://ucarecdn.com/{image-uid}/-/resize/500x/ 500w,
      https://ucarecdn.com/{image-uid}/-/resize/750x/ 750w,
      https://ucarecdn.com/{image-uid}/-/preview/ 780w
  ">
```
This ensures the browser selects the optimal image size based on the viewport and device characteristics, enhancing performance and user experience. On devices with narrower viewports, smaller images (e.g., 100w or 200w) will be prioritized, reducing bandwidth usage.

#### Example: Customizing `uploadcare_srcset_steps`

To customize the array, update the configuration as shown below:

```js
tinymce.init({
  selector: 'textarea',
  plugins: 'uploadcare',
  toolbar: 'uploadcare',
  uploadcare_public_key: '<your-public-key>',
  uploadcare_srcset_steps: [100, 200, 300, 500, 750],
});
```

### `uploadcare_filters`

The `uploadcare_filters` option defines the list of image filters available when using the Media Optimizer’s Image feature plugin. Each filter applies a stylized image effect consistent with the visual design of the content and can be configured with an amount value to control its intensity. Filters enhance images by applying consistent styling, improving overall quality, and boosting user engagement.

Each filter is defined as an object with the following properties:

```js
{
  name: 'filterName', // Required: name of the filter to apply
  amount: number, // Optional: strength of the filter (default = 100)
  label: 'string' // Optional: custom name to display in the UI
}
```

- `name`: A predefined filter identifier (e.g., adaris, zevcen, galen).
- `amount`: The intensity of the filter effect, ranging from -100 to 200:

  - **0**: No effect (image stays original).
  - **0** to **100**: Gradually increases filter strength.
  - **100**: Default intensity (as the filter is designed).
  - **>100**: Exaggerates the effect.
  - **<0**: Inverts the filter effect (produces a "negative" version).
- `label`: Optional display name for the filter in your UI. If omitted, it defaults to the name.

#### Example: Setting `uploadcare_filters`

```js
tinymce.init({
  selector: "textarea",
  plugins: 'uploadcare',
  toolbar: 'uploadcare',
  uploadcare_public_key: '<your-public-key>',

  // Define available Uploadcare image filters and their intensity levels
  uploadcare_filters: [
    { name: 'none' }, // No filter applied
    { name: 'adaris', amount: -100 }, // Adaris with inverted effect (amount -100), label defaults to 'adaris'
    { name: 'adaris', amount: -100, label: 'Vintage Fade' }, // Adaris with inverted effect (amount -100), label reads 'Vintage Fade'
    { name: 'adaris', amount: 0, label: 'Base' }, // Adaris with neutral effect (amount 0), label reads 'Base'
    { name: 'adaris', amount: 50, label: 'Light' }, // Adaris with light effect (amount 50), label reads 'Light'
    { name: 'adaris', amount: 100, label: 'Standard' }, // Adaris with standard effect (amount 100), label reads 'Standard'
    { name: 'adaris', amount: 200, label: 'Intense' }, // Adaris with intense effect (amount 200), label reads 'Intense'
    { name: 'zevcen', amount: 200, label: 'Glow Boost' }, // Zevcen with intense effect (amount 200), label reads 'Glow Boost'
    { name: 'galen', amount: 80, label: 'Soft Focus' }, // Galen with softening effect (amount 80), label reads 'Soft Focus'
    { name: 'carris', amount: 120, label: 'Sharp Contrast' }, // Carris with high contrast (amount 120), label reads 'Sharp Contrast'
    { name: 'ferand', amount: 60, label: 'Light Touch' }, // Ferand with light enhancement (amount 60), label reads 'Light Touch'
    { name: 'sorahel', amount: -50, label: 'Night Mood' } // Sorahel with darkened effect (amount -50), label reads 'Night Mood'
  ]
});
```

> **Important:** The `{ name: 'none' }` option adds a "No filter" or "Remove filter" choice to the list of available filters. This allows end users to remove any applied filter. If this option is **not** included, users will **not** have a way to remove a filter once it’s been applied.

> **Note:**
> - Filter names must be selected from the supported set:
> 
> - `adaris`, `briaril`, `calarel`, `carris`, `cynarel`, `cyren`, `elmet`, `elonni`, `enzana`, `erydark`, `fenralan`, `ferand`, `galen`, `gavin`, `gethriel`, `iorill`, `iothari`, `iselva`, `jadis`, `lavra`, `misiara`, `namala`, `nerion`, `nethari`, `pamaya`, `sarnar`, `sedis`, `sewen`, `sorahel`, `sorlen`, `tarian`, `thellassan`, `varriel`, `varven`, `vevera`, `virkas`, `yedis`, `yllara`, `zatvel`, `zevcen`.
> - If the amount is not set, it defaults to 100.
> - Some filters may behave unpredictably outside the 0–100 range.
> - Applying negative amount values inverts the filter, useful for creative effects.

#### Uploadcare Filter Previews

Each image below represents a filter applied to the same source image.

| adaris | briaril | calarel | carris |
| --- | --- | --- | --- |
| ![adaris](../_images/uploadcare/filters/cynarel.jpg) | ![briaril](../_images/uploadcare/filters/briaril.jpg) | ![calarel](../_images/uploadcare/filters/calarel.jpg) | ![carris](../_images/uploadcare/filters/carris.jpg) |
| cynarel | cyren | elmet | elonni |
| ![cynarel](../_images/uploadcare/filters/cynarel.jpg) | ![cyren](../_images/uploadcare/filters/cyren.jpg) | ![elmet](../_images/uploadcare/filters/elmet.jpg) | ![elonni](../_images/uploadcare/filters/elonni.jpg) |
| enzana | erydark | fenralan | ferand |
| ![enzana](../_images/uploadcare/filters/enzana.jpg) | ![erydark](../_images/uploadcare/filters/erydark.jpg) | ![fenralan](../_images/uploadcare/filters/fenralan.jpg) | ![ferand](../_images/uploadcare/filters/ferand.jpg) |
| galen | gavin | gethriel | iorill |
| ![galen](../_images/uploadcare/filters/galen.jpg) | ![gavin](../_images/uploadcare/filters/gavin.jpg) | ![gethriel](../_images/uploadcare/filters/gethriel.jpg) | ![iorill](../_images/uploadcare/filters/iorill.jpg) |
| iothari | iselva | jadis | lavra |
| ![iothari](../_images/uploadcare/filters/iothari.jpg) | ![iselva](../_images/uploadcare/filters/iselva.jpg) | ![jadis](../_images/uploadcare/filters/jadis.jpg) | ![lavra](../_images/uploadcare/filters/lavra.jpg) |
| misiara | namala | nerion | nethari |
| ![misiara](../_images/uploadcare/filters/misiara.jpg) | ![namala](../_images/uploadcare/filters/namala.jpg) | ![nerion](../_images/uploadcare/filters/nerion.jpg) | ![nethari](../_images/uploadcare/filters/nethari.jpg) |
| pamaya | sarnar | sedis | sewen |
| ![pamaya](../_images/uploadcare/filters/pamaya.jpg) | ![sarnar](../_images/uploadcare/filters/sarnar.jpg) | ![sedis](../_images/uploadcare/filters/sedis.jpg) | ![sewen](../_images/uploadcare/filters/sewen.jpg) |
| sorahel | sorlen | tarian | thellassan |
| ![sorahel](../_images/uploadcare/filters/sorahel.jpg) | ![sorlen](../_images/uploadcare/filters/sorlen.jpg) | ![tarian](../_images/uploadcare/filters/tarian.jpg) | ![thellassan](../_images/uploadcare/filters/thellassan.jpg) |
| varriel | varven | vevera | virkas |
| ![varriel](../_images/uploadcare/filters/varriel.jpg) | ![varven](../_images/uploadcare/filters/varven.jpg) | ![vevera](../_images/uploadcare/filters/vevera.jpg) | ![virkas](../_images/uploadcare/filters/virkas.jpg) |
| yedis | yllara | zatvel | zevcen |
| ![yedis](../_images/uploadcare/filters/yedis.jpg) | ![yllara](../_images/uploadcare/filters/yllara.jpg) | ![zatvel](../_images/uploadcare/filters/zatvel.jpg) | ![zevcen](../_images/uploadcare/filters/zevcen.jpg) |

### `a11y_advanced_options`

This option affects the functionality of:

- The [Accessibility Checker](../a11ychecker/) plugin (`a11ychecker`).
- The [Image](../image/) plugin (`image`).
- The [Media Optimizer Powered by Uploadcare](../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 Media 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 that need to be marked as decorative.

> **Important:** 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`

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'uploadcare',
  toolbar: 'uploadcare',
  uploadcare_public_key: '<your-public-key>',
  a11y_advanced_options: true,
});
```

## Toolbar buttons

The Media Optimizer’s Image feature plugin provides the following toolbar buttons:

| Identifier | Description |
| --- | --- |
| `uploadcare` | Inserts an image placeholder element. This placeholder supports image uploads via drag-and-drop, file selection, or by providing a URL. |

These toolbar buttons can be added to the editor using:

- The [`toolbar`](../toolbar-configuration-options/#toolbar) configuration option.
- The [`quickbars_insert_toolbar`](../quickbars/#quickbars_insert_toolbar) configuration option.
- [Custom Context toolbars](../contexttoolbar/).

## Menu items

The Media Optimizer’s Image feature plugin provides the following menu items:

| Identifier | Description |
| --- | --- |
| `uploadcare` | Inserts an image placeholder element. This placeholder supports image uploads via drag-and-drop, file selection, or by providing a URL. |

These menu items can be added to the editor using:

- The [`menu`](../menus-configuration-options/#menu) configuration option.
- The [`contextmenu`](../menus-configuration-options/#contextmenu) configuration option.
- [Custom Menu toolbar buttons](../custom-menu-toolbar-button/).