Uploading

FilePond ships with various extensions that handle file storage.

Form Post

This is the default upload mode. When we wrap a <input type="file"/> with the <file-pond> custom element we get the FilePond user experience and files are still uploaded to our server when the form is posted.

Usually this is fine for smaller files.

<form action="/upload" method="POST">
    <file-pond>
        <label for="my-file">Drop files here, or <u>browse</u></label>
        <input id="my-file" type="file" name="files" required />
    </file-pond>

    <button type="submit">Upload</button>
</form>

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

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

Asynchronous Form Post

A nice middle ground for when we’re uploading slightly larger files. We can register the FormPostStore extension which adds asynchronous file uploading.

When this store is added FilePond automatically adds an upload button to each entry item.

import { defineFilePond } from 'filepond';
import { locale } from 'filepond/locales/en-gb.js';
import { FormPostStore } from 'filepond/extensions/form-post-store.js';

defineFilePond({
    locale,
    extensions: [
        [
            FormPostStore,
            {
                // The URL the store will POST files to
                url: '/upload',

                // The name of the form field we'll use
                name: 'files',
            },
        ],
    ],
});

Server configuration

The FormPostStore will POST each file to the url, the name of the field is set to the name option. The server should return a unique id for the file.

To release an already uploaded file the FormPostStore will call DELETE on the url and pass the unique id of the file as id in the querystring.

If a file has been uploaded in an earlier session it can be restored. The FormPostStore will request the file header with an optional HEAD request and then a GET request to the url and pass the unique id of the file as id in the querystring.

Instant upload

The FormPostStore accepts the shouldStore option, this option can be set to a (optionally async) function that returns true if the file should be uploaded immediately.

import { defineFilePond } from 'filepond';
import { locale } from 'filepond/locales/en-gb.js';
import { FormPostStore } from 'filepond/extensions/form-post-store.js';

defineFilePond({
    locale,
    extensions: [
        [
            FormPostStore,
            {
                // The URL the store will POST files to
                url: '/upload',

                // When a file is added, just store it immediately
                shouldStore: (entry) => true,
            },
        ],
    ],
});

Trigger upload

We can trigger file upload programmatically by setting the store property on one or more entries.

<form action="/upload" method="POST">
    <file-pond>
        <label for="my-file">Drop files here, or <u>browse</u></label>
        <input id="my-file" type="file" name="files" required />
    </file-pond>

    <button type="button" id="myUploadButton">Store files</button>

    <button type="submit">Upload</button>
</form>

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

    const [element] = defineFilePond({
        locale,
        extensions: [
            [
                FormPostStore,
                {
                    // The URL the store will POST files to
                    url: '/upload',
                },
            ],
        ],
    });

    // On click for every entry in this element set the `store` state to `true`
    myUploadButton.onclick = function () {
        element.entries = element.entries.map((entry) => {
            entry.state = { ...entry.state, store: true };
            return entry;
        });
    };
</script>

Chunked File Uploads

We can use the ChunkedUploadStore when we need to upload very large files.

import { defineFilePond } from 'filepond';
import { locale } from 'filepond/locales/en-gb.js';
import { ChunkedUploadStore } from 'filepond/extensions/chunked-upload-store.js';

defineFilePond({
    locale,
    extensions: [
        [
            ChunkedUploadStore,
            {
                // The URL the store will send files to
                url: '/upload',
            },
        ],
    ],
});

Simulated Uploads

To test upload functionality we can use the SimulatedStore, it’ll behave just like the FormPostStore but files won’t be uploaded.

Custom Store Extension

We use the createStoreExtension function to create a custom store extension. We can set default StoreExtensionOptions and our custom extension needs to set storeEntry and can optionally set restoreEntry and releaseEntry.

The functions can call onprogress to update the entry progress state, onabort to abort the action, or use the abortController to handle abort signals arriving from FilePond.

createStoreExtension(
    'MyStore',
    {
        // default options
    },
    {
        restoreEntry: async function (value, entry, { onprogress, onabort, abortController }) {
            // Used to restore a previously stored entry with storage id `value`
        },
        storeEntry: async function (entry, { onprogress, onabort, abortController }) {
            // Used to store an entry
        },
        releaseEntry: async function (value, entry, { onabort, abortController }) {
            // Used to remove a stored entry with storage id `value`
        },
    }
);