Fields

File Upload

Erag\InertiaForms\Fields\FileUpload renders a drop zone. Users can drag files onto it, click it, or press Enter/Space to open the file dialog. Selected files are listed with their name, size, and a remove button. Image uploads show a thumbnail preview.

When to use: avatars, attachments, documents, image galleries.

Examples

Each example is a live form built from the PHP below it. Fill it in and press submit to see the data your controller would receive.

Basic

One image up to 2 MB. image() limits the file dialog to images and shows a thumbnail after picking.

use Erag\InertiaForms\Fields\FileUpload;

FileUpload::make('avatar')
    ->label('Profile photo')
    ->image()
    ->maxSize(2048);

Allowed types

accept() limits the extensions, and the hint under the drop zone lists them together with the size limit. The submitted data shows the file by name.

use Erag\InertiaForms\Fields\FileUpload;

FileUpload::make('resume')
    ->label('CV')
    ->accept(['pdf', 'doc', 'docx'])
    ->maxSize(5120)
    ->placeholder('Drop your CV here')
    ->required();

Advanced: several files

An insurance claim with two upload fields. multiple() turns the value into a list, maxFiles() caps its length and maxSize() applies to each file.

use Erag\InertiaForms\Fields\FileUpload;
use Erag\InertiaForms\Fields\Textarea;

[
    Textarea::make('description')
        ->label('What happened?')
        ->rows(3)
        ->required(),
    FileUpload::make('photos')
        ->label('Photos of the damage')
        ->multiple()
        ->image()
        ->accept(['jpg', 'png', 'webp'])
        ->maxFiles(4)
        ->maxSize(4096)
        ->required(),
    FileUpload::make('receipts')
        ->multiple()
        ->accept(['pdf'])
        ->maxFiles(3)
        ->maxSize(2048)
        ->help('Optional. Invoices or repair quotes.'),
];

Methods

All common field methods are available, plus:

multiple(bool $multiple = true)

Allow several files. The value becomes an array. New files are added to the list instead of replacing it.

FileUpload::make('photos')->multiple()->image();

image(bool $image = true)

Accept only images. Uses Laravel's image rule instead of file, limits the file dialog to images (unless accept() is set), and shows previews.

FileUpload::make('cover')->image();

accept(array|string $extensions)

Allowed file extensions. Leading dots are removed, so '.pdf' and 'pdf' are the same. Adds an extensions: rule and filters the file dialog.

FileUpload::make('resume')->accept(['pdf', 'doc', 'docx']);
FileUpload::make('data')->accept('csv');

maxSize(?int $kilobytes)

Maximum size per file, in kilobytes. Adds a max: rule and a size hint inside the drop zone ("up to 2.0 MB").

FileUpload::make('video')->maxSize(50 * 1024); // 50 MB

maxFiles(?int $count)

With multiple(), the maximum number of files. Adds max:<count> to the array rule. In the browser, extra files beyond the limit are dropped.

FileUpload::make('attachments')->multiple()->maxFiles(5);

placeholder(?string $placeholder)

The main text inside the drop zone. Defaults to "Click to upload or drag and drop", with the first part in the accent color. Below it, a hint lists the allowed types, the size limit, and (with multiple()) the file limit, for example "PDF, DOCX · up to 5.0 MB · max 3 files".

FileUpload::make('logo')->image()->placeholder('Drop your logo here');

Validation rules

Single file

Configuration	Rules on name
default	file
image()	image instead of file
accept(['pdf'])	adds extensions:pdf
maxSize(1024)	adds max:1024

FileUpload::make('avatar')->image()->maxSize(1024);
// ['nullable', 'image', 'max:1024']

Multiple files

Key	Rules
name	array, max:<maxFiles> if set, plus your own rules
name.*	file/image, extensions:, max:<maxSize>

FileUpload::make('documents')->multiple()->accept(['pdf'])->maxFiles(3);
// 'documents'   => ['nullable', 'array', 'max:3']
// 'documents.*' => ['file', 'extensions:pdf']

How files are sent

When a form has at least one file upload, hasFiles is true in the schema and <Form> sends the request as multipart/form-data.

Browsers and PHP can't send multipart bodies with PUT, PATCH, or DELETE, so in that case <Form> sends a POST with _method set to the real verb. Laravel routes it to your put/patch/delete route as usual.

Value

• Single: a File object in the browser, an UploadedFile on the server. Empty value: null.
• multiple(): an array of files. Empty value: [].
• Bound values are always ignored. A file field starts empty even when editing, because existing files can't be put back into a file input.

Storing the upload

public function update(Request $request)
{
    $data = ProfileForm::make()->validate($request);

    if ($data['avatar'] ?? null) {
        $request->user()->update([
            'avatar_path' => $data['avatar']->store('avatars', 'public'),
        ]);
    }

    return back();
}

Edit forms

Don't mark a file field required() on edit screens. Since the field always starts empty, the user would have to upload the file again every time.

Standalone use

Vue

<FileUpload v-model="avatar" :field="avatarField" id="avatar" :disabled="false" />

React

<FileUpload field={avatarField} id="avatar" value={avatar} disabled={false} onChange={setAvatar} />

Svelte

<FileUpload field={avatarField} id="avatar" bind:value={avatar} disabled={false} />

The value is a File (or File[]). When you submit it yourself with Inertia, use forceFormData: true. See Standalone Components.