<x-bt-file-dropzone />
Customize via presets →
Basic Usage
A minimal dropzone. Users can drag and drop files or click to open the file picker.
1<x-bt-file-dropzone name="basic-files" label="Upload Files" />Single File
Set :multiple="false" to allow only one file. Selecting a new file replaces the existing one.
1<x-bt-file-dropzone name="avatar" label="Profile Picture" :multiple="false" accept="image/*" />Accept Types
Restrict allowed file types using the accept prop. An auto-generated hint shows accepted types and size limits below the upload icon.
1<x-bt-file-dropzone name="images-only" accept="image/*" label="Images Only" />2<x-bt-file-dropzone name="docs-only" accept=".pdf,.doc,.docx" label="Documents" />Client-Side Validation
Files are validated before being added. Invalid files are rejected with inline error messages.
Three checks run on each file: type (matches accept), size (within max-file-size bytes), and count (within max-files limit).
Images and PDFs only. Max 5 MB each, up to 3 files.
1<x-bt-file-dropzone2 name="validated-uploads"3 label="Restricted Upload"4 accept="image/*,.pdf"5 :max-file-size="5242880"6 :max-files="3"7 help="Images and PDFs only. Max 5 MB each, up to 3 files."8/>Image Previews
When preview is enabled (default), image files show thumbnails. Non-image files display type-specific icons.
File type icons: photo (images), document-text (PDF), film (video), musical-note (audio), document (other). Disable previews with :preview="false".
1<x-bt-file-dropzone name="no-preview-docs" label="Documents (no previews)" :preview="false" accept=".pdf,.doc" />Existing Files
Display previously uploaded files alongside new selections using the existing-files prop.
Each item needs name and url. Optional: size and type. Removing an existing file dispatches an existing-file-removed Alpine event.
1<x-bt-file-dropzone2 name="existing-documents"3 label="Project Files"4 :existing-files="$existingFiles"5/>Clearable & Disabled
1<x-bt-file-dropzone name="not-clearable" label="Not Clearable" :clearable="false" />2<x-bt-file-dropzone name="disabled-dropzone" label="Disabled" :disabled="true" />Custom Placeholder
Override the default empty-state text with the placeholder prop.
1<x-bt-file-dropzone name="custom-placeholder" placeholder="Drag your photos here or click to browse!" />Colors
Colors affect the dropzone border, drag-over state, upload icon, and file item styling. Use the color prop or a magic color attribute.
1<x-bt-file-dropzone name="color-default" label="Default (beartropy)" />2<x-bt-file-dropzone name="color-blue" blue label="Blue" />3<x-bt-file-dropzone name="color-red" red label="Red" />4<x-bt-file-dropzone name="color-green" green label="Green" />5<x-bt-file-dropzone name="color-purple" purple label="Purple" />All available colors
beartropy (default), primary, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, slate, gray, zinc, neutral, stone.
Use the color prop for dynamic values: <x-bt-file-dropzone :color="$dynamicColor" />.
Validation Errors
Errors are automatically detected from the Laravel validation error bag. You can also force an error with custom-error.
Custom Error
Please upload at least one file.
1<x-bt-file-dropzone name="error-demo" label="Upload" :custom-error="'Please upload at least one file.'" />Help Text
Max 10 MB. PDF only.
Recommended: 1200x630px.
1<x-bt-file-dropzone name="help-demo" label="Upload" help="Max 10 MB. PDF only." />2<x-bt-file-dropzone name="hint-demo" label="Upload" hint="Recommended: 1200x630px." />Livewire Integration
When used with wire:model, the component shows upload progress with a progress bar on each file. Upload events are property-scoped so multiple dropzones on the same page don't cross-contaminate.
1<x-bt-file-dropzone2 id="dropzone-photos"3 wire:model="photos"4 label="Upload Photos"5 accept="image/*"6/>Real-World Example
A document upload form with validation constraints and Livewire integration.
1<div class="max-w-lg space-y-4"> 2 <x-bt-file-dropzone 3 id="dropzone-documents" 4 wire:model="documents" 5 label="Upload Documents" 6 accept=".pdf,.doc,.docx" 7 :max-file-size="10485760" 8 :max-files="5" 9 help="PDF and Word documents only. Max 10 MB per file, up to 5 files."10 color="blue"11 />12 <x-bt-button wire:click="submitDocuments" solid blue class="w-full">Upload Documents</x-bt-button>13</div>Props
| Prop | Type | Default | Description |
|---|---|---|---|
id
|
string|null
|
auto-generated
|
Component ID. Auto-generates as
beartropy-filedropzone-{uniqid} if omitted.
|
name
|
string|null
|
null
|
Input name attribute. Falls back to
id. In multiple mode, [] is appended automatically.
|
label
|
string|null
|
null
|
Label text displayed above the dropzone.
|
color
|
string|null
|
beartropy
|
Color preset name. Affects borders, drag-over state, icon, and file item styling.
|
multiple
|
bool
|
true
|
Allow multiple files. When
false, selecting a new file replaces the existing one.
|
accept
|
string|null
|
null
|
Accepted file types. Supports extensions (
.pdf), MIME wildcards (image/*), and exact MIME types (application/pdf).
|
maxFileSize
|
int|null
|
null
|
Maximum file size in bytes for client-side validation.
|
maxFiles
|
int|null
|
null
|
Maximum number of files for client-side validation.
|
placeholder
|
string|null
|
auto
|
Override the empty-state placeholder text. Auto-generated from
multiple when not set.
|
preview
|
bool
|
true
|
Show image thumbnails for image files. Non-image files display type-specific icons.
|
clearable
|
bool
|
true
|
Show remove buttons on individual files and a "Clear all" button when multiple files are selected.
|
disabled
|
bool
|
false
|
Disable the dropzone, preventing drag-and-drop and click-to-select.
|
customError
|
mixed
|
null
|
Custom error message that bypasses the validation error bag.
|
help
|
string|null
|
null
|
Help text displayed below the dropzone.
|
hint
|
string|null
|
null
|
Alias for
help.
|
existingFiles
|
array
|
[]
|
Previously uploaded files to display. Each item:
{name, url, size?, type?}. Removing dispatches an existing-file-removed Alpine event.
|