DropzoneJS
Drupal integration for the DropzoneJS library, providing drag-and-drop file upload functionality with image previews.
dropzonejs
Install
composer require 'drupal/dropzonejs:8.x-2.11'
Overview
DropzoneJS is a Drupal module that provides integration with the popular DropzoneJS JavaScript library, enabling modern drag-and-drop file upload functionality across your Drupal site. The module provides a custom form element that can be used anywhere in Drupal where file uploads are needed.
The module automatically replaces the default upload form in the Media Library for image, video, audio, and file media sources, providing a seamless drag-and-drop experience. It supports multiple file uploads, file size validation, allowed file extension filtering, and displays upload progress with image previews.
Additional features include optional client-side image resizing before upload (using the exif-js library), filename transliteration and sanitization for security, and chunked uploads for large files. The module also provides a submodule for Entity Browser integration, allowing the DropzoneJS uploader to be used within Entity Browser widgets for selecting and uploading files or media entities.
Features
- Drag-and-drop file upload interface with visual feedback and progress indicators
- Automatic integration with Drupal's Media Library for image, video, audio, and file media types
- Custom 'dropzonejs' form element that can be used in any Drupal form
- Client-side image resizing before upload (optional, requires exif-js library)
- Configurable upload settings including max file size, allowed extensions, and max number of files
- Filename sanitization and transliteration for uploaded files to ensure security
- Remove uploaded files before form submission with visual remove icons
- CSRF protection on the upload endpoint for security
- Support for both Dropzone 5 and Dropzone 6 library versions
- Event system allowing other modules to react to media entity creation during uploads
Use Cases
Media Library File Uploads
Site builders want to provide content editors with an intuitive drag-and-drop file upload experience in the Media Library. After installing DropzoneJS, editors can simply drag files onto the upload area instead of clicking through file browser dialogs. Multiple files can be dropped at once, and upload progress is displayed in real-time.
Custom Form File Uploads
Developers building custom forms can use the 'dropzonejs' form element type to add drag-and-drop file uploads. Configure properties like #max_filesize, #extensions, and #max_files to control upload behavior. The element returns an array of temporary file paths that can be processed in the form submission handler.
Entity Browser Media Selection
Sites using Entity Browser for media selection can enable the dropzonejs_eb_widget submodule to provide DropzoneJS-powered upload widgets. Choose from basic file uploads, automatic media entity creation, or media entity creation with inline editing for immediate field population.
Client-side Image Optimization
To reduce server bandwidth and speed up uploads, install the exif-js library and enable client-side resizing on your DropzoneJS element. Images are resized in the browser before upload, maintaining correct orientation from EXIF data. Configure max width, height, quality, and resize method.
High-volume Image Uploads
Photography sites or galleries need to upload many images quickly. DropzoneJS allows dragging entire folders of images, displays thumbnails as previews, and processes uploads in parallel. The auto-select feature in Entity Browser widgets can automatically save and select files as they finish uploading.
Tips
- Grant the 'Dropzone upload files' permission to authenticated users or specific roles that need to use the upload functionality
- Use token replacements in upload_location settings (e.g., public://[date:custom:Y]-[date:custom:m]) to organize files by date
- For the Entity Browser submodule, enable 'Inherit settings from the media type' to automatically use file field settings for max size and allowed extensions
- The dropzone element supports #max_files set to 0 for unlimited file uploads, or a positive integer to limit uploads
- Consider enabling client-side resizing for image uploads to reduce bandwidth usage and improve upload speed for large images
Technical Details
Permissions 1
Hooks 1
hook_media_source_info_alter
Used internally by the module to replace the default media library add form with the DropzoneJS version for image, video_file, audio_file, and file media sources.
Troubleshooting 5
Ensure the DropzoneJS library is installed in the libraries/dropzone folder. The module looks for dropzone-min.js or dropzone.min.js in several possible locations. Download the library dist.zip from GitHub and extract it properly.
Check that the user has the 'Dropzone upload files' permission. Without this permission, the dropzone element won't be accessible and uploads will fail silently.
Install the exif-js library in libraries/exif-js/exif.js. The library is required for client-side resizing functionality. Without it, the clientside_resize option will be disabled in widget configuration.
Check PHP settings for upload_max_filesize and post_max_size. The module respects these limits. Also check the upload_timeout_ms configuration if uploads are timing out.
The module sanitizes filenames for security. If using Drupal 10.2+, configure filename sanitization in core settings. The legacy filename_transliteration setting is deprecated and will be removed in a future version.
Security Notes 5
- All uploads require CSRF token validation for protection against cross-site request forgery attacks
- Executable file extensions (php, pl, py, cgi, asp, js) are automatically renamed with .txt extension to prevent code execution
- Files are initially uploaded with a .txt extension appended for security, which is removed only after validation
- The upload endpoint requires the 'dropzone upload files' permission, ensuring only authorized users can upload files
- File validation includes extension checking, file size limits, and filename length validation