Install the plugin with Composer:

composer require filament/spatie-laravel-media-library-plugin:"^3.1" -W

If you haven't already done so, you need to publish the migration to create the media table:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"

Run the migrations:

php artisan migrate

You must also prepare your Eloquent model for attaching media.

For more information, check out Spatie's documentation.

You may use the field in the same way as the original file upload field:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('avatar')

The media library file upload supports all the customization options of the original file upload component.

The field will automatically load and save its uploads to your model. To set this functionality up, you must also follow the instructions set out in the field relationships section. If you're using a panel, you can skip this step.

Optionally, you may pass a collection() allows you to group files into categories:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('avatar')
    ->collection('avatars')

By default, files will be uploaded publicly to your storage disk defined in the Filament configuration file. You can also set the FILAMENT_FILESYSTEM_DISK environment variable to change this. This is to ensure consistency between all Filament packages. Spatie's disk configuration will not be used, unless you define a disk for a registered collection.

Alternatively, you can manually set the disk with the disk() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->disk('s3')

The base file upload component also has configuration options for setting the directory() and visibility() of uploaded files. These are not used by the media library file upload component. Spatie's package has its own system for determining the directory of a newly-uploaded file, and it does not support uploading private files out of the box. One way to store files privately is to configure this in your S3 bucket settings, in which case you should also use visibility('private') to ensure that Filament generates temporary URLs for your files.

In addition to the behaviour of the normal file upload, Spatie's Media Library also allows users to reorder files.

To enable this behaviour, use the reorderable() method:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachments')
    ->multiple()
    ->reorderable()

You may now drag and drop files into order.

You may pass in custom properties when uploading files using the customProperties() method:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachments')
    ->multiple()
    ->customProperties(['zip_filename_prefix' => 'folder/subfolder/'])

You may pass in custom headers when uploading files using the customHeaders() method:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachments')
    ->multiple()
    ->customHeaders(['CacheControl' => 'max-age=86400'])

You may generate responsive images when the files are uploaded using the responsiveImages() method:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachments')
    ->multiple()
    ->responsiveImages()

You may also specify a conversion() to load the file from showing it in the form, if present:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachments')
    ->conversion('thumb')

You can store your conversions and responsive images on a disk other than the one where you save the original file. Pass the name of the disk where you want conversion to be saved to the conversionsDisk() method:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachments')
    ->conversionsDisk('s3')

You may pass in manipulations that are run when files are uploaded using the manipulations() method:

use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

SpatieMediaLibraryFileUpload::make('attachments')
    ->multiple()
    ->manipulations([
        'thumb' => ['orientation' => '90'],
    ])

To use the media library image column:

use Filament\Tables\Columns\SpatieMediaLibraryImageColumn;

SpatieMediaLibraryImageColumn::make('avatar')

The media library image column supports all the customization options of the original image column.

Optionally, you may pass a collection():

use Filament\Tables\Columns\SpatieMediaLibraryImageColumn;

SpatieMediaLibraryImageColumn::make('avatar')
    ->collection('avatars')

The collection you to group files into categories.

You may also specify a conversion() to load the file from showing it in the table, if present:

use Filament\Tables\Columns\SpatieMediaLibraryImageColumn;

SpatieMediaLibraryImageColumn::make('avatar')
    ->conversion('thumb')

To use the media library image entry:

use Filament\Infolists\Components\SpatieMediaLibraryImageEntry;

SpatieMediaLibraryImageEntry::make('avatar')

The media library image entry supports all the customization options of the original image entry.

Optionally, you may pass a collection():

use Filament\Infolists\Components\SpatieMediaLibraryImageEntry;

SpatieMediaLibraryImageEntry::make('avatar')
    ->collection('avatars')

The collection you to group files into categories.

You may also specify a conversion() to load the file from showing it in the infolist, if present:

use Filament\Infolists\Components\SpatieMediaLibraryImageEntry;

SpatieMediaLibraryImageEntry::make('avatar')
    ->conversion('thumb')