or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

constructor-config.mdevent-system.mdfile-management.mdindex.mdstatic-utilities.mdthumbnails.mdupload-processing.md
tile.json

tessl/npm-dropzone

Lightweight JavaScript library that transforms HTML elements into drag-and-drop file upload zones with thumbnail previews, progress tracking, and extensive customization options.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/dropzone@4.3.x

To install, run

npx @tessl/cli install tessl/npm-dropzone@4.3.0

index.mddocs/

Dropzone.js

Dropzone.js is a lightweight JavaScript library that transforms HTML elements into drag-and-drop file upload zones. It provides comprehensive file upload functionality with support for image thumbnails, progress tracking, multiple file uploads, and extensive customization options, all without requiring jQuery or other dependencies.

Package Information

  • Package Name: dropzone
  • Package Type: npm
  • Language: JavaScript (compiled from CoffeeScript)
  • Installation: npm install dropzone

Core Imports

ES6 Modules:

import Dropzone from "dropzone";

CommonJS:

const Dropzone = require("dropzone");

Browser (global):

<script src="dropzone.js"></script>
<!-- Dropzone is available as global variable -->

AMD:

require(["dropzone"], function(Dropzone) {
  // Use Dropzone
});

Basic Usage

import Dropzone from "dropzone";

// Automatic initialization on elements with .dropzone class
// Just add class="dropzone" to any form or div element

// Manual initialization
const myDropzone = new Dropzone("#my-dropzone", { 
  url: "/file/post",
  maxFilesize: 2, // MB
  acceptedFiles: "image/*",
  maxFiles: 5
});

// Listen to events
myDropzone.on("success", function(file, response) {
  console.log("Upload successful:", file.name);
});

myDropzone.on("error", function(file, errorMessage) {
  console.log("Upload failed:", errorMessage);
});

Architecture

Dropzone.js is built around several key components:

  • Main Class: Dropzone class extending Emitter for event-driven functionality
  • Auto-discovery: Automatic initialization of elements with .dropzone class
  • Event System: Comprehensive event system with 25+ events for upload lifecycle
  • File Management: Complete file lifecycle management from addition to completion
  • Thumbnail System: Automatic image thumbnail generation with configurable dimensions
  • Upload Queue: Configurable parallel upload processing with queue management
  • Browser Compatibility: Graceful fallback to traditional file inputs for older browsers

Capabilities

Constructor and Initialization

Core Dropzone class instantiation and configuration options for creating upload zones.

class Dropzone extends Emitter {
  constructor(element: string | HTMLElement, options?: DropzoneOptions);
}

interface DropzoneOptions {
  url?: string;
  method?: string;
  withCredentials?: boolean;
  parallelUploads?: number;
  uploadMultiple?: boolean;
  maxFilesize?: number;
  paramName?: string;
  createImageThumbnails?: boolean;
  maxThumbnailFilesize?: number;
  thumbnailWidth?: number;
  thumbnailHeight?: number;
  filesizeBase?: number;
  maxFiles?: number;
  params?: object;
  clickable?: boolean | string | HTMLElement | HTMLElement[];
  ignoreHiddenFiles?: boolean;
  acceptedFiles?: string;
  autoProcessQueue?: boolean;
  autoQueue?: boolean;
  addRemoveLinks?: boolean;
  previewsContainer?: string | HTMLElement;
  hiddenInputContainer?: string;
  capture?: string;
  renameFilename?: (name: string) => string;
  accept?: (file: File, done: (error?: string) => void) => void;
  init?: () => void;
  forceFallback?: boolean;
  fallback?: () => void;
  resize?: (file: File) => { srcX: number, srcY: number, srcWidth: number, srcHeight: number, trgX: number, trgY: number, trgWidth: number, trgHeight: number };
  // Dictionary options for UI text
  dictDefaultMessage?: string;
  dictFallbackMessage?: string;
  dictFallbackText?: string;
  dictFileTooBig?: string;
  dictInvalidFileType?: string;
  dictResponseError?: string;
  dictCancelUpload?: string;
  dictCancelUploadConfirmation?: string;
  dictRemoveFile?: string;
  dictRemoveFileConfirmation?: string;
  dictMaxFilesExceeded?: string;
}

