Cloudinary Blog

Introducing the Cloudinary Media Editor Widget

How to Use the Cloudinary Media Editor Widget

At Cloudinary, we manage the entire pipeline of media assets for thousands of customers of varying sizes from numerous verticals.

As part of our commitment to support the entire flow of media assets, we are now introducing an intuitive media editing widget: an out­-of­-the-­box, interactive UI providing your users with a set of common image editing actions for immediate use on your website or web app. The widget is interactive and simple, built on Cloudinary's transformation capabilities, and requiring only a few lines of code to integrate. Afterwards, you can seamlessly and effortlessly add content to your site or app with no need for in-house image editing capabilities.

The Media Editor is especially useful for enabling your own content providers that may need to make simple edits on images manually. The editor helps to scale internal operations by reducing dependency on designers for simple recurring tasks, and allowing content providers to quickly review and tweak assets when needed.

The Widget at a Glance

The Media Editor widget provides a flexible means to review, fix, or adjust your media assets when needed. The following widget features can help you achieve your goals:

  • Resize and crop: Provide your users with predefined options for resizing the image, allow them to manually crop an image using crop handles, or even to flip or rotate the image.
  • Image overlays: Supply your users with image overlays to select from, and define the optional locations to add them to the base image.
  • Export: Offer your users the ability to select from various exporting options, including changing format and quality.
  • Events: A variety of Media Editor widget events are triggered in order to allow you to introduce custom behavior in your application.
  • Analytics tracking: Data about how your users interact with the widget.
  • Localization: The text labels used in the widget can be fully customized for different languages and locales.

Integrate the Widget

Adding the widget into your application is simple: just include the widget script and then call the widget with a few lines of code, providing the publicId of an image to edit, and the name of your Cloudinary cloud. The "export" event will include the data for the final edited image. For example:

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){
   // your code to handle the final image, for example:
   console.log(data);
})
</script>

That's it --that's all that's needed to implement the default widget. You can try a live example right now by clicking the button below and editing an image.

As can be seen, the default functionality includes a resize and crop step, and an export step. Of course there are plenty of ways to extend the default functionality and override the default settings.

Customize the Resize and Crop Options

Instead of just using the default configuration for the resizeAndCrop step, one of the options you have is to limit the user's ability to resize the image, and provide your own presets for the user to select. For the following example, we disable the interactive cropping ("interactiveCrop": false) and then provide two Cloudinary predefined options (facebookCover and linkedInCover) and one custom option (label: "Cover Ad", width: 500, aspectRatio: "16:9"):

Copy to clipboard
const myEditor = cloudinary.mediaEditor();
myEditor.update({
  publicIds: ["sample"],
  cloudName: "demo", 
  "resizeAndCrop": {
      "interactiveCrop": false,
      "presets": [
         "facebookCover",
         "linkedInCover", 
         {
  label: "Cover Ad", 
  width: 500, 
  aspectRatio: "16:9" 
         }
      ]
    }
});
myEditor.show();
myEditor.on("export",function(data){
  console.log(data);
})

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

Add a Step for Image Overlays

The default widget doesn't include the overlay functionality out­-of­-the-­box. Adding an overlay can be a valuable addition to the image, letting your users add a company logo or even a watermark. To enable this step, you have to provide the imageOverlay parameter populated with an ordered array of overlays that the user can choose from. Each overlay in the array is defined with a publicId, a label, any transformation to apply, and an array of allowed placement options that are 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).

For example, to add 2 options for overlays to your users as follows: The 'cloudinary_logo' image with a blackwhite effect applied and 2 placement options (top-right and top-left), The 'cloudinary_text' image with a negative effect applied and a single placement option (bottom-right):

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["cloud"],
  widgetSteps: ["imageOverlay"],
  imageOverlay: {
    overlays: [
       {
        "publicId": "cloudinary_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": "cloudinary_text",
        "label": "Logo with Text",
        "transformation": [{ "effect": "negative" }],
        "placementOptions": [{
            "x": 0,
            "y": 0,
            "width": 400,
            "height": 400,
            "gravity": "south_east"
       }
    ]
  };  
});

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

Export the Image

Once the user finishes editing the image, the export step of the widget enables them to select how to finish with their editing. By default, only adjusting quality options are available, but you can also offer your users some format options to choose from, as well as limiting their ability to download the final image or share it. Use the export parameter to populate the Media Editor with an ordered array of formats and quality to select from, and whether the URL and Download options are displayed.

For example, to just use the widget as a way to change quality and format of an image, you can disable the download option, add some format options (jpg and png), and provide your own quality options:

Copy to clipboard
const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"],
  widgetSteps: ["export"],
  export: {
    "formats": [
      "jpg",
      "png"
    ],
    "quality": [
      "auto",
      60,
      "low"
    ],
    "download": false,
    "share": false
  };  
});
myEditor.on("export",function(data){
  // your code to handle the final image
})

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

An Interactive Demo

Just to make your life that much easier, we've created a live Media Editor Demo page that lets you experiment with the various customization options available for the widget. Not only can you use this demo to get a better idea of what the widget offers, but the Demo page also automatically generates the code template you need to implement your customized widget on your own site.

Summing Up

Cloudinary's Media Editor is an interactive and fully customizable user interface that allows you to provide your users with an easy way to do common editing tasks, including resizing, cropping, adding overlays, and more. For more information on the Media Editor widget, and all the customization and functional parameters, please see the documentation. If you have any questions, please comment below or test it on your own site by signing up for free.

Interested in more Media Editor features? Some are already planned and on our roadmap, for example Text Overlays, where you can vote or share your requests.

Recent Blog Posts

Why the Future of E-commerce Is Live

In a previous post, I discussed how “going live” is gaining popularity across industries and verticals. What began as a way for gamers to jam together has evolved into a medium for broader entertainment and business purposes. To continue the conversation, this post unpacks the current trends of shoppable live streams to shine a light on how brands are leveraging “lives” to connect with shoppers in new ways.

Read more
An Overview of Live-Streaming Video Trends

“Let’s go live.” For decades, that’s what newscasters say as they cut to real-time footage of a colleague reporting in the field. The live-video feed adds visual interest and perspective to a story beyond what can be communicated by someone sitting behind the news desk. In the same way, live-streaming video nowadays adds context to other consumer environments. From gaming and events to shopping and social media, “going live” enhances everyday experiences, and it’s something anyone can do with relative ease.

Read more
Readying Live Streams for Video on Demand

When planning a live broadcast or stream, companies often overlook the redistribution phase, but live-stream videos are useful well beyond their initial streaming. Why? Because not everyone watches the first run. For a wider audience, it makes sense to repost live content on your website under an “events” tab, on YouTube, and other social sites for video on demand (VOD). However, preparing footage for reposting can be a lot of work.

Read more
Optimize Visual Media for a Fast and Captivating Digital Experience

Did you know that humans process imagery 60,000 times faster than text? In fact, 90% of the information our brains process is visual, which makes it seem a no-brainer—pun intended—that brands are connecting with consumers through visual content online. However, adding media assets like images and videos to websites comes with a tradeoff: the more media, the heavier the site, which results in a noticeable slowdown in page loads and a reduction in content quality.

Read more