Filepicker

This component is a wrapper for the very popular Filepond filepicker project by PQINA. We have tried to include the most important features Filepond offers. Most important here refers to the features applicable to most projects and serves most use-cases. The component allows both dragging and dropping of files on the control as well as browsing for files using the browser's default file picker.

        
            <x-bladewind::filepicker />

By default the Filepicker component provides a random name when no name attribute is specified. If you intend to disable automatic file uploads or will need to grab the base64 version of your files, set the name attribute.

        
            <x-bladewind::filepicker name="certs" />

Changing the Placeholder

The filepicker loads with a placeholder that is broken into two lines. The first line reads, Browse or drag and drop files. The second line reads, IMAGE, VIDEO, AUDIO, PDF up to 5mb. The second line contains the values specified for the accepted_file_types (image/*, video/*, audio/*, .pdf) and max_file_size (5mb) attributes. The default placeholder will always use the values specified for these two attributes.

Option 1

To change the placeholder text to your preferred text (preferably translated), set the placeholder_line1 and placeholder_line2 attributes.


<x-bladewind::filepicker
    placeholder_line1="Upload proof of payment"
    placeholder_line2="Only PDF files are allowed"  />

In the example above, we typed out everything for placeholder lines 1 and 2. As mentioned earlier, the default placeholder_line2 contains the values specified for accepted_file_types and max_file_size. The component replaces image/* with the text images, video/* with the text videos, audio/* with the text audios. If you want the component to dynamically replace your accepted_file_types and max_file_size in your placeholder_line2, include two %s placeholders in your text.


<x-bladewind::filepicker
    placeholder_line1="Drag and drop proof of payment here"
    placeholder_line2="Files allowed: %s up to %s"  />

Option 2

This is the default option used by the component. This provides you with the flexibility to define your own layout for how the placeholder should look. You can use your own icons and colours. This option requires you to definitely set the name attribute of the filepicker. Simply define a DIV element with the class placeholder-[$name] hidden. Replace [$name] with the actual name of the filepicker. This DIV will need to exist before you define the filepicker component.


<!-- remember to add the hidden CSS class -->
<div class="placeholder-invoices space-y-2 flex hidden align-middle py-3">
    <div>
        <x-bladewind::icon
            name="receipt-percent"
            class="!size-14 rounded-full p-3 bg-purple-400 text-purple-100"/>
    </div>
    <div class="text-left pl-2.5 pt-1.5">
        <div>Drag & Drop Invoices</div>
        <div class="!text-xs tracking-wider opacity-70">
            <u>PDFs</u> only. Max of <u>10mb</u>
        </div>
    </div>
</div>


<x-bladewind::filepicker name="invoices" />

Allow Drag and Drop Only

By default the filepicker component allows users to both drag & drop files or browse to select files. You can turn off file browsing by setting can_browse="false".


<x-bladewind::filepicker
    can_browse="false"
    placeholder_line1="Drag and drop files" />

Allow Browsing of Files Only

By default the filepicker component allows users to both drag & drop files or browse to select files. You can turn off drag & drop by setting can_drop="false".


<x-bladewind::filepicker
    can_drop"false"
    placeholder_line1="Drag and drop files" />

Disable the Filepicker

Set disabled="true".


<x-bladewind::filepicker disabled"true" />

Enforce File Sizes

You can restrict the size of files your users are allowed to upload by defining the max_file_size attribute. It is expected that you add the file measure, example, bytes, kb, mb, tb. The default is 5mb. The component will display an error if the user uploads a file larger than what is specified in max_file_size. If you expect your users to upload really huge files, remember to set this attribute so your users don't get restricted by the default of 5mb.


<x-bladewind::filepicker max_file_size="15kb"/>

In cases where you allow users to upload multiple files, you can set max_total_file_size to restrict the total size your users are allowed to upload without necessarily bothering about the size of individual files.

Error Messages

When a selected file exceeds the size allowed, two error messages are displayed. You can change these by setting the max_file_size_exceeded_label and max_file_size_label attributes to the appropriate messages.

max_file_size_exceeded_label	File size is too large
max_file_size_label	Maximum file size is 15kb

Enforce File Types

You can restrict the types of files your users are allowed to upload by defining the accepted_file_types attribute. You can either specify one or a comma separated list of any of the MIME types available here. You can either specify MIME types or file extensions. You can have a comma separated mixture of file extensions and MIME types. Note however, the file extensions need to have the dot prefix. Example: accepted_file_types="image/*, .pdf, .xlsx"


<x-bladewind::filepicker
    accepted_file_types="application/pdf, .doc, .docx"/>

Select Multiple Files

By default the filepicker allows users to select only one file because the attribute max_files="1". To allow selection of multiple files set the max_files attribute to a value other than one (1). The placeholder is always visible even when the user has already selected files. This makes it possible to select other files. The placeholder gets hidden when the maximum number of files are selected. To select a new file, the user will need to delete one of the selecte files. The example below allows for a selection of 5 files.


<x-bladewind::filepicker max_files="5" />

Image Manipulation

Filepond comes with an awesome array of image manipulation features that we have included in BladewindUI as well. These features are only exposed if accepted_file_types contains image related MIME types.

Image Preview

By default the filepicker allows users to see previews of images they select. This can be turned on or off by setting the show_image_preview attribute to true or false. You can leave out the attribute if you always want to display image previews since that's the default behaviour. If the selected files are a mixture of images and non images, only the images will have previews if show_image_preview="true".


<x-bladewind::filepicker max_files="3"
    show_image_preview="false" />


<x-bladewind::filepicker max_files="3" />

Image Cropping

Cropping is disabled by default and can be enabled by setting can_crop="true". The filepicker component's cropping feature integrates Cropper.js.


<x-bladewind::filepicker can_crop="true" />

When cropping is enabled it is important to set the aspect ratio. This defines how the cropping should be done. To define the aspect ratio set the crop_aspect_ratio attribute to a any of these: 16:9, 4:3, 2:3, 1:1 or free. The free aspect ratio allows the user to drag the cropper across the image to crop to their preferred dimensions. The default aspect ratio is 16:9.


<x-bladewind::filepicker can_crop="true" crop_aspect_ratio="4:3" />

Clicking on the 'Cancel' button from the Cropper popup window does not cancel the file selection. It only cancels the user's option to crop.

Image Resizing

There are no visual elements to this. This setting simply provides Filepond with information required to resize the image before it gets uploaded to the server. Assume you are building a shopping website and need all product images to have the same dimensions. You can use this option to resize all images uploaded using the filepicker to the required dimensions. Set can_resize="true" to allow image resizing and then set the preferred width and/or height by setting the image_resize_width and image_resize_height attributes.

Upload Selected Files to a Server

Files selected with the filepicker can either be uploaded automatically when the user selects the files or manually when the user clicks on a button to submit a form. The default behaviour is to manually upload files.

Automatically Upload Selected Files

Files can automatically be uploaded when they are selected in the filepicker by setting auto_upload="true". Next, you will need to tell the filepicker component which route is responsible for file uploads in your project by setting the upload_route attribute. File are automatically uploaded using the POST method. You can specify a different method by setting the upload_method attribute.

When files are selected and automatically uploaded, the filepicker component allows users to delete uploaded files by clicking on the trash icon. By default, the route for deleting files is the same as the route for uploading files. You can overwrite this by setting the delete_route attribute. When deleting files, the POST method is used, just like with uploading a file. You can change this by setting the delete_method attribute. Only the approved HTTP verbs can be used.

If your routes require additional headers you can specify them with upload_headers or delete_headers. These need to be defined as an array of headers. By default the delete_headers are the same as the upload_headers unless you explicitly set a different value.


$headers = [
    "Authorization" => "Bearer 67e518a8205b20.18576843",
]


<x-bladewind::filepicker
    name="auto_upload"
    max_file_size="1mb"
    auto_upload="true"
    upload_route="/upload"
    :upload_headers="$headers"
    delete_route="/upload-delete" />

When a file is selected, it will automatically be uploaded to the route specified. The routes and controller below handle this example upload.


// web.php
Route::post('/upload', [FileUploadController::class, 'upload']);
Route::post('/upload-delete', [FileUploadController::class, 'delete']);

// if you set delete_method="DELETE" and delete_route="/upload" on the component
// your route will then look like the line below
Route::delete('/upload', [FileUploadController::class, 'delete']);

This is a very barebones implementation of file uploading in Laravel to give you a sense of what's happening in the controller.

When deleting a file the component passes the JSON structure below. { "path" : "path/to/the/file-name-dot-extension" } example:
{ "path" : "uploads\/cqzbVgA5ydeQBvNkuBP4cZCGcpBTl3tt9dtufnKK.jpg" }


// FileUploadController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;

class FileUploadController extends Controller
{
    public function upload(Request $request)
    {
        $request->validate([
            'auto_upload' => 'required|mimes:jpg|max:1024',
        ]);

        $path = $request->file('auto_upload')->store('uploads', 'public');

        return response()->json(['path' => $path]);
    }

    public function delete(Request $request)
    {
        // path: will always contain the path to the file being deleted
        $filePath = $request->input('path');

        if (!$filePath) {
            return response()->json(['error' => 'No file path provided'], 400);
        }

        if (Storage::disk('public')->exists($filePath)) {
            Storage::disk('public')->delete($filePath);
            return response()->json(['message' => 'File deleted']);
        }
        return response()->json(['error' => 'File not found'], 404);
    }
}

Manually Upload Selected Files

This is the default option for the component. In some cases, you will want your user to trigger the actual upload of the files after they have probably finished filling a form with other fields. This is implemented when auto_upload="false" .You don't need to set this attribute since manual uploading is the default behaviour. The upload_route and upload_method attributes are ignored for manual uploads since it is expected that these should be set on your FORM tag. Remember to add the enctype="multipart/form-data" attribute on your form for uploads to work.

To support manual upload of multiple files, the name of the component will need to be an array. Example: name="idCards[]"


<form method="POST" action="/manual-upload" enctype="multipart/form-data">
    @csrf
<x-bladewind::filepicker
        name="manual_upload[]"
        max_file_size="1mb"
        max_files="3" />
    <x-bladewind::button can_submit="true">
        Upload Files
    </x-bladewind::button>
</form>


// web.php
Route::post('/manual-upload', [FileUploadController::class, 'manual_upload']);


// FileUploadController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;

class FileUploadController extends Controller
{
    ...
    public function manual_upload(Request $request)
    {
        $request->validate([
            'files.*' => 'mimes:jpg|max:1024',
        ]);

        $uploadedFiles = [];
        foreach ($request->file('manual_upload') as $file) {
            $path = $file->store('uploads', 'public');
            $uploadedFiles[] = $path;
        }
        dd($uploadedFiles);}
}

Encode Files as base64

The component allows for fies to be retrieved in base64 format. This works for uploading single files or multiple files. To encode uploaded files as base64, set base64="true". The name of input field for storing the base64 files has _b64 appended to it. So if the name of your filepicker field is attachment, the base64 encoded files will be written to attachment_b64.

You also need to specify how the encoded data should be returned using the base64_output attribute. The two values available for that attribute are string and url (default). The value to choose depends on your use case. The table below shows a sample of how each value's data is returned.

Value	Sample Output
`string`	/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAA ...
`url`	data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX ...


<form method="POST" action="/base64-upload" enctype="multipart/form-data">
    @csrf
<x-bladewind::filepicker
        name="attachments"
        max_file_size="1mb"
        base64="true"
        max_files="3" />
    <x-bladewind::button can_submit="true">
        Upload Files
    </x-bladewind::button>
</form>


// web.php
Route::post('/base64-upload', [FileUploadController::class, 'base64_upload']);


// FileUploadController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;

class FileUploadController extends Controller
{
    ...
    public function base64_upload(Request $request)
    {
        $base64Files = $request->input('attachments_b64');
        foreach ($base64Files as $file) {
            dump($file);
        }
    }

Both the selected files and their encoded base64 versions are available when the form is submitted. You can either use both or just focus on the base64 versions.

Preloading Component with Specific Files

In edit mode you will typically want to prepopulate the component with files the user selected earlier, so they can remove and/or add new files. Below is how you need to structure the list of files you pass to the filepicker's selected_value attribute


$existingFiles = [
    [ 'source' => asset('images/yoonbae-cho-Fes4eLW4mg0-unsplash.jpg') ],
    [ 'source' => asset('images/sam-carter-JU1SVl4smHM-unsplash.jpg') ],
    [ 'source' => asset('images/lissete-laverde-z9Ropm8edsw-unsplash.jpg') ],
];


<x-bladewind::filepicker
    name="edit"
    max_file_size="2mb"
    max_files="2"
    :selected_value="$existingFiles" />

Note from the above example that even though the $existingFiles array has 3 elements (files), the Filepicker displays only 2 files. This is because the Filepicker has been set to max_files="2". To ensure all files are loaded in the Filepicker, either set max_files to the number of elements in your selected_value array or remove the max_files attribute entirely.

Full List Of Attributes

The table below shows a comprehensive list of all the attributes available for the Filepicker component.

IMPORTANT: All component text/labels can be found in lang/bladewind.php. You can translate these into your preferred languages

Option	Default	Available Values
name	random	Name for the filepicker. So if you named the filepicker `profile_pic`, the resulting html will be `<input type="file" name="profile_pic" ../>`
accepted_file_types	image/, audio/, video/*, application/pdf	One or a comma separated list of any of the mimetypes available here.
placeholder_line1	Choose files or drag and drop to upload	Placeholder text to display on line 1
placeholder_line2	%s up to %s	Placeholder text to display on line 2
selected_value	[]	An array of file names to preload in the filepicker when in edit mode
required	false	Determines if the placeholder text should have an asterisk appended to it or not. `true` `false`
can_browse	true	Should user be able to click to launch the native file browser to select files. `true` `false`
can_drop	true	Should user be able to select files by dropping them on filepicker. `true` `false`
disabled	false	Should filepicker be disabled. `true` `false`
validate_file_size	true	Should all selected files have their sizes validated against what's been set for `max_file_size`. `true` `false`
base64	false	Should base64 versions of the selected files be generated. `true` `false`
base64_output	url	Should base64 versions of the selected files be generated. `url` `string`
show_credits	false	Show Filepond credits. `true` `false`
auto_upload	false	Automatically upload files once they are selected. `true` `false`
max_files	1	How many files can the user select. `positive integer`
max_file_size	5mb	Maximum size for each file. Must include the unit of measure bytes, kb, mb, gb, tb. `string`
auto_upload	false	Automatically upload files once they are selected. `true` `false`
add_new_files_to	top	When files already exist in the filepicker, any new selections should be placed in this position. `top` `bottom`
max_total_file_size	null	Maximum size allowed for all files selected. Must include the unit of measure bytes, kb, mb, gb, tb. Example: `1gb`
selected_value	[]	Files to automatically display when the component is loaded.
show_image_preview	true	Show image previews when images are selected. `true` `false`
can_resize_image	false	Allow image resizing in the background. This does not display any UI resizing controls. `true` `false`
image_resize_width	null	Images should be resized to this width. An aspect ratio is maintained if this is defined and the height is ignored. `positive integer`
image_resize_height	null	Images should be resized to this height. An aspect ratio is maintained if this is defined and the width is ignored. `positive integer`
can_crop	false	Allow image cropping. `true` `false`
crop_aspect_ratio	16:9	Aspect ratio used for image cropping. `top` `16:9` `4:3` `2:3` `1:1` `free`
upload_route	null	URL for automatic file uploads. See example.
upload_headers	[]	HTTP headers to append when calling $upload_route. See example.
upload_method	POST	HTTP method for automatically uploading files. `POST` `PUT` `PATCH`
delete_route	null	URL for deleting files automatically uploaded. See example.
delete_headers	null	HTTP headers to append when calling $delete_route. Defaults to what was set for `upload_headers` See example.
delete_method	null	HTTP method for deleting files automatically uploaded. Defaults to what was set for `upload_method`. `POST` `DELETE`

Filepicker with all attributes defined


<x-bladewind::filepicker
    name="profile_pic"
    required="false"
    placeholder_line1="Choose a profile picture"
    placeholder_line2="Only jpg files allowed"
    accepted_file_types=".jpg, .png"
    selected_value=""
    disabled="false"
    base64="false"
    base64_output="string"
    can_crop="false"
    can_drop="false"
    can_browse="true"
    validate_file_size="true"
    show_credits="true"
    auto_upload="true"
    max_files="2"
    max_file_size="1mb"
    max_total_file_size="2mb"
    add_new_files_to="bottom"
    show_image_preview="true"
    can_resize_image="true"
    image_resize_width="1024"
    image_resize_height=""
    can_crop="false"
    crop_aspect_ratio="free"
    upload_route="/dp/upload"
    upload_method="PATCH"
    :upload_headers="$headers"
    delete_route="/dp/delete"
    delete_method="DELETE"
    :delete_headers="$headers" />

The source file for this component is available in resources > views > components > bladewind > filepicker.blade.php

To prevent erratic behaviour when using multiple Filepickers on the same page, you should give each Filepicker a unique name. You can do this by setting the name attribute on the filepicker.