Media Editor (ALPHA)
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 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.
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:
<script src="https://media-editor.cloudinary.com/1.1.56/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>
- 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:
- Include the JavaScript file:
https://media-editor.cloudinary.com/1.1.56/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.
1. Include the JavaScript file
All the Media Editor functionality is included in the https://media-editor.cloudinary.com/1.1.56/all.js
JavaScript file. The file is optimized and delivered via a fast CDN.
For example:
<script src="https://media-editor.cloudinary.com/1.1.56/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 selector or DOM element as an appendTo
parameter, for example:
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:
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:
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:
Hide
Hides a previously rendered widget without removing it from memory.
For example:
Update
The update
method accepts a map of configuration parameters to update an already initialized widget.
For example:
Destroy
Use the destroy
method to erase the Media Editor widget and remove it from memory.
For example:
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:
myGallery.on("formatclick", (data) => { console.log("FormatClick: ", data.label); });
Sample response:
{ "event": "flipvertically", "action": "preview", "label": "flip vertically", "params": {} }
getConfig
Returns the current configuration options of the Media Editor widget.
For example:
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:
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:
const myEditor= cloudinary.mediaEditor(); myEditor.update({ cloudName: "demo", publicIds: ["sample"], widgetSteps: [ "resizeAndCrop", "export" ] });
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.
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"], widgetSteps: ["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"], 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" }; });
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:
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 }; });
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.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 theurl
,secureUrl
anddownloadUrl
. For example:
Localization
The text labels used in the widget can be fully customized for different languages. The translations for each language are specified using the text
parameter, which accepts a JSON structure defining the value to use for each text element in each language. The language
parameter sets which of the language options to use from those defined in the text parameter (en
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: "en", text: { "en": { "header": "Edit Image", "crop": { "presets": { "square": "Square", } } } } });
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. |
language | String | Determines which of the text parameter languages to use for the widget. Default: en |
text | Object | "key":"value" pairs of text to override the widget's default text labels. See the Localization sample as a reference implementation. |
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:
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: