MazDropzone

MazDropzone is a powerful and flexible file upload component with drag & drop support, progress tracking, and customizable UI. Perfect for handling single or multiple file uploads in your Vue applications.

Key Features

• 🎯 Drag & drop support
• 📁 Single or multiple file uploads
• 🖼️ Image preview thumbnails
• 🚀 Auto upload support
• ⚡ Async file processing
• 🎨 Fully customizable UI
• 🌐 Support for various file types
• ⚙️ Extensive configuration options
• 🔒 File validation (size, type, count)
• 🌍 Internationalization support

Error codes

Error Code	Description	Trigger
FILE_SIZE_EXCEEDED	File size exceeds the allowed limit	When a file is larger than maxFileSize (in MB)
FILE_SIZE_TOO_SMALL	File size is below the minimum limit	When a file is smaller than minFileSize (in MB)
MAX_FILES_EXCEEDED	Maximum number of allowed files exceeded	When trying to add more files than maxFiles or more than 1 file if multiple=false
FILE_TYPE_NOT_ALLOWED	File type is not allowed	When the file's MIME type doesn't match the specified dataTypes
FILE_DUPLICATED	An identical file already exists	When allowDuplicates=false and a file with the same name, size and type already exists
NO_FILES_TO_UPLOAD	No files to upload	When starting upload but there are no files in the dropzone
FILE_UPLOAD_ERROR	Error during individual file upload	When uploading a specific file fails (single mode)
FILE_UPLOAD_ERROR_MULTIPLE	Error during batch upload	When uploading multiple files fails (multiple mode)
NO_URL	No upload URL configured	When attempting auto-upload without defining the url prop

Error handling example

View code

<script setup>
function handleError({ code, files }) {
  switch (code) {
    case 'FILE_SIZE_EXCEEDED':
      console.log('File too large:', files[0].name)
      break
    case 'FILE_TYPE_NOT_ALLOWED':
      console.log('File type not allowed:', files[0].type)
      break
    case 'MAX_FILES_EXCEEDED':
      console.log('Too many files selected')
      break
      // ...
  }
}
</script>

<template>
  <MazDropzone
    :max-file-size="5"
    :max-files="3"
    :data-types="['image/*', 'application/pdf']"
    :allow-duplicates="false"
    @error="handleError"
  />
</template>

Basic Usage

Drop your files

or

Maximum 5 files - Maximum 3 MB

<script setup lang="ts">
import { useToast } from 'maz-ui'
import { ref } from 'vue'

const toast = useToast()

const files = ref<File[]>([])
const dropzone = ref<InstanceType<typeof MazDropzone>>()

function onUploadSuccess({ file, response }) {
  console.log('Upload success:', file, response)
  toast.success(`File ${file.name} uploaded successfully`)
}

function onUploadError({ file, code, error }) {
  console.error('Upload failed:', file, code, error)
  toast.error(`File ${file.name} upload failed: ${code} - ${error}`)
}

function onError({ files, event, code }) {
  console.error('Error:', files, event, code)
  toast.error(`${files?.length} files upload failed: ${code} - ${files?.map(file => file.name).join(', ')}`)
}
</script>

<template>
  <MazDropzone
    v-model="files"
    :data-types="['image/*']"
    :max-file-size="3"
    :max-files="5"
    url="https://httpbin.org/post"
    :request-options="{
      headers: { 'My-Awesome-Header': 'header value' },
    }"
    @upload-success="onUploadSuccess"
    @upload-error="onUploadError"
    @error="onError"
  />

  <MazBtn :loading="dropzone?.isUploading" @click="dropzone?.uploadFiles()">
    Upload Files
  </MazBtn>
</template>

File Type Restrictions

You can restrict allowed file types using the data-types prop:

Drop your files

or

Maximum 5 MB - Allowed file types: JPEG, PNG

<MazDropzone v-model="files" :data-types="['image/jpeg', 'image/png']" :max-file-size="5" @error="onError" />

Auto Upload

Enable automatic file upload using the auto-upload prop. Files can be uploaded individually (single) in separate requests or all at once (multiple) in a single request:

