@jodit/image-editor

A vanilla, framework-free, reactive image editor: crop, resize, rotate, flip, colour filters, finetune (brightness/contrast/saturation/blur/warmth) and text annotations. Inspired by the Filerobot Image Editor UI, built from scratch with no React, no runtime dependencies.

🌐 Live demo & docs: https://xdsoft.net/jodit/image-editor/

The whole editor is view = f(state): a pure reducer produces immutable state, a pure view turns state into a virtual DOM, and a tiny reconciler patches the real DOM. Image processing is a separate pure pipeline over a DOM-free pixel buffer, so every operation, filter and rule is unit-tested in Node.

Blob ──decode──▶ RasterImage ──pipeline(design)──▶ RasterImage ──encode──▶ Blob
update(patch) ─▶ reducer ─▶ Store ─scheduler(batch)─▶ render(state) ─▶ VNode ─diff─▶ DOM

Features

• ✂️ Crop (interactive handles), Resize (with aspect lock), Rotate, Flip X/Y
• 🎨 Filters: Original, Invert, B&W, Sepia, Solarize, Clarendon, Gingham (+ register your own)
• 🎚️ Finetune: brightness, contrast, saturation, blur, warmth
• 🔤 Annotate / Watermark: text labels
• ↩️ Undo / redo modelled as state, navigated via update (not methods)
• 🧩 Plugin API for tools and filters
• 📱 Mobile-first responsive UI, light & dark themes
• 🧪 140+ unit tests, SOLID, logic/render/event-loop cleanly separated
• 📦 Ships ESM + an ES2021 build + types; CSS is injected from JS (no .css file)

Install

npm install @jodit/image-editor

Or use it straight from a CDN — no build step (CSS is injected from JS):

<div id="editor" style="height: 600px"></div>
<script type="module">
  import { ImageEditor } from 'https://cdn.jsdelivr.net/npm/@jodit/image-editor/+esm';
  const editor = new ImageEditor({ container: '#editor' });
  document
    .querySelector('input[type=file]')
    .addEventListener('change', (e) => editor.fromBlob(e.target.files[0]));
</script>

New here? See docs/getting-started.md for a copy-paste demo, CDN/jsDelivr options and the full API at a glance.

Quick start

import { ImageEditor } from '@jodit/image-editor';

const editor = new ImageEditor({
  container: '#editor', // element or selector
  onSave: (blob) => console.log('exported', blob),
});

// Input is a blob, output is a blob.
const blob = await fetch('/photo.jpg').then((r) => r.blob());
await editor.fromBlob(blob);

// …user edits…
const result = await editor.toBlob({ type: 'image/png' });

Public API

| Member | Description | | ---------------------------------------- | ------------------------------------------------------ | | new ImageEditor(props) / init(props) | Create + mount the editor. | | editor.state | Current immutable EditorState snapshot. | | editor.update(patch) | The one universal mutation. Returns this. | | editor.fromBlob(blob) | Decode an image blob into the editor. | | editor.toBlob(opts?) | Render the current design at full resolution → Blob. | | editor.save() | Export + invoke onSave (fires jie:save). | | editor.saveAs() | Export + invoke onSaveAs (fires jie:saveas). | | editor.reset() | Reset every edit, behind the confirm gate. | | editor.use(plugin) | Apply an extension. | | editor.destroy() | Tear down listeners, observers and the DOM tree. |

Embedding without the built-in toolbar

The top bar (Save / size / zoom / undo-redo) is just state.showToolbar. Hide it and drive everything from your own UI — the host app subscribes to the store and calls the same public API:

const editor = new ImageEditor({
  container: '#editor',
  state: { showToolbar: false }, // no built-in top bar
  onSave: (blob) => overwrite(blob),
  onSaveAs: (blob) => saveUnderNewName(blob),
});

// Your own buttons drive it:
saveButton.onclick = () => editor.save();
saveAsButton.onclick = () => editor.saveAs();
undoButton.onclick = () => editor.update({ history: { step: -1 } });

// Keep your button states in sync with the editor:
import { selectors } from '@jodit/image-editor';
editor.store.subscribe((state) => {
  undoButton.disabled = !selectors.selectCanUndo(state);
  saveButton.disabled = !state.source;
});

showToolbar is also a normal patch: editor.update({ showToolbar: false }).

Undo / redo are state, not methods

