Media Editor

Cloudinary's Media Editor is an interactive user interface providing a set of common image editing actions to your users on your website or application. The Media Editor requires only native JavaScript to integrate, is easy to use within any web development framework, and eliminates the need to develop an in-house interactive media editor with just a few lines of code. The editor helps to scale internal operations by reducing dependency on designers for simple recurring tasks. Combined with AI for automating simple actions, this allows manual review / fixing of media assets when needed.

Important
Cloudinary supports only the documented configuration and the supplied files with the widget. Any direct changes to the widget code and its elements (for example, CSS and JS files) might break its functionality, and will not be supported.

Quick example

To use Cloudinary's Media Editor widget in your site, include a remote JavaScript file, call the mediaEditor method to initialize the widget, and then specify the following required information when calling the update method:

  • Your Cloudinary account cloud name.
  • The public_id of the image to edit.

The show method is called to display the initialized widget:

Copy to clipboard
<script src="https://media-editor.cloudinary.com/all.js" type="text/javascript"></script>
<script>
const myEditor = cloudinary.mediaEditor();
myEditor.update({
  publicIds: ["sample"],
  cloudName: "demo"
});
myEditor.show();
myEditor.on("export",function(data){
  console.log(data);
})
</script>

Known issues

  • Internet Explorer 11 is not supported.
  • Mobile devices are not supported.
  • If you flip or rotate after an interactive crop, the crop resets to the selected preset's initial value, and you need to re-crop the image.

Workflow

To add Cloudinary's Media Editor widget to your site:

  1. Include the JavaScript file: https://media-editor.cloudinary.com/all.js.
  2. Initialize the Media Editor widget with the cloudinary.mediaEditor() method.
  3. Update the Media Editor configuration with the update(options) method.
  4. Show the Media Editor widget with the show() method.

Tip

Check out the Media Editor interactive demo and try out some of the configuration options. Although the demo does not cover every possible option, it generates the required code for implementing the options you select, making for an ideal sandbox for getting started with widget.

1. Include the JavaScript file

All the Media Editor functionality is included in the https://media-editor.cloudinary.com/all.js JavaScript file. The file is optimized and delivered via a fast CDN.

For example:

Copy to clipboard
<script src="https://media-editor.cloudinary.com/all.js" type="text/javascript">  
</script>

2. Initialize the Media Editor widget

The JavaScript method for initializing the widget is publicly available after including the Media Editor's JavaScript file, which instantiates the cloudinary object and grants access to the cloudinary.mediaEditor(options) method. This method creates a Media Editor instance in memory.

For example:

Copy to clipboard
const myEditor = cloudinary.mediaEditor();

If you want the widget to open within an existing containing element on the page, you can pass the mediaEditor method a target element using a selector or DOM element as an appendTo parameter, for example:

Copy to clipboard
const myEditor = cloudinary.mediaEditor({appendTo: document.getElementById("my-widget-container");});
  // OR
const myEditor = cloudinary.mediaEditor({appendTo: '#my-widget-container'})

Note
When displayed as modal (by default), the z-index (stack order) of the widget is set to a high value of 99999 in order to appear above other elements on the page. You can change this z-index by overriding the css cld-media-editor-iframe stack order, for example:

Copy to clipboard
#cld-media-editor-iframe {
  z-index: 100 !important
}

3. Update the Media Editor widget

The update(options) method configures the Media Editor, where options is an object containing a map of configuration parameters to apply.

The options must include at least the following 2 required parameters:

  • Your Cloudinary account cloudName parameter.
  • The publicIds parameter with the PublicID of the image to edit.

For a complete list of parameters available for configuring the Media Editor widget, see the Parameter tables.

For example, to update an instantiated widget with the "sample" image:

Copy to clipboard
myEditor.update({ 
  cloudName: "demo",    
  publicIds: ["sample"],
});

Note
In order to edit private or authenticated assets within the widget you will also need to use the onSign method to resolve the delivery signature needed for a restricted asset.

4. Show the Media Editor widget

The mediaEditor method creates and initializes the widget but does not display it until the show() method of the returned instance is called.

For example:

Copy to clipboard
myEditor.show();

For a full listing of available methods, see the Instance methods section in the Media Editor API reference.

Image Configuration

The Media Editor has various options for editing images. All the image editing parameters are given within an image object parameter.

For example:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["sample"],
  image: {
    // image editing parameters are included here
  }
});

Image widget steps

