FilePond is a polished JavaScript file uploader web component, this quick start guide shows the fastest way to install and set up FilePond in your web project.

Quick Start

  1. Install the package

    We can install the filepond package using a package manager, load it from a cdn, or download the files manually.

    npm install filepond@alpha
     
    pnpm add filepond@alpha
     
    yarn add filepond@alpha

    To load FilePond from a CDN we add the import map below to the top of our webpage.

    <script type="importmap">
    {
        "imports": {
            "filepond": "https://unpkg.com/filepond@alpha/cdn/index.js",
            "filepond/": "https://unpkg.com/filepond@alpha/cdn/"
        }
    }
</script>

    To manually install FilePond we start by downloading the FilePond package below.

    filepond-5.0.0-alpha.9.tgz

    After we unzip the package we copy the “esm” folder to our project and add the import map below to the top of our webpage.

    <script type="importmap">
    {
        "imports": {
            "filepond": "./path-to-file-pond-esm/index.js",
            "filepond/": "./path-to-file-pond-esm/"
        }
    }
</script>

  2. Add the custom element

    Let’s assume we already have a <input type="file"> on our page, to add FilePond we wrap it with our new <file-pond> custom element. 

    <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>

    Nothing happens yet because we also have to register the <file-pond> custom element.

  3. Register the custom element

    We register the <file-pond> custom element using the defineFilePond function.

    In the example below we import both the function and the English locale.

    Then we call defineFilePond and pass the imported locale as our default locale. 

    <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 type="module">
    import { defineFilePond } from 'filepond';
    import { locale } from 'filepond/locales/en-gb.js';

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

    We’re done! After refreshing the page FilePond will have replaced the <input type="file"> and our <label> will be shown in the drop area.

    Tap the “Run now” button above to open this example as a live demo.

Things to keep in mind

  • FilePond won’t affect the behavior of the form. When we submit the form it still synchronously posts any files selected in FilePond to the server.

  • The <file-pond> custom element implements ElementInternals, this means it behaves as a normal form element.

  • FilePond copies relevant attributes that are set on the file input element to the <file-pond> element, in the example that would be the required attribute.

  • The FilePond styles are embedded in the custom element, there’s no need to link a separate stylesheet.

  • When using <file-pond> in a plain HTML page we can set a limited selection of attributes on the <file-pond> element, properties need to be set on the element reference.

    When we’re using a JavaScript framework the <file-pond> custom element behaves as a component and properties can be set directly on the element <file-pond property={value}>.

Developer tools

To make developing with FilePond easier we can add the ConsoleView extension, it logs the current file tree to the developer console. 

import { defineFilePond } from 'filepond';
import { locale } from 'filepond/locales/en-gb.js';
import { ConsoleView } from 'filepond/extensions/console-view.js';

const elements = defineFilePond({
    locale,
    extensions: [ConsoleView],
});

elements.forEach((element) => {
    element.entries = [
        {
            name: 'my-file.txt',
            size: 1234,
        },
    ];
});

Next steps