<x-widget.file-upload>
File upload Blade component for Laravel and Livewire
File uploads on a real file input: a drag-and-drop dropzone (single or multiple, with a file list and remove), a compact button, and an image or avatar picker with preview. Checks type and size in the browser from accept and max-size, and with upload-url uploads each file straight away with a progress bar and submits the stored ids. Works with Livewire wire:model.
php artisan bladewell:add file-upload
- Also adds
- Icon
- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guides
- Build a Laravel form from your validation rules · Using Blade components in Livewire 3 and 4 · Livewire file upload with progress and drag and drop
Usage
Validation
The browser's checks are for convenience; validate the same limits in your Form Request.
use Illuminate\Validation\Rules\File;
public function rules(): array
{
return [
'contract' => ['required', File::types(['pdf'])->max('5mb')],
// multiple: the array, then each file in it.
'attachments' => ['array', 'max:5'],
'attachments.*' => [File::types(['pdf', 'png', 'jpg', 'jpeg', 'webp'])->max('10mb')],
'avatar' => ['nullable', File::image()->max('2mb')],
'remove_avatar' => ['boolean'],
];
}
Direct upload route
upload-url: a route that stores one file (the request field is "file") and answers with its id. A 422 with errors.file shows that message on the file's row. Authorize it like any other write.
Route::post('/uploads', StoreUploadController::class)->middleware('auth')->name('uploads.store');
final class StoreUploadController
{
// StoreUploadRequest: ['file' => ['required', File::types(['pdf', 'jpg', 'png'])->max('10mb')]], and authorize()
// for who may upload. The widget's accept only filters the file picker, so the types are checked here. Kept on the
// private local disk: a file on the public one opens from your site's own address.
public function __invoke(StoreUploadRequest $request): JsonResponse
{
$upload = $request->user()->uploads()->create([
'path' => $request->file('file')->store('uploads', 'local'),
'name' => $request->file('file')->getClientOriginalName(),
'size' => $request->file('file')->getSize(),
]);
return response()->json(['id' => $upload->id]);
}
}
// The form then submits documents[] with those ids (its Form Request: 'documents.*' => ['integer', 'distinct']). Load
// them through the person's own uploads, so someone else's id finds nothing, and refuse the form if any did.
$ids = $request->validated('documents', []);
$uploads = $request->user()->uploads()->whereKey($ids)->get();
if ($uploads->count() !== count($ids)) {
throw ValidationException::withMessages(['documents' => 'One of these files is no longer available. Upload it again.']);
}
$application->attachments()->saveMany($uploads);
// And delete uploads nobody claimed after a day (a scheduled job), since a picked file may never be submitted.
Livewire
In a Livewire component that uses WithFileUploads, bind with wire:model; no name is needed. Each file goes to Livewire's temporary uploads as it's picked or dropped, and removing one from the list removes it from the property, so it always holds exactly what the list shows: one file, or an array with multiple. The list, name and preview survive every render; reset the property after saving ($this->reset('photo')) and they empty too. Livewire's livewire-upload-start, -progress and -finish events fire on the input. Not with upload-url, which sends files to your own route instead.
<form wire:submit="save" class="space-y-6">
<x-widget.file-upload label="Attachments" multiple max-size="10MB" wire:model="attachments" />
<x-widget.file-upload.image label="Photo" :src="$user->avatar_url" wire:model="photo" />
<button type="submit">Save</button>
</form>
On the server
The file upload can't stop a request that skips it. Here's what to check on your server, and what to keep cheap.
Security
-
acceptandmax-sizeonly check in the browser. Validate on the server withFilerules ormimes:andmax:, which read the file's content, not its name. -
Store under a generated name on a private disk, never in
public/. Serve files through a route that authorizes, or a temporary URL, and avoid serving SVG or HTML from your own domain. -
With
upload-url, the form submits ids: check each belongs to the person before attaching it.OWASP: Insecure direct object references · Laravel: Authorization
Server cost
-
A picked file may never be submitted. Consider a scheduled job that deletes uploads nobody claimed after a day, or storage keeps growing.
-
Make thumbnails, scan files or extract text in a queued job, not in the upload request, so a slow file doesn't hold a worker.
Examples
Dropzone
One file: drag it onto the area or click to browse. accept and max-size are checked as soon as it's picked, and say themselves in the hint; the Form Request checks them again (see Usage). Without JavaScript it's a plain file input.
Show code Hide code
<form method="POST" enctype="multipart/form-data" class="max-w-xl">
@csrf
<x-widget.file-upload name="contract" label="Signed contract" accept=".pdf" max-size="5MB" required />
</form>
Multiple
multiple with max-files: each file joins the list with its size and a remove button, and a file that's too big or the wrong type is listed with the reason instead of being added. The form sends the files still in the list.
Show code Hide code
<form method="POST" enctype="multipart/form-data" class="max-w-xl">
@csrf
<x-widget.file-upload name="attachments[]" label="Attachments" multiple max-files="5" accept="image/*,.pdf" max-size="10MB" />
</form>
Direct upload
upload-url sends each file to your route as soon as it's picked, with a progress bar and retry. The route stores it and returns its id, and the form submits the ids, not the files. Submitting waits for uploads still running. Uses an uploads.store route from your app; see Usage for it.
Show code Hide code
<form method="POST" class="max-w-xl">
@csrf
<x-widget.file-upload name="documents[]" label="Documents" multiple :upload-url="route('uploads.store')" max-size="10MB" />
</form>
Image
A profile photo or logo: pass the current one as src, pick a new one to preview it, or remove it. remove-name submits remove_avatar=1 when the current photo is removed. shape="square" suits logos; size is sm, md or lg. The preview needs img-src blob: in a Content Security Policy.
Show code Hide code
<form method="POST" enctype="multipart/form-data" class="flex flex-wrap gap-10">
@csrf
<x-widget.file-upload.image name="avatar" label="Profile photo" max-size="2MB" remove-name="remove_avatar" />
<x-widget.file-upload.image name="logo" label="Company logo" shape="square" size="lg" accept="image/png,image/svg+xml" max-size="1MB" />
</form>
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.file-upload>
| Prop | Default | Description |
|---|---|---|
| name |
null
|
What it submits as; its error is found under it (files aren't refilled after a failed submit). With multiple, [] is added if you leave it off. Optional with wire:model, which then names it. |
| id |
null
|
Defaults to one made from the name (or the wire:model property). |
| label |
null
|
Shown above the field, and its name for screen readers. |
| error |
null
|
An error message of your own; otherwise the validation error for the name, from the session or Livewire. |
| info |
null
|
A hint under the field. |
| bag |
'default'
|
Which error bag to read the error from. |
| disabled |
false
|
Greyed out: it can't be changed. |
| multiple |
false
|
Takes several files, listed one per row with a remove button. |
| accept |
null
|
The file types it takes, as for the accept attribute: extensions and MIME types, e.g. ".pdf,image/*". The picker only offers those, other files are turned away as they're picked, and the hint names them. |
| max-size |
null
|
The largest file it takes: 500KB, 5MB, 2GB, or a number of kilobytes like Laravel's max: rule. Bigger files are turned away as they're picked, and the hint says the limit. Your Form Request must still check it. |
| max-files |
null
|
The most files it takes; more than 1 turns on multiple. Extra ones are listed with an error instead of added. |
| upload-url |
null
|
Direct upload: each file is posted to this URL (as "file") as soon as it's picked, with progress and retry. The route stores it and returns JSON with its id, and the form submits the ids under the name instead of the files. |
| uploaded |
[]
|
Files already stored, listed as uploaded (after a failed submit, or when editing): [['id' => 7, 'name' => 'a.pdf', 'size' => 1024], …], size in bytes. Each id is submitted under the name until it's removed. Needs upload-url. |
| prompt |
'Drag files here or'
|
The text in the drop area, before the browse link. |
| browse |
'browse'
|
The browse link's text. |
| messages |
[]
|
Rewords or translates what it says, by key: tooBig (:name, :size), wrongType (:name), tooMany (:count), failed (:name), waiting, added (:count), removed (:name), uploadedOne (:name). |
<x-widget.file-upload.button>
| Prop | Default | Description |
|---|---|---|
| name |
null
|
What it submits as; its error is found under it (files aren't refilled after a failed submit). With multiple, [] is added if you leave it off. Optional with wire:model, which then names it. |
| id |
null
|
Defaults to one made from the name (or the wire:model property). |
| label |
null
|
Shown above the field, and its name for screen readers. |
| error |
null
|
An error message of your own; otherwise the validation error for the name, from the session or Livewire. |
| info |
null
|
A hint under the field. |
| bag |
'default'
|
Which error bag to read the error from. |
| disabled |
false
|
Greyed out: it can't be changed. |
| multiple |
false
|
Takes several files; beside the button it then says how many were chosen. |
| accept |
null
|
The file types it takes, as for the accept attribute: extensions and MIME types, e.g. ".pdf,image/*". The picker only offers those, other files are turned away as they're picked, and the hint names them. |
| max-size |
null
|
The largest file it takes: 500KB, 5MB, 2GB, or a number of kilobytes like Laravel's max: rule. Bigger files are turned away as they're picked, and the hint says the limit. Your Form Request must still check it. |
| button-label |
'Choose file'
|
The button's text. |
| empty-text |
'No file chosen'
|
Shown beside the button while no file is chosen. |
| messages |
[]
|
Rewords or translates what it says, by key: tooBig (:name, :size), wrongType (:name), count (:count, shown when several files are chosen). |
<x-widget.file-upload.image>
| Prop | Default | Description |
|---|---|---|
| name |
null
|
What it submits as; its error is found under it (files aren't refilled after a failed submit). Optional with wire:model, which then names it. |
| id |
null
|
Defaults to one made from the name (or the wire:model property). |
| label |
null
|
Shown above the field, and its name for screen readers. |
| error |
null
|
An error message of your own; otherwise the validation error for the name, from the session or Livewire. |
| info |
null
|
A hint under the field. |
| bag |
'default'
|
Which error bag to read the error from. |
| disabled |
false
|
Greyed out: it can't be changed. |
| accept |
'image/*'
|
The image types it takes, as for the accept attribute, e.g. "image/png,image/svg+xml". The picker only offers those, other files are turned away as they're picked, and the hint names them. |
| max-size |
null
|
The largest file it takes: 500KB, 5MB, 2GB, or a number of kilobytes like Laravel's max: rule. Bigger files are turned away as they're picked, and the hint says the limit. Your Form Request must still check it. |
| src |
null
|
The current image's URL, shown until a new one is picked; without it, a placeholder. |
| alt |
''
|
The image's alternative text. |
| shape |
'circle'
|
circle (avatars) or square (rounded corners, for logos). |
| size |
'md'
|
The preview's size: sm, md or lg. |
| remove-name |
null
|
A hidden field of this name submits 1 when the current image is removed (and 0 otherwise), so your controller knows to delete it. |
| choose-label |
'Upload'
|
The button's text while there's no image. |
| change-label |
'Change'
|
The button's text once there's an image. |
| remove-label |
'Remove'
|
The remove button's text. |
| messages |
[]
|
Rewords or translates what it says, by key: tooBig (:name, :size), wrongType (:name). |
Accessibility
All 5 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.
Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.
Source
What bladewell:add file-upload writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from
the components it also adds and Field, and the theme and base CSS.
resources/views/components/widget/file-upload/button.blade.php Show
resources/views/components/widget/file-upload/image.blade.php Show
resources/views/components/widget/file-upload/index.blade.php Show
resources/js/widget/file-upload/index.js Show
app/View/Widget/ElementIds.php Show
app/View/Widget/FormField.php Show
app/View/Widget/UploadLimits.php Show