Methods

These methods are available on every FilePond instance.

Method Description
setOptions(object) Override multiple options at once
addFile(source [, options]) Adds a file
addFiles(source [, options]) Adds multiple files
removeFile(query) Removes the file matching the given query
removeFiles([query]) Removes all files or files matching the query
processFile(query) Starts processing the file matching the given query
processFiles([query]) Starts processing all files or files matching the query
prepareFile(query) Starts preparing the file matching the given query, returns a Promise, the Promise is resolved with the file item and the output file { file, output }
prepareFiles([query]) Starts preparing all output files or files matching the query, returns a Promise, the Promise is resolved with an array of file prepare output objects { file, output }
getFile(query) Returns the file matching the supplied query
getFile()s Returns all files
browse() Opens the browse file dialog, please note that this only works if the user initiaded the callstack that ends up calling the browse method.
sort(compare) Sorts files in the list using the supplied compare function
moveFile(query, index) Moves the files to a new index in the files array
destroy() Destroys this FilePond instance

These methods are used to subscribe to events fired by FilePond.

Method Description
on(event, fn) Listen to an event with name, run fn when fired.
onOnce(event, fn) The fn handler will only be called once and will then automatically be removed.
off(event, fn) Removes event with handler fn.
These are events used to insert FilePond at a certain location in the DOM.
Method Description
insertAfter(element) Inserts the FilePond instance after the supplied element
insertBefore(element) Inserts the FilePond instance before the supplied element
appendTo(element) Appends FilePond to the given element
isAttachedTo(element) Returns true if the current instance is attached to the supplied element
replaceElement(element) Replaces the supplied element with FilePond
restoreElement(element) If FilePond replaced the original element, this restores the original element to its original glory.

Setting options

To override already set options on a FilePond instance we can either use the setOptions method or adjust the properties directly.

const pond = FilePond.create();
pond.setOptions({
    maxFiles: 10,
    required: true,
});

Adjusting individual properties:

const pond = FilePond.create();
pond.maxFiles = 10;
pond.required = true;

Adding files

To add files we can use the addFile and addFiles end points.

Both methods accept the following file references:

// Adding a single file
pond.addFile('./my-file.jpg');

// Adding multiple files
pond.addFiles('./my-file.jpg', './my-documents.zip');

// It also accepts arrays
pond.addFiles(['./my-file.jpg', './my-documents.zip']);

The last argument can be set to an option object which can be used to determine the index in the items list the file or files should be added at.

// Adding a single file with option object
pond.addFile('./my-file.jpg', { index: 0 });

// Adding multiple files with option object
pond.addFiles('./my-file.jpg', './my-documents.zip', { index: 0 });

// Supplying files as an array with option object
pond.addFiles(['./my-file.jpg', './my-documents.zip'], { index: 0 });

As stated earlier the addFile method also accepts Blobs, File objects and DataURLs.

// Adding a basic base64 encoded DataURL
pond.addFile('data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==');

// Adding a Blob or File
const data = { hello: 'world' };
const blob = new Blob([JSON.stringify(data, null, 2)], {
    type: 'application/json',
});
pond.addFile(blob);

Because Blobs and DataURLs don't supply any filename information FilePond sets the file name to the current date.

The addFile method returns a promise. This can be useful when loading remote files.

pond.addFile('./my-file.jpg')
    .then((file) => {
        // File has been added
    })
    .catch((error) => {
        // Something went wrong
    });

Processing files

We can trigger manual processing of files using the processFile method.

Files can be processed by id, index or file. A parameter is not required.

// processes the first file
pond.processFile().then((file) => {
    // File has been processed
});

// removes the file at index 1
pond.processFile(1).then((file) => {
    // File has been processed
});

// removes the file with the given id
pond.processFile('imzsdvxar').then((file) => {
    // File has been processed
});

Processing multiple files can be done by passing multiple items to the processFiles method.

pond.processFiles('imzsdvxar', 'afaoiwles').then((files) => {
    // files have been processed
});

Process all files

pond.processFiles().then((files) => {
    // files have been processed
});

Getting files

We can get access to a file by id or index. A parameter is not required.

// returns the first file item
pond.getFile();

// returns the file item at index 1
pond.getFile(1);

// returns the file item with the given id
pond.getFile('imzsdvxar');

Get all files with the getFiles method.

// returns all files currently in the list
pond.getFiles();

Removing files

Files can be removed by id, index or file. A parameter is not required.

If we don't supply a parameter to the removeFile method FilePond removes the first file in the file list.

// removes the first file item
pond.removeFile();

// removes the file item at index 1
pond.removeFile(1);

// removes the file item with the given id
pond.removeFile('imzsdvxar');

Files can also be removed by reference, pass a FilePond File to the remove method to have it removed from the list.

pond.addFile('./my-file.jpg').then((file) => {
    pond.removeFile(file);
});

A FilePond File is not the same a JavaScript File or Blob. The FilePond File is a wrapper around a JavaScript file object. Passing a JavaScript File or Blob to the removeFile method won't work.

Opening The File Browser

The browse method can be used to manually trigger the browse files panel.

This only works if the call originates from the user.

This works, as the call originates from the browser clicking the button.

document.querySelector('button').addEventListener('click', () => {
    pond.browse();
});

This doesn't work, the call to browse originates from the browser itself.

setTimeout(() => {
    pond.browse();
}, 5000);

This also doesn't work, the timeout "breaks" the callstack and the browser won't know the call originated from the button.

document.querySelector('button').addEventListener('click', () => {
    setTimeout(() => {
        pond.browse();
    }, 5000);
});

Sorting Files

Using the sort() method or the itemInsertLocation property we can sort the items in the files list.

This sort method behaves exactly the same as the default JavaScript sort compare function.

When loading URLs the file items passed to the sort function don't have file data yet, in that situation we need to check if the files have already been loaded, and if not, we can treat the files as equals. FilePond will call the compare function again after a file has fully loaded.

// Sort the current files from small to big
pond.sort((a, b) => {
    // If no file data yet, treat as equal
    if (!(a.file && b.file)) return 0;

    // Move to right location in list
    if (a.fileSize < b.fileSize) {
        return -1;
    } else if (a.fileSize > b.fileSize) {
        return 1;
    }

    return 0;
});

To automatically sort files when they're added to the list we can set the above sort method to the itemInsertLocation property.

const pond = FilePond.create({
    itemInsertLocation: (a, b) => {
        // If no file data yet, treat as equal
        if (!(a.file && b.file)) return 0;

        // Move to right location in list
        if (a.fileSize < b.fileSize) {
            return -1;
        } else if (a.fileSize > b.fileSize) {
            return 1;
        }

        return 0;
    },
});