Add a Media Editor to Your Web App with Cloudinary

Cloudinary provides a Media Editor, which is an interactive user interface that provides users on your website with common editing actions, reducing dependency on designers for simple recurring tasks.

In this post, we will build a demo application that shows how to use the Cloudinary Media Editor widget to perform image editing actions like cropping and resizing images, adding image and text overlay, e.t.c.

Here is a link to the demo on CodeSandbox.

To create a Next.js application, navigate to the project directory of your choice and run the following command:

npx create-next-app cloudinary-media-editor-demo

Now we can start our application on http://localhost:3000/ using the following command:

npm run dev

First, sign up for a free Cloudinary account if you don’t have one already. Important details are displayed on your account’s Management Console (aka Dashboard): your cloud name, API key, etc.

Next, we need to create some environment variables to hold our Cloudinary details. We will be sending images to Cloudinary via unsigned POST requests, and to do this, we need our account cloud name and an unsigned upload preset. Create a new file called .env at the root of the project and add the following to it:

NEXT_PUBLIC_CLOUD_NAME = "INSERT YOUR CLOUD NAME HERE";
NEXT_PUBLIC_UPLOAD_PRESET = "INSERT YOUR UNSIGNED UPLOAD PRESET KEY HERE";
Code language: JavaScript (javascript)

This will be used as a default when the project is set up on another system. To update your local environment, create a copy of the .env file using this command:

    cp .env .env.local
Code language: CSS (css)

By default, this local file is added to .gitignore and mitigates the security risk of inadvertently exposing secret credentials to the public. You can update .env.local with your cloud name and generated upload preset.

Create a new folder named utils at the root of your project. This folder will hold all our utility functions. In the utils folder, create a file called cloudinaryConfig.js. This file will give access to the environment variables and prevent repeated process.env. calls throughout the project. Add the following to your cloudinaryConfig.js file:

export const cloudName = process.env.NEXT_PUBLIC_CLOUD_NAME;
export const uploadPreset = process.env.NEXT_PUBLIC_UPLOAD_PRESET;
Code language: JavaScript (javascript)

Let’s create a component that allows a user to select an image to edit from their computer. We need the public ID of the selected image to configure the Media Editor widget, so the image has to be uploaded to Cloudinary.

Add the following to your index.js file:

import Script from "next/script";
import styles from "../styles/Home.module.css";
import { cloudName, uploadPreset } from "../utils/cloudinaryConfig";

export default function Home() {
  const handleUpload = async (e) => {
    const clUrl = `https://api.cloudinary.com/v1_1/${cloudName}/image/upload`;
    const file = e.target.files[0];
    const formData = new FormData();
    formData.append("file", file);
    formData.append("upload_preset", uploadPreset);
    const res = await fetch(clUrl, {
      method: "POST",
      body: formData,
    });
    const data = await res.json();
    const publicId = data.public_id;
    console.log(publicId);
  };

  return (
    <div className={styles.container}>
      <input type="file" accept="image/*" onChange={handleUpload} />
      <Script
        src="https://media-editor.cloudinary.com/all.js"
        type="text/javascript"
      ></Script>
    </div>
  );
}
Code language: JavaScript (javascript)

In the code above, we use Next.js Script tag to include a remote JavaScript file that contains all the Media Editor functionality. The Home component renders a file input with an onChange event. When the event is called, it triggers the handleUpload function. In the handleUpload function, we are making a POST request to the Cloudinary upload endpoint. The request body is a FormData object containing the selected file and the upload preset we defined. When the request is completed, we parse the response to JSON. Finally, we extract the public ID of the uploaded image from the data object, which will be used to configure the Media Editor widget.

So far, we have included the remote JavaScript file that brings the media editor functionality to our site. Next, we need to initialize and update the Media Editor configurations. In the utils folder, create a new file named startEditing.js and add the following to it:

import { cloudName } from "./cloudinaryConfig";

function startEditing(publicId) {
  const myEditor = cloudinary.mediaEditor();

  myEditor.update({
    cloudName: cloudName,
    publicIds: [publicId],
  });
  myEditor.show();
}

export default startEditing;
Code language: JavaScript (javascript)

The function above accepts publicId as props, which will be the public ID of the uploaded image. In the function, we start by creating and initializing the Media Editor widget with the cloudinary.mediaEditor() method. Then using the update method, we configure the widget with an object containing some configuration parameters — our cloud name and the public ID of the image to edit.

These are the only required parameters (options); the others are optional. Finally, we call the show method to display the initialized widget. See here for a complete list of parameters available for configuring the Media Editor widget.

Now let’s import this file in our index.js file. Add this line to the top of your pages/index.js file:

import startEditing from "../utils/startEditing";
Code language: JavaScript (javascript)

Then add this to the bottom of the handleUpload function:

const handleUpload = async (e) => {
  //…
  startEditing(publicId);
};
Code language: JavaScript (javascript)

Here we’re calling the startEditing function and passing the public ID of the image uploaded by the user. This open’s up the Media Editor widget with the image for editing.

Now run npm start in the project folder, open http://localhost:3000 in your browser, and select an image to be uploaded.

You should see the selected image uploaded and the Media Editor populated with the image. Neat right?

The media editor can be configured for both images and videos; however, we will only look at image configuration in this post. To set up the Media Editor for image editing, we must pass the image editing parameters to an image object parameter, as shown below:

import { cloudName } from "./cloudinaryConfig";

