API Reference
Loader API
The embed script (https://cdn.unlayer.com/image-editor/embed.js) is a lightweight loader. It exposes window.ImageEditor and only downloads the full editor when first used.
| Member | Description |
|---|---|
load(options?) | Optionally preload the editor ahead of time. Accepts an optional version and returns a Promise. |
createEditor(options) | Create and mount an editor. Loads the editor on first use. Returns Promise<ImageEditorInstance>. |
Once the full editor bundle 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 (for example, to enable an "Edit" button).
To preload a specific published editor build, pass its version to load. An unavailable version falls forward to the current release:
await window.ImageEditor.load({ version: '1.500.0' });
Mount Options
createEditor(options) accepts:
| Option | Type | Description |
|---|---|---|
container | string | HTMLElement | CSS selector or element to mount the editor into. Required. |
image | string | Image URL or base64 data URL to edit. Required. |
projectId | number | Your Unlayer project ID. Required for AI features. |
user | object | Optional user identity (id, name, avatar, email, signature) for verification. |
features | object | Feature flags for the AI Assistant, tools, and tool-rail dock. |
theme | 'light' | 'dark' | Editor color theme. Default: 'light'. |
locale | string | Language code (e.g. 'en', 'es', 'fr'). See Localization. |
translations | object | Custom translations by locale, keyed under image_editor.*. |
offline | boolean | Prevent external requests. Use with an offline license and locally bundled assets. Default: false. |
licenseUrl | string | URL of the encrypted license file used in offline mode. |
env | object | Advanced runtime overrides for API and image-editor asset base URLs. |
defaultPrompt | string | Pre-fill the AI chat input with this prompt. |
autoSubmitPrompt | boolean | With an open panel and defaultPrompt, submit the prompt automatically instead of only pre-filling it. Default: false. |
aiAssistantOpenState | 'open' | 'closed' | Whether the available AI Assistant panel is open when the editor is ready. Default: 'open'. |
onSave | (result) => void | Called when the user saves. result has dataUrl (base64 string) and blob (Blob). |
onCancel | () => void | Called when the user cancels. |
onLoadError | () => void | Called when the image fails to load into the canvas because of CORS, a missing resource, or a decode error. |
createEditor rejects if the container element cannot be found, or if an editor is already mounted in that container — call destroy() on the existing instance first.
Instance Methods
createEditor resolves with an editor instance:
| Method | Description |
|---|---|
destroy() | Unmount the editor and clean up. |
getImage() | Return the current canvas as a data URL, or null. |
hasChanges() | Return true if the canvas has unsaved edits relative to the input image. Useful for showing a confirmation prompt before closing. |
updateOptions(opts) | Update options at runtime (e.g. theme, locale, translations). Re-renders with the new options. |
reset(imageUrl?) | Reset the editor state (chat, undo/redo history) and optionally load a new image. |
const editor = await window.ImageEditor.createEditor({
/* ... */
});
editor.updateOptions({ theme: 'dark', locale: 'es' });
editor.reset('https://example.com/another-photo.jpg');
if (!editor.hasChanges()) {
editor.destroy();
}