FilePond v5 is a complete rewrite of FilePond which means we can’t “just” npm update a project using FilePond v4 and be done with it.

In the overview below we’ll outline the most important FilePond v4 APIs and their FilePond v5 counterparts.

Initialisation

FilePond v5 is a custom element. Instead of passing a file input to the FilePond FilePond.create method we now wrap it with the FilePond custom element.

Alternatively we can set up FilePond a programmatically.

<link href="filepond.css" rel="stylesheet" />
<script src="filepond.js"></script>

<input type="file" />

<script>
    // Get a reference to the file input element
    const inputElement = document.querySelector('input[type="file"]');

    // Create a FilePond instance
    const pond = FilePond.create(inputElement);
</script>
 
<file-pond>
    <input type="file" />
</file-pond>

<script type="module">
    import { defineFilePond } from 'filepond';
    import { locale } from 'filepond/locales/en-gb.js';

    defineFilePond({
        locale,
    });
</script>

Stylesheets

Styles are now part of the FilePond custom element and are added automatically, there’s no need to reference external stylesheets.

FilePond can be styled with custom properties and by adjusting the template used to render the view.

Plugins

Plugins have been renamed to extensions and are now part of the main FilePond repository instead of being placed in separate repositories.

Instead of calling registerPlugin, registering extensions can be done by passing them to defineFilePond. Each extension accepts configuration options which can be updated on the element.

Labels are no longer part of the plugin options, they’re all configured on the locale property. 

<script src="filepond-plugin-image-validate-size.js"></script>
<script src="filepond.js"></script>

<script>
    FilePond.registerPlugin(FilePondPluginImageValidateSize);

    // ... FilePond initialisation code here
</script>
 
<file-pond>
    <input type="file" />
</file-pond>

<script type="module">
    import { defineFilePond } from 'filepond';
    import { locale } from 'filepond/locales/en-gb.js';
    import { MediaResolutionValidator } from 'filepond/extensions/media-resolution-validator.js';

    const [element] = defineFilePond({
        locale,
        extensions: [
            // Add the MediaResolutionValidator extension
            [
                MediaResolutionValidator,
                {
                    // Initialise extension with these configuration options
                    minWidth: 1024,
                    minHeight: 768,
                },
            ],
        ],
    });

    // Update extension configuration options like this
    element.MediaResolutionValidator = {
        minWidth: 1024,
        minHeight: 768,
    };
</script>

Uploading files

In FilePond v4 we had to set the storeAsFile property to true to store files in the file input element, in v5 this is the default mode.

To upload files asynchronously with FilePond v4 we had to set the server property. With FilePond v5 we can add the FormPostStore extension, this store accepts a url parameter which points to where the files are uploaded. This extension also manages the restore and revert action of a file.

To load a previously stored file we can add the URLLoader extension.

Chunked uploads are now handled by the ChunkedUploadStore.

Instant uploading can now be achieved by adjusting the shouldStore property.

The FormPostStore and ChunkedUploadStore both expose a resolveRequest and resolveResponse hook to manipulate the request and response objects, this makes it possible to intergate with various server configurations. 

FilePond.setOptions({
    server: {
        url: 'http://192.168.0.100',
        process: {
            url: './process',
            method: 'POST',
            withCredentials: false,
            headers: {},
            timeout: 7000,
            onload: null,
            onerror: null,
            ondata: null,
        },
    },
});
 
defineFilePond({
    locale,
    extensions: [
        [
            FormPostStore,
            {
                url: 'http://192.168.0.100',
                resolveRequest: ({ url, options }) => {
                    // return modified options (may be async)
                    return {
                        url,
                        options: {
                            // spread default options
                            ...options,

                            // overwrite with custom options
                            method: 'POST',
                            withCredentials: false,
                            timeout: 7000,
                            headers: {
                                // custom headers here
                            },
                        },
                    };
                },
            },
        ],
    ],
});

Setting initial files

Files are now set using the entries property on the FilePondInputElement.

Updating the property will trigger an update of the state.

File items

File items are now called file entries.

serverId

The serverId is now only set when using a store extension, it’s stored as value in the entry state property.

poster

Add the image view component to the template and use the poster property on the EntryListView of an item.

Labels

Labels can now be set with the locale property.

Icons

In v4 icons were properties on the FilePond object, these have been moved to the assets object.

Layouts

With v4 the item layout was limited by what FilePond could render, with v5 there is no such limit. You can freely set a grid or flex layout to the entry list.

You can also customize the template FilePond uses to render the file tree.