@rageshpikalmunde/rp-image-editor

@rageshpikalmunde/rp-image-editor

A lightweight, framework-agnostic JavaScript image editor built on Fabric.js. Crop, zoom, rotate, draw, add text, shapes (circle / ellipse / square / arrow), callout annotations, erase, undo/redo — all in a beautiful modal UI with grouped toolbar. Annotations are preserved across both crop and rotate (no drift past 360°), exports run at the image's native resolution by default, and themes auto-contrast so customized backgrounds always get a readable foreground. Works with Angular, React, Vue, Ionic, Capacitor, and plain JavaScript.

Live Demo — Try it in your browser!

Features

Feature	Description
Crop	Free crop and aspect-ratio locked crop — annotations are preserved across crops
Zoom	Zoom in/out with pinch-to-zoom gesture support
Pan/Drag	Drag image inside the viewport
Rotate	Rotate left/right by 45° steps. Annotations are preserved across rotations and stay locked to the underlying pixels (no drift past 360°). Fast path skips PNG re-encoding so large 10–15 MB+ images rotate quickly; a loader overlay is shown during heavy renders.
Freehand Draw	Configurable brush color & width
Add Text	Inline editing with color and font size
Shapes	Circle, Ellipse, Square and Arrow primitives with resize handles. Circle/Square stay proportional, Ellipse resizes freely, Arrow has draggable start/end endpoints
Callout	Editable label with draggable tail, min-resize clamping, text constraints (40 chars, word-wrap), mobile double-tap support
Delete	Delete selected callout/annotation via toolbar trash button
Eraser	Remove annotations without affecting the image
Undo/Redo	Configurable stack depth (default: 20)
Reset	Reset to original image
Native-resolution export	Output preserves the source image's intrinsic resolution; annotations stay sharp
Grouped Toolbar	Compact toolbar with flyout menus (Zoom, Transform, Annotate, Shapes)
Disable Features	Hide individual tools or groups via disabledFeatures config
HEIC Support	Auto-converts iPhone HEIC photos to JPEG
EXIF Orientation	Auto-corrects rotated photos
Smart Resolution	Auto-downscales on iOS to stay within Safari canvas limits
Touch Gestures	Pinch zoom, drag, tap on mobile
Theming	Fully customizable colors for header, footer, buttons, toolbar. Auto-contrast: customized backgrounds without an explicit text/icon color get a readable foreground derived from luminance.
Output	Base64, Blob, and File object

Installation

npm install @rageshpikalmunde/rp-image-editor

Quick Start

Vanilla JavaScript / TypeScript

import { openEditorModal } from '@rageshpikalmunde/rp-image-editor';

const fileInput = document.querySelector<HTMLInputElement>('#fileInput');

fileInput.addEventListener('change', async (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (!file) return;

  const result = await openEditorModal({
    image: file,
    config: {
      exportFormat: 'jpeg',
      exportQuality: 0.92,
      theme: {
        headerTitle: 'Edit Photo',
        applyButtonBackground: '#4a90d9',
      },
    },
  });

  if (result) {
    console.log(result.file);   // File object — upload via FormData
    console.log(result.base64); // data:image/jpeg;base64,...
    console.log(result.blob);   // Blob
  }
});

Angular / Ionic

import { openEditorModal } from '@rageshpikalmunde/rp-image-editor';

// Or use the ImageEditorService wrapper for centralized config:
// import { ImageEditorService } from './services/image-editor.service';

async onFileSelected(file: File) {
  const result = await openEditorModal({
    image: file,
    config: { exportFormat: 'jpeg', exportQuality: 0.92 },
  });

  if (result) {
    // Upload result.file to your backend
  }
}

React

import { openEditorModal } from '@rageshpikalmunde/rp-image-editor';

function ImageUploader() {
  const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    const result = await openEditorModal({
      image: file,
      config: { exportFormat: 'jpeg' },
    });

    if (result) {
      // Use result.file, result.base64, or result.blob
    }
  };

  return <input type="file" accept="image/*" onChange={handleFile} />;
}

Programmatic API (Advanced)

import { RpImageEditor } from '@rageshpikalmunde/rp-image-editor';

