Getting started

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

Install the package

We can install the filepond package using a package manager, load it from a cdn, or download the files manually.
- npm
- pnpm
- yarn
- cdn
- zip
```
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>
```
We can import FilePond without using the import map, but typing out the whole CDN url gets tiresome real fast. The documentation examples import FilePond from 'filepond'.
```
import * from 'https://unpkg.com/filepond@beta/cdn/index.js'
// vs
import * from 'filepond'
```
The CDN version of FilePond is great for testing, but keep in mind that this bundle isn’t optimised for production as it includes all FilePond dependencies.

It’s good practise to use a package manager like npm combined with a build tool like Vite or Parcel to create an optimised build that only includes the parts of FilePond that we’re actually using.
To manually install FilePond we start by downloading the FilePond package below.

filepond-5.0.0-beta.23.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>
```
We can import FilePond without using the import map, but that’s rather lengthy. In the examples in the documentation we’ll import from 'filepond'.
```
import * from './path-to-file-pond-esm/index.js'
// vs
import * from 'filepond'
```
For optimal performance we can use bundlers like Vite or Parcel to create a minimized build that only includes the parts of FilePond that we’re actually using.

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">
    <label for="my-file">Document</label>
    <file-pond>
        <input id="my-file" type="file" name="files" multiple required />
    </file-pond>

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

Nothing happens because we have yet to register the <file-pond> custom element so the browser knows how to deal with it.

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">
    <label for="my-file">Document</label>
    <file-pond>
        <input id="my-file" type="file" name="files" multiple 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 the for attribute of our <label> will point to the <file-pond> element.

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

Please note that to use the import statement we have to set the type attribute on the <script> tag to "module".

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.

Relative paths
Import map

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

Content Security Policy

If a Content Security Policy (CSP) is present on your website or app we most likely have to update it.

The directives below cover all FilePonds configurations. See below explanation if you want to pick and choose based on your FilePond configuration. Please note that the worker-src directive is optional.

img-src 'self' blob: data:;
media-src 'self' blob:;
worker-src 'self' blob:;

To have the FilePondEntryListElement correctly render progress indicators on Safari we need to add the data: scheme to the img-src directive.
When using the MediaResolutionValidator or appendEntryImageView template we need to add the blob: scheme to the img-src directive so we can read image sizes.
When using the MediaResolutionValidator or appendEntryVideoView we have to add the blob: scheme to the media-src directive so we can read video size information and show video previews.
We can choose to add the blob: scheme to the worker-src directive. When its set FilePond can dynamically create threads for processes like creating image previews, asynchronously loading data, and manipulating images. Alternatively we can set the workersURL property when calling defineFilePond to pass the URL to the worker directy.
```
defineFilePond({
    // the `workers` subfolder of the filepond package contains the web worker files.
    workersURL: 'https://my-site.com/filepond/workers',
});
```

Next steps

Learn about FilePond custom element core concepts.
Read how to use FilePond with a JavaScript framework.
Adjust the FilePond styles to fit your project.
Customize the FilePond templates for full control over what is rendered.
Set up asynchronous file uploads, not strictly necessary but often needed.