@jaxtheprime/vue3-dropzone

Vue 3 dropzone component

Customizable easy to use dropzone | Only supported for vue3

Demo

About the Project

the features of this package include the following:

• Drag and drop upload files
• Highly customizable
• Lightweight, powerful and easy to use <g-emoji class="g-emoji" alias="smile"
• Provides with file preview, server-side uploads, multiple state like error success and disable, etc...

Installation

• Install Yarn package

yarn add @jaxtheprime/vue3-dropzone

• Install NPM package

npm install @jaxtheprime/vue3-dropzone

Usage

Local registration:

<template>
    <Vue3Dropzone v-model="files"/>
</template>

<script>
    import Vue3Dropzone from "@jaxtheprime/vue3-dropzone";
    import '@jaxtheprime/vue3-dropzone/dist/style.css'

    const files = ref([])
    };
</script>

Props

Prop	Type	Default	Note
modelValue	Array	[]	2 way binding ref
multiple	Boolean	false	Makes dropzone accept multiple files
previews	Array	[]	Preview images links (works with mode props)
mode	string	drop	Defines dropzone functionality to accept drops or just preview images
disabled	Boolean	false	Disables the whole dropzone
accept	String	undefined	Accepted type of files
maxFileSize	Number	5	Max file size in Megabytes
maxFiles	Number	5	Max files accepted by dropzone
width	Number String	undefined	Dropzone container width
height	Number String	undefined	Dropzone container height
imgWidth	Number String	undefined	Preview images width
imgHeight	Number String	undefined	Preview images height
previewWrapperClasses	String	undefined	Preview images container classes
previewPosition	String	inside, outside	Preview images position
showSelectButton	Boolean	true	Select files button in the dropzone
selectFileStrategy	String	'replace'	Defines selecting file strategy (replace, merge)

Server-Side File Upload

To enable the server-side file upload functionality, you can use the following props:

Prop	Description
server-side	true or false.
upload-endpoint	The URL endpoint where the file will be uploaded.
delete-endpoint	The URL endpoint where the file will be deleted.
headers	An object that contains any additional headers.

<template>
  <Vue3Dropzone
    v-model="files"
    :server-side="true"
    upload-endpoint="http://your-upload-endpoint"
    delete-endpoint="http://your-delete-endpoint"
    :headers="headers"
  />
</template>

<script setup>
import { ref, computed } from "vue";

const files = ref([]);
const headers = computed(() => {
  return {
    Authorization: "Bearer " + localStorage.getItem("token"),
  };
});
</script>

Slots

Name	data
button	fileInput
preview	data,formatSize,removeFile
description	undefined
placeholder-img	undefined
title	undefined

Customizing Slots

You can easily customize the component by overriding the available slots. Below is an example of how to use the different slots (button, placeholder-img, title, description) to personalize the behavior and appearance of the component.

<Vue3Dropzone v-model="files">
  <template #placeholder-img>
    <img src="your-custom-image" />
  </template>
  <template #title>Your Custom Title</template>
  <template #button="{ fileInput }">
    <button @click="fileInput?.click()" class="custom-button">Your Custom Select Button</button>
  </template>
  <template #description>Your Custom Description</template>
</Vue3Dropzone>

Using the Preview Slot

The preview slot allows for more complex customization of how uploaded files are displayed. This slot provides three props: data, formatSize, and removeFile.

Props

Prop	Description
data	- file: The File object.
	- id: The unique identifier for the file.
	- src: The URL or preview of the file.
	- progress: The progress of the file upload (percentage).
	- status: pending, uploading, success, error.
	- message: An error or success message regarding the file upload.
formatSize	format the file size (e.g., KB, MB, GB).
removeFile	remove the uploaded file from the list.

<Vue3Dropzone v-model="files">
  <template #preview="{ data, formatSize, removeFile }">
    <div class="your-custom-preview">
      <h2>{{ data.file.name }}</h2>
      <span>{{ formatSize(data.file.size) }}</span>
      <button @click="removeFile(data)">Remove File</button>
    </div>
  </template>
</Vue3Dropzone>

Events

Prop	Data Type	Note
error	Array	Emits the error event and also provides data to know which files caused the error
fileUploaded	Object	Emits when a file is uploaded, The event provides the file data so you can handle upload to the server as well as locally.
fileRemoved	Object	Emits when a file is removed, The event provides the file data so you can handle deletion from the server as well as locally.

Error Event

<template>
  <Vue3Dropzone v-model="files" @error="handleError" />
</template>

<script setup>
function handleError(error) {
  const { type, files } = error;

  if (type === "file-too-large") {
    console.error(
      `The following files are too large: ${files
        .map((file) => file.name)
        .join(", ")}`
    );
  } else if (type === "invalid-file-format") {
    console.error(
      `The following files are not accepted formats: ${files
        .map((file) => file.name)
        .join(", ")}`
    );
  }
}
</script>

File Uploaded Event

<template>
  <Vue3Dropzone v-model="files" @fileUploaded="handleFileUploaded" />
</template>

<script setup>
function handleFileUploaded(file) {
  // Do something with the uploaded file
  console.log("File uploaded:", file);
}
</script>

File Removed Event

<template>
  <Vue3Dropzone v-model="files" @fileRemoved="handleFileRemoved" />
</template>

<script setup>
function handleFileRemoved(file) {
  // Do something with the removed file
  console.log("File removed:", file);
}
</script>

Css variables

Name	Value
--v3-dropzone--primary	94, 112, 210
--v3-dropzone--border	214, 216, 220
--v3-dropzone--description	190, 191, 195
--v3-dropzone--overlay	40, 44, 53
--v3-dropzone--overlay-opacity	0.3
--v3-dropzone--error	255, 76, 81
--v3-dropzone--success	36, 179, 100

Contact

Emad Moghimi [e-mail]

Project Link: https://github.com/JaxThePrime/vue3-dropzone