Use the steps parameter to define which steps are included in the widget.

Possible values:

For example:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["sample"],
  image: {
    steps: [     
      "resizeAndCrop",
      "imageOverlay",
      "textOverlays",
      "export"
    ]
  }
});

Notes

  • By default, the resizeAndCrop and export steps are already included if you don't add the steps parameter.
  • You can change the order of the steps. The resizeAndCrop, textOverlays and imageOverlay steps are displayed in the widget in the same order given in the steps parameter. The export step should always be the last step.

Resize and crop

Media Editor resize

The resize and crop step of the widget enables your users to select a predefined option for resizing the image, to manually crop the image using the crop handles, and to flip or rotate the image.

Use the resizeAndCrop parameter to populate the Media Editor with an ordered array of presets that the user can choose from, in order to resize and crop the image. Each preset in the array can either be a predefined named shortcut, or can be defined as a custom preset with a label, width, height and/or aspectRatio. The guidelinesUrl property allows you to add an informative image (with cropping instructions for example) to the right-hand side of the display.

See the ResizeProps options for more details on the available options.

Note
The following presets are included by default: Original, Square, Landscape 16:9, Landscape 4:3, Portrait 3:4, and Portrait 9:16

For example, to add the Twitter Ad and LinkedIn Ad predefined shortcuts, as well as a custom preset with the label "Cover Ad" and dimensions of 500 x 1000:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["sample"],
  image: {
    steps: ["resizeAndCrop"],
    resizeAndCrop: {
      presets: ["facebookAd", "twitterAd", 
        {label: "Cover Ad", width: 500, height: 1000 }], 
      guidelinesUrl: "https://my.example.com/cropping_help.jpg"
    }
  }
});

Image overlays

Media Editor overlays

The image overlays step of the widget enables your users to choose an image overlay to add to the base image. Each of the overlay options is defined by a set of properties, including the size and allowed placements on the base image for the user to select.

  • Use the imageOverlay parameter to populate the Media Editor with an ordered array of overlays that the user can choose from.
  • Each overlay in the array is defined with a publicId, label, any transformation to apply, and an array of allowed placementOptions, where each placementOption is defined by a bounding box (width and height), a location on the base image (gravity) and any offset from the selected location (x and y).
  • The guidelinesUrl property allows you to add an informative image (with overlay instructions for example) to the right-hand side of the display.

See the ImageOverlayProps options for more details on the available options.

For example, to add 2 options for overlays as follows: The 'logo' image with a blackwhite effect applied and 2 placement options, and the 'logo_text' image with a negative effect applied and a single placement option:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"],
  image: {
    steps: ["imageOverlay"],
    imageOverlay: {
      overlays: [
         {
          "publicId": "logo",
          "label": "Logo",
          "transformation": [{ "effect": "blackwhite" }],
          "placementOptions": [{
              "x": 10,
              "y": 10,
              "width": 400,
              "height": 400,
              "gravity": "north_west"
            },
            {
              "x": 0,
              "y": 0,
              "width": 400,
              "height": 400,
              "gravity": "north_east"
            }
          ]
        },
        {
          "publicId": "logo_text",
          "label": "Logo with Text",
          "transformation": [{ "effect": "negative" }],
          "placementOptions": [{
              "x": 0,
              "y": 0,
              "width": 400,
              "height": 400,
              "gravity": "north_east"
         }
      ],
      guidelinesUrl: "https://my.example.com/overlay_help.jpg"
    }
  }
});

Text overlays

Media Editor text overlays

The text overlays step of the widget enables your users to add text to the base image. Once placed on the image, the overlay can be resized, the text can be edited, the color, font and style can be updated, and the overlay can be dragged to any location within the image. The editor supports multi line text boxes and displays alignment grids to help position the text overlay within the image or for aligning 2 text boxes.

Use the textOverlays parameter to customize the text overlay step with the following properties:

  • The fonts property to define an array of allowed fonts. Default (all the built-in fonts): ["Ariel", "Verdana", "Helvetica", "Trebuchet MS", "Times New Roman", "Georgia", "Courier New", "Open Sans", "Roboto", "Montserrat"]
  • The presets property to define an array of text overlay presets available for the user to select. Default: ["heading", "body", "subtitle", "caption"]
  • The guidelinesUrl property to add an informative image (with overlay instructions for example) to the right-hand side of the display.
  • The initialColors property to define an array of colors for the user to select. Default: ["#ffffff", "#000000"]
  • The showColorPicker boolean property to set whether the color picker is also available for the user to select a color.

