> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Media Editor API reference


The Media Editor API reference details all the parameter options, types and events for configuring the Media Editor widget.

> **TIP**: For in-depth information, see the [Media Editor](media_editor) guide.

## Parameters

The following tables list all available parameters (options) for configuring a Media Editor widget with the [update](media_editor##3_update_the_media_editor_widget) method:

### Required parameters

The following parameters are **required** when configuring the Media Editor widget:

Parameter | Type | Description
---|---|--- 
cloudName | string | Your Cloudinary product environment cloud name.Example: `"demo"`
publicIds | ([Asset](#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](#asset) object (necessary for videos and/or authenticated/private assets) or by a PublicID string (as a shortcut for public images only). Example: `[{publicId: "sandy_beach", type: "authenticated"}]`

> **INFO**: Besides the required parameters, **only include other parameters in order to override their default values**.

  
### Widget parameters

Parameter | Type | Description
---|---|--- 
mode | String | Determines how the widget is displayed, either as `modal` (default) or `inline` within the page body (or the element given by the `appendTo` parameter).
language | Object | The text strings to use in the widget, that includes all the "key":"value" pairs of text to override the widget's default text labels. See the [Localization](media_editor#localization) sample as a reference implementation.
theme | Object | The theme properties to apply to the widget. Currently only supports customizing the logo that appears in the top left corner of the widget.  Example: `theme: {logo: 'https://www.example.com/mylogo.png'}`

### Image parameters

Parameter | Type | Description
---|---|--- 
transformation |  Object  | The Cloudinary [transformation](transformation_reference) to apply to all images. Any transformations, 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 final image.
maxHeight | int | The maximum allowed height for the final image.
steps | string[] | An array of steps to include in the widget, in the specified order. **Possible values**: `resizeAndCrop`, `imageOverlay`, `textOverlays`, `export`
resizeAndCrop | [ResizeProps](#resizeprops) | The properties for the resize and crop step of the widget. Only relevant when the `resizeAndCrop` step is included.
imageOverlay | [ImageOverlayProps](#imageoverlayprops) | The properties for the image overlay step of the widget. Only relevant when the `imageOverlay` step is included.
textOverlays | [TextOverlaysProps](#textoverlaysprops) | The properties for the text overlay step of the widget. Only relevant when the `textOverlays` step is included.
export | [ExportProps](#exportprops) | The properties for the export step of the widget. Only relevant when the `export` step is included.
> **NOTE**: All transformations use the JavaScript (legacy) syntax. When looking at transformation examples in the rest of the documentation, you can change the JS tab to display the legacy (cloudinary-core) code examples.
### Video parameters

Parameter | Type | Description
---|---|--- 
steps | string[] | An array of steps to include in the widget, in the specified order. Currently only supports `trim`.
trim | [TrimProps](#trimprops) | The properties for the trim step of the widget. 
transformation |  Object  | The Cloudinary [transformation](transformation_reference) to apply to all videos. Any manipulations, effects, and other Cloudinary transformation options can be applied and will be added *in addition* to any other transformations added with the trim.  Example: `[{effect: "sepia"}]`
maxWidth | int | The maximum allowed width for the final video.
maxHeight | int | The maximum allowed height for the final video.

## Types

### 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.
resourceType | string | The file type of the asset. **Possible values**: `image` (default) or `video`
type | string | The delivery type of the uploaded asset. **Possible values**: `public` (default), `private` or `authenticated`
  

### ResizeProps

Parameter | Type | Description
---|---|---
presets |  ([PredefinedPreset](#predefinedpreset)  or [CustomPreset](#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`
minCropWidth | int | The minimum width allowed for the crop.
minCropHeight | int | The minimum height allowed for the crop.
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. If this parameter is not given then the right-hand section will not appear.

### ImageOverlayProps

Parameter | Type | Description
---|---|---
overlays | [OverlayProps](#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. 

### TextOverlaysProps

Parameter | Type | Description
---|---|---
fonts | (string or [FontProps](#fontprops))[] | An array of fonts for the user to choose from, where each font in the array is either a predefined 'built-in' font, or defines a [custom font](#fontprops) and its properties. Default (all the built-in fonts): `["Ariel", "Verdana", "Helvetica", "Trebuchet MS", "Times New Roman", "Georgia", "Courier New", "Open Sans", "Roboto", "Montserrat"]`
presets | ([PredefinedTextPreset](#predefinedtextpreset) or [CustomTextPreset](#customtextpreset))[]  |  An array of text preset objects for the user to choose from, where each object identifies an initial text overlay and its properties. Default: `["heading", "body", "subtitle", "caption"]`
guidelinesUrl| URL | The URL of an informative image (with overlay instructions for example) to appear on the right-hand side of the display. 
initialColors | string[]   | An array of preset colors for the user to initially select from. The colors can be given as an RGB or RGBA hex triplet or quadruplet, a 3- or 4-digit RGB/RGBA hex, or a named color. Default: `["#ffffff", "#000000"]`
showColorPicker | boolean  | Whether to display the color picker in addition to the preset colors. Default: `true`

### TrimProps (Beta)

Parameter | Type | Description
---|---|---
startOffset | float | The initial location of the starting trim handle for the video in seconds. Default: `0`
endOffset | float | The initial location of the ending trim handle for the video in seconds. Default: the full duration of the video.
minDuration  | float | The minimum duration for the trimmed video. Default: `0`
maxDuration | float |  The maximum duration for the trimmed video. Default: the full duration of the video.

### PredefinedTextPreset

These are the values of the predefined text presets:

label | previewText | size | font
---|---|---|---
heading | ABC | 59| Georgia
subtitle | ABC | 16| Ariel
body | ABC |14 | Roboto
caption  | ABC |12 | Montserrat

### CustomTextPreset

Property | Type | Description
---|---|---
label | string | (required) The label of the preset.
size | int | (required) The font size in points.
font | string | (required) The name of the font.
previewText| string | The preview text to showcase this text overlay preset. Maximum 3 characters. Default: `"ABC"`
weight | enum | Either `normal` or `bold`. Default: `"normal"`
style |enum | Either `normal` or `italic`. Default: `"normal"`
color | string | The color of the text. Default: `"#000000"`
underline | boolean | Whether to include an underline. Default: `false`

For example:

```json
{
  label: "My Header",
  size: 100,
  font: "Arial",
  previewText: "ABC",
  weight: "bold",
  style: "italic",
  color: "#fbff3a",
  underline: true
}
````

### FontProps

Property | Type | Description
---|---|---
font | string | The name of the custom font.
styles | object | An object detailing the public_ids of your custom font files. You can add up to four font files to use as values for each of the following keys: regular, bold, italic and boldItalic, and include whether to support underline.

{notes Notes for using custom fonts}

* All custom fonts you want to use need to be first uploaded to Cloudinary as [raw](upload_parameters#uploading_non_media_files_as_raw_files), [authenticated](upload_parameters#authenticated_assets) files.
* Since the custom font is uploaded as an [authenticated](upload_parameters#authenticated_assets) file, you will also need to implement the [onSign](media_editor_reference#onsign) method to return the signature needed for the widget to access a restricted asset.
* You need to specify the font's full `public_id` (as a raw file this will include the extension).
{/note}

For example:

```json
{
  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
  }
}
````

### ExportProps

Parameter | Type | Description
---|---|---
formats | string[] | An array of [image formats](image_transformations#supported_image_formats) (including [auto](image_transformations#f_auto)) 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](image_transformations#adjusting_image_quality) 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 HTTPS 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 | Type | Description
---|---|---
label | string | (required) The label of the preset.
width | int| The desired width of the image.
height | int | The desired height of the image
aspectRatio | string | 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:

```json
{
  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.
publicIds | [Asset](#asset) or PublicID |  The image to be placed as an overlay. The image can be described either by an [Asset](#asset) object (necessary for authenticated/private assets) or by a PublicID string (as a shortcut for public images only).<br> Example: `{publicId: "company_logo", type: "authenticated"}`
label |String| The label for this overlay option.
transformations | Object[] | An array of Cloudinary [transformation](transformation_reference) objects to apply to the overlay. Any transformations, effects, and other Cloudinary transformation options can be applied.  
placementOptions| ([PredefinedPlacement](#predefinedplacement) or [CustomPlacement](#customplacement))[] | An array of overlay placement options for the user to choose from, where each object identifies either a predefined placement or a custom placement location.<br>Example: <br/> `[ {"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"}]`

### 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:

```json
{
  "x": 0.8, 
  "y": 0.8, 
  "width": 300, 
  "height": 300, 
  "gravity": "north_west"
}
````

### 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"`

## Instance methods

The following methods can be used with the Media Editor instance returned by the `mediaEditor` [initialization method](media_editor#2_initialize_the_media_editor_widget):

* [Update](#update)
* [Show](#show)
* [Hide](#hide)
* [Destroy](#destroy)
* [On](#on)
* [getConfig](#getconfig)
* [getVersion](#getversion)
* [triggerExport](#triggerexport)
* [OnSign](#onsign)

### Update

The `update` method accepts a map of configuration [parameters](#parameters) to update an already initialized widget. The new configuration is merged with the existing configuration, so any new values will replace old ones. This includes arrays, where the entire array of values is replaced with the new array.

For example:

```js
myEditor.update({
  publicIds: ["running_shoes"]
});
```

### Show

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

For example:

```js
myEditor.show();
```

### Hide

Hides a previously displayed widget without removing it from memory. 

For example:

```js
myEditor.hide();
```

### Destroy

Use the `destroy` method to erase the Media Editor widget and remove it from memory and your DOM, and closes the event emitter. 

For example:

```js
myEditor.destroy();
```

### On

Use the `on` method to register to a specific event. For a full listing of available events, see the [Events](#events) section.

For example:

```js
myEditor.on("formatclick", (data) => {
  console.log("FormatClick: ", data.label);
});
```

Sample response:

```json
{ 
  "event": "flipvertically",  // this field is only returned for the `analytics` event
  "action": "preview", 
  "label": "flip vertically", 
  "params": {} 
}
````

### getConfig

Returns the current configuration of the Media Editor widget.

For example:

```js
var currentConfig = myEditor.getConfig();
```

### getVersion

Returns the widget version.

For example:

```js
var currentVersion = myEditor.getVersion();
```

### triggerExport 

Triggers the export function (as if the user had clicked on the export button).

For example:

```js
myEditor.triggerExport();
```

### onSign

Use the `onSign` method to resolve the delivery [signature](signatures) needed for a restricted asset or a custom font (see [Authenticated access to media assets](control_access_to_media#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:

```js
myEditor.onSign(async function(data) {
  const { publicId, resourceType, type, transformation } = data;
  const url = await generateUrl(publicId, resourceType, type, transformation)
  return { url }
});
````

## Events

The following table lists the events that can be registered with the [on](#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. 
textalign | type | The text alignment type, either: `canvas` when the text layer was aligned to the center (vertical or horizontal or both), or `layer` when the text layer was aligned to another layer.

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 above for details).

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:

```js
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);
});
````

> **See also**:
>
> For more information on the Cloudinary Media Editor, see the [Media Editor](media_editor) guide.