npx-image-editor

A zero-dependency, 100% local/offline image editor for the browser — full built-in UI and a headless JavaScript API. Nothing ever leaves the user's machine: no servers, no CDNs, no model downloads, no telemetry.

npm install npx-image-editor

import { ImageEditor } from 'npx-image-editor';

const editor = new ImageEditor('#container', { theme: 'dark' });
await editor.loadImage(fileOrUrlOrCanvas);

editor.applyFilter('vintage');
editor.addText('Hello!', { fontSize: 48, bold: true, color: '#fff' });
await editor.download('edited.png');

Or with zero build tools:

<script src="https://unpkg.com/npx-image-editor/dist/npx-image-editor.umd.min.js"></script>
<script>
  const editor = new NpxImageEditor.ImageEditor('#container');
</script>

(The CDN line is only for loading the library itself — the editor runs fully offline once loaded; you can also self-host the file.)

Feature overview

| Area | Features | |---|---| | Image management | load from file / URL / canvas / programmatic, export/download, resize, reset to original, canvas-based | | Crop & transform | free crop, preset ratios (1:1, 4:3, 3:2, 16:9, 9:16), rotate 90°/180°/custom angle, flip H/V, aspect-ratio lock | | Drawing | freehand, straight lines, arrow lines (arrowhead on by default, toggleable), brush size & color | | Shapes | rectangle (w/ corner radius), square, circle, oval/ellipse, triangle, diamond, pentagon, hexagon, N-sided polygon, star — interior always transparent by default (outline only; fill is opt-in), drag to size or single-click to place, stroke color & width, move/resize/rotate | | Icons & stickers | arrows (4 directions + double), star, polygon, location pin, heart, speech bubble, check, cross + custom SVG-path icons | | Text | add/edit inline, font size/family/color, bold, italic, underline, left/center/right alignment, multi-line | | Masks | upload mask image, apply mask filter (luminance → alpha), per-layer masks | | Filters | grayscale, invert, sepia, sepia2, blur, sharpen, emboss, remove-white, brightness, noise, pixelate, color filter (chroma-key), tint, multiply, blend modes, threshold, contrast, saturation, gamma, vignette | | Workflow | undo/redo, keyboard shortcuts, object select/move/resize/rotate/delete/duplicate, z-ordering | | UI | light/dark/custom themes, configurable menu layout, mobile-friendly (touch + pinch zoom), cross-browser, full JS API | | AI (local algorithms) | background removal, object removal, inpainting, upscaling, face/photo enhancement, auto-crop, smart selection (magic wand), colorization, OCR hook | | Layers | layers, groups, lock/unlock, opacity, 16 blend modes, layer masks | | Annotation | labeled arrows, measurement tool, live coordinate display, rulers & guides, grid + snapping, comments with panel | | Medical | uncompressed DICOM parsing, pixel-level zoom, window/level controls, ROI via shapes, mm calibration from PixelSpacing | | Social | 8 filter packs (clarendon, gingham, juno, lark, moon, vintage, dramatic, velvet), stickers, emojis, templates, collage builder | | Pro editing | curves, levels (+auto), histogram, color balance (R/G/B), white balance (auto/temperature), HSL editor (hue/saturation/lightness), gradient editor (linear/radial, applyGradient) | | Collaboration | local real-time sessions (BroadcastChannel, multi-tab), shared session files, comments, version history, audit log | | Export | PNG, JPG, WebP, AVIF*, PDF, SVG, watermark (text/image), batch export, quality/compression controls | | Developer | plugin system, custom tool API, React/Vue wrappers, web component (Angular & others), event hooks, headless mode |

* AVIF encoding depends on browser support (Chrome/Edge/Opera; feature-detected).

About the AI tools: they are implemented with classical computer-vision algorithms (flood-fill matting, onion-peel inpainting, edge-energy analysis, progressive resampling…) so they run instantly, offline, with no model downloads. They work best on images with reasonably uniform backgrounds. OCR is a pluggable hook — point it at any local engine (e.g. tesseract.js, which also runs fully in-browser).

The UI

const editor = new ImageEditor('#container', {
  theme: 'dark',                       // 'light' | 'dark' | { base:'dark', vars:{'--px-accent':'#e11d48'} }
  menus: ['file','edit','image','filters','ai','insert','view','theme'], // flexible layout
  user: 'alice',                       // shows up in comments / audit log / collab
  gridSize: 20,
});

Tools: select/move, pan, freehand, line, shapes, icons, text, crop, smart-select wand, measure, comment, color picker. Panels: properties, adjustments (histogram, sliders, curves presets, auto-levels, auto white balance), layers, comments.

Keyboard shortcuts: Ctrl+Z/Ctrl+Y undo/redo · Del delete · Ctrl+D duplicate · arrows nudge (Shift = ×10) · Enter apply crop · Esc cancel/deselect · V B L S I T C W M H tools · Ctrl +/-/0 zoom.

Headless API (no UI)

import { ImageEditor } from 'npx-image-editor';

const editor = new ImageEditor(null, { headless: true });
await editor.loadImage(blob);

editor.cropToRatio('16:9');
editor.rotate(7.5);
editor.flip('x');
editor.resize(1280, 720);

editor.applyFilter('brightness', { value: 20 });
editor.applyFilter('curves', { points: [[0,0],[64,48],[192,210],[255,255]] });
editor.applyFilter('hsl', { hue: 12, saturation: 8 });

