README

A modern, React-powered file upload and file viewer plugin for Filament. Supports Filament ^3.0, ^4.0, and ^5.0 with image previews, PDF thumbnails, gallery and list views, dark mode, and an optional document action system (verify/return) as a drop-in Filament form field and infolist entry.

Features

• Custom file upload field with drag & drop, progress tracking, and multi-file support
• PDF thumbnail rendering using pdfjs-dist
• Image & file viewer with zoom, pan, and page navigation
• Dark mode support out of the box
• Gallery and list view modes
• Optional file actions — attach verify/return controls per file (e.g. for document approval workflows)
• Assets loaded on demand — JS only loads on pages that use the components

Requirements

• PHP ^8.2
• Laravel version compatible with your chosen Filament major
• Filament ^3.0, ^4.0, or ^5.0
• Node.js (only needed if contributing or publishing changes)

Installation

Install via Composer:

composer require kukux/modern-file-upload

Important

This plugin ships pre-built JS assets. After installation or package updates, run php artisan filament:assets in your app so Filament can publish the package assets.

1. Add Plugin Views to Your Tailwind Config

If you are using a custom Filament theme (recommended), add the plugin's source paths so Tailwind includes its utility classes:

// tailwind.config.js
export default {
    darkMode: 'class',
    content: [
        // ... your existing paths
        './vendor/kukux/modern-file-upload/resources/views/**/*.blade.php',
        './vendor/kukux/modern-file-upload/resources/js/**/*.jsx',
    ],
}

Then rebuild your theme:

npm run build

2. Publish Filament Assets

Run:

php artisan filament:assets

3. Temporary Preview Behavior

Fresh uploads are previewed in the browser before the form is saved, so no extra Livewire page trait is required for normal image or PDF previews.

If your app still uses Livewire temporary preview configuration for PDFs, make sure the preview_mimes entry uses the extension format:

'temporary_file_upload' => [
    'preview_mimes' => [
        'png',
        'gif',
        'bmp',
        'svg',
        'wav',
        'mp4',
        'mov',
        'avi',
        'wmv',
        'mp3',
        'm4a',
        'jpg',
        'jpeg',
        'mpga',
        'webp',
        'wma',
        'pdf',
    ],
],

Use 'pdf', not 'application/pdf'.

Usage

File Upload Field (Form)

use Kukux\ModernFileUpload\Forms\Components\FileUpload;

public static function form(Form $form): Form
{
    return $form->schema([
        FileUpload::make('attachment')
            ->label('Upload File')
            ->disk('public')
            ->directory('uploads/attachments')
            ->accept('application/pdf')     
            ->multiple()                    
    ]);
}

File Viewer Entry (Infolist)

use Kukux\ModernFileUpload\Infolists\Components\FileViewer;

public static function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        FileViewer::make('attachment')
            ->label('Attached File')
            ->showDownload()
            ->showPdfThumbnails(),
    ]);
}

Optional: File Actions (Verify / Return)

For document approval workflows, you can attach per-file action controls (verify and return buttons) to any upload field. These only appear on already saved files — not on fresh temporary uploads.

1. Add a Livewire method to your resource or page

public function updateAction(int $fileId, string $action, ?string $remarks = null): void
{
    $file = Attachment::findOrFail($fileId);

    $file->update([
        'status'  => $action,
        'remarks' => $remarks,
    ]);
}

2. Attach the action to your field

FileUpload::make('attachment')
    ->disk('public')
    ->directory('uploads/attachments')
    ->accept('application/pdf')
    ->fileAction(function ($record) {
        return [
            'method' => 'updateAction',     // your Livewire method name
            'fileId' => $record?->id,
            'status' => $record?->status,   // "verified" | "returned" | null
        ];
    })

The verify/return buttons will appear on each saved PDF thumbnail. A confirmation modal is shown before any action is taken. Returned documents require a remarks/reason field before confirming.

Available Methods

FileUpload

FileViewer

Changelog

Please see CHANGELOG for what has changed in each release.

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

Security

If you discover a security vulnerability, please review our Security Policy.

Credits

• cortejojicoy
• All Contributors

License

The MIT License (MIT). Please see the License File for more information.