We advise to first read this short guide, and then optionally follow up with a framework specific guide.

FilePond works on all modern browsers and devices.

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@beta
     
    pnpm add filepond@beta
     
    yarn add filepond@beta

    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@beta/cdn/index.js",
            "filepond/": "https://unpkg.com/filepond@beta/cdn/"
        }
    }
</script>

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

    filepond-5.0.0-beta.5.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.

    Let’s import both the function and the English locale, then we call defineFilePond to register the <file-pond> custom element and pass the imported locale to set 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.

Importing the package

Because most web projects these days use a framework or a bundler like Vite the code examples in the documentation import FilePond like a node module.

import { defineFilePond } from 'filepond';

To import FilePond exports without a bundler we have to either use a relative path './filepond/esm/index.js', or we have to set up an import map to import the package.

-import { defineFilePond } from 'filepond';
+import { defineFilePond } from './filepond/esm/index.js';

The import map below redirects the 'filepond' module name to ./filepond/esm/index.js and redirects module paths starting with 'filepond/' to ./filepond/esm/.

<script type="importmap">
    {
        "imports": {
            "filepond": "./filepond/esm/index.js",
            "filepond/": "./filepond/esm/"
        }
    }
</script>

Developer tools

To make integrating FilePond easier we can register the ConsoleView extension. This extension logs the current file tree state 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