editor.addShape('rect', { x: 40, y: 40, width: 200, height: 120, fill: '#0008', stroke: 'none' });
editor.addIcon('heart', { fill: '#ef4444' });
editor.addLabeledArrow('look here', { x: 300, y: 200 });

const png  = await editor.export('png');
const pdf  = await editor.export('pdf');
const svg  = await editor.export('svg');
const all  = await editor.batchExport(['png','jpg','webp'], { quality: 0.9 });
const wm   = await editor.export('jpg', { watermark: { text: '© me', position: 'bottom-right', opacity: 0.5 } });

AI tools

editor.removeBackground({ tolerance: 38 });
editor.autoCrop();
editor.upscale(2);
editor.enhance();
editor.colorize({ palette: ['#1a1633','#7a3b5e','#d97b4f','#f2d6a2'] });

const sel = editor.smartSelectAt(120, 80, { tolerance: 32 }); // magic wand
editor.inpaintSelection();          // remove what was selected
editor.removeObject({ x: 10, y: 10, width: 80, height: 60 }); // or by rect

// OCR via any local engine (example: tesseract.js)
const worker = await Tesseract.createWorker('eng');
const text = await editor.ocr({ engine: async (canvas) => (await worker.recognize(canvas)).data.text });

Layers & masks

const layer = editor.addLayer('Annotations');
editor.setLayerProps(layer, { opacity: 0.8, blendMode: 'multiply', locked: false });
editor.groupLayers([layer.id], 'My group');
await editor.loadMask(maskImage, layer);   // luminance mask (white = visible)
await editor.applyMaskFilter(maskImage);   // bake into base image alpha
editor.moveLayer(layer, +1);

History, versions, audit

editor.undo(); editor.redo();
editor.saveVersion('before retouch');
editor.restoreVersion('before retouch');
editor.listVersions();
editor.getAuditLog();                       // [{ action, time, user }, …]
const session = await editor.exportSession(); // JSON-safe, portable
await editor.importSession(session);

Measurement, rulers, grid

editor.setRulers(true);
editor.setGrid({ enabled: true, size: 25, snap: true });
editor.addGuide('v', 200);
editor.calibrate(150, 25, 'mm');            // 150 px = 25 mm
editor.measure(0, 0, 300, 0);               // → { pixels: 300, value: 50, unit: 'mm' }

DICOM (medical imaging)

const meta = await editor.loadDICOM(file);  // uncompressed little-endian DICOM
editor.setWindowLevel(40, 400);             // window center / width
// PixelSpacing auto-calibrates measurements to millimetres.

Templates, collage, emoji

editor.applyTemplate('polaroid');           // also: 'quote', 'thumbnail'
editor.addEmoji('🎉', { size: 96 });
const canvas = await ImageEditor.collage([img1, img2, img3, img4], { columns: 2, gap: 10 });

Local real-time collaboration

// Open the same page in two tabs — edits sync instantly via BroadcastChannel.
const session = editor.collaborate({ session: 'design-review' });
editor.on('collab:peers', (peers) => console.log(peers));

Everything stays on the machine; to collaborate across machines, exchange exportSession() files.

Events

editor.on('change', () => {});
editor.on('image:loaded', ({ width, height }) => {});
editor.on('object:added', (obj) => {});
editor.on('selection:change', (sel) => {});
editor.on('history:change', ({ canUndo, canRedo }) => {});
editor.on('filter:applied', ({ name }) => {});
editor.on('*', (event, payload) => {});     // wildcard

Plugins & custom tools

editor.use({
  name: 'my-plugin',
  install(ed) {
    ed.registerTool('stamp', {
      onDown({ x, y, editor }) { editor.addIcon('star', { x: x - 20, y: y - 20 }); },
    });
  },
});

import { registerIcon } from 'npx-image-editor';
registerIcon('logo', 'M 0 0 L 100 0 L 50 100 Z');  // SVG path in a 100×100 box
editor.addIcon('logo');

Framework integrations

React (react ≥ 16.8 as peer):

import NpxImageEditor from 'npx-image-editor/react';
<NpxImageEditor src="/photo.jpg" options={{ theme: 'dark' }} onReady={(ed) => {}} />

Vue 3:

import NpxImageEditor from 'npx-image-editor/vue';
// <NpxImageEditor :src="url" :options="{ theme: 'dark' }" @ready="onReady" />

Angular / Svelte / anything (web component):

import 'npx-image-editor/element';
// <npx-image-editor src="photo.jpg" theme="dark"></npx-image-editor>
// (Angular: add CUSTOM_ELEMENTS_SCHEMA)

📘 Full Angular guide with a complete sample app: docs/angular-usage.md

Node / workers

The core (filters, history, DICOM parsing, SVG generation…) is environment-agnostic. To run pixel operations in Node, supply a canvas factory:

import { env } from 'npx-image-editor';
import { createCanvas } from '@napi-rs/canvas';
env.createCanvas = (w, h) => createCanvas(w, h);

In web workers, OffscreenCanvas is used automatically.

Privacy / offline guarantee

• No network calls are made by the library, ever. Search the source for fetch( — you won't find one.
• No analytics, no telemetry, no remote models or fonts.
• "AI" features are classical local algorithms — see the note above.

Browser support

Modern evergreen browsers (Chrome, Edge, Firefox, Safari, mobile). AVIF export and some blend modes depend on the platform and are feature-detected with clear error messages.

License

MIT