Get Started

Configuration

Configure Nuxt Upload Kit to fit your application needs.

Configuration

Nuxt Upload Kit can be configured at the module level in nuxt.config.ts or per-instance when using useUploadKit.

Module Options

Configure the module in your nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["nuxt-upload-kit"],

  uploadKit: {
    // Auto-import the useUploadKit composable (default: true)
    autoImport: true,
  },
})

Options Reference

Option	Type	Default	Description
`autoImport`	`boolean`	`true`	Auto-import the `useUploadKit` composable

Upload Manager Options

The useUploadKit composable accepts a configuration object:

const uploader = useUploadKit({
  // Storage plugin for uploads
  storage: undefined,

  // Additional processing plugins
  plugins: [],

  // Validation options
  maxFiles: false,
  maxFileSize: false,
  allowedFileTypes: false,

  // Processing options
  thumbnails: false,
  imageCompression: false,

  // Behavior options
  autoUpload: false,
})

Options Reference

Option	Type	Default	Description
`storage`	`StoragePlugin`	`undefined`	Storage plugin for file uploads (Azure, S3, etc.)
`plugins`	`ProcessingPlugin[]`	`[]`	Additional processing plugins
`maxFiles`	`number \| false`	`false`	Maximum number of files allowed
`maxFileSize`	`number \| false`	`false`	Maximum file size in bytes
`allowedFileTypes`	`string[] \| false`	`false`	Allowed MIME types
`thumbnails`	`boolean \| ThumbnailOptions`	`false`	Enable thumbnail generation
`imageCompression`	`boolean \| ImageCompressionOptions`	`false`	Enable image compression
`autoUpload`	`boolean`	`false`	Auto-upload after adding files
`initialFiles`	`MaybeRef<string \| string[]>`	`undefined`	Pre-populate with existing file paths

Initial Files

Pre-populate the uploader with existing files from your storage. This is useful for edit forms where users need to see and manage previously uploaded files.

Static Values

const uploader = useUploadKit({
  storage: myStoragePlugin,
  initialFiles: ["uploads/photo1.jpg", "uploads/photo2.png"],
})

Reactive Refs (Deferred Loading)

When working with data fetched asynchronously (e.g., from an API or defineModel), pass a ref:

// With defineModel
const model = defineModel<string[]>()

const uploader = useUploadKit({
  storage: myStoragePlugin,
  initialFiles: model, // Initializes when model receives data
})

// With async data
const existingFiles = ref<string[]>()

const uploader = useUploadKit({
  storage: myStoragePlugin,
  initialFiles: existingFiles,
})

// Later, when data is fetched
existingFiles.value = ["uploads/photo1.jpg"]

Ready State

Use isReady to show loading states while initial files are being fetched:

<template>
  <div v-if="!uploader.isReady">Loading existing files...</div>
  <FileList v-else :files="uploader.files" />
</template>

Events

Listen for initialization results:

uploader.on("initialFiles:loaded", (files) => {
  console.log("Loaded", files.length, "existing files")
})

uploader.on("initialFiles:error", (error) => {
  console.error("Failed to load existing files:", error)
})

Validation Options

Max Files

Limit the number of files that can be added:

const uploader = useUploadKit({
  maxFiles: 10, // Allow up to 10 files
})

Max File Size

Limit the size of individual files:

const uploader = useUploadKit({
  maxFileSize: 50 * 1024 * 1024, // 50MB limit
})

Allowed File Types

Restrict uploads to specific MIME types:

const uploader = useUploadKit({
  allowedFileTypes: ["image/jpeg", "image/png", "image/webp", "video/mp4", "application/pdf"],
})

Thumbnail Options

Enable automatic thumbnail generation for images and videos:

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

// Or customize
const uploader = useUploadKit({
  thumbnails: {
    width: 200, // Max thumbnail width (default: 128)
    height: 200, // Max thumbnail height (default: 128)
    quality: 0.8, // JPEG quality 0-1 (default: 1)
  },
})

Thumbnail Options Reference

Option	Type	Default	Description
`width`	`number`	`128`	Maximum thumbnail width in pixels
`height`	`number`	`128`	Maximum thumbnail height in pixels
`quality`	`number`	`1`	JPEG quality (0-1)
`upload`	`boolean`	`false`	Upload thumbnails to storage after file upload

Image Compression Options

Automatically compress images before upload:

// Enable with defaults
const uploader = useUploadKit({
  imageCompression: true,
})

// Or customize
const uploader = useUploadKit({
  imageCompression: {
    maxWidth: 1920, // Max width (default: 1920)
    maxHeight: 1920, // Max height (default: 1920)
    quality: 0.85, // Quality 0-1 (default: 0.85)
    outputFormat: "auto", // Output format (default: 'auto')
    minSizeToCompress: 100000, // Min size to compress (default: 100KB)
    preserveMetadata: true, // Keep EXIF data (default: true)
  },
})

Compression Options Reference

Option	Type	Default	Description
`maxWidth`	`number`	`1920`	Maximum width in pixels
`maxHeight`	`number`	`1920`	Maximum height in pixels
`quality`	`number`	`0.85`	JPEG/WebP quality (0-1)
`outputFormat`	`'jpeg' \| 'webp' \| 'png' \| 'auto'`	`'auto'`	Output image format
`minSizeToCompress`	`number`	`100000`	Minimum file size to compress (bytes)
`preserveMetadata`	`boolean`	`true`	Preserve EXIF metadata

Complete Example

Here's a full configuration example:

import { PluginAzureDataLake } from "nuxt-upload-kit"

const uploader = useUploadKit({
  // Azure storage
  storage: PluginAzureDataLake({
    sasURL: "https://your-storage.blob.core.windows.net/container?sv=...",
    path: "uploads/images",
  }),

  // Validation
  maxFiles: 20,
  maxFileSize: 100 * 1024 * 1024, // 100MB
  allowedFileTypes: ["image/*", "video/*"],

  // Processing
  thumbnails: {
    width: 256,
    height: 256,
    quality: 0.9,
  },
  imageCompression: {
    maxWidth: 2048,
    maxHeight: 2048,
    quality: 0.8,
    outputFormat: "webp",
  },

  // Auto-upload when files are added
  autoUpload: true,
})

Edit this pageorReport an issue

Overview

Get started with Nuxt Upload Kit in your Nuxt application.

Contributing

Learn how to contribute to Nuxt Upload Kit.