Assets
Media Editor API reference
Last updated: Dec-11-2024
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 guide.
On this page:
Parameters
The following tables list all available parameters (options) for configuring a Media Editor widget with the update 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 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 videos and/or authenticated/private assets) or by a PublicID string (as a shortcut for public images only). Example: [{publicId: "sandy_beach", type: "authenticated"}]
|
Important
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 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 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 | 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. |
| textOverlays | TextOverlaysProps | The properties for the text overlay step of the widget. Only relevant when the textOverlays step is included. |
| export | 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 | The properties for the trim step of the widget. |
| transformation | Object | The Cloudinary transformation 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 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
|
| 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 | 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)[] | 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 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 or 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:
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 for using custom fonts
- All custom fonts you want to use need to be first uploaded to Cloudinary as raw, authenticated files.
- Since the custom font is uploaded as an authenticated file, you will also need to implement the 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).
For example:
ExportProps
| Parameter | Type | Description |
|---|---|---|
| formats | string[] | An array of image formats (including 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 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:
OverlayProps
| Parameter | Type | Description |
|---|---|---|
| publicId | String | required. The ID of the image to be placed as an overlay. |
| publicIds | Asset or PublicID | The image to be placed as an overlay. The image 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: "company_logo", type: "authenticated"}
|
| label | String | The label for this overlay option. |
| transformations | Object[] | An array of Cloudinary transformation objects to apply to the overlay. Any transformations, effects, and other Cloudinary transformation options can be applied. |
| placementOptions | (PredefinedPlacement or 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. 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"}]
|
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:
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:
Update
The update method accepts a map of configuration 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:
Show
Displays an initialized Media Editor widget object, or a previously hidden widget.
For example:
Hide
Hides a previously displayed widget without removing it from memory.
For example:
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:
On
Use the on method to register to a specific event. For a full listing of available events, see the Events section.
For example:
Sample response:
getConfig
Returns the current configuration of the Media Editor widget.
For example:
getVersion
Returns the widget version.
For example:
triggerExport
Triggers the export function (as if the user had clicked on the export button).
For example:
onSign
Use the onSign method to resolve the delivery signature needed for a restricted asset or a custom font (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:
Events
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. | |
| 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 theurl,secureUrlanddownloadUrl. For example:
See also
For more information on the Cloudinary Media Editor, see the Media Editor guide.
✖️
Error
Rate this page:
