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 plugin, and can also be useful to display image previews in a custom UI.
Thumbnails are only generated for local files. Remote files through 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
- NPM
- Yarn
- CDN
npm install @uppy/thumbnail-generator
yarn add @uppy/thumbnail-generator
The bundle consists of most Uppy plugins, so this method is not recommended for production, as your users will have to download all plugins when you are likely using only a few.
It can be useful to speed up your development environment, so don't hesitate to use it to get you started.
<!-- 1. Add CSS to `<head>` -->
<link href="https://releases.transloadit.com/uppy/v4.7.0/uppy.min.css" rel="stylesheet">
<!-- 2. Initialize -->
<div id="uppy"></div>
<script type="module">
import { Uppy, ThumbnailGenerator } from "https://releases.transloadit.com/uppy/v4.7.0/uppy.min.mjs"
const uppy = new Uppy()
uppy.use(ThumbnailGenerator)
</script>
Use
If you use the Dashboard then it’s already installed. If you want to use it programmatically for your own UI:
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
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.
Produce a 300px height thumbnail with calculated width to match ratio:
uppy.use(ThumbnailGenerator, { thumbnailHeight: 300 });
Produce a 300px width thumbnail with calculated height to match ratio (and ignore the given height):
uppy.use(ThumbnailGenerator, { thumbnailWidth: 300, thumbnailHeight: 300 });
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
thumbnail:generated
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);
});