Getting started

@image-ultra/react is an image editor component. Give it a photo; get back the edited image and the edits as JSON.

Install

npm install @image-ultra/react

React 18.2 or 19. The package ships its own types; there's nothing else to install.

Add the editor

import { ImageEditor } from '@image-ultra/react';
import '@image-ultra/react/styles.css';

export function PhotoEditor() {
  return (
    <div style={{ height: 600 }}>
      <ImageEditor
        src="/photo.jpg"
        onSave={(result) => {
          // result.blob: the edited image · result.state: the edits (JSON)
          console.log(result.fileName, result.width, result.height);
        }}
      />
    </div>
  );
}

Two things matter:

Import the stylesheet once, anywhere in your app (usually the root layout or entry file).
Give the container a height. The editor fills its container and needs at least 480 × 320 px.

src can be a URL, a File or Blob from an <input type="file">, an <img>, a <canvas> or an ImageBitmap. Leave it out to show a drop zone where people pick a photo themselves.

Next.js (App Router)

The package is marked 'use client', so a Server Component page can render it directly:

// app/layout.tsx
import '@image-ultra/react/styles.css';

// app/edit/page.tsx — a Server Component
import { ImageEditor } from '@image-ultra/react';

export default function Page() {
  return (
    <div style={{ height: '100dvh' }}>
      <ImageEditor src="/photo.jpg" />
    </div>
  );
}

Handlers like onSave are functions, and Server Components can't pass functions to Client Components — put the editor with its handlers in a component of your own marked 'use client'.

Vite

// src/main.tsx
import '@image-ultra/react/styles.css';

Then render <ImageEditor> anywhere. Nothing to configure.

React Router (framework mode)

Import the stylesheet in app/root.tsx and render the editor in a route. It renders on the server too (the editor's frame appears before JavaScript loads).

Working examples

The repository has three small apps — Next.js App Router, Vite with React 18, and React Router — each opening a photo, saving it as a download and reopening the saved edits: apps/examples/.