Skip to main content
Unlayer Docs
Version: Latest

Image Editor Quickstart

This guide walks you through embedding Unlayer's standalone Image Editor into your web application — from adding the script to handling the saved image.

Using React?

Use the official @unlayer/react-image-editor component to manage script loading and the editor lifecycle.

Step 1: Add the Embed Script​

Add the script tag to your HTML:

<script src="https://cdn.unlayer.com/image-editor/embed.js"></script>

This is a lightweight loader — it does not download the full editor until you create one. If you want to preload the editor ahead of time (for example, to make an "Edit" button feel instant), you can call:

await window.ImageEditor.load();

Once the full editor has loaded — after the first load() or createEditor() call — the loader dispatches an image-editor-ready event on window. Listen for it if you preload and want to know when the editor is ready to use (for example, to enable an "Edit" button).

Step 2: Add a Container​

Add an element for the editor to mount into:

<div id="editor-container" style="height: 700px;"></div>
Recommended Size

For the best experience, ensure the editor container is at least 1024px wide and 700px high. The editor will expand to fill the entire container.

Step 3: Create the Editor​

Call createEditor with the container, the image to edit, and your project ID. It always returns a Promise that resolves with the editor instance once mounted.

<script>
  (async () => {
    const editor = await window.ImageEditor.createEditor({
      container: '#editor-container',
      image: 'https://example.com/photo.jpg', // Image URL or base64 data URL
      projectId: 1234, // Replace with your project ID
      theme: 'light',
      locale: 'en',
      onSave: (result) => {
        // result.dataUrl — base64 data URL of the edited image
        // result.blob   — Blob, ready to upload
      },
      onCancel: () => {
        // User dismissed the editor without saving
      },
      onLoadError: () => {
        // The image could not be loaded because of CORS, a 404, or a decode error
      },
    });
  })();
</script>

Where to get the Project ID?​

  1. Log in to the Developer Console
  2. Create a Project
  3. You can find the project ID in Project > Builder > Settings

Step 4: Handle the Saved Image​

The onSave callback receives the edited image in two forms: a dataUrl for previews or inline use, and a blob for uploading to your server or storage.

onSave: async (result) => {
  const formData = new FormData();
  formData.append('file', result.blob, 'edited.png');
  await fetch('/api/upload', { method: 'POST', body: formData });
},

When you're done with the editor, clean it up with destroy(). If you show the editor in a modal, use hasChanges() to ask the user for confirmation before closing with unsaved edits:

if (editor.hasChanges()) {
  const close = confirm('Discard unsaved changes?');
  if (!close) return;
}
editor.destroy();

What's Next​