filepond

Drupal 10+ integration for FilePond - a flexible JavaScript file upload library with support for drag and drop, image previews, chunked uploads, and more.

If you're familiar with DropzoneJS, you'll find the same familiar features here - a form element, Entity Browser widget, and Media Library integration - while gaining additional functionality like an image field widget, clipboard paste support, and crop integration.

Features

• Chunked uploads - Upload large files reliably with automatic chunking and resume support
• Drag and drop - Modern drag and drop interface with image previews
• Form element - A 'filepond' form element for use in custom forms
• Media Library integration - Optional replacement for core's Media Library upload widget
• Entity Browser widget - Widget for creating Media entities via Entity Browser
• Field widget - Image field widget using FilePond for uploads
• Crop widget - Image field widget with Cropper.js integration for cropping (single-cardinality fields)
• Reordering - Drag to reorder uploaded files
• Paste from clipboard - Paste images and screen grabs from your clipboard directly into the upload field
• Configurable - Global defaults with per-element overrides to control many aspects of the uploader

You can see a demo video of some of the widgets here.

S3 / Remote Storage Optimization

There's a common bottleneck with file uploaders when using cloud storage like S3FS: saving an image field requires width and height dimensions. Drupal's default behavior downloads the entire file back from S3 just to read these dimensions - a 5MB image can take 500+ ms for this single operation.

FilePond solves this by capturing image dimensions while the file is still on the local filesystem during upload, before it's moved to S3. This makes the process ~5000x faster (0.12ms vs 580ms in benchmarks).

Other S3-friendly features:

• Async uploads - Files are uploaded and saved as temporary files before form submission, avoiding the slow "upload everything on submit" pattern.
• Chunked uploads - Large files are split into chunks, uploaded in parallel, and reassembled. Failed chunks retry automatically.
• FastImage fallback - For files already on S3, reads only header bytes (11-29 bytes) to get dimensions instead of downloading the entire file.

See the README section on FilePondUploadPreMoveEvent for benchmark details.

Requirements

• Drupal 10.2 + or Drupal 11
• FilePond JavaScript library and plugins (see Installation)

Required Libraries

• filepond - Core upload library
• filepond-plugin-file-validate-type - MIME type validation
• filepond-plugin-file-validate-size - File size validation
• filepond-plugin-image-preview - Image thumbnail previews
• filepond-plugin-file-poster - Display existing file thumbnails
• filepond-plugin-image-crop - Crop previews to aspect ratio

Installation

composer require drupal/filepond
drush en filepond

That's it! The module uses jsDelivr CDN by default, so no library installation is required. It works out of the box.

Self-Hosting Libraries (Optional)

If you prefer to host the libraries yourself instead of using the CDN, disable "Load libraries from CDN" in Configuration → Media → FilePond and install the libraries using one of these methods:

Option 1: Composer with Asset Packagist (Recommended)

composer require npm-asset/filepond \
  npm-asset/filepond-plugin-file-validate-type \
  npm-asset/filepond-plugin-file-validate-size \
  npm-asset/filepond-plugin-image-preview \
  npm-asset/filepond-plugin-file-poster \
  npm-asset/filepond-plugin-image-crop

This requires:

• Asset Packagist repository configured in composer.json
• oomphinc/composer-installers-extender package
• Installer path configured for npm-asset packages to install to libraries/

Option 2: Custom Package Repository

If you're not using Asset Packagist, you can use the module's composer.libraries.json file with the Composer Merge Plugin:

composer require wikimedia/composer-merge-plugin

Then add to your project's composer.json:

{
    "extra": {
        "merge-plugin": {
            "include": [
                "web/modules/contrib/filepond/composer.libraries.json"
            ]
        }
    }
}

Then require the libraries:

composer require pqina/filepond \
  pqina/filepond-plugin-file-validate-type \
  pqina/filepond-plugin-file-validate-size \
  pqina/filepond-plugin-image-preview \
  pqina/filepond-plugin-file-poster \
  pqina/filepond-plugin-image-crop

Option 3: Manual Download

Download each library from unpkg.com (an npm CDN) and place in libraries/:

libraries/filepond/dist/filepond.min.js
libraries/filepond/dist/filepond.min.css
libraries/filepond-plugin-file-validate-type/dist/filepond-plugin-file-validate-type.min.js
libraries/filepond-plugin-file-validate-size/dist/filepond-plugin-file-validate-size.min.js
libraries/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.js
libraries/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css
libraries/filepond-plugin-file-poster/dist/filepond-plugin-file-poster.min.js
libraries/filepond-plugin-file-poster/dist/filepond-plugin-file-poster.min.css
libraries/filepond-plugin-image-crop/dist/filepond-plugin-image-crop.min.js

Direct download links:

• filepond
• filepond-plugin-file-validate-type
• filepond-plugin-file-validate-size
• filepond-plugin-image-preview
• filepond-plugin-file-poster
• filepond-plugin-image-crop

Once you have the libraries set up:

drush en filepond

Configuration

After installation visit: Administration -> Configuration -> Media -> FilePond (/admin/config/media/filepond) to configure the default settings:

Grant the filepond upload files permission to users that you want to be able to use the uploader.

Usage

There are 5 different ways to use FilePond:

• Media Library widget - Enable FilePond in core's Media Library
• Entity Browser Media Widget - Create Media entities in an entity browser
• Views Area Plugin - Add a FilePond uploader to Views headers/footers
• Image Field Widget - Form widget for uploading images to image fields
• Form API element - A filepond form element for use in custom forms

Field Widget

• This allows you to upload image files (not media) to entities using the core image field
• Select "FilePond Image Uploader" in the field's form display settings

Crop Widget

• Combines FilePond uploads with Cropper.js for image cropping
• Stores crop coordinates using Drupal's Crop API (non-destructive)
• Works with image styles that use focal point or crop effects
• Supports circular crop mode for avatars
• Enable the filepond_crop submodule and select "FilePond Crop" in form display settings
• Note: Only works with single-cardinality image fields

See the README for detailed configuration options.

Entity Browser Media Widget

• This creates media entities from your uploaded files
• Enable the Entity Browser widget submodule (filepond_eb_widget)
• Create a new "FilePond Media Upload" entity browser form

Views Area Plugin

• Add a FilePond uploader to Views headers, footers, or empty text areas
• When files are uploaded, media entities are created and the view refreshes
• Enable the filepond_views submodule

Media Library Uploader

• This replaces the uploader in the media library modals
• Enable it on the FilePond config settings page

Form Element

You can also use the element in your own forms

$form['images'] = [
  '#type' => 'filepond',
  '#title' => $this->t('Upload images'),
  '#extensions' => 'jpg jpeg png gif',
  '#max_filesize' => '10M',
  '#max_files' => 10,
  '#upload_location' => 'public://uploads',
];

• Note: the files are saved as temporary. You must set them to permanent in your submit handler.

  // Fet the file ids.
  $fids = $form_state->getValue(['images', 'fids']);
  // Load the files.
  $files = \Drupal\file\Entity\File::loadMultiple($fids);
  // Set each file to permanent.
  foreach($files as $file){
    $file->setPermanent();
    $file->save();
  }

Resources

• This modules README file as some advanced configuration options.
• FilePond Documentation
• FilePond Server Protocol
• FilePond GitHub Repository

Development

This module is in the early stages of development. Expect breaking changes until there is a stable release.

Patches, suggestions, and all that good stuff are welcome.

I also set up a #filepond Slack channel to for support and discussions.