laravel-form-components

Components

FilePond

On this page

{note} You're browsing the documentation for an old version of laravel-form-components. Consider upgrading your project to v8. Check your version with the following command:

`composer show rawilk/laravel-form-components`

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

While the file-pond component works out-of-the-box when you've set the directive, we recommend that you install and compile the JavaScript libraries before you deploy to production:

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

There are also some styles required for FilePond. If you're using Sass, you can import it before you import the styles for this package:

@import '~filepond/dist/filepond.min.css';

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 wire:ignore
     x-data
     x-cloak
     x-init="..."
>
    <input x-ref="input"
           type="file"
           style="display:none;"
    />
</div>

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

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

Multiple

You can accept multiple files by passing in multiple 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.

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.

Callbacks

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

<x-file-pond wire:model="avatar">
    <x-slot name="optionsSlot">
        server: {
            process: () => { ... }
        }
    </x-slot>
</x-file-pond>

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 make use of the plugins slot to initialize the plugin. The following example shows setting up the image preview FilePond Plugin.

<x-file-pond wire:model="avatar">
    <x-slot name="plugins">
        FilePond.registerPlugin(FilePondPluginImagePreview);
    </x-slot>
</x-file-pond>

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

<link href="https://unpkg.com/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css" rel="stylesheet">
<script src="https://unpkg.com/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.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.

You can opt out of this behavior by setting the boolean attribute watch-value to false on the component.

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->dispatchBrowserEvent('file-pond-clear', ['id' => $this->id]);

Each Livewire component has its own unique id assigned to it, so by passing $this->id into the event you're emitting, the component will be able to match the ids and clear the files for the correct component.

Edit on GitHub
Previous
File Upload