Validators
Validators
Validators check files before they're added to the upload queue. If validation fails, the file is rejected with an error.
ValidatorMaxFiles
Limits the maximum number of files that can be added.
Usage
// Via options (recommended)
const uploader = useUploadKit({
maxFiles: 10,
})
// Via plugin
import { ValidatorMaxFiles } from "nuxt-upload-kit"
const uploader = useUploadKit({
plugins: [ValidatorMaxFiles({ maxFiles: 10 })],
})
Options
| Option | Type | Required | Description |
|---|---|---|---|
maxFiles | number | Yes | Maximum number of files allowed |
Error
When exceeded, throws an error with message: "Maximum number of files ({maxFiles}) reached"
ValidatorMaxFileSize
Limits the maximum size of individual files.
Usage
// Via options (recommended)
const uploader = useUploadKit({
maxFileSize: 50 * 1024 * 1024, // 50MB
})
// Via plugin
import { ValidatorMaxFileSize } from "nuxt-upload-kit"
const uploader = useUploadKit({
plugins: [ValidatorMaxFileSize({ maxFileSize: 50 * 1024 * 1024 })],
})
Options
| Option | Type | Required | Description |
|---|---|---|---|
maxFileSize | number | Yes | Maximum file size in bytes |
Error
When exceeded, throws an error with message: "File size ({fileSize}) exceeds maximum ({maxFileSize})"
Helper: Byte Calculations
const KB = 1024
const MB = 1024 * KB
const GB = 1024 * MB
// Examples
maxFileSize: 500 * KB // 500 KB
maxFileSize: 10 * MB // 10 MB
maxFileSize: 1 * GB // 1 GB
ValidatorAllowedFileTypes
Restricts uploads to specific MIME types.
Usage
// Via options (recommended)
const uploader = useUploadKit({
allowedFileTypes: ["image/jpeg", "image/png", "application/pdf"],
})
// Via plugin
import { ValidatorAllowedFileTypes } from "nuxt-upload-kit"
const uploader = useUploadKit({
plugins: [
ValidatorAllowedFileTypes({
allowedFileTypes: ["image/*", "video/*"],
}),
],
})
Options
| Option | Type | Required | Description |
|---|---|---|---|
allowedFileTypes | string[] | Yes | Array of allowed MIME types |
Wildcards
Use wildcards to allow entire categories:
allowedFileTypes: [
"image/*", // All images (jpeg, png, gif, webp, etc.)
"video/*", // All videos (mp4, webm, mov, etc.)
"audio/*", // All audio (mp3, wav, ogg, etc.)
"application/pdf", // Specific type
]
Common MIME Types
| Type | MIME |
|---|---|
| JPEG | image/jpeg |
| PNG | image/png |
| GIF | image/gif |
| WebP | image/webp |
| SVG | image/svg+xml |
| MP4 | video/mp4 |
| WebM | video/webm |
| MP3 | audio/mpeg |
application/pdf | |
| Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Error
When rejected, throws an error with message: "File type ({mimeType}) is not allowed"
ValidatorDuplicateFile
Prevents adding files that are already in the queue (based on name and size).
Usage
import { ValidatorDuplicateFile } from "nuxt-upload-kit"
const uploader = useUploadKit({
plugins: [ValidatorDuplicateFile()],
})
Options
This validator has no options.
Error
When duplicate detected, throws an error with message: "File already exists"
Combining Validators
Validators run in order. Use multiple validators for comprehensive validation:
const uploader = useUploadKit({
maxFiles: 20,
maxFileSize: 100 * 1024 * 1024,
allowedFileTypes: ["image/*", "video/*"],
plugins: [ValidatorDuplicateFile()],
})
Handling Validation Errors
When validation fails, the file is added with status: 'error':
uploader.on("file:error", ({ file, error }) => {
if (error.message.includes("File type")) {
toast.error("Please upload images or videos only")
} else if (error.message.includes("Maximum number")) {
toast.error("Too many files. Please remove some first.")
} else if (error.message.includes("File size")) {
toast.error("File is too large. Maximum size is 100MB.")
}
})
Or check the file list for errors:
<template>
<div v-for="file in uploader.files" :key="file.id">
<span v-if="file.status === 'error'" class="error">
{{ file.error?.message }}
</span>
</div>
</template>
Creating Custom Validators
See the Custom Plugins guide for creating your own validators.
import { defineProcessingPlugin } from "nuxt-upload-kit"
const ValidatorNoEmoji = defineProcessingPlugin(() => ({
id: "validator-no-emoji",
hooks: {
validate: async (file, context) => {
const emojiRegex = /[\u{1F600}-\u{1F64F}]/u
if (emojiRegex.test(file.name)) {
throw { message: "Filenames cannot contain emoji" }
}
return file
},
},
}))