DOCSEARCHbyAlgolia
Submit Docs

Spatie Livewire Filepond

repository·main·Indexed 43 days ago

https://github.com/spatie/livewire-filepond

A Livewire component that integrates the Filepond JavaScript library into Laravel applications, providing server-side validation, lifecycle management, and a dedicated <x-filepond::upload /> Blade component.

Tokens
1.3K
Snippets
7
Records
9
Agent score
5%

What's inside Livewire Filepond

  1. Quickstart: Use Filepond in a Livewire component

    main

    To implement Filepond, follow these three steps:

    1. Add scripts: Include the @filepondScripts directive in your layout or view.
    2. Add the trait: Use the WithFilePond trait in your Livewire component.
    3. Add the component: Use the <x-filepond::upload /> Blade component and bind it to a public property using wire:model.
    use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class MyLivewireComponent extends Component
{
    use WithFilePond;
    
    public $file;
}
    @filepondScripts

<x-filepond::upload wire:model="file" />

  2. Customize the Filepond component

    main

    You can customize the <x-filepond::upload /> component using several properties. Note that for any property or plugin property from Filepond, you must use kebab-case.

    Available Properties

    • multiple: Allow multiple files (default: false).
    • required: Make the input required (default: false).
    • disabled: Disable the input (default: false).
    • max-files: Maximum number of files allowed (default: null).
    • placeholder: Placeholder text (default: Drag & Drop your files or <span class="filepond--label-action"> Browse </span>).
    • maxfilesmsg: Error message for max files (default: You can upload a maximum of :max files.).

    Handling Max Files Errors

    If you use the max-files property, you must implement a public method in your Livewire component to display the error message when the limit is reached:

    public function setMaxFilesError(string $message): void
{
    $this->addError('file', $message);
}

    Example Usage

    <x-filepond::upload wire:model="file" max-files="5" />

  3. Perform server-side validation on upload

    main

    To validate files immediately upon upload (without waiting for a form submission), implement the validateUploadedFile() method in your component and call $this->validate() within it.

    use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class MyLivewireComponent extends Component
{
    use WithFilePond;

    public $file;

    public function rules(): array
    {
        return [
            'file' => 'required|mimetypes:image/jpg,image/jpeg,image/png|max:3000',
        ];
    }

    public function validateUploadedFile()
    {
        $this->validate();

        return true;
    }
}
    public function validateUploadedFile()
{
    $this->validate();

    return true;
}

  4. Publish assets and translations

    main

    Use the following commands to publish package assets or configuration:

    Views

    php artisan vendor:publish --tag="livewire-filepond-views"

    Translations

    php artisan vendor:publish --tag="livewire-filepond-translations"

    Assets

    To serve assets directly instead of through the package endpoint:

    php artisan vendor:publish --tag=livewire-filepond-assets --force

  6. Include FilePond assets using the @filepondScripts directive

    main
    To include the necessary CSS and JavaScript for FilePond in your application, use the @filepondScripts Blade directive in your layout file. This directive automatically handles loading the styles and scripts, and it intelligently switches between the package's internal routes, published static assets, or Vite-served assets if you are running in a development environment.
    @filepondScripts

  7. Listen to Filepond Alpine.js events

    main

    You can listen to the following Alpine.js events emitted by the component:

    • filepond-upload-started: Started file upload.
    • filepond-upload-finished: Finished file upload.
    • filepond-upload-reverted: File upload reverted by user.
    • filepond-upload-file-removed: File removed from list by user.
    • filepond-upload-completed: All files in the list have been processed and uploaded.

  8. Restrict which files may be deleted

    main

    By default, the component deletes files from disk when a user removes them from the list, provided the files are in the public directory or configured symlinks.

    To restrict deletion to specific paths, override the canRemoveFile method. The $path argument is relative to the public directory and starts with a slash.

    protected function canRemoveFile(string $path): bool
{
    return str_starts_with($path, '/uploads/');
}

    If your application uses directories linked into the public directory that are not registered in filesystems.links, override filePondRemovalRoots to return an array of absolute paths that are safe to delete from.