image-compressor

A simple JavaScript image compressor. Uses the Browser's native canvas.toBlob API to do the compression work. General use this to precompress a client image file before upload it.

• Website

Table of contents

• Main
• Getting started
• Options
• Methods
• Browser support
• Versioning
• License

Main

dist/
├── image-compressor.js        (UMD)
├── image-compressor.min.js    (UMD, compressed)
├── image-compressor.common.js (CommonJS, default)
└── image-compressor.esm.js    (ES Module)

Getting started

Install

npm install image-compressor.js

Usage

Syntax

new ImageCompressor([file[, options]])

file

• Type: File or Blob
• Optional

The target image file for compressing.

options

• Type: Object
• Optional

The options for compressing. Check out the available options.

Example

<input type="file" id="file" accept="image/*">

import axios from 'axios';
import ImageCompressor from 'image-compressor.js';

document.getElementById('file').addEventListener('change', (e) => {
  const file = e.target.files[0];

  if (!file) {
    return;
  }

  new ImageCompressor(file, {
    quality: .6,
    success(result) {
      const formData = new FormData();

      formData.append('file', result, result.name);

      // Send the compressed image file to server with XMLHttpRequest.
      axios.post('/path/to/upload', formData).then(() => {
        console.log('Upload success');
      });
    },
    error(e) {
      console.log(e.message);
    },
  });
});

⬆ back to top

Options

checkOrientation

• Type: boolean
• Default: true

Indicates if read the image's Exif Orientation value (JPEG image only), and then rotate or flip the image automatically with the value.

Notes:

• Don't trust this all the time as some JPEG images have incorrect (not standard) Orientation values.
• If the size of target image is too large (e.g., greater than 10 MB), you should disable this option to avoid out-of-memory crash, see #40 for more information.

maxWidth

• Type: number
• Default: Infinity

The max width of the output image. The value should be greater then 0.

Avoid to get a blank output image, you might need to set the maxWidth and maxHeight options to limited numbers, because of the size limits of a canvas element.

maxHeight

• Type: number
• Default: Infinity

The max height of the output image. The value should be greater then 0.

minWidth

• Type: number
• Default: 0

The min width of the output image. The value should be greater then 0 and should not be greater than the maxWidth.

minHeight

• Type: number
• Default: 0

The min height of the output image. The value should be greater then 0 and should not be greater than the maxHeight.

width

• Type: number
• Default: undefined

The width of the output image. If not specified, the natural width of the original image will be used, or if the height option is set, the width will be computed automatically by the natural aspect ratio.

height

• Type: number
• Default: undefined

The height of the output image. If not specified, the natural height of the original image will be used, or if the width option is set, the height will be computed automatically by the natural aspect ratio.

Note: In order to keep the same aspect ratio to the original image, if the width option is set, will use it compute the height automatically, which means the height option will be ignored.

quality

• Type: number
• Default: 0.8

The quality of the output image. It must be a number between 0 and 1. Be careful to use 1 as it may make the size of the output image become larger. Check out canvas.toBlob for more detail.

Note: This option only available for image/jpeg and image/webp images.

Examples (in Chrome 61):

| Quality | Input size | Output size | Compression ratio | Description | | --- | --- | --- | --- | --- | | 0 | 2.12 MB | 114.61 KB | 94.72% | - | | 0.2 | 2.12 MB | 349.57 KB | 83.90% | - | | 0.4 | 2.12 MB | 517.10 KB | 76.18% | - | | 0.6 | 2.12 MB | 694.99 KB | 67.99% | Recommend | | 0.8 | 2.12 MB | 1.14 MB | 46.41% | Recommend | | 1 | 2.12 MB | 2.12 MB | 0% | Not recommend | | NaN | 2.12 MB | 2.01 MB | 5.02% | - |

mimeType

• Type: string
• Default: 'auto'

The mime type of the output image. By default, the original mime type of the source image file will be used.

convertSize

• Type: number
• Default: 5000000 (5MB)

PNG files over this value will be converted to JPEGs. To disable this, just set the value to Infinity. See #2.

Examples (in Chrome 61):

| convertSize | Input size (type) | Output size (type) | Compression ratio | | --- | --- | --- | --- | | 5 MB | 1.87 MB (PNG) | 1.87 MB (PNG) | 0% | | 5 MB | 5.66 MB (PNG) | 450.24 KB (JPEG) | 92.23% | | 5 MB | 9.74 MB (PNG) | 883.89 KB (JPEG) | 91.14% |

beforeDraw(context, canvas)

• Type: Function
• Default: null
• Parameters:
  • context: The 2d rendering context of the canvas.
  • canvas: The canvas for compression.

The hook function to execute before draw the image into the canvas for compression.

new ImageCompressor(file, {
  beforeDraw(context) {
    context.fillStyle = '#fff';
  },
});

drew(context, canvas)

• Type: Function
• Default: null
• Parameters:
  • context: The 2d rendering context of the canvas.
  • canvas: The canvas for compression.

The hook function to execute after drew the image into the canvas for compression.

new ImageCompressor(file, {
  drew(context) {
    context.filter = grayscale(100%);
  },
});

success(result)

• Type: Function
• Default: null
• Parameters:
  • result: The compressed image (a Blob object).

The hook function to execute when success to compress the image.

error(err)

• Type: Function
• Default: null
• Parameters:
  • err: The compression error (an Error object).

The hook function to execute when fail to compress the image.

⬆ back to top

Methods

compress(file[, options])

• file:
  • Type: File or Blob
  • The target image file for compressing.
• options (optional):
  • Type: Object
  • The options for compressing.
• (return value):
  • Type: Promise

Compress an image file.

const imageCompressor = new ImageCompressor();

imageCompressor.compress(file, options)
  .then((result) => {
    // Handle the compressed image file.
  })
  .catch((err) => {
    // Handle the error
  })

⬆ back to top

Browser support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)
• Edge (latest)
• Internet Explorer 10+ (requires a Promise polyfill as es6-promise)

Versioning

Maintained under the Semantic Versioning guidelines.

License

MIT © Xkeshi

⬆ back to top