const container = document.getElementById('editor-container');
const editor = new RpImageEditor(container, {
  exportFormat: 'png',
  maxUndoSteps: 30,
  defaultBrushColor: '#ff0000',
  showToolbar: true,
});

await editor.loadImage(file);

// Control the editor programmatically
editor.setMode('draw');
editor.zoomIn();
editor.rotate(90);

// Export
const result = await editor.getResult();
console.log(result.file);

// Clean up
editor.destroy();

Configuration

interface RpEditorConfig {
  maxResolution?: number | null;    // Max image resolution (auto-detect per platform)
  cropAspectRatios?: CropAspectRatio[];
  exportFormat?: 'png' | 'jpeg';   // Default: 'jpeg'
  exportQuality?: number;          // 0.0–1.0, Default: 0.92
  exportPixelRatio?: number;       // 1 = standard, 2 = retina. Default: 1
  exportAtNativeResolution?: boolean; // Render export at the source image's native resolution. Default: true
  maxUndoSteps?: number;           // Default: 20
  defaultBrushColor?: string;      // Default: '#ff0000'
  defaultBrushWidth?: number;      // Default: 3
  defaultTextColor?: string;       // Default: '#ff0000'
  defaultTextFontSize?: number;    // Default: 24
  defaultShapeColor?: string;      // Default: matches defaultBrushColor
  defaultShapeStrokeWidth?: number; // Default: 3
  colorPalette?: string[];
  showToolbar?: boolean;           // Default: true
  disabledFeatures?: string[];     // Default: [] — see below
  theme?: RpEditorTheme;
  locale?: string;
}

Disabling Features

Hide individual tools or entire groups from the toolbar:

const result = await openEditorModal({
  image: file,
  config: {
    // Hide individual tools
    disabledFeatures: ['eraser', 'reset'],

    // Or hide entire groups
    // disabledFeatures: ['zoom', 'transform'],
  },
});

Individual tool names: move, crop, zoomIn, zoomOut, rotateLeft, rotateRight, draw, text, callout, eraser, shape-circle, shape-ellipse, shape-square, shape-arrow, undo, redo, reset

Group names (disables all children): zoom (zoomIn + zoomOut), transform (rotateLeft + rotateRight), annotate (draw + text + callout + eraser), shapes (shape-circle + shape-ellipse + shape-square + shape-arrow)

Toolbar Layout

The toolbar is organized into compact items with flyout menus:

Button	Type	Contains
Move	Standalone	Pan / drag mode
Crop	Standalone	Free & aspect-ratio crop
Zoom ▾	Flyout	Zoom In, Zoom Out
Transform ▾	Flyout	Rotate Left, Rotate Right
Annotate ▾	Flyout	Draw, Text, Callout, Eraser
Shapes ▾	Flyout	Circle, Ellipse, Square, Arrow
Undo	Standalone	Undo last action
Redo	Standalone	Redo last undone action
Reset	Standalone	Reset to original image

Theming

All theme tokens are optional. When you customize a background (headerBackground, toolbarBackground, or footerBackground) but do not set its paired foreground (headerTextColor, toolbarIconColor, cancelButtonTextColor), the editor will automatically derive a readable foreground from the background's WCAG relative luminance — dark backgrounds get white text/icons, light backgrounds get dark. Explicit overrides always win.

const result = await openEditorModal({
  image: file,
  config: {
    theme: {
      headerBackground: '#1a1a2e',
      headerTextColor: '#ffffff',
      headerTitle: 'Edit Image',
      editorBackground: '#000000',
      toolbarBackground: '#1a1a2e',
      toolbarIconColor: '#cccccc',
      toolbarActiveIconColor: '#4a90d9',
      footerBackground: '#1a1a2e',
      applyButtonBackground: '#4a90d9',
      applyButtonTextColor: '#ffffff',
      cancelButtonBackground: 'transparent',
      cancelButtonTextColor: '#ffffff',
      modalBorderRadius: '12px',
      buttonBorderRadius: '6px',
    },
  },
});

Browser Support

Browser	Version
Chrome	60+
Firefox	60+
Safari	12+
Edge	79+
iOS Safari	12+
Android Chrome	60+

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT Ragesh Pikalmunde