@elizabeth011685/vue3-dropzone

Vue3 Dropzone

A flexible Vue 3 dropzone component with unified preview and edit capabilities. Perfect for file uploads, image galleries, and product management interfaces. Demo

Getting Started

Installation

npm install @jaxtheprime/vue3-dropzone
# or
yarn add @jaxtheprime/vue3-dropzone

Basic Usage

// In your main.js
import { createApp } from 'vue'
import vue3Dropzone from '@jaxtheprime/vue3-dropzone'
import "@jaxtheprime/vue3-dropzone/dist/style.css" // Don't forget to import the styles!

const app = createApp(App)
app.component('Vue3Dropzone', Vue3Dropzone)

// OR in your component file (local registration)
import vue3Dropzone from '@jaxtheprime/vue3-dropzone'
import "@jaxtheprime/vue3-dropzone/dist/style.css"

Minimal Example

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

<script setup>
import { ref } from 'vue'

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

Complete Example

<template>
  <Vue3Dropzone 
    v-model="files" 
    multiple
    width="100%" 
    height="400px" 
    imgWidth="45%" 
    imgHeight="300px"
    :maxFileSize="10"
    :maxFiles="2"
    :state="state"
  />
</template>

<script setup>
import { ref } from 'vue'

const files = ref([])
const state = ref('indeterminate') // Can be 'indeterminate', 'success', or 'error'
</script>

Version Support

• Vue.js 3.x
• Modern browsers with ES6 support

Key Features

Unified Data Handling

• Multiple Data Sources: Combines File objects (new uploads) with URL strings (existing files)
• Smart Type Detection: Automatically handles different file types and sources
• Two-Way Binding: Reactive updates for both new files and existing previews

Three Flexible Modes

• Drop Mode: Standard dropzone for new file selection
• Preview Mode: Display existing files with optional interaction (can be enhanced with allowSelectOnPreview)
• Edit Mode: Combined functionality - show existing files AND allow full modification capabilities (add, remove, replace)

File Management

• Drag & Drop Support: Native HTML5 drag and drop with visual feedback
• File Validation: Size limits, type restrictions, and custom validation
• Progress Tracking: Built-in upload progress with server-side support
• Error Handling: Comprehensive error states and user feedback

Layout Options

• Preview Positioning: Display previews inside or outside the dropzone
• Responsive Design: Adapts to different screen sizes and containers
• Customizable Styling: CSS variables for easy theming
• Slot Support: Override any part of the interface

Props Reference

Core Configuration

Prop	Type	Default	Description
modelValue	Array	[]	Array of File objects representing newly selected files. Two-way binding with v-model.
previews	Array	[]	Array of URL strings for existing files/images. Two-way binding with v-model:previews.
mode	String	"drop"	Component behavior mode: "drop" (new files only), "preview" (display only, can be enhanced with allowSelectOnPreview), "edit" (combined functionality with full file management capabilities). Edit mode automatically enables file selection and removal, and has special behaviors like clearing previews when using replace strategy.
multiple	Boolean	false	Allow selection of multiple files simultaneously.
disabled	Boolean	false	Completely disable all interactions with the dropzone.

File Selection & Strategy

Prop	Type	Default	Description
selectFileStrategy	String	"replace"	How new files interact with existing ones: "replace" (clear existing), "merge" (add to existing).
allowSelectOnPreview	Boolean	false	Allow file selection and removal in preview mode. When true, clicking on empty areas in the preview container triggers file selection, while clicks on images and preview items are prevented to avoid accidental selection. This adds limited interactivity to preview mode without enabling all edit mode features. When false, preview mode is read-only. Note: For full editing capabilities, use mode="edit" instead.
ignoreOriginalPreviews	Boolean	false	When true and using replace strategy in preview mode, original preview URLs are permanently hidden after new files are selected, even if all new files are removed. When false, original previews reappear when new files are removed.
maxFiles	Number	5	Maximum number of files that can be selected at once.
maxFileSize	Number	5	Maximum file size allowed in megabytes (MB).
accept	String	undefined	Comma-separated list of allowed file types (MIME types). Example: "image/*,application/pdf".

Visual Layout & Positioning