Drop your files

or

<MazDropzone
  v-model="files"
  auto-upload="single"
  url="https://your-upload-endpoint.com/upload"
  @upload-success="onUploadSuccess"
  @upload-error="onUploadError"
  @error="onError"
/>

You can also upload all files at once using multiple:

TIP

Multiple upload is allowed:

• when max-files is greater than 1
• when auto-upload is set to multiple
• when multiple prop is set to true

Link to the source code

Drop your files

or

<template>
  <MazDropzone
    v-model="files"
    auto-upload="multiple"
    url="https://your-upload-endpoint.com/upload"
    @upload-success-multiple="onUploadSuccessMultiple"
    @upload-error-multiple="onUploadErrorMultiple"
    @error="onError"
  />
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  import { useToast } from 'maz-ui'

  const files = ref<File[]>([])

  const toast = useToast()

  const onUploadSuccessMultiple = ({ files, response }) => {
    console.log('Upload multiple success:', files, response)
    toast.success(`${files.length} files uploaded successfully`)
  }

  const onUploadErrorMultiple = ({ files, code, error }) => {
    console.error('Upload mulitple failed:', files, code, error)
    toast.error(`${files.length} files upload failed: ${code} - ${error}`)
  }
</script>

Custom Upload Area

Customize the upload area using slots:

Drop your files here or click to browse

<MazDropzone v-model="files" @error="onError">
  <template #no-files-area="{ handleFileInputClick }">
    <div class="maz-flex maz-flex-col maz-items-center maz-gap-4">
      <MazIcon name="arrow-up-on-square" class="maz-text-4xl" />
      <p>Drop your files here or click to browse</p>
      <MazBtn @click="handleFileInputClick"> Select Files </MazBtn>
    </div>
  </template>
</MazDropzone>

Custom Translations

Using translations prop

Customize text messages using the translations prop:

Drag files here

or

<MazDropzone
  v-model="files"
  :translations="{
    dragAndDrop: 'Drag files here',
    selectFile: 'Browse files',
    fileInfos: 'Accepted files: Images up to 5MB'
  }"
  @error="onError"
/>

Using MazUi plugin

You can also use the MazUi plugin to customize the translations:

View code

import { MazUi } from 'maz-ui/plugins/maz-ui'

app.use(MazUi, {
  translations: {
    locale: 'en',
    messages: {
      en: {
        dropzone: {
          dragAndDrop: 'Drag files here',
          selectFile: 'Select files',
          divider: 'or',
          fileMaxCount: 'Maximum {count} files',
          fileMaxSize: 'Maximum {size} MB',
          fileTypes: 'Allowed file types: {types}',
        },
      },
    },
  },
})

Custom Upload Request

Customize the upload request using uploadUrl, requestOptions and transformBody:

Drop your files

or

<MazDropzone
  v-model="files"
  url="/api/upload"
  :request-options="{
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token123'
    },
  }"
  :transform-body="(formData, files) => {
    // Add additional data to FormData
    formData.append('userId', '123')
    formData.append('fileCount', files.length.toString())
    return formData
  }"
  @error="onError"
/>

Props