History lives inside state as { entries, index }. You navigate it with the same update you use for everything else — so any screen/state is reachable by calling update:

editor.update({ history: { step: -1 } }); // undo
editor.update({ history: { step: +1 } }); // redo
editor.update({ history: { index: 0 } }); // jump to the start
editor.update({ activeTab: 'filters' }); // open any tab
editor.update({ design: { rotate: 90 } }); // an edit (pushes history)
editor.update({ resetDesign: true }); // back to the original

props accepts initial state too: new ImageEditor({ container, state: { theme: 'dark' } }).

Extending

import type { EditorPlugin } from '@jodit/image-editor';

const stickerPlugin: EditorPlugin = {
  name: 'sticker',
  setup(api) {
    api.registerFilter({ id: 'duotone', label: 'Duotone', apply: (raster) => /* … */ raster });
    api.registerTool({ id: 'sticker', label: 'Sticker', icon: '<svg…>', renderPanel: () => null });
  },
};

new ImageEditor({ container: '#editor', plugins: [stickerPlugin] });

See src/plugins/README.md.

Internationalisation

The core bundle ships English only (gettext-style: the English string is the key). Five locales ship as separate, opt-in modules — ru, es, fr, de, zh — and switching language is just an update:

import { ImageEditor } from '@jodit/image-editor';
import ru from '@jodit/image-editor/locales/ru';

const editor = new ImageEditor({ container: '#editor', locales: [ru], locale: 'ru' });
editor.update({ locale: 'en' }); // back to built-in English

Full guide: docs/06-i18n.md.

Architecture & module map

A guided, four-part deep-dive lives in docs/: state & reducer · store & scheduler · virtual DOM · pixel core & pipeline.

Each module also has its own README:

| Area | Module | Responsibility | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | State | core/state | Types, reducer, history, selectors | | Reactivity | core/store · core/scheduler | Reactive store + event-loop batching | | Pixels | core/raster · core/operations · core/filters | DOM-free pixel buffer, transforms, filters | | Geometry | core/geometry | Crop/resize/fit math | | Pipeline | core/pipeline | Pure design → pixels | | Annotations | core/annotations | Annotation list operations | | Render | render/vdom | h(), diff/patch, host abstraction | | UI | ui | Design system, icons, components, view | | Plugins | plugins | Tool registry + extension API | | Image I/O | image | Blob ⇄ raster, annotation compositing | | Facade | editor | Wires it all into ImageEditor |

Scripts

npm start      # Vite dev server for the demo stand
npm test       # Vitest (run once)
npm run build  # ESM + ES2021 + .d.ts into dist/
npm run lint   # ESLint + Prettier check

# Bundle-size monitoring (Statoscope)
npm run analyze # build + open the interactive Statoscope report
npm run report  # build + write a shareable statoscope/report.html
npm run stats   # build + emit statoscope/stats.json only
npm run size    # build + fail if shipped JS exceeds the budget (SIZE_BUDGET_KB, default 90)

Bundle-size monitoring

Bundle size is tracked with Statoscope. Since the build runs on Vite/Rollup, rollup-plugin-webpack-stats emits a webpack-compatible statoscope/stats.json (only in --mode analyze, so normal builds and published artifacts stay clean), which the Statoscope CLI turns into a report:

• npm run analyze — serves the interactive report (modules, treemap, sizes).
• npm run report — writes a static statoscope/report.html for CI artifacts.
• npm run size — a hard budget gate over the stats (scripts/check-size.mjs), handy in CI. Override with SIZE_BUDGET_KB=120 npm run size.

The statoscope/ folder is git-ignored.

Build output

Each entry is an ESM file with CSS injected as a <style> element (no separate .css). Readable builds ship for debuggable consumption and bundler tree-shaking; the .min builds are ready for direct <script type="module"> / CDN use (unpkg/jsdelivr point at the ES2021 min build).

| File | Target | Minified | | --------------------------------------- | -------- | ------------------------- | | dist/jodit-image-editor.js | esnext | no | | dist/jodit-image-editor.min.js | esnext | yes | | dist/jodit-image-editor.es2021.js | ES2021 | no | | dist/jodit-image-editor.es2021.min.js | ES2021 | yes | | dist/index.d.ts | — | bundled type declarations |

Browser support

"Green" / evergreen browsers — the last two versions of Chrome, Firefox, Safari and Edge (see .browserslistrc).

License

MIT © Valeriy Chupurnov and contributors.