ImageProcessor.js

CSS Filters Aren't Enough

CSS filters change how an image looks — they never touch the underlying pixel data. That means you can't export the result, enforce a watermark, or generate a resized thumbnail. Whenever you need the processed image to actually exist, you reach for the Canvas API — and that's where the boilerplate piles up fast:

const img = new Image();
img.crossOrigin = 'anonymous';
img.onload = () => {
  const canvas = document.createElement('canvas');
  const ctx = canvas.getContext('2d');
  canvas.width = 800; canvas.height = 600;
  ctx.filter = 'grayscale(100%) brightness(1.2)';
  ctx.drawImage(img, 0, 0, 800, 600);
  // ... watermark logic ...
  // ... inject into DOM ...
};
img.src = url;

Multiply that by every image on the page, add watermarks, rotation, batch processing, and error callbacks — and you've reinvented ImageProcessor.js. Instead:

new ImageProcessor('https://example.com/photo.jpg', {
  width: 800,
  grayscale: 'grayscale(100%)',
  brightness: 'brightness(1.2)',
  watermark: '© 2026 Peter Benoit',
  targetElement: document.getElementById('output'),
});

CSS Filters vs. ImageProcessor

The key distinction: CSS is visual-only. ImageProcessor operates on actual pixel data.

How It Works

No magic — just a thin wrapper around APIs your browser already ships with.

1. 1. A hidden <img> loads the source URL with the configured crossOrigin, loading, decoding, and referrerpolicy attributes.
2. 2. On load, the image is drawn onto an off-screen <canvas> with the composed CSS filter string applied via the Canvas 2D filter property.
3. 3. Crop, resize, and rotation transforms are applied during drawImage() using the canvas coordinate system.
4. 4. If a watermark is specified, it is drawn on top — either as composited text or as a second image via drawImage().
5. 5. The canvas is exported via canvas.toDataURL(format, quality) and injected into the target DOM element as an <img> tag.
6. 6. Lifecycle callbacks (onProcessingStart, onProcessed, onError) fire at each step.

The original source image is never mutated. The output is a new, independent image that can be saved, uploaded, or displayed separately.

Options Reference

All options passed as the second argument to new ImageProcessor(url, options).

Dimensions & Transforms

Filters (CSS filter function syntax)

Watermark

Output, Loading & Callbacks

Usage

A single script tag — no bundler, no build step.

Include

<script src="path/to/ImageProcessor.js"></script>

Single image

new ImageProcessor('photo.jpg', {
  width: 400, height: 300,
  brightness: 'brightness(1.4)',
  contrast: 'contrast(1.2)',
  watermark: '© 2026',
  altText: 'Enhanced landscape photo',
  targetElement: document.getElementById('output'),
  onProcessed: ({ imageUrl }) => console.log('Done:', imageUrl),
});

Batch processing

new ImageProcessor([
  { url: 'img1.jpg', options: { grayscale: 'grayscale(100%)', targetElement: el1 } },
  { url: 'img2.jpg', options: { sepia: 'sepia(80%)',         targetElement: el2 } },
  { url: 'img3.jpg', options: { blur: 'blur(3px)',           targetElement: el3 } },
]);

Sensitive image blurring

<!-- Blurred by default, click to reveal -->
<div class="sensitive-image" data-img="photo.jpg" data-alt="..."></div>
<script>new ImageProcessor();</script>

The blur is applied at the canvas level — not a CSS class — so it can't be bypassed through DevTools.