FilePond properties

The FilePond instance exposes a set of properties that enable us to update its state.

Core properties

The FilePond core module exposes the following properties.

Property Default value Description
element
null
The root element of the FilePond instance. This property has no setter
status
0
Returns the current status of the FilePond instance, use the FilePond.Status enum to determine the status. Has no setter.
name
'filepond'
The input field name to use
className
null
Additional CSS class to add to the root element
required
false
Sets the required attribute to the output field
disabled
false
Sets the disabled attribute to the output field
captureMethod
null
Sets the given value to the capture attribute
files
A list of file locations that should be loaded Immediately
allowDrop
true
Enable or disable drag n' drop
allowBrowse
true
Enable or disable file browser
allowPaste
true
Enable or disable pasting of files. Pasting files is not supported on all browesrs.
allowMultiple
false
Enable or disable adding multiple files
allowReplace
true
Allow drop to replace a file, only works when allowMultiple is false
allowRevert
true
Enable or disable the revert processing button
allowRemove
true
When set to false the remove button is hidden and disabled
allowProcess
true
Enable or disable the process button
allowReorder
false
Allow users to reorder files with drag and drop interaction. Note that this only works in single column mode. It also only works on browsers that support pointer events.
storeAsFile
false
Tells FilePond to store files in hidden file input elements so they can be posted along with normal form post. This only works if the browser supports the DataTransfer constructor, this is the case on Firefox, Chrome, Chromium powered browsers and Safari version 14.1 and higher.
forceRevert
false
Set to true to require the file to be successfully reverted before continuing
maxFiles
null
The maximum number of files that the pond can handle
maxParallelUploads
null
The maxmimum number of files that can be uploaded in parallel
checkValidity
false
Set to true to enable custom validity messages. FilePond will throw an error when a parent form is submitted and it contains invalid files.
itemInsertLocation
'before'
Set to 'after' to add files to end of list (when dropped at the top of the list or added using browse or paste), set to 'before' to add files at start of list. Set to a compare function to automatically sort items when added
itemInsertInterval
75
The interval to use before showing each item being added to the list
credits
{label,url}
Shows Powered by PQINA in footer

Drag n' Drop

Property Default value Description
dropOnPage
false
FilePond will catch all files dropped on the webpage
dropOnElement
true
Require drop on the FilePond element itself to catch the file.
dropValidation
false
When enabled, files are validated before they are dropped. A file is not added when it's invalid.
ignoredFiles
['.ds_store', 'thumbs.db', 'desktop.ini']
Ignored file names when handling dropped directories. Dropping directories is not supported on all browsers.

Server

Property Default value Description
server
null  
A server configuration object describing how FilePond should interact with the server.
instantUpload
true  
Immediately upload new files to the server
chunkUploads
false  
Enable chunked uploads, when enabled will automatically cut up files in chunkSize chunks before upload
chunkForce
false  
Force chunks even for files smaller than the set chunkSize
chunkSize
5000000  
The size of a chunk in bytes
chunkRetryDelays
[500,1000,3000]
Amount of times, and delayes, between retried uploading of a chunk

Labels

Property Default value Description
labelDecimalSeparator
undefined  
The decimal separator used to render numbers. By default this is determined automatically.
labelThousandsSeparator
undefined
The thousdands separator used to render numbers. By default this is determined automatically.
labelIdle
'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'
Default label shown to indicate this is a drop area. FilePond will automatically bind browse file events to the element with CSS class .filepond--label-action
labelInvalidField
'Field contains invalid files'  
Label shown when the field contains invalid files and is validated by the parent form.
labelFileWaitingForSize
'Waiting for size'  
Label used while waiting for file size information
labelFileSizeNotAvailable
'Size not available'  
Label used when no file size information was received
labelFileLoading
'Loading'  
Label used while loading a file
labelFileLoadError
'Error during load'  
Label used when file load failed
labelFileProcessing
'Uploading'  
Label used when uploading a file
labelFileProcessingComplete
'Upload complete'  
Label used when file upload has completed
labelFileProcessingAborted
'Upload cancelled'  
Label used when upload was cancelled
labelFileProcessingError
'Error during upload'  
Label used when something went wrong during file upload
labelFileProcessingRevertError
'Error during revert'  
Label used when something went wrong during reverting the file upload
labelFileRemoveError
'Error during remove'  
Label used to indicate something went wrong when removing the file
labelTapToCancel
'tap to cancel'  
Label used to indicate to the user that an action can be cancelled.
labelTapToRetry
'tap to retry'  
Label used to indicate to the user that an action can be retried.
labelTapToUndo
'tap to undo'  
Label used to indicate to the user that an action can be undone.
labelButtonRemoveItem
'Remove'  
Label used for remove button
labelButtonAbortItemLoad
'Abort'  
Label used for abort load button
labelButtonRetryItemLoad
'Retry'  
Label used for retry load button
labelButtonAbortItemProcessing
'Cancel'  
Label used for abort upload button
labelButtonUndoItemProcessing
'Undo'  
Label used for undo upload button
labelButtonRetryItemProcessing
'Retry'  
Label used for retry upload button
labelButtonProcessItem
'Upload'  
Label used for upload button