Prop	Type	Default	Description
width	Number/String	auto	Width of the dropzone container. Can be px, %, or any CSS unit.
height	Number/String	200px	Height of the dropzone container. Can be px, %, or any CSS unit.
previewPosition	String	"inside"	Where to display file previews: "inside" (within dropzone), "outside" (below dropzone).
imgWidth	Number/String	auto	Width of individual preview images.
imgHeight	Number/String	auto	Height of individual preview images.
previewWrapperClasses	String	""	Additional CSS classes to apply to the preview container.

User Interface Elements

Prop	Type	Default	Description
showSelectButton	Boolean	true	Display the "Select File" button within the dropzone interface.
fileInputId	String	auto-generated	Custom ID for the hidden file input element. Auto-generated if not provided.
state	String	"indeterminate"	Visual state of the dropzone: "indeterminate", "success", "error". Affects border colors.

Server Integration

Prop	Type	Default	Description
serverSide	Boolean	false	Enable server-side file upload functionality with progress tracking.
uploadEndpoint	String	undefined	URL endpoint for file uploads when serverSide is enabled.
deleteEndpoint	String	undefined	URL endpoint for file deletion when serverSide is enabled.
headers	Object	{}	Additional HTTP headers to send with server requests.

Events Reference

Event	Payload	Description
update:modelValue	Array	Emitted when the files array changes. Contains File objects.
update:previews	Array	Emitted when the previews array changes. Contains URL strings.
drop	Event	Emitted when files are dropped onto the dropzone.
fileUploaded	Object	Emitted when a file successfully uploads (server-side mode).
fileRemoved	Object	Emitted when a File object is removed from the list.
previewRemoved	Object	Emitted when a preview URL is removed from the list.
error	Object	Emitted on validation errors or upload failures. Contains error type and files.

Styling & Customization

CSS Variables

The component uses CSS custom properties for easy theming:

Variable	Default	Purpose
--v3-dropzone--primary	94, 112, 210	Primary color (RGB values)
--v3-dropzone--border	214, 216, 220	Border color (RGB values)
--v3-dropzone--description	190, 191, 195	Description text color (RGB values)
--v3-dropzone--error	255, 76, 81	Error state color (RGB values)
--v3-dropzone--success	36, 179, 100	Success state color (RGB values)
--v3-dropzone--overlay	40, 44, 53	Overlay background color (RGB values)
--v3-dropzone--overlay-opacity	0.3	Overlay opacity value

Slot Support

Override default content with custom implementations:

Slot	Purpose
placeholder-img	Replace the default placeholder image
title	Replace the default "Drop your files here" title
button	Replace the default "Select File" button
description	Replace the default file requirements description
preview	Custom preview item rendering

Component Methods

Access these methods via template ref:

Method	Parameters	Description
clearFiles()	None	Remove all File objects (new uploads)
clearPreviews()	None	Remove all preview URLs (existing files)
clearAll()	None	Remove both files and previews completely
clearPreview()	None	Legacy method - equivalent to clearAll()

Use Cases

Product Management

Perfect for e-commerce platforms where users need to manage product images - showing existing images while allowing additions, removals, and replacements.

Profile/Avatar Updates

Ideal for user profile interfaces where you display current profile pictures and allow users to upload new ones.

Document Management

Great for document upload interfaces where users can see existing documents and add new ones.

Gallery Applications

Excellent for photo gallery management where users can view existing images and upload additional ones.

Content Management Systems

Perfect for CMS interfaces where content creators need to manage media files alongside text content.

General Media Management Admin Panels

Ideal for administrative interfaces across various platforms where administrators need to manage user-uploaded content, system assets, or shared media libraries. Works well for social platforms, educational systems, corporate portals, and any application requiring centralized media administration.

Features

File Handling

• Automatically detects file types and displays appropriate previews
• Handles both image files (with thumbnails) and other file types (with icons)
• Maintains file metadata and upload status

Interaction Models

• Read-only preview mode for display purposes
• Interactive preview mode for file management
• Combined edit mode for comprehensive file management
• Smart click handling:
  • Click on empty preview container areas to select new files
  • Click prevention on images and preview items to avoid accidental file selection
  • Dedicated remove buttons for each preview item

Responsive Design

• Adapts to container sizes automatically
• Supports both fixed and flexible dimensions
• Mobile-friendly touch interactions

Error Prevention

• File size validation before upload
• File type validation against accepted formats
• Clear error messaging for user guidance

This component provides a complete solution for file management interfaces with the flexibility to adapt to various use cases and design requirements.