FilePond

• Introduction
• Installation
• Basic Usage
• Livewire Integration
• Options
  • Multiple
  • Max Files
  • Disabled
  • Allow Drop
• Callbacks
• Plugins
• Manually Deleting Files
• Clear Event Listener
  • Browser Clear Event
• Type
• API Reference
  • props
  • slots
  • config

#Introduction

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.

#Installation

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.

#Basic Usage

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

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

#Livewire Integration

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

#Options

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.

#Multiple

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.

#Max Files

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.

#Disabled

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

#Allow Drop

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.

#Callbacks

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>
</x-file-pond>

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

#Plugins

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:

<script>
    document.addEventListener("DOMContentLoaded", () => {
        FilePond.registerPlugin(FilePondPluginFileValidateType);
    });
</script>

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

<script src="https://unpkg.com/filepond-plugin-file-validate-type/dist/filepond-plugin-file-validate-type.js"></script>

#Manually Deleting Files

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.

#Clear Event Listener

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:

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

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.

#Browser Clear Event

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

#Type

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/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
excel	.csv,application/vnd.ms-excel,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.

#API Reference

#props

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

#slots

slot	description
config	Provides a place for a JavaScript configuration object for FilePond. Most useful for defining JS callbacks.

#config

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' => [],
    ],
],