Name	Description	Type	Required	Default
id	The id of the dropzone	string	No	undefined
multiple	Allow multiple files to be uploaded.	boolean	No	false
data-types	Allowed data types/MIME types for files (e.g. ['application/json'])	string[]	No	['*\/*']
prevent-default-for-unhandled	Prevent default behavior for unhandled drag & drop events.	boolean	No	true
max-file-size	Maximum file size in MB.	number	No	undefined
max-files	Maximum number of files allowed.	number	No	undefined
disabled	Disable the dropzone	boolean	No	undefined
preview	Show file preview	boolean	No	undefined
min-file-size	Minimum file size in MB	number	No	undefined
allow-duplicates	Allow duplicates	boolean	No	false
translations	Translations Custom translations for the component	{ dragAndDrop?: string fileMaxCount?: string fileMaxSize?: string fileTypes?: string selectFile?: string divider?: string }	No	{ dragAndDrop: 'Drag and drop your files', fileMaxCount: 'Maximum {count} files', fileMaxSize: 'Maximum {size} MB', fileTypes: 'Allowed file types: {types}', selectFile: 'Select file', divider: 'or' }
color	Main color of the component	MazColor	No	primary
select-file-btn-props	MazBtn props MazBtn props	MazBtnProps	No	{}
remove-file-btn-props	MazBtn props MazBtn props	MazBtnProps	No	{}
spinner-props	MazSpinner props MazSpinner props	MazSpinnerProps	No	{}
auto-upload	Auto upload files If set to multiple, all files will be uploaded at once in a single request. If set to single, files will be uploaded one by one in separate requests. If set to false, no upload will be done automatically.	"multiple" | "single" | false	No	false
url	Upload URL If set, files will be uploaded to the given URL.	string	No	undefined
request-options	Request options Request options to be used for the upload (using fetch) Request options Example: { mode: 'no-cors', headers: { 'Content-Type': 'multipart/form-data', 'Authorization': 'Bearer 1234567890' } }	RequestInit	No	undefined
transform-body	Transform the body of the request	TSFunctionType	No	undefined

Events

Event name	Properties	Description
drop	values { files: File[] | null, event: DragEvent } - The dropped files and the drag event	Event emitted when files are dropped in the dropzone
enter	values { files: File[] | null, event: DragEvent } - The dragged files and the drag event	Event emitted when dragged files enter the dropzone
leave	values { files: File[] | null, event: DragEvent } - The dragged files and the drag event	Event emitted when dragged files leave the dropzone
over	values { files: File[] | null, event: DragEvent } - The dragged files and the drag event	Event emitted when dragged files are over the dropzone
add	value File - The added file	Event emitted when a file is added to the dropzone
remove	value File - The removed file	Event emitted when a file is removed from the dropzone
error	values { files: File[] | null, event: DragEvent | null, code: MazDropzoneErrorCode } - The files, event and error code	Event emitted when an error occurs
upload-error	values { file: File, code: MazDropzoneErrorCode, error: unknown } - The file, error code and error details	Event emitted when an error occurs during file upload
upload-error-multiple	values { files: File[], code: MazDropzoneErrorCode, error: unknown } - The files, error code and error details	Event emitted when an error occurs during multiple files upload
upload-success	values { file: File, response?: Response } - The uploaded file and the response	Event emitted when a file is successfully uploaded
upload-success-multiple	values { files: File[], response?: Response } - The uploaded files and the response	Event emitted when multiple files are successfully uploaded

Slots

Name	Description	Bindings
files-area	Slot to customize the files area	files-data MazDropzoneFileData[] - The files data
file-item	Slot to customize the file item	file MazDropzoneFileData - The drop file data
no-files-area	Slot to customize the no files area	select-file Function - The function to select the file
upload-icon	Slot to customize the upload icon

Expose

uploadFiles

Upload files
@description With this method, the files are uploaded one by one (a request for each file)
@usage mazDropzoneInstance.value?.uploadFiles()

uploadFilesMultiple

Upload multiple files
@description With this method, the files are uploaded all at once in a single request
@usage mazDropzoneInstance.value?.uploadFilesMultiple()

getFormData

Get form data
@description Get the form data of one file
@usage const formData = mazDropzoneInstance.value?.getFormData(file)

getFormDataMultiple

Get form data multiple
@description Get the form data of all files
@usage const formData = mazDropzoneInstance.value?.getFormDataMultiple()

reset

Reset the files
@description Remove all files from the dropzone
@usage mazDropzoneInstance.value?.reset()

isUploading

Check if the files are uploading
@description Check if the files are uploading
@usage const isUploading = mazDropzoneInstance.value?.isUploading

addFile

Add a file to the dropzone
@description Add a file manually to the dropzone
@usage mazDropzoneInstance.value?.addFile(file)

removeFile

Remove a file from the dropzone
@description Remove a file manually from the dropzone
@usage mazDropzoneInstance.value?.removeFile(file)