Thumbnail Generator

The PluginThumbnailGenerator creates preview thumbnails for images and videos, providing instant visual feedback in your UI.

Usage

// Via options (recommended)
const uploader = useUploadKit({
  thumbnails: true, // Enable with defaults
})

// With custom options
const uploader = useUploadKit({
  thumbnails: {
    width: 200,
    height: 200,
    quality: 0.8,
  },
})

// Via plugin directly
import { PluginThumbnailGenerator } from "nuxt-upload-kit"

const uploader = useUploadKit({
  plugins: [
    PluginThumbnailGenerator({
      maxWidth: 256,
      maxHeight: 256,
      quality: 0.9,
    }),
  ],
})

Options

How It Works

Images

1. Loads the image into memory
2. Calculates dimensions preserving aspect ratio
3. Draws to a canvas at thumbnail size
4. Exports as JPEG data URL

Videos

1. Loads video metadata
2. Seeks to videoCaptureTime (or 10% of duration)
3. Captures the frame
4. Exports as JPEG data URL

Accessing Thumbnails

After preprocessing, thumbnails are available on file.preview:

<template>
  <div v-for="file in uploader.files" :key="file.id">
    <img v-if="file.preview" :src="file.preview" :alt="file.name" class="thumbnail" />
    <div v-else class="placeholder">No preview</div>
  </div>
</template>

Skipped Files

The generator skips:

• Non-image and non-video files
• GIF files (to avoid showing only first frame)
• SVG files (vector graphics don't need thumbnails)
• Remote files without local data

Timing

Thumbnails are generated during the preprocess stage, immediately after file selection. This means:

• Thumbnails appear instantly in the UI
• No waiting for upload to complete
• Users see previews while files are queued

Video Thumbnail Timing

Control when to capture the video frame:

const uploader = useUploadKit({
  thumbnails: {
    videoCaptureTime: 5, // Capture at 5 seconds
  },
})

The plugin automatically adjusts if the video is shorter:

• Uses videoCaptureTime or 10% of duration, whichever is smaller

Quality vs Size

Thumbnail data URLs are embedded in the file object. Higher quality means larger strings:

Example: Custom Thumbnail Sizes

// Small thumbnails for grid view
const uploader = useUploadKit({
  thumbnails: {
    width: 100,
    height: 100,
    quality: 0.6,
  },
})

// Large previews for detail view
const uploader = useUploadKit({
  thumbnails: {
    width: 400,
    height: 400,
    quality: 0.9,
  },
})

Example: Fallback for Non-Image Files

<template>
  <div v-for="file in uploader.files" :key="file.id" class="file-preview">
    <!-- Image/video preview -->
    <img v-if="file.preview" :src="file.preview" />

    <!-- PDF icon -->
    <div v-else-if="file.mimeType === 'application/pdf'" class="icon">📄</div>

    <!-- Document icon -->
    <div v-else-if="file.mimeType.includes('document')" class="icon">📝</div>

    <!-- Generic file icon -->
    <div v-else class="icon">📁</div>
  </div>
</template>

After Upload

When a file is uploaded, file.preview is automatically updated to use file.remoteUrl if no thumbnail was generated. This ensures previews always work:

// Before upload: file.preview = 'data:image/jpeg;base64,...' (local thumbnail)
// After upload:  file.preview = 'https://storage.com/file.jpg' (or stays as thumbnail)

Uploading Thumbnails

By default, thumbnails are only generated locally as data URLs for preview purposes. To automatically upload thumbnails to your storage provider alongside the main file, set upload: true:

const uploader = useUploadKit({
  storage: myStoragePlugin,
  thumbnails: {
    width: 200,
    height: 200,
    quality: 0.8,
    upload: true, // Upload thumbnails to storage
  },
})

When enabled:

1. Thumbnails are generated during preprocess (as before)
2. After the main file uploads successfully, the thumbnail data URL is converted to a Blob and uploaded via the storage adapter's standalone upload() method
3. The thumbnail storage key is derived from the file ID with a _thumb suffix (e.g., photo.jpg becomes photo_thumb.jpg)
4. The uploaded thumbnail URL and storage key are available on file.thumbnail

uploader.on("files:uploaded", (files) => {
  files.forEach((file) => {
    console.log("File URL:", file.remoteUrl)
    console.log("Thumbnail URL:", file.thumbnail?.url)
    console.log("Thumbnail key:", file.thumbnail?.storageKey)
  })
})

Thumbnail upload failures are non-fatal — the main file upload completes successfully even if the thumbnail upload fails.

Memory Management

The plugin automatically:

• Revokes object URLs after use
• Cleans up canvas elements
• Uses efficient data URLs for thumbnails

For very large uploads (100+ files), consider using lower quality thumbnails to reduce memory usage.