React Image Editor

The excellent Unlayer Image Editor as a React.js wrapper component — crop, resize, draw, text, shapes, stickers, frames, filters, and an optional AI Assistant.

Live Demo

Try the live demo: react-image-editor-example.vercel.app

Installation

npm install @unlayer/react-image-editor

Usage

Requires React >= 18.

import React, { useRef } from 'react';
import ImageEditor from '@unlayer/react-image-editor';

const App = () => {
  const editorRef = useRef(null);

  return (
    <ImageEditor
      ref={editorRef}
      image="https://example.com/photo.jpg"
      options={{ theme: 'light' }}
      onSave={({ dataUrl, blob }) => {
        // Persist the edited image
        console.info('Saved', dataUrl.length, 'bytes');
      }}
      onCancel={() => console.info('Editing cancelled')}
    />
  );
};

The component works out of the box in React Server Components environments (e.g. Next.js App Router) — it ships with the 'use client' directive and touches the DOM only inside effects.

Props

Prop	Type	Description
image	string (required)	Image URL or base64 data URL to edit.
options	ImageEditorOptions	Editor configuration: projectId, user, features, theme, locale, translations, env, offline, licenseUrl, defaultPrompt, autoSubmitPrompt, aiAssistantOpenState.
editorId	string	id for the container div. Cosmetic — the editor mounts by element reference.
minHeight	number | string	Minimum height of the editor container. Defaults to 500.
style	CSSProperties	Styles applied to the container div.
onLoad	(editor) => void	Called with the editor instance once it is mounted.
onSave	({ dataUrl, blob }) => void	Called when the user saves the edited image.
onCancel	() => void	Called when the user cancels editing.
onLoadError	() => void	Called when the image fails to load into the canvas (CORS, 404, decode error).
onError	(error: Error) => void	Wrapper-level failures: embed script load, editor creation, or image reset. Falls back to console.error when absent.

Editor instance (ref)

The ref exposes { editor } — null until the editor mounts, then an instance with:

Method	Description
getImage()	Current canvas as a data URL (flattened), or null.
hasChanges()	Whether there are unsaved edits.
reset(imageUrl?)	Reset editor state (clears undo/redo and chat), optionally load a new image.
updateOptions(partial)	Update options like theme / locale at runtime.
destroy()	Unmount the editor (the component does this automatically on unmount).

const dataUrl = editorRef.current?.editor?.getImage();

How prop changes are applied

Change	Behavior
image	Applied via reset(newImage) — clears undo/redo history and AI chat. Rapid changes are serialized and collapse to the latest value.
options.theme, options.locale, options.translations	Applied via updateOptions() — no remount, editor state preserved.
Any other options key	Full remount — the editor is destroyed and recreated with the new configuration.
onSave / onCancel / onLoadError / onLoad / onError	Always call the latest handler; changing them never remounts.

Error handling

Two distinct channels:

• onLoadError — the editor loaded fine, but the image couldn't be loaded into the canvas (CORS, dead URL, decode error).
• onError — the wrapper couldn't reach a working editor: the embed script failed to load, editor creation was rejected, or re-applying a changed image failed. After a CDN failure the wrapper automatically resets its loader state, so a later remount retries from scratch.

Tools

The editor ships eight tools, rendered as a tab rail beside the canvas:

Tool	What it does
crop	Crop with rotate (90° steps), flip, and a straighten slider.
resize	Change the output dimensions.
filter	One-tap presets plus adjustment sliders (brightness, contrast, saturation, hue, blur, noise…).
draw	Freehand brush with color, type, and size controls.
text	Text layers with style presets, fonts, color/background/outline/shadow.
shapes	Filled/outline/gradient shape palettes with drag, resize, rotate, and styling.
stickers	A bundled sticker library grouped by category, with color/outline/shadow for vector sets.
frame	Frame presets with a size slider and color picker.

All tools are enabled by default. Configure them through options.features.imageEditor.tools — each entry is either a boolean shorthand or { enabled?: boolean; icon?: string }:

// Hide the tools you don't want
<ImageEditor
  image={url}
  options={{
    features: {
      imageEditor: {
        tools: {
          draw: false,
          stickers: false,
          frame: { enabled: false }, // object form, same effect
        },
      },
    },
  }}
/>

// Allow-list style: a minimal crop-and-filter editor
<ImageEditor
  image={url}
  options={{
    features: {
      imageEditor: {
        tools: {
          resize: false,
          draw: false,
          text: false,
          shapes: false,
          stickers: false,
          frame: false,
          // crop and filter stay enabled by default
        },
      },
    },
  }}
/>

// Custom tool icon: a URL, raw <svg>…</svg> markup, or a Font Awesome name
<ImageEditor
  image={url}
  options={{
    features: {
      imageEditor: {
        tools: {
          crop: { icon: 'fa-crop-simple' },
          text: { icon: 'https://example.com/icons/text.svg' },
        },
      },
    },
  }}
/>

Two things to keep in mind:

• features is a remount-tier option (see the table above): changing the tools config destroys and recreates the editor, discarding unsaved edits — decide the toolset before mounting rather than toggling it live.
• features.imageEditor: false disables the editing UI entirely; newer editor versions also support features.imageEditor.dock: 'left' | 'right' for the rail position and a corners entry (the rounded-corners control inside Crop) — these type-check once your @unlayer/types version includes them.

AI Assistant

The editor includes an optional AI Assistant for chat-based edits. It requires a projectId from your Unlayer account with the feature enabled.

Enable AI Assistant

<ImageEditor
  image={url}
  options={{
    projectId: 1234, // get from console
    features: { ai: { enabled: true, assistant: true } },
  }}
/>

Localization

Set options.locale (bundled: en, es, fr, de, it, pt, nl, ja, ko, zh) and optionally override strings with options.translations.

Demo

Try the live demo at react-image-editor-example.vercel.app, or run it locally — a Vite-based demo lives in demo/:

cd demo
npm install
npm run dev

License

Copyright (c) 2026 Unlayer. MIT Licensed.