Constructor and Configuration

File Management

File addition, removal, and lifecycle management for handling uploaded files.

// File addition and removal
addFile(file: File): void;
removeFile(file: File): void;
removeAllFiles(cancelIfNecessary?: boolean): void;

// File validation
accept(file: File, done: (error?: string) => void): void;

// File querying
getAcceptedFiles(): File[];
getRejectedFiles(): File[];
getFilesWithStatus(status: string): File[];
getQueuedFiles(): File[];
getUploadingFiles(): File[];
getAddedFiles(): File[];
getActiveFiles(): File[];

File Management

Upload Processing

Upload queue management and file processing functionality.

// Queue management
processQueue(): void;
processFile(file: File): void;
processFiles(files: File[]): void;
enqueueFile(file: File): void;
enqueueFiles(files: File[]): void;

// Upload control
uploadFile(file: File): void;
uploadFiles(files: File[]): void;
cancelUpload(file: File): void;

Upload Processing

Event System

Comprehensive event handling system with 25+ events covering the complete upload lifecycle.

// Event management (inherited from Emitter)
on(event: string, handler: Function): Dropzone;
off(event?: string, handler?: Function): Dropzone;
emit(event: string, ...args: any[]): Dropzone;

// Available events
events: string[]; // Array of all available event names

Available Events: drop, dragstart, dragend, dragenter, dragover, dragleave, addedfile, addedfiles, removedfile, thumbnail, error, errormultiple, processing, processingmultiple, uploadprogress, totaluploadprogress, sending, sendingmultiple, success, successmultiple, canceled, canceledmultiple, complete, completemultiple, reset, maxfilesexceeded, maxfilesreached, queuecomplete

Event System

Thumbnail Generation

Automatic image thumbnail creation with customizable dimensions and processing.

createThumbnail(file: File, callback?: (dataUrl: string) => void): void;
createThumbnailFromUrl(file: File, imageUrl: string, callback?: (dataUrl: string) => void, crossOrigin?: string): void;

Thumbnail Generation

Static Methods and Utilities

Static utility methods and global configuration for Dropzone instances.

// Instance management
static forElement(element: string | HTMLElement): Dropzone;
static discover(): void;

// Utility methods
static createElement(string: string): HTMLElement;
static elementInside(element: HTMLElement, container: HTMLElement): boolean;
static getElement(el: string | HTMLElement, name: string): HTMLElement;
static getElements(els: string | HTMLElement | HTMLElement[], name: string): HTMLElement[];
static confirm(question: string, accepted: () => void, rejected?: () => void): void;
static isValidFile(file: File, acceptedFiles: string): boolean;
static isBrowserSupported(): boolean;

// Global configuration
static options: { [elementId: string]: DropzoneOptions | false };
static instances: Dropzone[];
static autoDiscover: boolean;
static version: string;

Static Methods and Utilities

File Status Constants

// File status constants
static ADDED: "added";
static QUEUED: "queued"; 
static ACCEPTED: "queued"; // Alias for QUEUED
static UPLOADING: "uploading";
static PROCESSING: "uploading"; // Alias for UPLOADING
static CANCELED: "canceled";
static ERROR: "error";
static SUCCESS: "success";

Types

interface File {
  // Standard File properties plus Dropzone additions
  name: string;
  size: number;
  type: string;
  status: string;
  accepted: boolean;
  xhr?: XMLHttpRequest;
  previewElement?: HTMLElement;
  previewTemplate?: string;
  width?: number;
  height?: number;
}

interface Emitter {
  on(event: string, handler: Function): this;
  off(event?: string, handler?: Function): this;
  emit(event: string, ...args: any[]): this;
  addEventListener(event: string, handler: Function): this;
  removeListener(event?: string, handler?: Function): this;
  removeAllListeners(event?: string, handler?: Function): this;
  removeEventListener(event?: string, handler?: Function): this;
}