uppy/docs/compressor.mdx

---
sidebar_position: 12
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

import UppyCdnExample from '/src/components/UppyCdnExample';

# Compressor

The `@uppy/compressor` plugin optimizes images (JPEG, PNG, and any other format
supported by the client’s browser) before upload, saving up to 60% in size
(roughly 18 MB for 10 images). It uses [Compressor.js][] library under the hood.

## When should I use it?

When your users are likely to upload images, potentially on mobile devices, and
saving data and faster uploads are important.

## Install

<Tabs>
  <TabItem value="npm" label="NPM" default>

```shell
npm install @uppy/compressor
```

  </TabItem>

  <TabItem value="yarn" label="Yarn">

```shell
yarn add @uppy/compressor
```

  </TabItem>

  <TabItem value="cdn" label="CDN">
    <UppyCdnExample>
      {`
        import { Uppy, Compressor } from "{{UPPY_JS_URL}}"
        const uppy = new Uppy()
        uppy.use(Compressor, {
          // Options
        })
      `}
    </UppyCdnExample>
  </TabItem>
</Tabs>

## Use

```js {7} showLineNumbers
import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import Compressor from '@uppy/compressor';

new Uppy()
  .use(Dashboard, {inline:true, target: '#dashboard')
  .use(Compressor);
```

No action is needed from the user — Uppy will automatically optimize images,
show an [Informer](/docs/informer) message with saved bytes, and then begin the
upload as usual.

## API

### Options

:::tip

You can also pass any of the [Compressor.js options][] here as well.

:::

#### `id`

A unique identifier for this plugin (`string`, default: `'Compressor'`).

#### `quality`

The quality of the output image passed to [Compressor.js][] (`number`, default:
`0.6`).

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. In most cases, going with the
default value is best.

:::note

This option is only available for `image/jpeg` and `image/webp` images.

:::

#### `limit`

Number of images that will be compressed in parallel (`number`, default: `10`).

You likely don’t need to change this, unless you are experiencing performance
issues.

#### `locale`

```js
export default {
	strings: {
		// Shown in the Status Bar
		compressingImages: 'Compressing images...',
		compressedX: 'Saved %{size} by compressing images',
	},
};
```

## Events

#### `compressor:complete`

The event is emitted when all files are compressed. You can use it for side
effects or custom UI notifications.

[compressor.js]: https://github.com/fengyuanchen/compressorjs
[compressor.js options]: https://github.com/fengyuanchen/compressorjs#options