SVG Icons

Property Default value Description
iconRemove
'<svg>...</svg>'
The icon used for remove actions
iconProcess
'<svg>...</svg>'
The icon used for process actions
iconRetry
'<svg>...</svg>'
The icon used for retry actions
iconUndo
'<svg>...</svg>'
The icon used for undo actions

Callbacks

Property Function Description
oninit() FilePond instance has been created and is ready.
onwarning(error[, file, status]) FilePond instance throws a warning. For instance when the maximum amount of files has been reached. Optionally receives file if error is related to a file object.
onerror(error[, file, status]) FilePond instance throws an error. Optionally receives file if error is related to a file object.
oninitfile(file) Created file item
onaddfilestart(file) Started file load
onaddfileprogress(file, progress) Made progress loading a file
onaddfile(error, file) If no error, file has been succesfully loaded
onprocessfilestart(file) Started processing a file
onprocessfileprogress(file, progress) Made progress processing a file
onprocessfileabort(file) Aborted processing of a file
onprocessfilerevert(file) Processing of a file has been reverted
onprocessfile(error, file) If no error, Processing of a file has been completed
onprocessfiles() Called when all files in the list have been processed
onremovefile(error, file) File has been removed.
onpreparefile(file, output) File has been transformed by the transform plugin or another plugin subscribing to the prepare_output filter. It receives the file item and the output data.
onupdatefiles(files) A file has been added or removed, receives a list of file items
onactivatefile(file) Called when a file is clicked or tapped
onreorderfiles(files, origin, target) Called when the files list has been reordered, receives current list of files (reordered) plus file origin and target index.

Hooks

Property Description
beforeDropFile(file) FilePond is about to allow this item to be dropped, it can be a URL or a File object. Return true or false depending on if you want to allow the item to be dropped.
beforeAddFile(item) FilePond is about to add this file, return false to prevent adding it, or return a Promise and resolve with true or false.
beforeRemoveFile(item) FilePond is about to remove this file, return false to prevent removal, or return a Promise and resolve with true or false.

Styles

Property Default value Description
stylePanelLayout
null
Set a different layout render mode. Can be either 'integrated', 'compact', and/or 'circle'. Compact mode will remove padding, integrated mode is used to render FilePond as part of a bigger element. Circle mode adjusts the item position offsets so buttons and progress indicators don't fall outside of the circular shape.
stylePanelAspectRatio
null
Set a forced aspect ratio for the FilePond drop area. Useful to make the drop area take up a fixed amount of space. For example when cropping a single square image. Accepts human readable aspect ratios like '1:1' or numeric aspect ratios like 0.75.
styleButtonRemoveItemPosition
'left'
The position of the remove item button, 'left', 'center', 'right', and/or 'bottom'.
styleButtonProcessItemPosition
'right'
The position of the process item button, 'left', 'center', 'right', and/or 'bottom'.
styleLoadIndicatorPosition
'right'
The position of the load indicator, 'left', 'center', 'right', and/or 'bottom'.
styleProgressIndicatorPosition
'right'
The position of the progress indicator, 'left', 'center', 'right', and/or 'bottom'.
styleItemPanelAspectRatio
null
Set a forced aspect ratio for the file items. Useful when rendering cropped or fixed aspect ratio images in grid view, this will improve performance as FilePond will know beforehand the size of the item to render.

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.

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.

<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" required multiple />
</fieldset>

Disabling Credits

FilePond is given to you for free. Please support the project by not removing the tiny Powered by PQINA footer.

If you don't like the way the footer looks but still want to support FilePond, please link to https://pqina.nl somewhere else on your website.

You can also restyle the footer by adjusting the .filepond--credits CSS class.

Your support helps keep the project alive.

Of course you can still disable the credits message by setting the credits property to false. If you do decide to remove the credits message and use FilePond in a commercial project please consider donating to keep the project alive.