Media Editor (ALPHA)

Important
The Media Editor is currently in the ALPHA phase of development. Some parameter names and other implementation details will change before the official release.

Cloudinary's Media Editor is an interactive user interface providing a set of common editing actions to your users on your website or application. The Media Editor requires only pure 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 (minimum) 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 - alpha version

  • There may be some issues using private/authenticated assets, and we recommend using public assets for testing purposes.
  • Internet Explorer 11 is not supported.
  • Mobile devices are not supported.
  • If you rotate after an interactive crop, the crop resets and you need to re-crop.

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.

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 selector or DOM element as an appendTo parameter, for example:

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

3. Update the Media Editor widget

The update(options) method configures the Media Editor, where options is an object containing the Media Editor 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();

Instance methods

The following methods can be used with the Media Editor instance returned by the mediaEditor initialization method:

Show

Renders an initialized Media Editor widget object, or a previously hidden widget.

For example:

Copy to clipboard
myEditor.show();

Hide

Hides a previously rendered widget without removing it from memory.

For example:

Copy to clipboard
myEditor.hide();

Update

The update method accepts a map of configuration parameters to update an already initialized widget.

For example:

Copy to clipboard
myEditor.update({
  publicIds: ["running_shoes"]
});

Destroy

Use the destroy method to erase the Media Editor widget and remove it from memory.

For example:

Copy to clipboard
myEditor.destroy();

Important
To avoid memory leaks and performance issues, make sure to use the destroy method before removing the Media Editor widget from your DOM.

On

Use the on method to register to a specific event. For a full listing of available events, see the Events section.

For example:

Copy to clipboard
myGallery.on("formatclick", (data) => {
  console.log("FormatClick: ", data.label);
});

Sample response:

Copy to clipboard
{ 
  "event": "flipvertically", 
  "action": "preview", 
  "label": "flip vertically", 
  "params": {} 
}

getConfig

Returns the current configuration options of the Media Editor widget.

For example:

Copy to clipboard
var currentConfig = myEditor.getConfig();

onSign

Use the onSign method to resolve the delivery signature needed for a restricted asset (see Authenticated access to media assets). You should provide the code in the form of a Promise that will request the delivery URL from your back-end server, and then set the url parameter with the full delivery URL of the image (including a signature component or token query string if required).

For example:

Copy to clipboard
myEditor.onSign(async function(data) {
  const { publicId, resourceType, type, transformation } = data;
  const url = generateUrl(publicId, resourceType, type, transformation)
  return url
});

Widget steps

Use the widgetSteps 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"],
  widgetSteps: [     
    "resizeAndCrop",
    "export"
  ]
});

Note
By default, the resizeAndCrop and export steps are already included if you don't add the widgetSteps parameter. The example above is for demonstration purposes.

Resize and crop

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 with a label, width, height and/or aspectRatio. The guidelinesUrl parameter 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"],
  widgetSteps: ["resizeAndCrop"],
  resizeAndCrop: {
    presets: ["facebookAd", "twitterAd", 
      {label: "Cover Ad", width: 500, height: 1000 }], 
    guidelinesUrl: "https://my.example.com/cropping_help.jpg"
  }
});

Media Editor resize

Image 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 parameter 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"],
  widgetSteps: ["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"
  };  
});

Media Editor overlays

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 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"],
  widgetSteps: ["export"],
  export: {
    "formats": [
      "jpg",
      "png",
      "webp"
    ],
    "quality": [
      "auto",
      10,
      55,
      "low"
    ],
    "download": true,
    "share": true
  };  
});

Media Editor export

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.

The following information is included when the event is triggered, and is available in the (data) structure:

  • action: The action that triggered the event.
  • label: A description of the event.
  • params: Additional information returned as key/values pairs (see the table below for details).

The following table lists the events that can be registered with the on method of a Media Editor instance.

