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.
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:
<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>
- 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:
- Include the JavaScript file:
https://media-editor.cloudinary.com/all.js
. - Initialize the Media Editor widget with the
cloudinary.mediaEditor()
method. - Update the Media Editor configuration with the
update(options)
method. - Show the Media Editor widget with the
show()
method.
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:
<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:
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:
const myEditor = cloudinary.mediaEditor({appendTo: document.getElementById("my-widget-container");}); // OR const myEditor = cloudinary.mediaEditor({appendTo: '#my-widget-container'})
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:
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:
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:
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:
const myEditor= cloudinary.mediaEditor(); myEditor.update({ cloudName: "demo", publicIds: ["sample"], image: { steps: [ "resizeAndCrop", "export" ] } });
- By default, the
resizeAndCrop
andexport
steps are already included if you don't add thesteps
parameter. The example above is for demonstration purposes. - You can change the order of the steps. The
resizeAndCrop
andimageOverlay
steps are displayed in the widget in the same order given in thesteps
parameter. Theexport
step should always be the last step.
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.
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:
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
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 ofoverlays
that the user can choose from. - Each overlay in the array is defined with a
publicId
,label
, anytransformation
to apply, and an array of allowedplacementOptions
, 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:
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" } } });
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:
const myEditor= cloudinary.mediaEditor(); myEditor.update({ cloudName: "demo", publicIds: ["flower"], image: { steps: ["export"], export: { "formats": [ "jpg", "png", "webp" ], "quality": [ "auto", 10, 55, "low" ], "download": true, "share": true } } });
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:
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:
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.