FilePond

To use FilePond in a modern JavaScript project, install the package via npm and then initialize a FilePond instance using FilePond.create(). You can pass configuration options like multiple: true to enable multi-file uploads.

import * as FilePond from 'filepond';

// Create a multi file upload component
const pond = FilePond.create({
    multiple: true,
    name: 'filepond',
});

// Add it to the DOM
document.body.appendChild(pond.element);

FilePond supports multiple languages via locale files. To change the language of the interface, import the desired locale file and apply it globally using FilePond.setOptions().

import pt_BR from 'filepond/locale/pt-br.js';

FilePond.setOptions(pt_BR);

FilePond uses a custom event system. You can listen to events in two ways:

1. Using the .on() method: This is the primary way to attach callbacks to specific event types.
2. Using standard DOM events: FilePond dispatches CustomEvent objects on its root element with the prefix FilePond:. These events are configured to bubble and are composed (allowing them to cross shadow DOM boundaries).

// Using the .on() API
pond.on('processfile', (error, file) => {
    console.log('File processed:', file);
});

// Using standard DOM event listeners
pond.element.addEventListener('FilePond:processfile', (e) => {
    console.log('Event detail:', e.detail);
});

To start using FilePond, call createApp() with an optional configuration object. This initializes the internal data store, sets up event listeners for window resizing and visibility changes, and renders the initial view. The function returns a FilePond instance containing the public API, event handlers, and DOM manipulation methods.

import { createApp } from 'filepond/src/js/app/index';

const pond = createApp({
    // your initial options here
});

FilePond provides official adapters for several popular frameworks to ensure seamless integration:

• React: @pqina/react-filepond
• Vue: @pqina/vue-filepond
• Angular: @pqina/ngx-filepond
• Svelte: @pqina/svelte-filepond
• jQuery: @pqina/jquery-filepond
• Angular 1: angularjs-filepond
• Blazor: soenneker.blazor.filepond
• Ember: ember-filepond

FilePond provides methods to manage configuration globally:

• getOptions(): Returns the current set of default options.
• setOptions(opts): Updates the default options for all existing FilePond instances and sets the new defaults for any future instances created. It accepts an object of configuration keys and values.

import { getOptions, setOptions } from 'filepond';

// Get current defaults
const currentOptions = getOptions();

// Update defaults for all instances
setOptions({
    allowMultiple: true
});

You can dynamically update the configuration of a running FilePond instance using setOptions(). To retrieve the current status of the pond, use the status property.

// Update options
pond.setOptions({
    allowMultiple: true
});

// Get current status
const currentStatus = pond.status.get();

FilePond distinguishes between 'preparing' and 'processing' files:

• prepareFile(query): Requests the preparation of a specific file (e.g., for output generation). Returns a Promise that resolves with the prepared item.
• processFile(query): Starts the upload/processing of a specific file. Returns a Promise.
• prepareFiles(...args): Prepares all files or a specific subset provided as arguments.
• processFiles(...args): Starts processing all files or a specific subset. If no arguments are provided, it attempts to process all files that are not currently idle, processing, or already completed.

// Process a single file
pond.processFile(fileQuery);

// Process all files
pond.processFiles();

// Prepare a specific file
pond.prepareFile(fileQuery).then(item => {
    console.log('File prepared:', item);
});

The applyFilterChain(key, value, utils) function executes all registered filters associated with a specific key in a sequential pipeline.

Each filter in the chain receives the output of the previous filter as its input. This is useful for complex, multi-step transformations where each step depends on the result of the last. The function returns a Promise that resolves with the final transformed value or rejects if any filter in the chain fails.

import { applyFilterChain } from 'filepond';

// Usage within the FilePond lifecycle
applyFilterChain('some-key', initialValue, utils)
    .then(finalValue => {
        console.log('Transformation complete:', finalValue);
    })
    .catch(error => {
        console.error('Filter chain failed:', error);
    });