mirror of
https://github.com/transloadit/uppy.git
synced 2026-07-20 16:53:33 +00:00
168 lines
4 KiB
Text
168 lines
4 KiB
Text
---
|
||
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);
|
||
});
|
||
```
|