---
sidebar_position: 2
slug: /thumbnail-generator
---

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

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

# Thumbnail generator

`@uppy/thumbnail-generator` generates proportional thumbnails (file previews)
for images that are added to Uppy.

## When should I use this?

This plugin is included by default with the [Dashboard](/docs/dashboard) plugin,
and can also be useful to display image previews in a custom UI.

:::note

Thumbnails are only generated for _local_ files. Remote files through
[Companion](/docs/companion) generally won’t have thumbnails because they are
downloaded on the server. Some providers, such as Google Drive, have baked in
thumbnails into their API responses.

:::

## Install

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

```shell
npm install @uppy/thumbnail-generator
```

  </TabItem>

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

```shell
yarn add @uppy/thumbnail-generator
```

  </TabItem>

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

## Use

If you use the [Dashboard](/docs/dashboard) then it’s already installed. If you
want to use it programmatically for your own UI:

```js showLineNumbers
import Uppy from '@uppy/core';
import ThumbnailGenerator from '@uppy/thumbnail-generator';

const uppy = new Uppy();

uppy.use(ThumbnailGenerator);
uppy.on('thumbnail:generated', (file, preview) => doSomething(file, preview));
```

## API

### Options

#### `id`

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

#### `locale`

```js
export default {
	strings: {
		generatingThumbnails: 'Generating thumbnails...',
	},
};
```

#### `thumbnailWidth`

Width of the resulting thumbnail (`number`, default: `200`).

Thumbnails are always proportional and not cropped. If width is provided, height
is calculated automatically to match ratio. If both width and height are given,
only width is taken into account.

#### `thumbnailHeight`

Height of the resulting thumbnail (`number`, default: `200`).

Thumbnails are always proportional and not cropped. If height is provided, width
is calculated automatically to match ratio. If both width and height are given,
only width is taken into account.

:::note

Produce a 300px height thumbnail with calculated width to match ratio:

```js
uppy.use(ThumbnailGenerator, { thumbnailHeight: 300 });
```

Produce a 300px width thumbnail with calculated height to match ratio (and
ignore the given height):

```js
uppy.use(ThumbnailGenerator, { thumbnailWidth: 300, thumbnailHeight: 300 });
```

See issue [#979](https://github.com/transloadit/uppy/issues/979) and
[#1096](https://github.com/transloadit/uppy/pull/1096) for details on this
feature.

:::

#### `thumbnailType`

MIME type of the resulting thumbnail (`string`, default: `'image/jpeg'`).

This is useful if you want to support transparency in your thumbnails by
switching to `image/png`.

#### `waitForThumbnailsBeforeUpload`

Whether to wait for all thumbnails to be ready before starting the upload
(`boolean`, default: `false`).

If set to `true`, Thumbnail Generator will invoke Uppy’s internal processing
stage and wait for `thumbnail:all-generated` event, before proceeding to the
uploading stage. This is useful because Thumbnail Generator also adds EXIF data
to images, and if we wait until it’s done processing, this data will be
available on the server after the upload.

### Events

:::info

You can use [`on`](/docs/uppy#onevent-action) and
[`once`](/docs/uppy#onceevent-action) to listen to these events.

:::

#### `thumbnail:generated`

Emitted with `file` and `preview` local url as arguments:

```js
uppy.on('thumbnail:generated', (file, preview) => {
	const img = document.createElement('img');
	img.src = preview;
	img.width = 100;
	document.body.appendChild(img);
});
```