PHPackages                             filament/spatie-laravel-media-library-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Admin Panels](/categories/admin)
4. /
5. filament/spatie-laravel-media-library-plugin

ActiveLibrary[Admin Panels](/categories/admin)

filament/spatie-laravel-media-library-plugin
============================================

Filament support for `spatie/laravel-medialibrary`.

v5.4.1(2mo ago)1764.8M—3.2%3720MITPHPPHP ^8.2

Since Aug 29Pushed 1mo ago6 watchersCompare

[ Source](https://github.com/filamentphp/spatie-laravel-media-library-plugin)[ Packagist](https://packagist.org/packages/filament/spatie-laravel-media-library-plugin)[ Docs](https://github.com/filamentphp/filament)[ RSS](/packages/filament-spatie-laravel-media-library-plugin/feed)WikiDiscussions 5.x Synced 1mo ago

READMEChangelogDependencies (4)Versions (1156)Used By (20)

Filament Spatie Media Library Plugin
====================================

[](#filament-spatie-media-library-plugin)

Installation
------------

[](#installation)

Install the plugin with Composer:

```
composer require filament/spatie-laravel-media-library-plugin:"^5.0" -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="medialibrary-migrations"
```

Run the migrations:

```
php artisan migrate
```

You must also [prepare your Eloquent model](https://spatie.be/docs/laravel-medialibrary/basic-usage/preparing-your-model) for attaching media.

> For more information, check out [Spatie's documentation](https://spatie.be/docs/laravel-medialibrary).

Form component
--------------

[](#form-component)

You may use the field in the same way as the [original file upload](https://filamentphp.com/docs/forms/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](https://filamentphp.com/docs/forms/file-upload).

### Passing a collection

[](#passing-a-collection)

Optionally, you may pass a [`collection()`](https://spatie.be/docs/laravel-medialibrary/working-with-media-collections/simple-media-collections) that allows you to group files into categories:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

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

### Configuring the storage disk and directory

[](#configuring-the-storage-disk-and-directory)

By default, files will be uploaded publicly to your storage disk defined in the [Filament configuration file](https://filamentphp.com/docs/forms/installation#publishing-configuration). You can also set the `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](https://spatie.be/docs/laravel-medialibrary/working-with-media-collections/defining-media-collections#content-using-a-specific-disk).

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.

### Reordering files

[](#reordering-files)

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

To enable this behavior, use the `reorderable()` method:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

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

You may now drag and drop files into order.

### Adding custom properties

[](#adding-custom-properties)

You may pass in [custom properties](https://spatie.be/docs/laravel-medialibrary/advanced-usage/using-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 use a function to dynamically set the properties based on the uploaded file:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;
use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;
use Spatie\Image\Image;

SpatieMediaLibraryFileUpload::make('image')
    ->image()
    ->customProperties(function (TemporaryUploadedFile $file): array {
        $image = Image::load($file->getRealPath());

        return [
            'height' => $image->getHeight(),
            'width' => $image->getWidth(),
        ];
    })
```

### Adding custom headers

[](#adding-custom-headers)

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'])
```

### Generating responsive images

[](#generating-responsive-images)

You may [generate responsive images](https://spatie.be/docs/laravel-medialibrary/responsive-images/getting-started-with-responsive-images) when the files are uploaded using the `responsiveImages()` method:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

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

### Using conversions

[](#using-conversions)

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')
```

#### Storing conversions on a separate disk

[](#storing-conversions-on-a-separate-disk)

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')
```

### Storing media-specific manipulations

[](#storing-media-specific-manipulations)

You may pass in [manipulations](https://spatie.be/docs/laravel-medialibrary/advanced-usage/storing-media-specific-manipulations#breadcrumb) that are run when files are uploaded using the `manipulations()` method:

```
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;

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

### Filtering media

[](#filtering-media)

It's possible to target a file upload component to only handle a certain subset of media in a collection. To do that, you can filter the media collection using the `filterMediaUsing()` method. This method accepts a function that receives the `$media` collection and manipulates it. You can use any [collection method](https://laravel.com/docs/collections#available-methods) to filter it.

For example, you could scope the field to only handle media that has certain custom properties:

```
use Filament\Schemas\Components\Utilities\Get;
use Filament\Forms\Components\SpatieMediaLibraryFileUpload;
use Illuminate\Support\Collection;

SpatieMediaLibraryFileUpload::make('images')
    ->customProperties(fn (Get $get): array => [
        'gallery_id' => $get('gallery_id'),
    ])
    ->filterMediaUsing(
        fn (Collection $media, Get $get): Collection => $media->where(
            'custom_properties.gallery_id',
            $get('gallery_id')
        ),
    )
```

### Using media library for rich editor file attachments

[](#using-media-library-for-rich-editor-file-attachments)

You can use media library to store file attachments in the [rich editor](https://filamentphp.com/docs/forms/rich-editor). To do this, you must [register a rich content attribute](https://filamentphp.com/docs/forms/rich-editor#registering-rich-content-attributes) on your model, similar to how a media library collection is registered. You should call `fileAttachmentProvider()` on the attribute registration, passing in a `SpatieMediaLibraryFileAttachmentProvider::make()` object:

```
use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;
use Filament\Forms\Components\RichEditor\Models\Concerns\InteractsWithRichContent;
use Filament\Forms\Components\RichEditor\Models\Contracts\HasRichContent;
use Illuminate\Database\Eloquent\Model;

class Post extends Model implements HasRichContent
{
    use InteractsWithRichContent;

    public function setUpRichContent(): void
    {
        $this->registerRichContent('content')
            ->fileAttachmentProvider(SpatieMediaLibraryFileAttachmentProvider::make());
    }
}
```

> Using `SpatieMediaLibraryFileAttachmentProvider` requires that the rich content attribute (`content` in this example) must be defined as nullable in database.

A media collection with the same name as the attribute (`content` in this example) will be used for the file attachments. The collection must not contain any other media apart from file attachments for that attribute, since Filament will clear any unused media from the collection when the model is saved. To customize the name of the collection, you can pass it to the `collection()` method of the provider:

```
use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;
use Filament\Forms\Components\RichEditor\Models\Concerns\InteractsWithRichContent;
use Filament\Forms\Components\RichEditor\Models\Contracts\HasRichContent;
use Illuminate\Database\Eloquent\Model;

class Post extends Model implements HasRichContent
{
    use InteractsWithRichContent;

    public function setUpRichContent(): void
    {
        $this->registerRichContent('content')
            ->fileAttachmentProvider(
                SpatieMediaLibraryFileAttachmentProvider::make()
                    ->collection('content-file-attachments'),
            );
    }
}
```

You may want to preserve the original filenames of the uploaded files, using the `preserveFilenames()` method:

```
use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;

SpatieMediaLibraryFileAttachmentProvider::make()
    ->preserveFilenames()
```

You can customize the [media name](https://spatie.be/docs/laravel-medialibrary/api/adding-files#content-usingname) using the `mediaName()` method:

```
use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;
use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;
use Illuminate\Support\Str;

SpatieMediaLibraryFileAttachmentProvider::make()
    ->mediaName(fn (TemporaryUploadedFile $file): string => Str::random() . '_' . $file->getClientOriginalName())
```

You may pass in [custom properties](https://spatie.be/docs/laravel-medialibrary/advanced-usage/using-custom-properties) when uploading files using the `customProperties()` method:

```
use Filament\Forms\Components\RichEditor\FileAttachmentProviders\SpatieMediaLibraryFileAttachmentProvider;

SpatieMediaLibraryFileAttachmentProvider::make()
    ->customProperties(['archived' => false])
```

Table column
------------

[](#table-column)

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](https://filamentphp.com/docs/tables/columns/image).

### Passing a collection

[](#passing-a-collection-1)

Optionally, you may pass a `collection()`:

```
use Filament\Tables\Columns\SpatieMediaLibraryImageColumn;

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

The [collection](https://spatie.be/docs/laravel-medialibrary/working-with-media-collections/simple-media-collections) allows you to group files into categories.

By default, only media without a collection (using the `default` collection) will be shown. If you want to show media from all collections, you can use the `allCollections()` method:

```
use Filament\Tables\Columns\SpatieMediaLibraryImageColumn;

SpatieMediaLibraryImageColumn::make('avatar')
    ->allCollections()
```

### Using conversions

[](#using-conversions-1)

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')
```

### Filtering media

[](#filtering-media-1)

It's possible to target the column to only display a subset of media in a collection. To do that, you can filter the media collection using the `filterMediaUsing()` method. This method accepts a function that receives the `$media` collection and manipulates it. You can use any [collection method](https://laravel.com/docs/collections#available-methods) to filter it.

For example, you could scope the column to only display media that has certain custom properties:

```
use Filament\Tables\Columns\SpatieMediaLibraryImageColumn;
use Illuminate\Support\Collection;

SpatieMediaLibraryImageColumn::make('images')
    ->filterMediaUsing(
        fn (Collection $media): Collection => $media->where(
            'custom_properties.gallery_id',
            12345,
        ),
    )
```

Infolist entry
--------------

[](#infolist-entry)

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](https://filamentphp.com/docs/infolists/entries/image).

### Passing a collection

[](#passing-a-collection-2)

Optionally, you may pass a `collection()`:

```
use Filament\Infolists\Components\SpatieMediaLibraryImageEntry;

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

The [collection](https://spatie.be/docs/laravel-medialibrary/working-with-media-collections/simple-media-collections) allows you to group files into categories.

By default, only media without a collection (using the `default` collection) will be shown. If you want to show media from all collections, you can use the `allCollections()` method:

```
use Filament\Infolists\Components\SpatieMediaLibraryImageEntry;

SpatieMediaLibraryImageEntry::make('avatar')
    ->allCollections()
```

### Using conversions

[](#using-conversions-2)

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')
```

### Filtering media

[](#filtering-media-2)

It's possible to target the entry to only display a subset of media in a collection. To do that, you can filter the media collection using the `filterMediaUsing()` method. This method accepts a function that receives the `$media` collection and manipulates it. You can use any [collection method](https://laravel.com/docs/collections#available-methods) to filter it.

For example, you could scope the entry to only display media that has certain custom properties:

```
use Filament\Tables\Columns\SpatieMediaLibraryImageEntry;
use Illuminate\Support\Collection;

SpatieMediaLibraryImageEntry::make('images')
    ->filterMediaUsing(
        fn (Collection $media): Collection => $media->where(
            'custom_properties.gallery_id',
            12345,
        ),
    )
```

###  Health Score

71

—

ExcellentBetter than 100% of packages

Maintenance88

Actively maintained with recent releases

Popularity63

Solid adoption and visibility

Community32

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

1155

Last Release

82d ago

Major Versions

v4.4.0 → v5.0.0-beta82025-12-09

3.x-dev → v4.7.12026-02-10

v4.7.1 → v5.2.12026-02-10

v4.7.2 → v5.2.22026-02-20

4.x-dev → v5.2.42026-02-25

PHP version history (3 changes)v2.0.0-beta2PHP ^8.0

v3.0.0-alpha100PHP ^8.1

v4.0.0-alpha6PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/d5513b5defa6f680b8db229a305abf62d4e70f3e943b0da57dd5b303095c50c6?d=identicon)[DanHarrin](/maintainers/DanHarrin)

---

Top Contributors

[![danharrin](https://avatars.githubusercontent.com/u/41773797?v=4)](https://github.com/danharrin "danharrin (155 commits)")

### Embed Badge

![Health badge](/badges/filament-spatie-laravel-media-library-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/filament-spatie-laravel-media-library-plugin/health.svg)](https://phpackages.com/packages/filament-spatie-laravel-media-library-plugin)
```

###  Alternatives

[filament/forms

Easily add beautiful forms to any Livewire component.

4624.0M300](/packages/filament-forms)[filament/filament

A collection of full-stack components for accelerated Laravel app development.

3722.7M2.4k](/packages/filament-filament)[filament/tables

Easily add beautiful tables to any Livewire component.

3623.6M100](/packages/filament-tables)[filament/notifications

Easily add beautiful notifications to any Livewire app.

2423.8M62](/packages/filament-notifications)[filament/infolists

Easily add beautiful read-only infolists to any Livewire component.

1220.8M36](/packages/filament-infolists)[filament/widgets

Easily add beautiful dashboard widgets to any Livewire component.

1220.2M27](/packages/filament-widgets)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)