Skip to main content
The File component provides a styled file input for uploading documents and other files with automatic validation and mime type handling.

​
Basic Usage

<x-forms::file name="document" />

​
With Model Binding

<x-forms::form :model="$article">
    <x-forms::file name="featured_image" />
</x-forms::form>
When bound to a model that implements Spatie’s HasMedia interface, the component automatically retrieves and displays the file from the media library.

​
File Types

{{-- Document files (default) --}}
<x-forms::file 
    name="document" 
    type="document" 
/>

{{-- Multiple file types --}}
<x-forms::file 
    name="attachment" 
    :type="['document', 'image']" 
/>

{{-- PDF only --}}
<x-forms::file 
    name="pdf_file" 
    mimetypes="application/pdf" 
/>

​
Custom Validation

{{-- Custom mime types --}}
<x-forms::file 
    name="custom_file" 
    :mimetypes="['application/pdf', 'text/plain']" 
/>

{{-- Custom extensions --}}
<x-forms::file 
    name="custom_file" 
    :extensions="['pdf', 'txt', 'doc']" 
/>

{{-- Custom max size (in kilobytes) --}}
<x-forms::file 
    name="large_file" 
    :max-size="10240" 
/>

​
Spatie Media Library Integration

The File component integrates seamlessly with Spatie Media Library: 
{{-- Custom collection name --}}
<x-forms::file 
    name="attachment" 
    collection="documents" 
/>

{{-- Display specific conversion --}}
<x-forms::file 
    name="thumbnail" 
    conversion="thumb" 
/>

​
Model Setup

Your model should implement the HasMedia interface: 
use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class Article extends Model implements HasMedia
{
    use InteractsWithMedia;
    
    public function registerMediaCollections(): void
    {
        $this->addMediaCollection('featured_image')
            ->singleFile();
    }
}

​
File Display

{{-- Show file download link --}}
<x-forms::file 
    name="document" 
    download-icon="fa-download" 
/>

{{-- Custom clear icon --}}
<x-forms::file 
    name="document" 
    clear-icon="fa-times" 
/>

​
Hints and Help Text

{{-- Show automatic hint --}}
<x-forms::file 
    name="document" 
    :show-hint="true" 
/>
{{-- Displays: "Only .pdf, .jpeg and .png files of max 2MB allowed." --}}

{{-- Custom help text --}}
<x-forms::file 
    name="document" 
    help="Please upload your signed contract." 
/>

{{-- Hide hint --}}
<x-forms::file 
    name="document" 
    :show-hint="false" 
/>

​
Attributes

​
name
string
required
The name attribute for the file input
​
label
string
Label text for the file input. Auto-generated from name if not provided
​
type
string|array
default:"document"
File type category. Accepts: document, image, or array of types. Automatically determines allowed mime types
​
mimetypes
string|array
Allowed mime types. Overrides automatic detection from type. Examples: application/pdf, image/jpeg
​
extensions
string|array
Allowed file extensions. Overrides automatic detection from mime types. Example: ['pdf', 'doc', 'docx']
​
max-size
int
Maximum file size in kilobytes. Defaults to system default for the file type
​
collection
string
Spatie Media Library collection name. Defaults to the input name
​
conversion
string
Spatie Media Library conversion name to display. Example: thumb
​
file-input-class
string
Additional CSS classes for the file input wrapper
​
clear-icon
string
Icon class for the clear/remove button. Uses framework default if not specified
​
download-icon
string
Icon class for the download link. Framework default: fa-arrow-to-bottom (Bootstrap 5) or zmdi-open-in-new (Material Admin)
​
upload-icon
string
Icon class for the upload button. Framework default: fa-arrow-to-top (Bootstrap 5) or zmdi-upload (Material Admin)
​
model
object
Model instance to bind to. Automatically retrieves file from media library if model implements HasMedia
​
default
string
Default file URL if no value is bound
​
show-hint
bool
default:"true"
Show automatic hint with allowed file types and max size
​
show-errors
bool
default:"true"
Show validation errors
​
show-label
bool
default:"true"
Show the label
​
required
bool
default:"false"
Mark the field as required
​
disabled
bool
default:"false"
Disable the file input
​
ignore-accessor
bool
default:"false"
Ignore model accessors when retrieving value. Only retrieve from media library
​
inline
bool
default:"false"
Display label and input inline (horizontal layout)
​
help
string
Custom help text. Overrides automatic hint

​
Default File Types

The component automatically detects mime types based on the type attribute:
  • document: PDF, JPEG, PNG files (default)
  • image: JPEG, PNG, GIF, TIFF, SVG files
Mime types and extensions are automatically resolved using the AllowedMimeTypes helper from the javaabu/helpers package.

​
File Validation

The component renders the accept attribute with allowed mime types: 
<input type="file" accept="application/pdf,image/jpeg,image/png" />
For server-side validation, use Laravel’s file validation rules: 
$request->validate([
    'document' => 'required|file|mimes:pdf,jpeg,png|max:2048',
]);

​
Examples

​
Document Upload with Custom Size

<x-forms::file 
    name="contract" 
    label="Contract Document"
    type="document"
    :max-size="5120"
    required
/>

​
PDF Only Upload

<x-forms::file 
    name="invoice" 
    label="Invoice PDF"
    mimetypes="application/pdf"
    extensions="pdf"
    help="Please upload your invoice in PDF format."
/>

​
Media Library with Conversion

<x-forms::form :model="$article">
    <x-forms::file 
        name="thumbnail" 
        collection="featured_image"
        conversion="thumb"
        label="Thumbnail"
    />
</x-forms::form>

Build docs developers (and LLMs) love

Get started for freeTalk to us