Notes for using custom fonts

  • All custom fonts you want to use need to be first uploaded to your Cloudinary account as raw, authenticated files.
  • Since the custom font is uploaded as an authenticated file, you will also need to implement the onSign method of the widget to return the signature needed to access a restricted asset.
  • You need to specify the font's full public_id (as a raw file this will include the extension).

See the TextOverlaysProps options for more details on the available options.

For example, to allow 3 possible font options (Arial, Times New Roman, and a custom font called MyFont), and predefine 4 presets (heading, body and 2 custom presets), and set some initial color options while hiding the color picker:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"],
  image: {
    steps: ["textOverlays"],
    textOverlays: {
      fonts: [
        "Arial",
        "Times New Roman",
        {
          font: "MyFont",
          styles: {
            regular: "fonts/MyFont-Regular.ttf",
            bold: "fonts/MyFont-Bold.ttf",
            italic: "fonts/MyFont-Italic.ttf",
            boldItalic: "fonts/MyFont-BoldItalic.ttf",
            underline: true
          }
        }
      ],
      presets: [
        "heading", // predefined preset
        "body", // predefined preset
        {
          label: "Custom Subtitle",
          previewText: "DEF",
          size: 40,
          font: "MyFont", // requires the MyFont font to be defined in the fonts property
          weight: "normal",
          style: "normal",
          color: "#ffffff",
          underline: true
        },
        {
          label: "My Header",
          previewText: "ABC",
          size: 70,
          font: "Arial", // requires the Arial font to be defined in the fonts property
          weight: "bold",
          style: "italic",
          color: "#fbff3a",
          underline: true
        }
      ],
      initialColors: ["#3448c5", "#ff5050","#f7bc00"," #48c4d8" ,"#0052cc", "#a600cc", "#8ecc00"],
      showColorPicker: false,
      guidelinesUrl: "https://my.example.com/overlay_help.jpg"
    }
  }
});
// for custom fonts you need a signature service running.

myEditor.onSign(function (data) {
  return new Promise(function (resolve) {
    // you need to replace this with a working end-point with your signature service
    fetch(
      "http://my.endpoint.com/asset${encPath(data.publicId)}${encPath(
        data.resourceType
      )}${encPath(data.type)}${encPath(data.transformation)}"
    )
      .then((response) => response.json())
      .then((d) => resolve(d));
  });
});

Export

Media Editor export

The export step of the widget enables your users to select from provided exporting options.

Use the export parameter to populate the Media Editor with an ordered array of formats and quality to select from, and whether the HTTPS URL and Download options are displayed.

See the ExportProps options for more details on the available options.

For example:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"],
  image: {
    steps: ["export"],
    export: {  
      "formats": [
        "auto",
        "png",
        "webp"
      ],
      "quality": [
        "auto",
        55,
        75,
        "low"
      ],
      "download": false,
      "share": false
    }
  }  
});

Editor events

You can register to a variety of Media Editor widget events in order to introduce custom behavior in your application, or for analytics tracking once your application is deployed. Use the on method with an initialized widget to register to a specific event. For example, to register the initialized myEditor Media Editor widget to the headerclick event:

Copy to clipboard
myEditor.on("headerclick", (data) => {
  console.log("HeaderClick: ", data);
});

Important
If you want your code to have access to the final delivery URLs once your user has finished interacting with the widget, make sure to register to the export event, which is called when the user clicks on the Export button.

For a full listing of available events, see the Events section in the Media Editor API reference.

Localization

The text used in the widget can be fully customized for different languages or locales by specifying a language object parameter. The strings for each language are specified using the messages parameter, which accepts a JSON structure defining the value to use for each text element in each language. The locale parameter sets which of the string options to use from those defined in the messages parameter (en-US by default). To override any of the default values, you only need to include the elements you want to override.

All the default values can be found at: https://media-editor.cloudinary.com/widget/messages.json.

For example, to only customize the header and the crop - presets - square texts:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"], 
  language: {
    locale: 'en_US',
    messages: {
      en_US: { 
        "header": "Edit Image",
        "crop": {
          "presets": {
            "square": "Square",
          }
        }
      }
    }
  }
});

Media Editor widget reference

For details on all the available methods, parameters and events, see the Media Editor reference.

✔️ Feedback sent!

Rate this page: