js-scissor

Lightweight browser image resizer. Resize from any source — <img>, <canvas>, or URL — and get results as Base64, Blob, or image elements. Zero server required.

Features

• Flexible input — accepts HTMLImageElement, HTMLCanvasElement, or image URL strings
• Multiple fit modes — fill, cover, and contain just like CSS object-fit
• Multiple output formats — Base64, HTMLImageElement, or Blob
• Image format support — PNG, JPEG, WebP
• Aspect ratio handling — specify width only, height only, or both

Install

npm i js-scissor

Quick Start

import Scissor from 'js-scissor';

// Resize an <img> element to 100px wide (height auto-calculated)
const output = await new Scissor(document.querySelector('img')).resize(100);
document.querySelector('#result').src = output.toBase64();

Usage

Resize width

Specify width only — height is auto-calculated to preserve aspect ratio.

import Scissor from 'js-scissor';

// HTML: <img id="src1" src="img/sample1.jpg">
//       <img id="dest1">
let src = document.querySelector('#src1');
let dest = document.querySelector('#dest1');
dest.src = (await new Scissor(src).resize(100)).toBase64();

Resize height

Specify height only — width is auto-calculated to preserve aspect ratio.

import Scissor from 'js-scissor';

// HTML: <img id="src2" src="img/sample2.png">
//       <img id="dest2">
let src = document.querySelector('#src2');
let dest = document.querySelector('#dest2');
dest.src = (await new Scissor(src).resize(null, 100)).toBase64();

Resize with cover

Crop from center while maintaining aspect ratio. The image fills the entire target area with no gaps.

import Scissor from 'js-scissor';

// HTML: <img id="src3" src="img/sample1.jpg">
//       <img id="dest3">
let src = document.querySelector('#src3');
let dest = document.querySelector('#dest3');
dest.src = (await new Scissor(src).resize(100, 225, {fit: 'cover'})).toBase64();

Resize with contain

Fit inside the target area while maintaining aspect ratio. Blank areas are filled with the background color (default: black).

import Scissor from 'js-scissor';

// HTML: <img id="src4" src="img/sample1.jpg">
//       <img id="dest4">
let src = document.querySelector('#src4');
let dest = document.querySelector('#dest4');
dest.src = (await new Scissor(src).resize(100, 225, {fit: 'contain'})).toBase64();

Resize with fill

Stretch to the exact target dimensions. Aspect ratio is not preserved.

import Scissor from 'js-scissor';

// HTML: <img id="src5" src="img/sample1.jpg">
//       <img id="dest5">
let src = document.querySelector('#src5');
let dest = document.querySelector('#dest5');
dest.src = (await new Scissor(src).resize(100, 225)).toBase64();

Resize from URL

Pass an image URL string directly instead of a DOM element.

import Scissor from 'js-scissor';

// HTML: <img src="img/sample2.png">
//       <img id="dest6">
let dest = document.querySelector('#dest6');
dest.src = (await new Scissor('img/sample2.png').resize(100, 225, {fit: 'cover'})).toBase64();

API

new Scissor(target)

Create an instance from an image source.

| Parameter | Type | Description | |-----------|------|-------------| | target | HTMLImageElement \| HTMLCanvasElement \| string | Image element, canvas element, or image URL |

import Scissor from 'js-scissor';

let siz;

// From an image element
// HTML: <img id="img" src="img/sample1.jpg">
siz = new Scissor(document.querySelector('#img'));

// From a canvas element
// HTML: <canvas id="cvs"></canvas>
siz = new Scissor(document.querySelector('#cvs'));

// From a URL
siz = new Scissor('img/sample1.jpg');
siz = new Scissor('https://example.com/img/sample1.jpg');

.resize(width, height?, options?)

Returns Promise<Output> — the resized image wrapped in an Output object.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | width | number \| null | — | Resize width. Pass null to auto-calculate from height | | height | number \| null | — | Resize height. Omit or null to auto-calculate from width | | options.fit | 'fill' \| 'cover' \| 'contain' | 'fill' | How the image fits the target dimensions | | options.background | string | '#000' | Background fill color | | options.format | 'image/png' \| 'image/jpeg' \| 'image/webp' | 'image/png' | Output image format |

import Scissor from 'js-scissor';

const siz = new Scissor('https://example.com/img/sample2.png');
let res, base64;

// Resize width
res = await siz.resize(100);
base64 = res.toBase64();

// Resize height
res = await siz.resize(null, 100);
base64 = res.toBase64();

// Cover — crop from center, maintaining aspect ratio
res = await siz.resize(100, 225, {fit: 'cover'});
base64 = res.toBase64();

// Contain — fit inside, maintaining aspect ratio
res = await siz.resize(100, 225, {fit: 'contain'});
base64 = res.toBase64();

// Fill — stretch to exact dimensions
res = await siz.resize(100, 225);
base64 = res.toBase64();

Output methods

| Method | Returns | Description | |--------|---------|-------------| | .toBase64() | string | Data URL string (e.g. data:image/png;base64,...) | | .toImage() | HTMLImageElement | A new <img> element with the resized image | | .toBlob() | Blob | Binary blob of the resized image |

import Scissor from 'js-scissor';

const siz = new Scissor('https://example.com/img/sample2.png');
const res = await siz.resize(100);

const base64 = res.toBase64();  // "data:image/png;base64,iVB..."
const img    = res.toImage();   // <img> element ready to append
const blob   = res.toBlob();    // Blob for upload or download

Changelog

See CHANGELOG.md.

Author

shumatsumonobu  GitHub · X · Facebook

License

MIT