FilePond object

The FilePond object is the object available after importing FilePond in your project. It exposes the FilePond public API which we’ll mostly use to add create, find or destroy FilePond instances on the page.

Methods

Properties

Events

The FilePond object fires a FilePond:loaded event when it’s ready. This is useful when we’re directly embedding filepond on a page using a defer or async attribute on the <script> tag. In those situations the script will be loaded asynchronously so it might not be available on document ready.

The event detail property will contain the FilePond API.

document.addEventListener('FilePond:loaded', e => {
    console.log('FilePond ready for use', e.detail);
});

Creating a FilePond instance

Enhancing an HTML element

The create method can be used to turn an element into a FilePond element. Pass an element reference as the first argument and presto!

We can still pass options to our instance by using data attributes.

FilePond will automatically clone attribute values and map them to its properties. This is very useful when progressively enhancing an existing <input type="file"> element.

In the example below the attributes name, data-max-files and required will automatically be passed to the created FilePond instance and converted from a string to the right property unit type.

<input type="file" name="filepond" data-max-files="10" required>

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

// create a FilePond instance at the input element location
const pond = FilePond.create( inputElement );

// attributes have been set to pond options
console.log(pond.name);  // 'filepond'
console.log(pond.maxFiles); // 10
console.log(pond.required); // true
</script>

Attribute to option mapping is done by removing the data- part, removing dashes and uppercasing each character after a dash. This process turns data-max-files into maxFiles.

It’s also possible to pass an additional option object to the create method.

<input type="file" name="filepond" required multiple>

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

// create a FilePond instance at the input element location
const pond = FilePond.create( inputElement, {
    maxFiles: 10,
    allowBrowse: false
});

// attributes and initial options have been set to pond options
console.log(pond.name);  // 'filepond'
console.log(pond.maxFiles); // 10
console.log(pond.required); // true
console.log(pond.allowMultiple); // true
</script>

Using an option object

We can also create a FilePond instance out of thin air and then add it to the page later on.

// create a FilePond instance at the input element location
const pond = FilePond.create({
    name: 'filepond',
    maxFiles: 10,
    allowBrowse: false
});

// add our pond to the body
pond.appendTo(document.body);
</script>

Setting initial files

You can populate FilePond with a set of initial files using the files property. This property is suitable for restoring earlier temporary uploads or already uploaded files. While the files property can also be populated with new files, it is advised to add new files using only the addFile and addFiles methods.

The files property takes an array of file references, it accepts the same formats as the addFile method.

• Local and Remote URLs
• DataURLs
• Blobs or File objects

It extends this selection with the option to add server files.

Adding a temporary server file. The limbo type will direct the load request to the server API restore end point.

const pond = FilePond.create({
    files: [
        {
            // the server file reference
            source: '12345',

            // set type to limbo to tell FilePond this is a temp file
            options: {
                type: 'limbo'
            }
        }
    ]
});

Adding an already uploaded server file. The local type will direct the load request to the server API load end point.

const pond = FilePond.create({
    files: [
        {
            // the server file reference
            source: '12345',

            // set type to local to indicate an already uploaded file
            options: {
                type: 'local'
            }
        }
    ]
});

You can also mock the file by supplying file information in the options object, this will be the same information that FilePond otherwise fetches from the server. FilePond will now create a mock file item, and won’t load the file data.

const pond = FilePond.create({
    files: [
        {
            // the server file reference
            source: '12345',

            // set type to local to indicate an already uploaded file
            options: {
                type: 'local',

                // mock file information
                file: {
                    name: 'my-file.png',
                    size: 3001025,
                    type: 'image/png'
                }
            }
        }
    ]
});

Note that this will impact the way plugins render or process the file as no actual file data is available.

If you want to supply initial metadata to a loaded file (accessible using setMetadata and getMetadata on the file item) you can do so with the metadata property. The following example will create a date entry in the FilePond file item metadata object.

const pond = FilePond.create({
    files: [
        {
            // the server file reference
            source: '12345',

            // set type to local to indicate an already uploaded file
            options: {
                type: 'local',

                // file initial metadata
                metadata: {
                    date: '2018-10-5T12:00'
                }
            }
        }
    ]
});

// get the data of the first file
const date = pond.getFile().getMetadata('date');

