The file-pond component provides an easy way to utilize advanced file uploads via FilePond. Before using this component, we recommend familiarizing yourself with the FilePond library.

The following third-party libraries are required for the file-pond component to work properly.

  • Alpine.js
  • FilePond

As per the FilePond docs, you can install FilePond via npm:

npm i filepond --save

You can then import it in your project using imports:

import * as FilePond from "filepond";

window.FilePond = FilePond;

There are also some styles required for FilePond. You should import the styles before you import the styles for this package:

@import "filepond/dist/filepond.min.css";

See Third-Party Assets on the installation guide for further setup information.

The most basic usage of the file-pond component involves just adding a self-closing tag:

<x-file-pond />

This will output the following HTML (omitting JS):

    <div wire:ignore x-data="filepond(...)">
        <input x-ref="input" type="file" ... />

{note} The FilePond library will completely remove the input element we are rendering from the component once initialized.

The file-pond component integrates smoothly with livewire out-of-the-box and just requires you to provide a wire:model to the component. This will help it set up the necessary server configuration options on the library and will handle uploading and reverting automatically for you via livewire.

<x-file-pond wire:model="avatar" />

You can provide options to the FilePond library via an array through the options attribute. This requires you to pass in a PHP array with scalar values only. Below is an example where we set a class of "foo" on the root element generated by FilePond:

<x-file-pond wire:model="avatar" :options="['className' => 'foo']" />

In the defaults configuration for the file-pond component, you may specify some default options to always set on a FilePond instance. They will not apply however if you pass in an array of options via the options attribute on the component.

For a full reference of all options, please consult the FilePond documentation.

You can accept multiple files by passing in allowMultiple as a boolean value. This attribute has been added as a way to conveniently set the allowMultiple option for FilePond.

You can limit the number of files accepted when allowMultiple is set to true by providing max-files with an integer value.

This option can be set globally in the config, and on a per-element basis.

You can easily disable the FilePond input by passing disabled in as a boolean value.

The allow-drop boolean attribute has been added as a way to conveniently set the allowDrop option. Setting it to false will prevent users from being able to drop files onto the input.

This option can be set globally in the config, and on a per-element basis.

Since the options attribute only accepts scalar values, the component offers a config slot that will allow you to specify an option callbacks, such as onaddfile, that you need to:

<x-file-pond wire:model="avatar">
    <x-slot:config> onaddfile(error, file) { // do stuff }, </x-slot:config>

This slot is inside a function that returns an object. You'll have access to the following variables:

variable description
instance The x-data instance for filepond. If you need the filepond instance, you can access it via instance.__pond
options The options object generated for FilePond by the component
pondOptions The options for FilePond our JavaScript generated before calling the config slot

The file-pond component doesn't make use of any FilePond plugins itself, but you can easily install and implement your own plugins.

First, install the necessary JavaScript and CSS required by the plugin. A list of plugins can be found here.

With the plugin's assets installed, you can register them with FilePond either in an external script, or inline in the DOM somewhere. Here's an example of loading the file type validation plugin in an inline script:

    document.addEventListener("DOMContentLoaded", () => {

If you're into using CDNs, you can add these lines to your layout file for the above example:

<script src=""></script>

If you decide to do something like list out the files and delete them yourself manually instead of the revert button provided by FilePond, you will find that the files still appear to be in FilePond, even though Livewire has actually cleared out your wire:model value. To help with this, the file-pond component adds a watcher on your wire:model by using @entangle. Now, when you remove the files manually, the component will pick up on those changes and remove the removed files from the FilePond instance.

You may encounter some edge cases where you may need to clear the files out of the FilePond instance yourself. When using livewire, this can easily be accomplished by adding the following inside your component somewhere:


If you have multiple filepond instances in a Livewire component, you may pass the id of the filepond instance as an argument to only clear that specific filepond instance. The id should be the id you give to the filepond instance, which defaults to the name attribute if omitted.

$this->emitSelf('file-pond-clear', 'avatar');

This example will only clear the files out of a filepond instance with the id of avatar.

You can also dispatch an event via JavaScript to clear out a filepond instance as well. If you have multiple filepond components rendered on the page, you may pass in the id of the component as an argument.

<button @click="$dispatch('file-pond-clear', { id: 'avatar' })">
    Clear avatar

For convenience, you may specify a type attribute that will limit the types of files that can be selected. If a supported type is entered, the component will set the acceptedFileTypes FilePond option for you.

type rendered accept value
audio audio/*
image image/*
video video/*
pdf .pdf
csv .csv
spreadsheet .csv,application/,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
excel .csv,application/,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
text text/plain
html text/html

{note} For this to work, you must have the File Type Validation plugin installed. See Plugins for more information.

prop description
name Name of the input
id Id of the input. Defaults to name.
multiple A boolean value indicating that multiple files can be uploaded. Defaults to false
disabled A boolean value indicating the input is disabled
maxFiles The maximum amount of files allowed to be uploaded. Only applies if multiple is set to true
options An optional array of FilePond options to set
description Set a description inside the filepond markup
type Set a type of files that are only allowed to be uploaded. Requires the File Validate plugin from FilePond
showErrors If a validation error is present for the input, it will show the error state on the input
extraAttributes Pass an array of HTML attributes to render on the input
slot description
config Provides a place for a JavaScript configuration object for FilePond. Most useful for defining JS callbacks.

The following configuration keys and values can be adjusted for common default behavior you may want for the filepond element.

'defaults' => [
    'global' => [
        // Show error states by default.
        'show_errors' => true,

    'file_pond' => [
        // Allow drag and drop file uploads by default.
        'allow_drop' => true,

        // Limit multiple file uploads to a certain number of files by default.
        // Set to null to allow unlimited files.
        'max_files' => null,

        // Configure FilePond options by default.
        'options' => [],
File Upload
Caught a mistake? Suggest an edit on GitHub