Have ideas to improve npm?Join in the discussion! »

    compressorjs
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.7 • Public • Published

    Compressor.js

    Build Status Coverage Status Downloads Version Dependencies

    JavaScript image compressor. Uses the Browser's native canvas.toBlob API to do the compression work, which means it is lossy compression. General use this to precompress a client image file before upload it.

    Table of contents

    Main

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

    Getting started

    Install

    npm install compressorjs

    Usage

    Syntax

    new Compressor(file[, options])

    file

    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 Compressor from 'compressorjs';
     
    document.getElementById('file').addEventListener('change', (e) => {
      const file = e.target.files[0];
     
      if (!file) {
        return;
      }
     
      new Compressor(file, {
        quality: 0.6,
        success(result) {
          const formData = new FormData();
     
          // The third parameter is required for server
          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(err) {
          console.log(err.message);
        },
      });
    });

    ⬆ back to top

    Options

    You may set compressor options with new Compressor(file, options). If you want to change the global default options, You may use Compressor.setDefaults(options).

    strict

    • Type: boolean
    • Default: true

    Indicates if output the original image instead of the compressed one when the size of the compressed image is greater than the original one's, except the following cases:

    • The mimeType option is set and its value is different from the mime type of the image.
    • The width option is set and its value is greater than the natural width of the image.
    • The height option is set and its value is greater than the natural height of the image.
    • The minWidth option is set and its value is greater than the natural width of the image.
    • The minHeight option is set and its value is greater than the natural height of the image.

    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.

    maxWidth

    • Type: number
    • Default: Infinity

    The max width of the output image. The value should be greater than 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, recommend to use 4096 or lesser.

    maxHeight

    • Type: number
    • Default: Infinity

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

    minWidth

    • Type: number
    • Default: 0

    The min width of the output image. The value should be greater than 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 than 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.

    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:

    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 (5 MB)

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

    Examples:

    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 Compressor(file, {
      beforeDraw(context, canvas) {
        context.fillStyle = '#fff';
        context.fillRect(0, 0, canvas.width, canvas.height);
        context.filter = 'grayscale(100%)';
      },
    });

    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 Compressor(file, {
      drew(context, canvas) {
        context.fillStyle = '#fff';
        context.font = '2rem serif';
        context.fillText('watermark', 20, canvas.height - 20);
      },
    });

    success(result)

    • Type: Function
    • Default: null
    • Parameters:
      • result: The compressed image (a File (read only) or 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

    abort()

    Abort the compression process.

    const compressor = new Compressor(file);
     
    // Do something...
    compressor.abort();

    No conflict

    If you have to use other compressor with the same namespace, just call the Compressor.noConflict static method to revert to it.

    <script src="other-compressor.js"></script>
    <script src="compressor.js"></script>
    <script>
      Compressor.noConflict();
      // Code that uses other `Compressor` can follow here.
    </script> 

    Browser support

    • Chrome (latest)
    • Firefox (latest)
    • Safari (latest)
    • Opera (latest)
    • Edge (latest)
    • Internet Explorer 10+

    Contributing

    Please read through our contributing guidelines.

    Versioning

    Maintained under the Semantic Versioning guidelines.

    License

    MIT © Chen Fengyuan

    ⬆ back to top

    Install

    npm i compressorjs

    DownloadsWeekly Downloads

    31,121

    Version

    1.0.7

    License

    MIT

    Unpacked Size

    125 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar