Thumbnail Generator

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

This plugin is included by default with the Dashboard, so you don’t have to include it manually. But it is useful if you are not using the Dashboard and want to display image previews in your custom UI.

const ThumbnailGenerator = require('@uppy/thumbnail-generator')

uppy.use(ThumbnailGenerator, {
  thumbnailWidth: 200,
  // thumbnailHeight: 200 // optional, use either width or height,
  waitForThumbnailsBeforeUpload: false
})

Now, the file.preview property will contain a URL to the thumbnail and thumbnail:generated event will be emitted, see below for details.

Installation

This plugin is published as the @uppy/thumbnail-generator package.

Install from NPM:

npm install @uppy/thumbnail-generator

In the CDN package, it is available on the Uppy global object:

const ThumbnailGenerator = Uppy.ThumbnailGenerator

Options

The @uppy/thumbnail-generator plugin has the following configurable options:

uppy.use(ThumbnailGenerator, {
  id: 'ThumbnailGenerator',
  thumbnailWidth: 200,
  thumbnailHeight: 200,
  waitForThumbnailsBeforeUpload: false
})

`id: 'ThumbnailGenerator'`

A unique identifier for this plugin. It defaults to 'ThumbnailGenerator'.

`thumbnailWidth: 200`

Width of the resulting thumbnail. Default thumbnail dimension is 200px. 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.

uppy.use(ThumbnailGenerator, { thumbnailWidth: 300 }) will produce a 300px width thumbnail with calculated height to match ratio.

`thumbnailHeight: null`

Height of the resulting thumbnail. Default thumbnail dimension is 200px. 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.

uppy.use(ThumbnailGenerator, { thumbnailHeight: 300 }) will produce a 300px height thumbnail with calculated width to match ratio.

uppy.use(ThumbnailGenerator, { thumbnailWidth: 300, thumbnailHeight: 300 }) will produce a 300px width thumbnail with calculated height to match ratio (and ignore the given height).

See https://github.com/transloadit/uppy/issues/979 and https://github.com/transloadit/uppy/pull/1096 for details on this feature.

`waitForThumbnailsBeforeUpload: false`

Whether to wait for all thumbnails to be ready before starting the upload. If set to true, Thumbnail Generator will envoke 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 avilable on the server after the upload.

Event

thumbnail:generated event is emitted with file and preview local url as arguments:

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

Docs

UI Elements

Sources

Destinations

File Processing

Miscellaneous

React

Contributing