Event Params Description
aspectratioclick The aspect ratio toggle has been clicked.
close The widget was closed with the X button.
copyurl resourceType The URL was copied.
cropclick presetName A crop preset has been clicked.
dimensionsedit width, height An image's dimensions were edited (width or height).
download resourceType The image was downloaded.
formatclick selectedFormat A format option was clicked.
interactivecropresize An image was interactively resized.
interactivecropmove An image was interactively moved.
next fromStep, toStep The user moved to the next widget step.
overlayclick selectedPreset An overlay preset has been clicked.
overlayplacementclick An overlay placement has been clicked.
prev fromStep, toStep The user moved to the previous widget step.
qualityclick selectedQuality A quality option was clicked.
flipvertically The flip vertical button has been clicked.
fliphorizontally The flip horizontal button has been clicked.
rotateclockwise The rotate clockwise button has been clicked.
rotatecounterclockwise The rotate counterclockwise button has been clicked.

We also support 2 special events:

  • analytics - Registers to all the events, which is useful for analytics purposes. The (data) structure will also include the event that triggered.
  • export - The user clicks on the "Export" button. The (data) structure will also include an array of assets with the url, secureUrl and downloadUrl. For example:

    Copy to clipboard
    myEditor.on("export", function(data) {
    console.log("URL: ", data.assets[0].url);
    console.log("Secure URL: ", data.assets[0].secureUrl);
    console.log("Download URL: ", data.assets[0].downloadUrl);
    });

Media Editor options

The following tables list the available Media Editor widget options.

Required parameters

The following parameters are required when initializing the Media Editor widget:

Parameter Type Description
cloudName string Your Cloudinary account cloud name.
Example: "demo"
publicIds Asset[] or PublicID[] Initializes the Media Editor with the specified publicIds (Note: currently only supports a single public ID). The individual assets in the array can be described either by an Asset object (necessary for authenticated/private assets) or by a PublicID string (as a shortcut for public images only).
Example: [{publicId: "sandy_beach", type: "authenticated"}]

Widget parameters

Parameter Type Description
transformation Object The Cloudinary transformation to apply to all images. Any manipulations, effects, and other Cloudinary transformation options can be applied and will be added in addition to any other transformations added with the Media Editor (resize, overlay, etc).
Example: [{effect: "sepia"}]
maxWidth int The maximum allowed width for the image.
maxHeight int The maximum allowed height for the image.
widgetSteps string[] An array of steps to include in the widget, in the specified order. Possible values: resizeAndCrop, imageOverlay, export
resizeAndCrop ResizeProps The properties for the resize and crop step of the widget. Only relevant when the resizeAndCrop step is included.
imageOverlay ImageOverlayProps The properties for the image overlay step of the widget. Only relevant when the imageOverlay step is included.
export ExportProps The properties for the export step of the widget. Only relevant when the export step is included.

Asset

An object identifying an uploaded asset. This object is only necessary to identify restricted assets (private/authenticated).

Parameter Type Description
publicId string A string value representing the identifier that is used for accessing an uploaded media asset.
type string The delivery type of the uploaded asset. Possible values: private, authenticated

ResizeProps

Parameter Type Description
presets (PredefinedPreset or CustomPreset)[] An array of preset options that the user can choose from, where each object identifies either a predefined social media preset or a custom preset.
interactiveCrop boolean Whether to allow interactive cropping. Default: true
aspectRatioLock boolean Whether to lock the aspect ratio. If true, aspect ratio starts locked. Default: true
toggleAspectRatio boolean Whether to allow toggling the aspect ratio. If false, the toggle is disabled and set to the value of aspectRatioLock. Default: true
flip boolean Whether to display the flip buttons, enabling the user to flip the image. Default: true
rotate boolean Whether to display the rotate buttons, enabling the user to rotate the image. Default: true
guidelinesUrl URL The URL of an informative image (with instructions for example) to appear on the right-hand side of the display.

ImageOverlayProps

Parameter Type Description
overlays OverlayProps An array of overlay objects for the user to choose from, where each object identifies a possible image overlay and its properties.
guidelinesUrl URL The URL of an informative image (with overlay instructions for example) to appear on the right-hand side of the display.

ExportProps

