API Reference

This page contains the complete API reference for Vue3 Dropzone, including all props, events, slots, styling options, and component methods.

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), "edit" (combined functionality).
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 triggers file selection.
ignoreOriginalPreviews	Boolean	false	When true and using replace strategy in preview mode, original preview URLs are permanently hidden after new files are selected.
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

Vue3 Dropzone emits the following events:

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.

Event Examples

<template>
  <Vue3Dropzone
    v-model="files"
    v-model:previews="previews"
    @update:modelValue="onFilesChange"
    @update:previews="onPreviewsChange"
    @drop="onDrop"
    @fileUploaded="onFileUploaded"
    @error="onError"
  />
</template>

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

const files = ref([])
const previews = ref([])

const onFilesChange = (newFiles) => {
  console.log('Files changed:', newFiles)
}

const onPreviewsChange = (newPreviews) => {
  console.log('Previews changed:', newPreviews)
}

const onDrop = (event) => {
  console.log('Files dropped:', event)
}

const onFileUploaded = (file) => {
  console.log('File uploaded successfully:', file)
}

const onError = (error) => {
  console.error('Upload error:', error)
}
</script>

Slots

Override default content with custom implementations using these slots:

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

Slot Examples

<template>
  <!-- Custom placeholder image -->
  <Vue3Dropzone v-model="files">
    <template #placeholder-img>
      <img src="/custom-placeholder.png" alt="Custom placeholder" />
    </template>
  </Vue3Dropzone>

  <!-- Custom title and description -->
  <Vue3Dropzone v-model="files">
    <template #title>
      <h3>Upload Your Documents</h3>
    </template>
    <template #description>
      <p>Drag and drop your files or click to browse</p>
    </template>
  </Vue3Dropzone>

  <!-- Custom preview rendering -->
  <Vue3Dropzone v-model="files" mode="edit">
    <template #preview="{ file, index, remove }">
      <div class="custom-preview">
        <img :src="file.url" :alt="file.name" />
        <button @click="remove" class="remove-btn">✕</button>
      </div>
    </template>
  </Vue3Dropzone>
</template>

Styling & CSS Variables

The component uses CSS custom properties for easy theming. Override them in your CSS to customize the appearance:

:root {
  /* Primary colors */
  --v3-dropzone--primary: 94, 112, 210;

  /* State colors */
  --v3-dropzone--success: 36, 179, 100;
  --v3-dropzone--error: 255, 76, 81;

  /* UI colors */
  --v3-dropzone--border: 214, 216, 220;
  --v3-dropzone--description: 190, 191, 195;

  /* Overlay colors */
  --v3-dropzone--overlay: 40, 44, 53;
  --v3-dropzone--overlay-opacity: 0.3;
}

Complete CSS Variables Reference

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

Component Methods

Access these methods via template ref for programmatic control:

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()

Methods Examples

<template>
  <div>
    <Vue3Dropzone ref="dropzone" v-model="files" />
    <div class="mt-4 space-x-2">
      <button @click="clearNewFiles" class="px-4 py-2 bg-blue-500 text-white rounded">
        Clear New Files
      </button>
      <button @click="clearExistingFiles" class="px-4 py-2 bg-green-500 text-white rounded">
        Clear Existing
      </button>
      <button @click="clearAll" class="px-4 py-2 bg-red-500 text-white rounded">
        Clear All
      </button>
    </div>
  </div>
</template>

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

const files = ref([])
const dropzone = ref()

const clearNewFiles = () => {
  dropzone.value.clearFiles()
}

const clearExistingFiles = () => {
  dropzone.value.clearPreviews()
}

const clearAll = () => {
  dropzone.value.clearAll()
}
</script>