function startEditing(publicId) {
  const myEditor = cloudinary.mediaEditor();
  myEditor.update({
    cloudName: cloudName,
    publicIds: [publicId],
    image: {
      steps: ["resizeAndCrop", "imageOverlay", "textOverlays", "export"],
    },
  });
  myEditor.show();
}

export default startEditing;
Code language: JavaScript (javascript)

In the code above, we passed the steps parameter, containing the steps we want to include in our image widget, to an image object parameter. The steps defined above are the only options and will be displayed in the order specified in the steps parameter. The export step should always be the last.

Next, within the image object, we need to define the configuration for each step we want to include in the Media Editor Widget.

resizeAndCrop Parameter

With the resizeAndCrop parameter, we can populate the Media Editor with an array of presets from which the user can choose to resize and crop the image. Cloudinary provides some predefined presets included by default and some predefined shortcuts that we can include.

Add the following to the image object parameter:

    resizeAndCrop: {
      flip: true,
      rotate: true,
      presets: [
        "original",
        "square",
        "landscape-16:9",
        "landscape-4:3",
        "portrait-3:4",
        "portrait-9:16",
        "facebookAd",
        "facebookCover",
        "instagramStory",
        "twitterAd",
        "linkedInAd",
        "linkedInCover",
        { label: "Cover Ad", width: 500, height: 1000 },
      ],
    },
Code language: CSS (css)

In the code above, we added a few predefined presets (Twitter Ad and LinkedIn Ad, e.t.c )and one custom preset named Cover Ad. We defined the custom preset by specifying the label, width, and height properties. We also specified the flip and rotate parameters, whose values are set to true to display the flip and rotate buttons to enable flipping and rotating the image.

Save the changes and open your browser to test the application.

You should be able to select from the predefined options we specified and also crop the image manually using the crop handles. See the ResizeProps options available for the resizeAndCrop parameter.

imageOverlay Parameter

We can use the imageOverlay parameter to populate the Media Editor with an array of images from which a user can choose to add to the base image. Let’s add one Cloudinary logo as an overlay option.

Add the following to the image object parameter below the resizeAndCrop parameter:

    imageOverlay: {
      overlays: [
        {
          publicId: "logo",
          label: "Logo",
          placementOptions: [
            "right",
            "left",
            "top",
            "bottom",
            "top_left",
            "top_right",
            "bottom_left",
            "bottom_right",
            "middle",
          ],
        },
      ],
    },
Code language: CSS (css)

In the code above, we specified an overlay option in the array with a publicId, a label, and an array of placementOptions. We are using predefined placement options, but you can also define custom placement locations. Each placement option 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).

Now, save the changes and open your browser to test the application.

You should be able to select an image from the different placement options we specified to add to the base image. See the ImageOverlayProps options available for the imageOverlay parameter.

textOverlays Parameter

Specifying the textOverlay parameter will enable us to add text to the base image that can be scaled, edited, moved to any location within the image, e.t.c, and it accepts the following properties:

• The fonts property is used to define an array of allowed fonts and defaults to all the built-in fonts.
• The presets property is used to define an array of text overlay presets available for the user to select, and it defaults to: [“heading”, “body”, “subtitle”, “caption”].
• The guidelinesUrl property can be used to add an informative image with overlay instructions.
• The initialColors property is used to define an array of colors for the user to select. Default: [“#ffffff“, “#000000”]
• The showColorPicker is a boolean property that indicates if the color picker is available for the user to select a color, and it defaults to true.

Add the following to the image object parameter below the imageOverlay parameter:

    textOverlays: {
      presets: [
        "heading",
        "subtitle",
        "body",
        "caption",
        {
          label: "My Header",
          size: 100,
          font: "Helvetica",
          previewText: "ABC",
          weight: "bold",
          style: "italic",
          color: "#ffffff",
        },
      ],
      initialColors: [
        "#3448c5",
        "#ff5050",
        "#f7bc00",
        " #48c4d8",
        "#0052cc",
        "#a600cc",
        "#8ecc00",
      ],
    },
Code language: JavaScript (javascript)

In the code above, we didn’t specify the fonts property because we will be using the default built-in fonts, but you can also define some custom fonts if you wish. We specified some predefined text presets and defined one custom text preset named My Header. We also specified some initial color options.

You can save the changes now and open your browser to test the application.

See the TextOverlaysProps for options available for the textOverlay parameter.

export Parameter

Specifying the widget’s export step allows your users to select and export from the provided exporting options.

Add the following to the image object parameter below the textOverlay parameter:

    export: {
      formats: ["auto", "png", "webp"],
      quality: ["auto", "best", "good", 55, 75, "low"],
      download: true,
      share: true,
    },
Code language: CSS (css)

Using the export parameter, we specified an array of formats and quality with which we would like to populate the Media Editor. We also specified the download property and set its values to true, indicating that we want the download button to be displayed. See the ExportProps options available for the export parameter.

Save the changes again and test the application in your browser.

You should be able to select and download any of the different exporting options provided.

Find the complete project here on GitHub.

Image editing is important in marketing or branding because properly edited images represent your brand. Cloudinary provides a Media Editor, an interactive user interface that offers users on your website with common editing actions. In this post, we built a demo application that shows how to configure and use the Media Editor widget.

Here are some resources you may find helpful:

• Documentation on Cloudinary Media Editor
• Cloudinary Media Editor API Reference
• Next.js Documentation