Parameter Type Description
formats string[] An array of image formats for the user to choose from, by file extension. If this parameter is not given, defaults to the original file type, and no options are provided to the user.
quality string[] An array of image qualities for the user to choose from. If this parameter is not given, defaults to auto, best, good, eco
download Boolean Whether the download button is displayed. Default true
share Boolean Whether to display the URL and enable the copy URL function when clicked. Default true

PredefinedPreset

Value Label Dimensions
original Original {The original dimensions of the image}
square Square Ratio: 1:1
landscape-16:9 Landscape Ratio: 16:9
landscape-4:3 Landscape Ratio: 4:3
portrait-9:16 Portrait Ratio: 9:16
portrait-3:4 Portrait Ratio: 3:4
facebookStory Facebook Story 1080 x 1920
facebookPost Facebook Post 940 x 788
facebookCover Facebook Cover 820 x 312
facebookAd Facebook Ad 1200 x 628
facebookEvent Facebook Event 1920 x 1080
instagramStory Instagram Story 1080 x 1920
instagramPost Instagram Post 1080 x 1080
twitterTweet Twitter Tweet 1024 x 512
twitterAd Twitter Ad 800 x 320
linkedInCover LinkedIn Cover 1584 x 396
linkedInCompanyCover LinkedIn Company Cover 1536 x 768
linkedInAd LinkedIn Ad 1200 x 627
pinterestBoardCover Pinterest Board Cover 222 x 150
pinterestPin Pinterest Pin 600 x 900

CustomPreset

Property Description
label (required) The label of the preset.
width The desired width of the image.
height The desired height of the image
aspectRatio The desired aspect ratio of the image. If neither width nor height is provided, use the original width for portrait images and the height for landscape images. Ignore this property if both width and height are given.

For example:

Copy to clipboard
{
  label: "Cover Ad", 
  width: 500, 
  aspectRatio: "16:9" 
}

OverlayProps

Parameter Type Description
publicId String required. The ID of the image to be placed as an overlay.
label String The label for this overlay option.
transformations Object[] An array of Cloudinary transformation objects to apply to the overlay. Any manipulations, effects, and other Cloudinary transformation options can be applied.
placementOptions (PredefinedPlacement or CustomPlacement)[] An array of overlay placement options for the user to chose from, where each object identifies either a predefined placement or a custom placement location.
Example:
[ {"x": 0.8, "y": 0.8, "width": 300, "height": 300, "gravity": "north_west"}, {"x": 0, "y": 0, "width": 200, "height": 200, "gravity": "north_east", "top"}]

PredefinedPlacement

Value Description
top "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "north"
top_right "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "north_east"
right "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "east"
bottom_right "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "south_east"
bottom "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "south"
bottom_left "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "south_west"
left "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "west"
top_left "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "north_west"
middle "x": 0, "y": 0, "width": 0.1, "height": 0.1, "gravity": "center"

CustomPlacement

Parameter Type Description
width int or float The width of the overlay: an integer sets the value in pixels (e.g., 150 sets the width to exactly 150 pixels) and a float sets the value as a multiple of the base image width (e.g., 0.1 sets the width to 10% of the base image width).
height int or float The height of the overlay: an integer sets the value in pixels (e.g., 100 sets the height to exactly 100 pixels) and a float sets the value as a multiple of the base image height (e.g., 0.2 sets the height to 20% of the base image height).
gravity string Specifies where to place the overlay on the base image. Possible values: north_east, north, north_west, west, south_west, south, south_east, east, center
x int or float The horizontal offset of the overlay from the specified gravity: an integer sets the value in pixels (e.g., 10 sets the horizontal offset to exactly 10 pixels) and a float sets the value as a multiple of the base image width (e.g., 0.15 sets the horizontal offset to 15% of the base image width).
y int or float The vertical offset of the overlay from the specified gravity: an integer sets the value in pixels (e.g., 15 sets the vertical offset to exactly 15 pixels) and a float sets the value as a multiple of the base image height (e.g., 0.1 sets the vertical offset to 10% of the base image height).

For example:

Copy to clipboard
{
  "x": 0.8, 
  "y": 0.8, 
  "width": 300, 
  "height": 300, 
  "gravity": "north_west"
}

✔️ Feedback sent!