Getting started
Library
Components
Integrations
Drivers
The Media Library provides three drivers out-of-the-box, with the option to write your own custom driver if needed. You can pick the one that best fits your needs.
It is even possible to use multiple drivers at the same time, for example use the default driver to give your users a manageable media library, and also register a storage/disk driver with readonly authorization to let them browse files from the disk.
| Media Library Item | Spatie Media Library | Storage/disk | |
|---|---|---|---|
| Best for | New projects | Existing Spatie setup | Existing files on disk |
| Reusable files | Yes | No | Yes |
| Folders | Yes | By collection, model type & model | Yes |
| Custom metadata | Yes (database columns) | Via custom properties | No |
| Stores reference as | Model ID | Spatie media record | File path |
Drivers
The default driver is the MediaLibraryItemDriver. It is a combination of spatie/laravel-media-library and two custom database models: MediaLibraryItem and MediaLibraryFolder.
The benefit of this driver is that it combines the advantages of Spatie Media Library with re-usable media items. Out of the box, each Spatie media record can only be linked to one other record. By placing an intermediate MediaLibraryItem model between your models and the Spatie media records, the file becomes reusable across many models.
Using this driver in your forms looks like:
MediaPicker::make('featured_image_id')
->label('Featured image')
->required(),This stores the id of the MediaLibraryItem in the featured_image_id column. You can then access the image through a relationship:
class YourModel extends Model
{
public function featuredImage(): BelongsTo
{
return $this->belongsTo(MediaLibraryItem::class, 'featured_image_id');
}
}Resulting in clean view code:
<img
src="{{ $yourModel->featuredImage->getUrl('thumb') }}"
alt="{{ $yourModel->featuredImage->name }}"
>This is the recommended driver for new installations. Since it is database-driven, it's also great for storing additional data on your media items – such as alt-text, copyright information, or photographer – by adding columns to your filament_media_library table. You can then build custom filters and custom sorters based on those columns.
It's also possible to write an importer to migrate existing files into this driver. Contact me with some details about your current structure for a free, personalised example import script.
Read the Media Library Item-driver page for installation and configuration.
If you have an existing library of files managed by Spatie Media Library – each linked to one model – you can use the SpatieMediaLibraryDriver. This driver lets your users manage their existing Spatie media records inside a Media Library UI, organised by collection, model type, and model.
The downside is that you cannot re-use files: each Spatie media record can only be linked to one model. If you need re-usable files, switch to the MediaLibraryItemDriver.
When using this driver, can you place a MediaPicker::make('collection_name') in your form schema. This will allow your users to manage the collection of media for this record. The files in the collection are previewed inline and the user can open the Media Library in a modal to manage this collection.
MediaPicker::make('collection_name')
->label('Manage files')
->required(),Read the Spatie Media Library driver page for installation and configuration.
The FilesystemStorageDriver is a more straightforward driver that simply stores files on a filesystem disk of your choice. This driver is a great choice when you already have a disk with existing files and now need a nice way to manage them in Filament.
You can provide authorization logic, so files that are in use cannot be deleted from the Media Library.
Using this driver in your forms looks like:
MediaPicker::make('featured_image_path')
->label('Featured image')
->required(),This stores the path of the selected file on the featured_image_path column. You're then free to use that path however you want.
Read the Storage/disk driver page for installation and configuration.
If none of the above fit your storage backend, you can write your own. See the Custom driver page for a step-by-step walkthrough. This will give you almost unlimited flexibility, as long as you implement the methods required by the driver interface. Support is available at [email protected].