Fitting with the progressive enhancement strategy FilePond adheres to, it’s also possible to feed FilePond an initial file using HTML.

The example below might seem elaborate at first, maybe it is a bit. But should JavaScript fail to load, for whatever reason, the user will still be able to remove files (by unchecking them) and add new files. The resulting form object when posted will contain all information required to update any server state.

<fieldset>

    <legend>Files</legend>

    <!-- a list of already uploaded files -->
    <ul>
        <li>
            <label>
                <input value="foo.jpg" data-type="local" checked type="checkbox">
                foo.jpeg
            </label>
        </li>
        <li>
            <label>
                <input value="bar.png" data-type="local" checked type="checkbox">
                bar.png
            </label>
        </li>
    </ul>

    <!-- our filepond input -->
    <input type="file" name="filepond" required multiple>

</fieldset>

<script>
// get a reference to the fieldset element
const fieldsetElement = document.querySelector('fieldset');

// create a FilePond instance at the fieldset element location
const pond = FilePond.create( fieldsetElement );

// files have been gathered
console.log(pond.files); // [{ source: 'foo.jpeg' }, { source: 'bar.png' }]
</script>

And this is how that HTML renders without styles. It’s not super fancy, but it allows the user to upload or change his file selection, even without JavaScript.

<legend>Files</legend>

<!-- a list of already uploaded files -->
<ul>
    <li>
        <label>
            <input value="foo.jpg" data-type="local" checked type="checkbox">
            foo.jpeg
        </label>
    </li>
    <li>
        <label>
            <input value="bar.png" data-type="local" checked type="checkbox">
            bar.png
        </label>
    </li>
</ul>

<!-- our filepond input -->
<input type="file" required multiple>

Destroying a FilePond instance

Destroying a FilePond instance will reset the HTML to its original state.

<intput type="file" name="filepond" required multiple>

<script>
const inputElement = document.querySelector('input[type="file"]');

// create the FilePond instance
FilePond.create( inputElement );

// destroy the FilePond instance by element reference
FilePond.destroy( inputElement );
</script>

Automatically Loading FilePond Instances

The parse method lets us automatically load FilePond elements on the page.

This will look for elements with the class .filepond in the subtree of the <body> element.

<input type="file" class="filepond"/>

<script>
FilePond.parse(document.body);
</script>

Setting Options

We can set default options for all our FilePond instances on the page using the setOptions method.

FilePond.setOptions({
    allowDrop: false,
    allowReplace: false,
    instantUpload: false,
    server: {
        url: 'http://192.168.33.10',
        process: './process.php',
        revert: './revert.php',
        restore: './restore.php?id=',
        fetch: './fetch.php?data='
    }
});

Registering Plugins

With the plugins available on the page we can now register them with FilePond using the registerPlugin method.

FilePond.registerPlugin(FilePondPluginImagePreview);

We can pass multiple plugin references to the registerPlugin method.

FilePond.registerPlugin(
    FilePondPluginImagePreview,
    FilePondPluginFileValidateSize
);

Plugins need to be registered before we create our first FilePond instance.

A plugin will fire a FilePond:pluginloaded event on the document when it’s ready for use. The event detail property will contain the plugin.

document.addEventListener('FilePond:pluginloaded', e => {
    console.log('FilePond plugin is ready for use', e.detail);
});

FilePond Status

These are the properties available on the Status enum.

{
    EMPTY: 0,
    IDLE: 1,
    ERROR: 2,
    BUSY: 3,
    READY: 4
}

FileStatus Enum

These are the properties available on the FileStatus enum. We can use it to get the actual status from the file item status property.

{
    INIT: 1,
    IDLE: 2,
    PROCESSING_QUEUED: 9,
    PROCESSING: 3,
    PROCESSING_COMPLETE: 5,
    PROCESSING_ERROR: 6,
    PROCESSING_REVERT_ERROR: 10,
    LOADING: 7,
    LOAD_ERROR: 8
}

FileOrigin Enum

This enum contains the names for the different file origins. A file item is either INPUT by the user, restored from the server a temporary file LIMBO, or is a LOCAL server file (a file already uploaded and confirmed that is not in the server temporary uploads folder).

{
    INPUT: 1,
    LIMBO: 2,
    LOCAL: 3
};